JohnXu22786/memory-standard

English | 简体中文

面向 DeepSeek Harness（dsh）的记忆标准协议（mm） 插件：一种确定性、分层、 跨 agent 互认的记忆系统，基于普通 Markdown 文件——而非专有协议。

dsh 生态已有数十个记忆类插件却缺乏统一标准，官方核心也只带一个默认关闭的 MCP 记忆示例。本插件抢占缺失的「标准位」：确定性预算 + 分层 MEMORY.md + 跨 agent 互认 + 与官方 compaction/会话日志的摄取协同。

• 分层记忆 —— MEMORY.md 为优先加载的索引（硬顶：默认 200 行 / 25 KB）； 详细记忆存放于 memories/<topic>.md，按需加载。
• 确定性预算 —— 超过任何预算都是带用量指标的确定性错误，并要求重写索引， 绝不静默截断。写入带字符预算并返回用量，便于 agent 当场压缩。
• 跨 agent 互认 —— 有规范的纯 Markdown 格式、可移植的 mm://<memoryId>/<topic> URI、JSON Schema（schema/memory.schema.json）与 开放读写接口，而非闭锁协议。
• 写入时机 —— mem_write API + 会话结束/周期提示（nudging）；写入立即 落盘、下一会话生效（会话内读取保持冻结，保护提示词缓存）。
• 摄取协同 —— mem_digest 识别官方 dsh 会话日志 / compaction 产物作为 记忆来源并蒸馏候选记忆（可选、自包含、无需 LLM）。
• 工具链 —— dsh 工具 mem_read、mem_write、mem_search、mem_budget、 mem_digest，外加 dsh-memory CLI。

核心库零运行时依赖（仅 Node 内置模块），既能嵌入 dsh 使用，也可独立运行。

状态

dsh 生态为开发者预览期；格式版本 mm v1（见 SPEC.md）。 与已安装的 @deepseek-ai/dsh CLI 及 bundle 规范（dsh.bundle.patch + cordis.patch.yml + apply(ctx)）兼容。

---

快速开始

1. 接入 dsh（本地目录 bundle）

在包含本包的目录（dsh-memory-standard/）内执行：

dsh plugin --profile demo add ./

# 或直接从本 GitHub 仓库安装
dsh plugin --profile demo add github:JohnXu22786/memory-standard
# 或发布后从 npm 安装
dsh plugin --profile demo add dsh-memory-standard
# 独立的 CLI 也会以全局 npm bin 形式发布
npm install -g dsh-memory-standard

# 启动 profile，五个 mem_* 工具与 'memory-standard' 系统段随之加载
dsh --profile demo

dsh plugin 会在 profile 目录内转调 pnpm；peer 依赖（@deepseek-ai/cordis、 @deepseek-ai/dsh-tools、@deepseek-ai/schemastery）从 dsh 安装解析。 已在 dsh@0.1.0-rc.6 上验证。

其他安装路径：

• 作为开发 overlay：将 cordis.patch.yml 复制或引用到 --patch 覆盖层， 行内 name 指向本包入口。
• 插件首次加载会自动初始化记忆根（$DSH_HOME/memory 或 $DSH_MEMORY_ROOT）， 无需手动 init。

2. 配置

bundle 自带默认值；可在更上层（profile 的 cordis.patch.yml、$DSH_HOME 覆盖层或 --patch）通过行 id 覆盖 memory-standard：

- id: memory-standard
  config:
    root: ''                 # '' => $DSH_MEMORY_ROOT，否则 $DSH_HOME/memory
    memoryId: local
    indexLines: 200          # MEMORY.md 行数硬顶
    indexBytes: 25600        # MEMORY.md 字节硬顶（25 KB）
    detailMaxBytes: 65536    # 单个详细记忆文件字节硬顶
    defaultWriteBudget: 4000 # 每次写入的字符预算
    search:
      mode: auto             # auto | scan | fts5
      limit: 10
      maxSnippetChars: 160
    nudge:
      enabled: true          # 会话结束/周期提示（memory/nudge 事件）
      intervalMs: 1800000
    lang: auto               # auto | en | zh（系统提示段语言）

3. 使用

dsh 会话中，agent 会获得五个工具（外加解释该协议的系统提示段）：

工具	用途
mem_read	读取索引、全部摘要或单个 note 全文（冻结快照）
mem_write	带字符预算写入/更新 note；返回用量；绝不截断
mem_search	记忆搜索（可用时用 FTS5，否则用 scan；scan 支持中文）
mem_budget	确定性预算报告（索引上限、各 note 用量、pending 写入）
mem_digest	从会话日志 / 文本蒸馏候选记忆（绝不写入）

其他插件可通过提供的服务直接访问记忆：

const memory = ctx.get('memory')
memory.write({ topic: 'deploy-region', content: 'us-east-1', summary: '部署区域' })
memory.search('deploy')

4. 独立 CLI

npm run build                # 首次使用需先编译 lib/
node lib/cli.js init --root <dir>
node lib/cli.js write deploy --content "we deploy to us-east-1" --root <dir>
node lib/cli.js read deploy --root <dir>
node lib/cli.js budget --root <dir>
node lib/cli.js search deploy --root <dir>
node lib/cli.js digest --file <session.log.jsonl> --root <dir>

所有命令均支持 --json 机器可读输出；--root 指定记忆根。全局安装 npm i -g . 后可直接使用 dsh-memory。

---

工作原理

分层记忆

<root>/MEMORY.md         优先加载的索引（小、有硬顶）
<root>/memories/t1.md    按需加载的详细记忆（自由 Markdown）

不传 topic 的 mem_read 返回索引（即优先加载面）；传 topic 则返回该 note 全文。预算可帮助 agent 判断哪些内容进索引摘要、哪些进详细 note。

确定性预算

三条「绝不截断」保证（详见 SPEC.md §6）：

1. 写入超过字符预算即失败并返回 usage.overflow，不写任何内容； 压缩后重试，
2. note 超过字节上限即失败，保留原有内容，
3. 索引超过行/字节硬顶即失败并明确要求重写——错误文案会明说。 删除/合并使索引重新达标是恢复路径。

规范的写入方绝不能用「静默丢内容」来“修复”超预算写入——标准将其视为数据丢失。

冻结快照

Memory 每会话只加载一次快照。读取与搜索都服务于该快照；写入落盘、下一会话 生效。pendingWrites 暴露本会话已暂存的写入；reload() 重新快照（CLI 与集成 场景使用）。这保证了会话内视图自洽，并保护提示词缓存。

跨 agent 互认

• 磁盘格式为规范的纯 Markdown（SPEC.md），URI 为 mm://<memoryId>/<topic>。
• schema/memory.schema.json 描述任何合规写入/读取方都应遵循的 note 形状。
• 公开 API（Memory，以及 dsh 中的 ctx.get('memory')）是开放接口—— 不是封闭工具协议。任何 agent 或工具都能读写同一批文件。

摄取协同

dsh 将会话存放在 $DSH_HOME/sessions 并做 compaction；这些日志即被识别为 记忆来源。mem_digest 会读取最近的 *.jsonl/*.md（或显式文件/文本）， 识别 mm: 标记、MEMO:/记忆：/记住： 行、总结行与 Markdown 标题，并返回 带预算的候选供审查。它绝不自动写入——由 agent 决定提交哪些。

---

项目结构

src/
  types.ts            共享/互认类型 + 默认值（mm v1）
  core/               零依赖库（仅 Node 内置模块）
    memory.ts         Memory 门面：快照、写入、预算、搜索、蒸馏
    format.ts         索引/note 的 Markdown 文法 + URI（SPEC 的实现）
    budget.ts         确定性预算计算
    search.ts         scan 搜索 + 可选 SQLite FTS5（node:sqlite）
    digest.ts         会话日志蒸馏
    paths.ts          目录布局与根解析
  dsh/
    tools.ts          五个 mem_* 工具的 defineTool 注册
    guide.ts          系统提示「标准段」
  cli.ts              dsh-memory CLI
  index.ts            dsh bundle 入口（name/inject/Config/apply）
cordis.patch.yml      bundle 补丁层
schema/memory.schema.json
SPEC.md / README.md / README.zh.md
examples/root/        可运行的示例记忆
test/                 node:test 测试套件（预算/分层/快照/搜索/蒸馏/互认/CLI）

开发

npm install
npm run build      # tsc -> lib/
npm test           # 构建 + node --test
npm run typecheck

仅使用开发依赖（typescript、@types/node，以及用于类型检查的 dsh peer 包）。运行时除了 Node 内置模块外零依赖（node:sqlite 可选用于 FTS5；不可用时 自动降级为 scan）。

许可证

MIT —— 见 LICENSE。