dsh-task-memory

一句话定位

为 DeepSeek Harness 提供任务隔离的长期记忆：每个任务一个独立的 vault，记忆写入、读取、检索与提示注入都只在当前任务边界内生效，避免不同项目之间的记忆串味。

核心能力

• 按任务分库存储：每个任务在 ~/.dsh/storages/task-memory/<task-id>.json 下持有一份独立 vault，记忆永远不会跨任务自动泄露
• 8 个 memory 工具：模型可通过 memory_bind_task / memory_remember / memory_recall / memory_search / memory_forget / memory_current_task / memory_list_tasks / memory_clear_task 完整管理记忆
• 默认任务自动推导：未绑定时按 session 的工作目录（cwd）哈希生成稳定任务 id，无需手动配置即可"按目录隔离"
• 提示注入按会话隔离：每个 agent 的系统提示只注入该会话所属任务的记忆，优先置顶条目，再补近期条目，受字符预算约束
• 容量与并发安全：vault 容量上限可配；置顶条目永不淘汰；新 key 满时显式报错而非静默丢弃；同任务写入经进程内异步锁串行化
• 原子写入与崩溃恢复：每次保存走"临时文件 + 原子 rename"，启动时清理超过 1 小时的崩溃残留 tmp 文件

技术实现

• 语言: TypeScript（src/index.ts / src/store.ts / src/search.ts，编译为 lib/index.js，type: module ESM）
• 关键依赖: 宿主 peer 依赖 @deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-agent ^0.1.0-rc.8、@deepseek-ai/dsh-tools ^0.1.0-rc.6、@deepseek-ai/dsh-system-prompt ^0.1.0-rc.6、@deepseek-ai/dsh-home-paths ^0.1.0-rc.6、@deepseek-ai/schemastery ^3.18.1；运行时仅用 Node 内置 node:fs/promises / node:path / node:crypto
• 架构模式: Cordis 单面插件——export const name = 'task-memory'、export const inject = ['tools', 'systemPrompt']；通过 dsh.bundle.patch 指向 cordis.patch.yml 注入宿主层，注册 8 个工具 + 1 个固定 systemPrompt section + 1 个 agent-scoped systemPrompt.context
• 入口文件: src/index.ts（导出 apply(ctx, config)，完成工具注册、提示注入、session-task 绑定清理、tmp 清理与默认任务缓存预热）

适用场景

同一个 DSH 里同时维护多个项目（前端 + 后端 + 实验脚本）、用 DSH 做长期研发助手、且不希望模型把 A 项目的技术栈约定误用到 B 项目的用户。痛点是多数 DSH 记忆插件要么全局共享、要么按 workspace 切，对"同一工作树里多线任务并行"的人不友好；这个插件把 task 当边界，副产物还顺带解决了"会话级别提示污染"——每个 agent 会话的系统提示只看到自己任务的记忆。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:wangyihao0001-oss/dsh-task-memory

配置项

配置位于 cordis.patch.yml 的 config 字段，Schema 由 src/index.ts 的 Config 校验，所有字段都有默认值，可零配置运行：

修改后需要重启 dsh web（或重启 profile）让 Cordis 重新加载。

常见问题

Q: 卸载插件后记忆文件还在吗?

A: 在。记忆以纯 JSON 保存在 ~/.dsh/storages/task-memory/<task-id>.json，从 profile 移除 bundle 不会删除这些文件；想彻底清理需要手动备份或删除该目录。

Q: 提示注入的内容会跨任务串味吗?

A: 不会。注入按 agent 作用域注册（agent.ctx.systemPrompt.context），每个会话的系统提示只包含它自己所属任务的记忆；其他任务、其他会话、其他 agent 的记忆永远看不到。

Q: 关键词搜索支持中文吗?

A: 支持。检索会做英文 token 切分 + 中文 bigram（相邻两字组合）匹配（见 src/search.ts#tokenize），但仍是词法匹配，不支持向量检索或语义相似度。

Q: vault 满了之后再写新 key 会怎样?

A: 写入失败并返回明确错误（提示先 forget 或 unpin 一些条目），绝不静默丢弃刚写入的事实；但对已有 key 的就地更新（upsert）不会因容量被拒，会尽力收缩非置顶条目。

Q: 还需要手动指定 taskId 吗?

A: 默认不需要：没绑定时由 session 的工作目录（cwd）哈希生成稳定任务 id。需要同时跑多个项目时调用 memory_bind_task 显式切换。

Q: 怎么在生产环境固定版本?

A: 安装时在包名后追加 40 位 commit SHA，例如 dsh plugin --profile web add "github:wangyihao0001-oss/dsh-task-memory#<sha>"，避免上游更新被自动拉到。

Q: 升级/卸载后要重启 DSH 吗?

A: 要。插件通过 cordis.patch.yml 注入宿主的 Cordis 层，安装或移除后必须重启 dsh web（或重启 profile）让 Cordis 重新加载。

Q: 能把敏感信息写进记忆吗?

A: 不建议。README 与 8 个工具的描述都明确提醒不要写入密钥、token、个人隐私；vault 是纯 JSON，备份或人工编辑时一样会落盘。

上手难度

入门 — 安装后无需任何配置即可获得"按 cwd 自动分任务 + 8 个记忆工具 + 提示注入"能力；所有偏好都能在 cordis.patch.yml 的 config 字段按需调整。

已知问题与限制

• 检索是词法匹配：英文 token + 中文 bigram，不支持向量检索或语义相似度（src/search.ts:8-50）
• 暂无浏览 vault 的 Web UI：目前是 Host-only 组合包，vault 只能通过工具或直接编辑 JSON 文件管理
• 隔离边界仅作用于本插件的 task id：不沙箱化 DSH 其他插件或工作区本身
• tmp 清理保守：启动时只清理 > 1 小时的崩溃残留 tmp，避免误删其他进程的进行中写入（src/store.ts:189-208）——代价是 1 小时内的 tmp 会留到下次启动
• 卸载不删数据：从 profile 移除不再清空 ~/.dsh/storages/task-memory/，需要手动备份或清理
• 容量上限对已有 key 透明但对新增 key 严格：vault 满且可淘汰的只有置顶条目时，新 key 写入会报错（避免"刚写入就被淘汰"的静默丢失），需要先 forget 或 unpin
• 同任务写入是进程内锁：跨进程/跨机器不互斥，vault 文件可手工拷贝但并发写入需自行协调
• 工具提示词会消耗上下文：memory_bind_task / memory_search 等 8 个工具的描述随工具列表加载到模型上下文，频繁切换任务或开多任务并行时占用可观的 token 预算

English | 中文

Task-isolated long-term memory for DeepSeek Harness.

Memories live in per-task vaults under ~/.dsh/storages/task-memory/. Facts stored for one task are invisible to another unless you deliberately switch.

Catalog: dsh.pub/en/plugins/dsh-task-memory

Why this exists

Most DSH memory plugins are global or workspace-wide. This one treats task as the isolation boundary:

1. Default task = derived from session cwd
2. memory_bind_task rebinds the current session to a named vault
3. Search / recall / prompt injection never cross that boundary — prompt injection is registered at agent scope, so each session's system prompt only ever shows its own task's memories

Quick start

# Install into the web profile (pin a full commit SHA for production)
dsh plugin --profile web add "github:wangyihao0001-oss/dsh-task-memory"

# Or via the catalog CLI
npx dshpub add wangyihao0001-oss/dsh-task-memory --profile web

Restart the web UI (or reboot the profile), then in a session:

1. memory_bind_task — e.g. taskId: "my-app" (optional title)
2. memory_remember — key: "stack", content: "Node 22 + Postgres", optionally pinned: true
3. memory_recall / memory_search — read back within the same task
4. memory_current_task — confirm which vault this session is on

Tools

Never store secrets in memory entries.

Install / verify / disable

# Install
dsh plugin --profile web add "github:wangyihao0001-oss/dsh-task-memory#<40-char-sha>"

# Confirm the bundle layer is present
dsh --profile web --dump-config

# Remove from the profile when done
dsh plugin --profile web remove dsh-task-memory

After install or remove, restart dsh web (or reboot the profile) so the Cordis layer reloads.

Vault files under ~/.dsh/storages/task-memory/ are not deleted on uninstall — back up or delete them yourself if needed.

Local develop (without installing)

npm install
npm run build
npm test        # node:test unit tests
npm run smoke   # build + smoke

Link a checkout while developing:

dsh plugin --profile web add "$(pwd)"

If you run DSH from a source checkout:

pnpm dsh web --patch /absolute/path/to/dsh-task-memory/cordis.dev.yml

Update the absolute path in cordis.dev.yml so it points at this checkout’s built lib/index.js.

Config

cordis.patch.yml defaults:

injectLimit: 8           # max memories in prompt context
injectMaxChars: 2400     # soft char budget for the injected block
injectMaxEntryChars: 400 # per-entry char cap in the injected block (truncated)
injectPrompt: true       # inject pinned/recent facts for the active task
maxEntries: 500          # vault cap (>= 1); oldest non-pinned entries are evicted first
                         # (pinned are never evicted; new keys over the cap are rejected;
                         # upserts of existing keys are not blocked by capacity)

Optional storageRoot overrides ~/.dsh/storages/task-memory.

Storage & reliability

~/.dsh/storages/task-memory/
  <task-id>.json

Each file:

{
  "taskId": "<task-id>",
  "title": "<title>",
  "updatedAt": 0,
  "entries": [
    {
      "id": "m_…",
      "key": "<key>",
      "content": "…",
      "tags": [],
      "pinned": true,
      "createdAt": 0,
      "updatedAt": 0
    }
  ]
}

• Files are plain JSON — safe to hand-edit or back up
• Writes go through tmp file + atomic rename, so readers always see a consistent snapshot
• Mutations for the same task (including memory_bind_task title updates, save, and update) are serialized in-process (per-task lock); concurrent agents cannot lose updates. Prefer update over load → mutate → save for read-modify-write
• Pinned entries are never evicted; when a full vault has nothing removable but pinned entries, new keys are rejected with a clear error instead of silently dropping the just-written fact, while upserts of existing keys are never blocked by capacity (they still shrink best-effort)
• On startup, stale *.tmp files from crashed writes are cleaned up (only those older than 1h, so another process's live write is never touched)

Model experience

When injectPrompt is true, the plugin injects a short memory block into the current agent session's system prompt:

• Only the vault bound to that session (or the cwd-derived default)
• Prefer pinned entries, then recent ones, up to injectLimit / char budgets
• Other sessions and other tasks never appear in this block

Tools remain available for explicit recall/search beyond what fits in the prompt.

Known limitations

• Host-only bundle: no Web UI for browsing vaults yet (see roadmap)
• Keyword search is lexical (EN tokens + 中文 bigrams), not embeddings / vector search
• Isolation is per task id within this plugin — it does not sandbox the rest of DSH
• Catalog listing on dsh.pub is an automated contract check, not a security audit
• Do not store credentials, tokens, or personal secrets in memories

Compatibility

• Node.js >= 20
• DeepSeek Harness peers as declared in package.json (@deepseek-ai/dsh-* / cordis / schemastery)
• Installs as a Git bundle via dsh.bundle.patch → cordis.patch.yml
• Intended profile: web (or any profile that loads Host tools)

Roadmap

• ✅ Per-session prompt injection via agent-scoped context (replaces process-level binding guess)
• Optional vector search behind the same tools
• Tiny Web UI page to browse / pin / delete vaults

License

MIT — see LICENSE.