前言¶
在 DSH（DeepSeek Harness / Cordis）里跑智能体时，上下文窗口有限，会话结束后的偏好、结论和项目事实很难稳定留在下一轮里。常见做法是再装一两个记忆插件，或把状态塞进外部向量库；路径一多，依赖、索引口径和「模型一次能读多少」往往各说各话。下面介绍维护者 ububwudb 发布的 dsh-memory-agent：把固定阅读预算、BM25 检索、确认闸门、索引重建、原子写入和按会话忘却等机制收进一个零硬依赖的包，默认把记忆落在工作目录下的纯文件树里，并暴露 MemoryBackend 供以后替换后端。
这是什么¶
dsh-memory-agent 是 SkillHub 分类「记忆」下的 DSH 插件（目录页：ububwudb/dsh-memory-agent，源码：GitHub）。package.json 当前版本为 0.1.1，许可证 MIT，运行时 dependencies 为 {}，不捆绑也不依赖 dsh-persist、dsh-memory-pyramid 等其它记忆插件。面向需要在 Harness 里做可审计、可本地备份的长时记忆，且希望工具 handler 能脱离宿主做单元测试的开发者。
核心功能¶
存储与索引¶
默认根目录为 <cwd>/.agent/memory/，包含 index.jsonl（一行一条索引）、ledger.jsonl（审计事件）、episodes/、raw/、topics/ 等。文件是真相源；状态变更会写回记忆文件的 front-matter，rebuildIndex() 可与磁盘一致。面板或 YAML 可配置 root 覆盖路径。
九个工具与阅读预算¶
插件向模型注册九个工具，handler 形状为 async (backend, input) => output，可在 fixture 里直接测：
| 工具 | 作用概要 |
|---|---|
memory_nav |
分页浏览摘要层；指定 path 可读单条全文 |
memory_search_hybrid |
BM25 混合检索（非简单子串匹配），支持标签、时间等过滤 |
memory_assemble |
在 token 预算内组装上下文 |
write_memory |
写入；支持查重、冲突与确认闸门 |
memory_confirm |
待确认条目转为可检索 |
memory_resolve |
冲突行保留或丢弃 |
forget_memories_by_session |
按会话批量忘却 |
memory_sweep |
只读体检 |
memory_digest |
「当前认知」分层蒸馏槽位 |
memory_nav 默认一次最多 50 条摘要（上限 500），避免一次把整库塞进上下文；读全文必须显式传 path。memory_assemble 与配置里的 defaultBudget（默认 1200 token）共同约束固定阅读预算。
写入、确认与自动沉淀¶
写入可走 requireConfirmation：新条可为 suggested，经 memory_confirm 或设置面板确认后变为 active。冲突状态可用 memory_resolve 或面板「保留 / 丢弃」收尾。README 还描述 自动沉淀、常驻注入（面板可调字符预算 200–8000）等运行期行为；具体开关见配置与设置 → 记忆面板。
设置面板与本地 API¶
安装后可在 设置 → 记忆 查看路径与统计、改六项行为、BM25 搜索、手写记忆、确认 / 冲突 / 软删 / 重建索引 / 导出备份等。面板写 <root>/config.json，保存后立即生效；删掉该文件则回落 Cordis YAML。宿主提供 webServer 时，POST /memory-agent/api 按 op 分发（仅本机回环与限定请求头），无 webServer 时面板跳过，工具仍可用。
零硬依赖与降级¶
apply() 创建 backend、注册工具、注册卸载清理。defineTool 优先来自 @deepseek-ai/dsh-tools；解析失败时插件用内置 DSL→JSON Schema 编译器降级，避免因 import 失败整体不可用。
安装与启用¶
全局或装入某个 DSH profile：
npm i -g dsh-memory-agent # 或装进某个 DSH profile
包内通过 cordis.patch.yml 声明 bundle patch，向 Cordis 插入插件行（name 为 npm 包名 dsh-memory-agent）。默认片段示例：
- insert:
- id: memory-agent
name: dsh-memory-agent
inject: [tools, systemPrompt, webServer, sessions]
config:
root: null
requireConfirmation: false
defaultBudget: 1200
maxTopK: 200
lifecycle:
enabled: false
audit: true
插件入口导出 name、inject: ['tools'] 与 apply(ctx, config)。peerDependencies 含 @deepseek-ai/cordis（约 ~4.0.5）与 @deepseek-ai/dsh-tools（0.2.1-rc.2，可选）；engines.node 要求 >=18.19。发布目标 dshTarget 为 0.2.1-rc.2，安装前请对照你本地的 Harness / Cordis 版本。
典型用法¶
浏览与检索¶
模型或你在工具里可以这样用（语义来自 README 契约说明）：
- 第一页摘要：
memory_nav空对象或默认参数。 - 翻页：
memory_nav带offset。 - 某目录：
memory_nav带path: "topics/"。 - 单条全文：
memory_nav带path: "raw/mem_x.md"或path: "mem_x"。 - 任务相关检索：
memory_search_hybrid带query，必要时tags、top_k；再用memory_assemble带task与hits（或让工具链自行衔接）。
写入与确认¶
write_memory：summary、source、session_id 等；requireConfirmation 为 true 时状态可为 suggested。
memory_confirm：{ id } → status active。
面板里手写的记忆不过确认闸门，直接生效。
按会话清理¶
forget_memories_by_session 读索引里的 sources 数组；共享 topics 仅解绑来源。面板「按会话忘却」提供两步确认的同等能力。
索引损坏时¶
设置里点「重建索引」，等价调用 rebuildIndex()；也可在工具侧由宿主触发同一后端逻辑。
适用场景与注意¶
适合：希望在项目目录内用 Git 或文件备份管理记忆、需要 BM25 + 预算内组装的 Harness 工作流、想少装几个互相依赖的记忆插件、要在 CI 里跑 test/run-fixtures.mjs 一类纯函数测试的场景。
注意：
- 插件以当前 DSH 进程权限读写
<cwd>/.agent/memory/；安装 npm 包或改 patch 前，应自行查看 GitHub 源码 与 MIT 许可证，确认符合你的安全与合规要求。 - README「安全与隐私」一节提到本地存储、面板 API 的本机限制；导出备份有 ≤8MB 上限，超出会标记截断。
- 已知限制以仓库 README 为准（例如向量字段
vector_id为 null、lifecycle 默认关闭等）；不要假设与云端向量库等价。 - SkillHub 目录为社区插件索引，与 DeepSeek / 幻方无官方从属关系；星标等元数据以目录页为准（当前 GitHub 1 star）。
结尾¶
dsh-memory-agent 把「文件真相源 + BM25 + 固定阅读预算 + 确认与冲突收尾 + 按会话忘却」压进零运行时依赖的一个包，并附带设置面板与可替换的 MemoryBackend。若你要在 DSH 里做可落地的长时记忆，可从全局安装和 cordis.patch.yml 接线开始，再用九个工具或面板验证读写是否符合预期。
- 目录页：https://www.skillhub.cn/plugins/ububwudb/dsh-memory-agent
- GitHub：https://github.com/ububwudb/dsh-memory-agent
