hj01857655/dsh-context-memory

dsh-context-memory

npm version
npm downloads
CI
license
node
GitHub stars
dsh plugin

为你的 dsh agent 提供跨会话记忆——被记住、被回忆、被重新验证，而非被假定。

安装

dsh plugin --profile web add dsh-context-memory

它的作用

与你的 agent 的每一次会话都从零开始。你昨天的决定、哪条路走不通、你解释过一次的约束——全都消失了，你只能再解释一遍。

这个插件把它们保留下来，并且——不同于一个笔记文件——会重新检查那些可以检查的部分。

- 记住。 一条记忆带有来源信息：哪个会话、哪个步骤、它来自你、agent 还是插件。“agent 为什么认为它知道这件事”是有答案的。
- 回忆。 检索是经过排序的（token 重叠度、新近程度、验证强度），而不是把每条记忆都粘贴进上下文窗口。每次命中都会报告其得分的明细，因此排序从来不是你必须盲目信任的东西。
- 有理由地遗忘。 一条记忆会被取代，而绝不会被删除。错误的记忆是日志中最有价值的记录——它们是唯一能解释过去某个决定的东西。
- 冲突检测。 关于同一主题的两条活跃记忆会被报告为冲突。插件不会选出赢家；日志并没有说明哪一条是对的，而猜测恰恰是这个插件旨在消除的那种没有根据的断言。
- 验证。 一条陈述具有可检查形态的记忆会被编译成一个平台感知的守卫，并按需重新检查。这是笔记文件做不到的部分。

要点

一条记忆是关于世界的一个断言。存储它使它变得可用；但并不会使它变得真实。像“文件 README.md 存在”或“config.json 包含 pnpm”这样的陈述，在你说的那一刻是真的，然后会悄无声息地不再为真。

因此 verify 会把每条可检查的记忆重新变成一个检查并运行它：

dsh-context-memory verify

passed      4f2a9c1b8e30  the file package.json exists
violated    7d1e0a55c9f2  the file README.md contains Installation
无法检查 2b8f31aa0456  我们最终选择了 pnpm，因为 yarn 的 hoisting 破坏了构建
损坏      a91c4e77b0d3  文件 scripts/release.sh 存在

通过 1，违反 1，损坏 1，无法检查 1

四种结果，而它们之间的区别正是关键所在：

| 结果 | 含义 |
|---|---|
| passed | 检查已运行，且记忆成立。 |
| violated | 检查已运行，但现实与记忆不符。 |
| broken | 检查本身无法运行——拼写错误、缺少二进制文件。并非关于记忆的证据。 |
| uncheckable | 无法编译出任何检查。记忆仍被存储和召回；只是未被验证。 |

verify 仅在 violated 时以非零状态退出。损坏的守卫是检查本身的缺陷，
让它把流水线变红，正是拼写错误会把真实记忆标记为假的方式——
此后你就会学会忽略输出。

任何东西都不会因为被存储就被标记为已验证，而且由 agent 提供的记忆
绝不会作为命令执行：守卫来自模板，模板只会插入带引号的文件路径和字面搜索字符串。

CLI

dsh-context-memory remember "the file package.json exists"
dsh-context-memory list
dsh-context-memory recall "how do we install"
dsh-context-memory conflicts
dsh-context-memory forget 4f2a9c1b8e30 "moved to bun"
dsh-context-memory verify        # exit 1 only on a real violation

面板

Settings 中的 Context memory 页面：活跃和已被取代的记忆、每条记忆的验证
状态、冲突以及来源。宿主注册
GET /api/context-memory.panel，并在每次请求时从日志重建载荷，
因此面板显示的是磁盘上的内容，而不是启动时内存中的内容。无头
宿主没有 Web 连接，会直接跳过该路由。

布局

| 路径 | 作用 |
|---|---|
| src/index.ts | 宿主部分——apply(ctx)，暴露 contextMemory 服务 |
| src/memory.ts | 折叠日志、记住、取代、冲突、验证 |
| src/store.ts | 仅追加的 .memory/events.jsonl |
| src/guard.ts | 语句 → 平台感知的检查；运行它；分类为通过 / 违反 / 损坏 |
| src/recall.ts | 带可解释评分的相关性排序 |
| src/identity.ts | Id 由规范化后的主体派生，因此重复项会折叠 |
| src/cli.ts / src/bin.ts | 命令行入口，无需 dsh 即可使用 |
| src/routes.ts | 宿主 Web 连接上的面板和验证路由 |
| src/client/view.tsx | 浏览器部分——纯渲染，在 Node 中静态测试 |
| src/client/index.tsx | 浏览器部分——fetch 和设置注册 |

为什么日志是仅追加的

当前状态始终是对事件的一次折叠，在每次读取时重新计算。
另一种选择——可变存储——会让最后一个写入者决定什么一直为真，而
“agent 在周二相信什么，以及为什么”就变得无法回答。日志就是
证据，因此崩溃后末尾被撕裂的一行会被丢弃（可恢复），而损坏
其他任何地方都会被报告，而不是被跳过。

开发

npm ci
npm run typecheck
npm run build
npm test

许可证

MIT