dsh-df-memory

Readme

# dsh-df-memory

DeepSeek Harness（Cordis）插件：把 [lhdrc-agent-memory](https://github.com/lhdrc/lhdrc-agent-memory)（df-memory 核心仓）的记忆能力接入 agent 工具面。

当前版本 **0.5.1**（npm 已发布）。

## 安装

### 方式一：npm 安装（推荐）

```bash
dsh plugin --profile web add dsh-df-memory
# 或
cd <profile 目录> && pnpm add dsh-df-memory
```

核心库会作为依赖自动从 npm 拉取，无需手动安装。

### 方式二：clone 本地安装（开发用）

```bash
git clone https://github.com/lhdrc/lhdrc-agent-memory
git clone (https://github.com/lhdrc/dsh-df-memory.git)
# 本地 link 安装插件（改动插件源码即时生效）
dsh plugin --profile web add ./dsh-df-memory
# 或
dsh --patch ./dsh-df-memory/cordis.patch.yml
```

> clone 方式下插件的核心依赖指向 npm；若需直接使用本地 core 源码，请手动改为 `file:../lhdrc-agent-memory/packages/core`。

安装后若 bundles 列表未自动更新，检查 profile `package.json` 的 `dsh.profile.bundles` 包含 `dsh-df-memory`。

## 主 API 是工具，不是读仓文件

Agent 应通过以下工具访问记忆，**不要**把 `cat brains/…` 或直接读 markdown 当作主路径：

| 工具 | 用途 |
|---|---|
| `memory_query` | 检索相关记忆；可选 `type` 过滤（decision\|lesson\|note\|experience\|skill），命中带 `schema_type` 层标签。**默认排除 skill 与 `*.overview.md`/`*.abstract.md` 侧车**（显式 `type=skill` 时豁免；侧车原文仍可 `memory_read`）。experience/skill 命中额外带 `eta_score`/`support`/`source_paths`（snippet 优先 trigger）。可选 `brain` 覆盖本次调用的 brain |
| `memory_read` | 读单个节点原文；可选 `brain` |
| `memory_remember` | LLM 编译写入（默认异步：返回 `accepted`+`task_id`；`wait=true` 同步等到 kept；无 Key 且无 bridge → `E_DISABLED`）。可选 `brain` |
| `memory_job_status` | 查询 remember/compile 任务状态（`.dfmemory/jobs/{brainId}/`）。只给 `task_id` 时只查当前默认 brain，**不**扫其它 brain；可另传 `brain` |
| `memory_capture` | **零 LLM** 显式写一条 L0 笔记（`captureNode`，ADD-only，`llm.provider=off` 也可用）。可选 `metric`/`value`/`unit`/`period` 为该次 `facts` 记量纲（`value` 必须有 `metric`，`metric` 需至少一条 `facts`） |
| `memory_init` | 在工作区初始化记忆仓（`initMemoryRepo`；`git: init\|existing\|off`） |
| `memory_tree` | 只读盘点仓内目录/文件（`listTree`/`renderTree`） |
| `memory_forget` | 软归档节点（`status=archived`，D17，记 ledger） |
| `memory_sync` | 显式把 dirty 刷进 git 账本（`flushRepoLedger` explicit，等价 `sync --commit`） |
| `memory_brain` | brain 管理：`list`（含 `sources` / `is_default`）/ `create`（已有则保持） |
| `memory_rebuild_index` | 从 md 重建索引（`rebuildIndex`；D1 索引可丢可重建） |
| `memory_events` | 列出近期 ledger 事件（`listLedgerEvents`） |
| `memory_skill` | **规则层**：`list` / `find` / `read` / `inject`；skill 不混默认 `memory_query`。`inject` 经宿主 `ctx.skills.register` 登记为会话 skill（trigger + procedure 摘要，非全文）。可选 `brain` |
| `memory_skill_outcome` | 显式打分 `{ name, success, note? }` → `eta_score`/`support`/`status`；**不**因 success 自动 activate |
| `memory_trend` | 查指标趋势 `{ metric, threshold?, direction?, brain? }` → 扫 facts 的 metric/value 检测回归；`points:[]` 是合法结果（不报错）。数据用 `memory_capture` + `metric`/`value` 写入 |

Prompt section `df-memory` 会在 system prompt 中提醒模型遵守上述约定。

## 配置（cordis.yml）

```yaml
repoRoot: null    # 默认从 DSH 会话工作区向上找 memory.yml（不是 dsh 进程 cwd）
brainId: null     # 默认仓内 brain_id
agentId: dsh      # created_by 前缀
llmBridge: true   # provider=off 时用 DSH 的 LLM 跑 memory_remember；false 关闭
llmProvider: deepseek-official   # bridge 路由 provider（可选）
llmModel: deepseek-v4-flash      # bridge 路由 model（可选）
skillInjectMaxChars: 2000  # 单 skill 注入体上限（可选）
skillInjectMaxCount: 3     # 会话级注入 skill 个数上限（可选）
injectTopK: 5              # pre-step 知识注入 top-k（可选）
bootInjectExperiences: true  # session-start 注入成熟经验（可选）
bootInjectTopK: 3            # 启动注入条数（可选）
rememberAsync: true          # false 时 remember 等价 wait:true
# compile.job_timeout_ms: 120000  # 写在 memory.yml 的 compile 段；超时 job 标 failed + E_TIMEOUT，不写 L0
```

定位顺序：`repoRoot` → `DF_MEMORY_ROOT` → 当前会话 `SessionHeader.cwd` → `workspaceRegistry` → `process.cwd()`。Web UI 里请把工作区选成含 `memory.yml` 的目录。若仍报「未找到 memory.yml」，在插件 config 里写绝对 `repoRoot`，或让 agent 调用 `memory_init` 建仓。

## 自动行为（挂钩）

- **会话摄入**：`autoBuffer` 默认 true。`session/event` 只收 user/model + assistant；达窗 / dispose 入队 compile（任务权威 `.dfmemory/jobs/`，不进检索、不进 git）。`autoBuffer: false` 可关。
- **门控注入**：pre-step 命中 `shouldQueryMemory` → 检索 top-k 注入（`injectOnGate` / `injectTopK`），失败 fail-open。
- **启动注入**：`agent/session-start` 注入该 brain active 经验 top-3（`bootInjectExperiences` 默认 true）；与门控注入按 path 去重。不注 skill、不注 L0。
- **LLM bridge**：仓内 `llm.provider=off` 时，`memory_remember` 自动走 DSH 自己的 LLM（`ctx.get("llm")` → `complete()`），无需在仓内配 API key；bridge 覆盖 compile 抽取与懒蒸馏。`kill_switch` 仍优先。

> 宿主侧注意：**`ctx.llm` 属性不可读**（llm 不在插件 inject 列表），必须走规范访问 `ctx.get("llm")`。

## 测试

```bash
bun install
bun test
```

## 引用

- 核心仓（df-memory）：<https://github.com/lhdrc/lhdrc-agent-memory>