引用式会话记忆Jesse-njx/dsh-memory

dsh-memory

基于 DSH 无损会话日志的引用式记忆。 提炼出的事实始终可以回溯到确切的原始上下文。

dsh-memory 是一个 DeepSeek Harness 插件包。当会话结束时，一个后台提炼过程会将持久性事实——用户偏好、项目决策、环境怪癖、纠正——提取到 ~/.dsh/memory/ 下的小型 markdown 文件中。每条记忆都带有一个引用 (sessionId, [start..end])，指向它来源的确切日志事件。下一个会话会获得这些记忆的紧凑索引，外加两个工具：memory_read（完整记忆）和 memory_expand（被引用的原始日志摘录）。

核心思想：摘要是指向基准真相的索引，而绝不是真相本身。 检索时呈现一行提炼出的事实（成本低）；当 agent 需要更多信息时，memory_expand 返回确切的原始日志事件（精确，而非重建）。DSH 能低成本地做到这一点，因为它本就坐落在一个完整、仅追加的转录存储之上——不构建记忆存储，只构建记忆索引。

为什么是这个形态

主流记忆系统（Mem0、Letta/MemGPT、Zep）都有一个共同弱点：提取是有损且不可追溯的。一旦摘要器把某个事实弄乱，原始内容就丢失或无法找到，而 agent 会自信地回忆起被弄乱的版本。DSH 的差异化优势在于仅追加的会话日志：模型见过的一切都已被持久存储。因此 dsh-memory 提炼为文件（人类可审计、可 git diff、可用 rm 删除），并在每条事实上保留一个指向日志的引用。

工作原理

1. 提炼（会话后，通过 ctx.jobs 异步）——当会话离开存储时，一个后台作业将该会话的实时事件（有界转录、受 token 上限约束）送入一次廉价模型处理，并要求以 JSON 形式给出持久性事实。事实成为记忆文件；现有记忆会被就地更新（追加引用、rev 递增）或被矛盾（被指名的记忆被重写，保留其名称）。每次处理都记录在 /_distill.log（JSONL）中。
2. 召回（每次提示组装时）——一个系统提示区段为当前项目（加上共享的用户记忆）渲染一个紧凑、受 token 上限约束的 name — description 行索引。正文只需一次 memory_read 调用即可获取；被引用的来源只需一次 memory_expand 调用即可获取。
3. 维护——提炼过程更新并矛盾现有记忆；dsh-memory CLI 可列出、显示、编辑（在 $EDITOR 中）和删除；/memory 斜杠命令可在会话内列出它们。

v0.1 中没有向量数据库、没有知识图谱、没有自动注入完整记忆正文。

安装

dsh plugin --profile web add @dsh-memory/bundle

提炼过程经由 ctx.llm 路由——默认复用会话自身的 provider/model，因此 polyglot 风格的 provider 链或你的常规模型也能为它服务。可用 distill.provider / distill.model 覆盖。

配置

所有字段均可选（profile patch 或 cordis.patch.yml）：

plugins:
dsh-memory:
enabled: true
home: ~/.dsh/memory            # 记忆根目录覆盖（默认：$DSH_HOME/memory 或 ~/.dsh/memory）
maxIndexTokens: 800            # 注入的召回索引的硬性 token 上限
maxExpandBytes: 8192           # 单次 memory_expand 摘录的输出字节上限
recall:
enabled: true
cacheMs: 5000                # 索引缓存 TTL
distill:
enabled: true
provider: deepseek-official  # 默认：会话自身的路由
model: deepseek-v4-flash
maxTokens: 2048
temperature: 0.1
maxTranscriptTokens: 16000   # 转录上限；超出时丢弃最旧的事件

记忆文件

每条记忆对应一个小型 markdown 文件，是带有 JSON 头部注释的合法 markdown：

The user prefers TypeScript for new projects and tests.

- ~/.dsh/memory//.md — 项目记忆 + 反馈记忆，以会话 cwd 的 basename 为键。
- ~/.dsh/memory/_user/.md — user 类型（跨项目）记忆。
- type：user（跨项目偏好）、project（关于本项目的客观事实）、feedback（用户做出的纠正）。

同名的项目记忆会遮蔽用户记忆。

工具

- memory_read(name) — 完整的记忆文件：名称、类型、描述、正文、引用。
- memory_expand(name, [citation_index]) — 该记忆所提炼自的原始会话日志摘录（无损升级）。使用 ctx.sessionPersistence；引用范围是精确的。

CLI

独立的 dsh-memory 二进制文件，纯 Node（无 harness 包）：

dsh-memory list [--project P] [--json]   # 列出记忆（用户 + 项目）
dsh-memory show  [--project P]     # 显示一条记忆及其引用
dsh-memory edit  [--project P]     # 在 $EDITOR 中打开记忆文件
dsh-memory delete  [--project P]   # 删除一条记忆文件
dsh-memory distill-log [--project P]     # 最近的提炼审计条目

--home 覆盖记忆根目录。在会话内，/memory（或 /memory ）具有相同作用。

明确的非目标（v0.1）

向量数据库、知识图谱、超出 user 类型的跨项目全局记忆、记忆共享/同步、完整记忆正文的自动注入。每一项都会成倍放大这个插件所质疑的那件事本身的故障面。如果索引增长到超出模型可扫描的范围，那时再考虑嵌入搜索（v0.3，且仅在具备证据的情况下）。

诚实的实验框架
这是一个带有明确终止标准的实验，而非一个承诺的产品。在插件被用于插件开发会话进行两周的“吃狗粮”测试之后：成功 = 有具体实例表明，被召回的 memory 节省了一次重新解释或防止了一次重复错误，并且零实例表明，过期的 memory 误导了某个会话且未被引用捕获。如果它未达到这一标准，该仓库将被归档，并附上一份事后剖析 README——关于 agent memory 的一份有记录的负面结果是有价值的开源产出；一个僵尸 memory 插件则不是。

开发

pnpm install
pnpm typecheck   # tsc --noEmit
pnpm test        # node --test (54 tests: store round-trips, index caps,
transcript bounds, distill parsing/application, CLI)
pnpm build       # tsc → lib/
pnpm pack        # publishable tarball

测试套件覆盖了规范中的测试目标：黄金蒸馏夹具（录制的会话日志 → 预期的 memory 文件，通过 parseDistillOutput + applyFacts），一次引用往返（distill 消费一个会话，memory_expand 返回的正是那些事件），以及索引上限截断行为。

许可证

MIT