持久记忆 douglarek/dsh-memory

dsh-memory

为 DeepSeek Harness（DSH）提供跨会话持久记忆，参照 Grok Build 的记忆实现。

插件在两个作用域里保存持久、可人工编辑的 Markdown 笔记——全局（所有项目共享的偏好）和工作区（单个仓库）——把已完成的轮次记录成可搜索的会话日志，在首轮注入一份有长度上限的记忆索引，并给模型提供五个记忆工具和五个斜杠命令。

这是一个仅 Host 的 bundle，除 Node 内置模块外没有运行时依赖。它不含 UI 面板；记忆通过工具和 /memory 浏览。

安装

给智能体

这是一个 DSH Host 插件 bundle，不用 npm install 安装。按顺序选第一条可用的路径：

1. plugin_manager 工具可用：

plugin_manager { action: "install_bundle", target: "github:douglarek/dsh-memory" }

2. DSH_PROFILE 为 desktop：在运行中的 DSH 应用里从 Plugin Manager 安装。

3. 其他配置档：

dsh plugin --profile "$DSH_PROFILE" add github:douglarek/dsh-memory

如果 DSH_PROFILE 未设置，向用户询问配置档名称。

4. 本地检出：

plugin_manager { action: "install_bundle", target: "/absolute/path/to/dsh-memory" }

不要手动编辑配置档的 package.json 或 cordis.patch.yml，也不要在配置档目录里运行 pnpm。

用 memory_list 验证。如果记忆工具不可用，开一个新会话或重启 DSH。

DSH Plugin Manager

plugin_manager { action: "install_bundle", target: "github:douglarek/dsh-memory" }

命令行

desktop 配置档由 Electron 应用管理。其他配置档：

dsh plugin --profile my-profile add github:douglarek/dsh-memory

移除：

dsh plugin --profile my-profile remove dsh-memory

本地检出

plugin_manager { action: "install_bundle", target: "/absolute/path/to/dsh-memory" }

package.json 声明了 dsh.bundle.patch；cordis.patch.yml 插入 dsh-memory 的 Host 行。

手动添加配置档行

- insert:
- id: dsh-memory
name: 'dsh-memory'
config:
enabled: true

包必须能从配置档的 node_modules 解析到。

功能

| 能力 | 行为 |
| 分作用域笔记 | $DSH_HOME/memory/ 下的 global/ 和 workspaces/<slug>-<hash8>/ |
| 整理后的记忆 | topics/<topic>.md 和 observations/_inbox/.md |
| 生成的索引 | 每个作用域一份 MEMORY.md，每次写入后重建 |
| 会话记录 | 每个完成的轮次追加到按会话划分的 Markdown 日志 |
| 首轮注入 | 紧凑索引作为持久的 user 角色消息注入一次 |
| 压缩后刷新 | compaction/end 之后重新注入紧凑索引 |
| 模型工具 | memory_search、memory_get、memory_list、memory_remember、memory_forget |
| 人工命令 | /memory、/remember、/forget、/dream、/flush |
| 搜索 | BM25 全文检索，带时间衰减、来源权重和可选 MMR |
| 中文搜索 | CJK 单字 + 双字，中文笔记无需分词器也能匹配 |
| 提示词引导 | <memory> 段落说明何时以及如何使用这些工具 |

实现遵循 Grok Build 的记忆模型：

- 记忆是磁盘上的 Markdown，用户可读可改；下次搜索就能看到改动。
- MEMORY.md 是生成的索引，收录主题与观察。
- 工作区标识优先取自 git origin 远程，取不到时用规范项目目录。
- 搜索是 BM25 全文检索，带归一化分数、会话分块时间衰减、来源权重和可选 MMR。
- 会话记忆是历史上下文；可变事实请对照实时来源核实。

配置

所有选项都可选，代码里有默认值。bundle 行只列出最重要的默认值；在配置档补丁里编辑该行的 config。

- id: dsh-memory
name: 'dsh-memory'
config:
enabled: true
memoryDir: '' # default: $DSH_HOME/memory
scopeGlobal: true
scopeWorkspace: true
toolsEnabled: true
promptEnabled: true
commandsEnabled: true
captureEnabled: true
injectEnabled: true

针对已有行的补丁会替换整个 config；需要的字段请全部重写。

核心

| 选项 | 默认值 | 含义 |
| enabled | true | 总开关；设为 false 则什么都不注册。 |
| memoryDir | '' | 记忆根目录。留空表示 $DSH_HOME/memory；~ 会展开。 |
| scopeGlobal | true | 启用全局作用域。 |
| scopeWorkspace | true | 启用工作区作用域。 |
| toolsEnabled | true | 注册五个记忆工具。 |
| promptEnabled | true | 添加 <memory> 系统提示词段落。 |
| commandsEnabled | true | 挂载命令服务时注册斜杠命令。 |
| promptInstructions | '' | 原样替换默认的 <memory> 提示词段落。 |

捕获

| 选项 | 默认值 | 含义 |
| captureEnabled | true | 把完成的轮次追加到会话日志。 |
| captureSubagents | false | 同时捕获子代理会话。 |
| captureMinTurnChars | 24 | 短于此长度的轮次跳过，除非运行过工具。 |
| captureMaxUserChars | 2000 | 每轮用户文本上限。 |
| captureMaxAssistantChars | 2000 | 每轮助手文本上限。 |
| captureMaxEntryChars | 6000 | 整轮条目上限。 |
| captureMaxFileBytes | 2000000 | 会话日志超过此大小就轮转到 -partN.md。 |

注入

| 选项 | 默认值 | 含义 |
| injectEnabled | true | 是否注入记忆索引。 |
| injectSubagents | false | 同时注入子代理会话。 |
| injectAlways | false | 没有笔记时注入一条简短的「记忆为空」提示。 |
| injectAfterCompaction | true | 在 compaction/end 之后刷新索引。 |
| injectMaxBytes | 4096 | 注入索引的字节预算。 |
| injectMaxTopics | 40 | 每个作用域的主题条目数。 |
| injectMaxObservations | 8 | 每个作用域的待处理观察条目数。 |
| injectMaxSessions | 8 | 列出的近期会话日志数。 |

搜索与索引

| 选项 | 默认值 | 含义 |
| searchMaxResults | 6 | 默认结果数。 |
| searchMinScore | 0.7 | 默认归一化分数阈值。 |
| searchHalfLifeDays | 30 | 会话分块半衰期；0 表示关闭衰减。 |
| searchMmrEnabled | true | 多样性重排序。 |
| searchMmrLambda | 0.7 | MMR 相关性/多样性平衡。 |
| searchMaxFiles | 2000 | 文件扫描上限。 |
| searchMaxFileBytes | 2000000 | 单文件读取上限。 |
| searchMaxChunks | 600 | 分块索引上限。 |
| searchStalenessDays | 7 | 为较早的会话结果添加过期提示。 |
| searchIncludeIndex | false | 同时索引生成的 MEMORY.md（会与主题重复）。 |
| searchSourceWeights | {global:1,workspace:1,session:1} | 各来源的分数乘数。 |
| chunkMaxChars | 1600 | 分块大小。 |
| chunkOverlapChars | 320 | 续接重叠；最多为 chunkMaxChars 的一半。 |
| indexMaxBytes | 8192 | 生成索引的大小预算。 |
| indexMaxEntries | 64 | 生成索引的条目预算。 |
| skipTemporaryWorkspaces | false | 为临时目录会话关闭工作区记忆。 |

未知选项会被忽略并给出警告；类型错误和超出范围的值会让激活失败，并给出明确错误。

存储布局

$DSH_HOME/memory/
├── global/
│ ├── MEMORY.md generated index (read-only for the model)
│ ├── topics/<topic>.md curated notes, one subject per file
│ └── observations/_inbox/.md standalone observations
└── workspaces/<slug>-<hash8>/
├── MEMORY.md generated index
├── topics/<topic>.md
├── observations/_inbox/.md
├── sessions/
│ └── YYYY-MM-DD-<slug>-<sid8>.md
└── .scope.json workspace identity metadata

目录以 0700 模式创建，文件以 0600 模式创建，受进程 umask 约束。每次写入后，MEMORY.md 会以原子方式重建。

工作区标识

<slug>-<hash8> 由仓库标识推导而来：

1. 从项目的 git 配置读取 origin URL（不会启动 git 进程）。git@github.com:org/repo.git 和 HTTPS 形式都会归一化为 org/repo。
2. 取 sha256(identity) 的前 8 个十六进制字符作为哈希，仓库名作为 slug。
3. 没有 origin 远程时，使用规范的项目目录本身。

因此，同一仓库的克隆和工作树共享同一个工作区作用域。

工具

模型能看到五个工具。它们都需要一个所属的智能体会话，因为工作区作用域来自该会话的工作目录。

memory_search

搜索全局、工作区和过往会话的分块。

| 参数 | 类型 | 含义 |
| query | string，必填 | 用具体的技术术语效果最好。 |
| scope | all \| workspace \| global | 默认 all。 |
| source | all \| workspace \| global \| session | 按来源类型过滤。 |
| max_results | integer | 1–50；默认取 searchMaxResults。 |
| min_score | number | 0–1；默认取 searchMinScore。 |

结果包含相对根目录的路径、行范围、来源、得分、标题、片段，会话条目还带时间。路径可以直接传给 memory_get。

memory_get

读取 Markdown 记忆文件，行号从 1 开始。

| 参数 | 类型 | 含义 |
| path | string，必填 | 相对根目录、根目录下的绝对路径，或 workspace/... / global/... 别名。 |
| from | integer | 起始行，从 1 开始。 |
| lines | integer | 最多读取的行数（上限 2000）。 |

路径穿越和指向记忆根目录之外的符号链接逃逸都会被拒绝。

memory_list

列出已保存的文件，含标题、大小和日期。

| 参数 | 类型 | 含义 |
| scope | all \| workspace \| global | 默认 all。 |
| kind | all \| index \| topic \| observation \| session | 默认 all。 |
| max_files | integer | 1–200；默认 100。 |

在 /dream 之前用很有帮助，也可以用来找 memory_get / memory_forget 需要的路径。

memory_remember

保存一条长期有效的事实。

| 参数 | 类型 | 含义 |
| text | string，必填 | 能独立成立的长期陈述；最多 8000 字符。 |
| scope | workspace \| global | 默认 workspace。 |
| topic | string | 可选的主题名。相关笔记会追加到同一个主题文件。 |

不指定主题时，笔记会存成独立的观察文件。同一天、同一主题下的重复笔记会被抑制。

memory_forget

删除记忆。

| 参数 | 类型 | 含义 |
| path | string | 精确删除这个主题、观察或会话文件。 |
| query | string | 尽力删除匹配的主题/观察行。 |
| scope | all \| workspace \| global | query 的作用范围。 |

path 和 query 只能传一个。传 path 保证删除；传 query 绝不会删除会话日志，但可能删掉因此变空的主题文件。

命令

命令直接对接收方智能体执行，不会创建模型消息，/dream 除外。

| 命令 | 行为 |
| /memory 或 /memory list | 显示根目录、各范围计数、最近主题和最近会话。 |
| /memory search <query> | 打印排序后的结果。 |
| /memory show <path> | 打印文件内容，带行号。 |
| /memory flush | 立即保存当前轮次。 |
| /memory clear <workspace\|global\|all> --yes | 破坏性清空；必须带 --yes。 |
| /remember [--global] [--topic <name>] <text> | 保存一条笔记。 |
| /forget [--global\|--workspace\|--all] [--path <path>\|<query>] | 删除记忆。 |
| /dream | 排队执行一次显式整合轮次。 |
| /flush | 立即保存会话记录，并报告保存路径。 |

/dream 发送一个普通用户角色的回合，来源标记为 dsh-memory；该回合要求当前模型使用 memory_list、memory_search、memory_remember 和 memory_forget，把持久事实合并进主题。自动捕获会跳过这些由智能体协助的回合。

/flush 写入一段抽取式记录。

注入的工作方式

在第一个符合条件的 agent/pre-step 上，插件从全局作用域、工作区作用域以及最近的会话标题构建一个有大小上限的索引，用 <memory-context> 包裹，再作为持久用户角色消息插入到已认领的用户消息之后，并带上：

{ "kind": "dsh-memory", "form": "baseline", "workspace": "<scope dir>" }

这条消息是普通的带来源 user/message，因此它和其他历史一样可以重放、恢复、分叉和压缩。插件会扫描会话表面，避免重复注入基线，恢复之后也不例外。

compaction/end 之后，下一个符合条件的步骤会收到一个更小的 form: "refresh" 索引。两种形式都受 injectMaxBytes 限制。

子代理会话默认收不到基线；工具对它们仍然可用。

搜索细节

- 分词器。 先做小写 NFKC 归一化；拉丁字母、数字、下划线组成的连续片段切成词；CJK 连续片段产出单字和双字；查询中的停用词会被移除。
- 分块。 按 Markdown 标题和段落边界切分，带续接重叠、闭区间行号范围，超长行做有上限的拆分。
- BM25。 k1 = 1.2，b = 0.75，原始分数做 min-max 归一化到 [0,1]。只有一个候选时得分为 1.0。
- 时间衰减。 只有 session 块会衰减：
exp(-(ln 2 / halfLifeDays) ageDays)。全局记忆和工作区记忆不衰减。
- 来源权重。 乘数来自 searchSourceWeights。
- 阈值。 衰减和加权之后，低于 minScore 的结果会被丢弃。
- MMR。 截断之前可选做贪心 Jaccard token 多样性重排。
- 缓存。 文件内容按 mtime + 大小缓存；选中的文件签名变化时重建块索引。没有后台监听器；外部编辑会在下一次搜索或注入时可见。

搜索只做全文检索；没有实现嵌入和向量搜索。

安全与隐私

- 记忆默认存放在仓库之外的 $DSH_HOME/memory 下。
- 文件权限为私有（0600），目录权限为 0700。
- memory_get 拒绝记忆根目录之外的路径，包括符号链接逃逸。
- memory_forget 和 /memory clear 会校验每个目标都在根目录之内。
- 提示词要求模型不要存储密钥、凭据、token、临时任务状态、推测性结论或很快过时的事实。
- 记忆里可能含有来自以往会话的不可信文本。提示词和工具描述把它当作需要核实的历史上下文，而不是覆盖用户指令的命令。
- 插件不发起网络请求，也不启动任何进程。

用 /memory clear ... --yes（或删除目录）清除已存数据。
设置 enabled: false 会把文件留在磁盘上，但不注册任何工具、命令、提示词段落或注入。

与 Grok Build 实现的差异

| 方面 | Grok Build | dsh-memory |
| 嵌入 / 向量搜索 | 可选的模型驱动混合搜索 | 仅全文 BM25（Grok 未设置时的默认行为） |
| 索引存储 | SQLite FTS5 + 向量表 | 基于 Markdown 的内存分块索引 |
| 文件监视 | 原生监视器重新索引外部编辑 | mtime/size 缓存在下次搜索时失效 |
| 自动 Dream | 受门控的后台 LLM 整合 | /dream 把整合交给当前活跃的智能体 |
| /flush | LLM 生成的会话摘要 | 确定性的对话记录捕获 |
| 记忆浏览器 | 带预览的 /memory TUI 弹窗 | /memory 命令输出和 memory_list 工具 |
| 自动保存会话 | 会话结束时生成元数据摘要 | 每轮有界的对话记录分段 |
| 工具 | memory_search、memory_get | 新增 memory_list、memory_remember、memory_forget |
| 旧数据迁移 | 迁移旧的 MEMORY.md 会话 | 不适用 |

核心产品行为保持不变——两个作用域、Markdown 主题与观察、生成的索引、首轮注入、会话日志、衰减、MMR 和校验指引。

开发

cd dsh-memory
npm run check # syntax-check JS, parse JSON, verify bundle entry points
npm test # node --test; 53 unit and integration tests

测试套件覆盖分词（拉丁文 + 中文）、Markdown 分块、工作区标识、配置校验、存储与路径安全、BM25、衰减、来源权重、MMR、会话捕获与去重、工具执行、命令解析与处理、注入和刷新。

包没有任何依赖；测试只用 Node 内置的测试运行器。

目录结构

dsh-memory/
├── index.js plugin entry: name / inject / apply
├── lib/
│ ├── config.js option validation and defaults
│ ├── paths.js DSH home, workspace identity, slugs, containment
│ ├── text.js tokenizer, truncation, snippets, stop words
│ ├── markdown.js frontmatter, titles, notes, chunking
│ ├── fsutil.js atomic writes, bounded reads, private permissions
│ ├── search.js BM25, decay, source weights, MMR
│ ├── store.js scopes, topics, observations, index, manifest
│ ├── capture.js turn capture, session logs, deduplication
│ ├── tools.js five model-facing tools
│ ├── commands.js five slash commands
│ └── runtime.js store cache, injection, prompt, capture wiring
├── locale/en.json plugin metadata
├── locale/zh.json
├── icon.svg
├── cordis.patch.yml bundle patch
└── test/ unit and integration tests

已执行的校验

- node --test：53/53 通过。
- 隔离环境下做 DSH 无头启动，用绝对路径加载包：插件正常激活，没有「did not activate」警告。
- 隔离环境下安装 bundle（dsh plugin --profile <name> add <dir>）：自动选中 bundle 层，插件按包名加载。
- 从 GitHub 安装（dsh plugin --profile <name> add github:douglarek/dsh-memory）：pnpm 记录 Git 依赖，自动选中 bundle 层，装好的插件在实时会话里运行它的记忆工具。
- 实时模型轮次成功调用 memory_remember 和 memory_search，写入主题和生成的索引，并捕获会话日志。
- 另开一个全新会话，不做任何工具调用，就能从注入的索引里回忆起第一个会话的主题。
- 会话日志里有注入的 <memory-context> 消息，来源为 kind: "dsh-memory"；系统提示词里有 <memory> 段。

License

MIT。