记忆桥接 rasyidmmz/dsh-ai-memory

dsh-ai-memory

DeepSeek Harness 与 ai-memory 之间的记忆桥梁。

ai-memory 在 20 多个编码代理之间共享同一份记忆：Claude Code、Codex、Cursor、Gemini CLI、OpenCode 等等都读写同一个 wiki。DSH 此前只能读取它。这个插件让 DSH 也成为一个完整的写入者。

这不是什么

请先读这一部分，因为它决定了这个包是否适合你。

- 它不是 ai-memory。 ai-memory 是由另一位作者开发的独立项目。这个插件不包含它，不捆绑它，也不替代它。
- 它不是 ai-memory 的 fork。 没有共享代码，也没有 git 关系。ai-memory 是用 Rust 编写的；这个插件是一个约 800 行的 JavaScript 单文件，它调用你自己安装的 ai-memory 命令行程序。参见致谢。
- 它与 ai-memory 的作者没有关联，未获其认可，也未受其支持。 它是一个独立的第三方集成。
- 它不捕获任何内容。 它只最终化 ai-memory 已经捕获的会话。捕获来自你单独安装的 DSH hook 接线——参见前置条件。

致谢

这个插件所驱动的记忆引擎完全是他人之作：

akitaonrails/ai-memory —— MIT 许可。一个 Rust 二进制文件，通过生命周期 hook 捕获代理会话，将它们整合成可搜索的 Markdown wiki，并通过 MCP 和 HTTP 将该记忆提供给 20 多个 harness。

此处不包含任何 ai-memory 代码。 这个仓库不包含来自该项目的任何一行代码。它是一个 DSH 侧的适配器，只是调用 ai-memory 二进制文件，仅此而已。如果这个插件对你有用，功劳属于上游——请给他们的仓库点个 star。

跨 harness 的记忆

这是这个插件的核心意义，所以值得精确说明。

ai-memory 建立在这样一个理念之上：记忆应该跟随你，而不是你的编辑器。在任务中途退出 Claude Code，在同一目录中打开 Codex，下一个代理就能接上一份真正的交接。这之所以可行，是因为每个 harness 都写入同一个共享存储，而会话结束时的整合会把原始记录变成下一个代理可以搜索的可读 wiki 页面。

DSH 曾是那个例外。ai-memory 的整合由一个会话结束事件触发，而 DSH 从不触发它——它的会话终止路径通过一个信号退出，该信号根本不发出任何 dispose 事件。因此 DSH 会话作为原始观察记录落入 ai-memory，然后就停在那里：

Claude Code 会话结束 ──► 已整合 ──► wiki 页面 ──► 每个 harness 都可读 DSH 会话结束 ──► 仅原始观察记录 ──► 每个 harness 都不可见

DSH 可以搜索其他代理写入的记忆，但 DSH 所做的任何事情都不会成为其他代理可以读取的记忆。单向的，而且是错误的方向。

这个插件通过触发 DSH 从不触发的最终化步骤来闭合这个循环。有了它安装了：

DSH 会话结束 ──► 此插件 ──► ai-memory finalize-session ──► wiki 页面 │ Claude Code、Codex、Cursor、Gemini CLI、…… ◄────────────┘

一个 DSH 会话变成一页内容，Claude Code 可以检索它，队友的 Codex 可以搜索它，它会出现在下一个 agent 的交接简报中。DSH 不再是共享记忆的只读消费者，而是成为其中的对等写入者。

这就是全部价值所在：不是一个新的记忆系统，而是让一个 harness 正确地加入一个已有的系统。

前置条件

有两件事必须已经正常工作。插件不会替你完成其中任何一件。

1. 一个正在运行的 ai-memory 服务器，且捕获已接入 DSH。

从上游安装 ai-memory，然后接入 DSH 的生命周期钩子，以便捕获事件。ai-memory 自带的 install-hooks 命令不支持 DSH（--agent dsh 会被拒绝），因此钩子文件需要手动编写。一个可用的示例位于 docs/hooks-dsh.json。

在归咎于此插件之前，请先独立验证捕获是否正常：

ai-memory status # sessions and observations should be increasing
ai-memory doctor # inside your project directory

2. 同一台机器上有 ai-memory CLI。

仅此而已。它会自行解析自己的数据目录和服务器 URL，因此默认配置完全不需要任何设置。

如果服务器未运行，此插件会在启动时记录一条清晰的警告，除此之外不做任何事。捕获失败是一个单独的问题，有单独的原因。

安装

dsh plugin --profile web add dsh-ai-memory

从 GitHub 而非 npm 安装：

dsh plugin --profile web add github:rasyidmmz/dsh-ai-memory

之后重启 DSH。加载器导入插件代码时没有使用缓存破坏参数，因此编辑过或新添加的插件在进程重启之前不会被加载。

通过在 harness 日志中搜索 ai-memory 来确认它已加载：

[dsh-ai-memory] active v1.0.3 -- fast path session/disposed (zero idle cost) + ...
[dsh-ai-memory] preflight: ai-memory v2.4.1 | data_dir=... | server=127.0.0.1:49374

preflight 这一行是确认插件找到了与你的钩子正在写入的同一个 ai-memory 的最快方式。

配置

可选。对于标准的 ai-memory 安装，默认值是正确的，而且即使完全没有 config: 块，插件的行为也完全相同。

- insert:
- id: ai-memory
name: dsh-ai-memory
config:
exePath: /usr/local/bin/ai-memory # default: platform standard location
dataDir: /home/me/.local/share/ai-memory # default: let the CLI decide
agentKind: claude-code # default: claude-code
sweep: true # default: true
preflight: true # default: true
timeoutMs: 120000 # default: 120000

| Key | Default | Meaning |
| exePath | Windows：%LOCALAPPDATA%\Programs\ai-memory\ai-memory.exe；其他平台：从 PATH 中查找 ai-memory | ai-memory 可执行文件的路径。 |
| dataDir | 未设置 | ai-memory 数据目录。保持未设置，除非你使用非标准位置；CLI 会自行解析其位置，而钩子使用的正是该位置。 |
| agentKind | claude-code | 记录在 ai-memory 存储中的 agent 类型。请参阅下方说明——这不是可以随意选择的。 |
| sweep | true | 废弃会话安全网。设为 false 可将其完全禁用。 |
| preflight | true | 在启动时记录一行日志，说明找到的 ai-memory 版本、数据目录和服务器。 |
| timeoutMs | 120000 | 每次 finalize-session 的超时时间。 |

为什么 agentKind 应保持为 claude-code

ai-memory 识别一组固定的 agent 类型——claude-code、codex、 cursor、open-code、opencode2、pi、omp、zero、kiro-cli、pool、 zcode——并直接拒绝其他任何值。不存在 dsh 类型。

DSH 通过 Claude Code 钩子桥接到达 ai-memory，因此每个捕获的 DSH 会话都存储为 claude-code。这就是存储中实际包含的内容，而 finalize-session 必须被告知去那里查找。传入其他任何值——包括 CLI 自身的默认值，即 codex——都将永远匹配不到任何会话。

工作原理

两条路径，刻意不对称。

快速路径——一个事件，空闲时零开销

当会话正常关闭时，DSH 会触发 session/disposed。插件监听该事件，推导出会话存储的 UUID，并调用 ai-memory finalize-session。

- 空闲开销：零。 没有定时器、没有查询、不启动任何进程。
- 反应：即时，无需等待计划中的清扫。

它使用 session/disposed 而不是与之同时触发的另外两个事件，因为它是唯一携带完整会话对象的事件，因此工作目录是直接读取的，而不是被缓存或猜测的。

安全网——分层清扫器

DSH 通过 SIGTERM 终止，而 SIGTERM 不会触发任何处置事件。
此时打开的会话永远不会被最终化：它会永远保持打开状态，没有页面。
这不是假设——曾有一个包含 459 条观察的会话就这样被遗留了下来。

因此存在一个不依赖任何事件的清扫器：它直接读取 ai-memory 的存储，并将可证明已死亡的会话最终化。它的调度一开始很密集，然后逐渐放缓—— 25 秒、1 分钟、3 分钟、10 分钟，之后每 30 分钟一次——因为事件唯一会遗漏的情况是被重启废弃的会话，而这恰好发生在 DSH 启动时。

搞错这一点比不做更糟：最终化一个活跃会话会从其一半内容生成一个页面，而该页面永远不会再被更新。因此必须通过全部四项防护：

1. 该会话不在本进程的活跃会话列表中；
2. 其最后一条观察已超过 2 分钟；
3. 其 UUID 为版本 5——仅限主会话，绝不包括子代理；
4. 每次清扫最多处理 10 个会话。
Guard 2 覆盖第二个 DSH 窗口：那是一个独立的进程，因此它的会话在这里不可见，如果没有延迟，它会在写入过程中被关闭。

Guard 3 有一个有用的副作用，如果你在同一个仓库中同时运行 DSH 和真实的 Claude Code 会话，这一点值得了解：ai-memory 将它们存储为版本 4 UUID，因此它们永远不会被这个清理器选中。

设置 sweep: false 可以关闭整个网络；快速路径不受影响。

这解决的七个陷阱

每一个都曾破坏过早期版本，而每一个修复都是关键性的。它们值得列出，因为正是它们导致一个天真的“只需调用 finalize-session”插件无法工作。

1. 会话 id 不是原始 UUID。 DSH id 看起来像 session-，而 ai-memory 将它们存储为派生的 UUID v5。传入原始字符串会被拒绝：invalid uuid: invalid character: found 's' at 1。子代理使用裸 UUID，必须原样传入——两种 id 形态，两种处理方式。
2. 工作目录必须显式指定。 shell 服务默认使用 DSH 进程自身的目录，而不是会话的仓库，因此作用域会解析到错误的项目。
3. 项目名称并不总是文件夹的基名。 钩子以小写形式写入它；CLI 以原始大小写派生它。没有 .ai-memory.toml 标记的仓库只有在小写重试后才能匹配。
4. 不要用 2>&1。 DSH 运行命令时不会重定向 stderr，而在命令内部合并它在那里会失败，以非零状态退出且什么都没做。
5. 子代理检测必须读取会话头，而不是注册表。 代理注册表在宣布其处置之前删除条目，因此注册表查找总是为空——包括主会话。早期版本将其用作过滤器，因此跳过了每个代理，什么都没做，同时也没有记录任何错误。
6. 并发会话结束必须排队，而不是丢弃。 在两个会话打开的情况下关闭 DSH 会连续触发两个处置事件；一个天真的 running 守卫会静默丢弃第二个。
7. SIGTERM 不会触发任何东西——因此有了上面的清理器。

故障排除

所有输出都以 [dsh-ai-memory] 为前缀。在 harness 日志中搜索它。

该前缀故意不是 [ai-memory]：ai-memory 有自己的日志，而相同的前缀会让你无法分辨正在阅读的是谁的行。

| 日志行 | 含义 | 操作 |
| active v1.0.3 ... | 插件已加载 | — |
| preflight: ai-memory vX \| data_dir=... | 找到了服务器 | 确认数据目录与你的钩子匹配 |
| WARNING: ai-memory executable not found | exePath 错误 | 在配置中设置 exePath |
| preflight: the ai-memory server did not answer | 服务器未运行 | 启动 ai-memory |
| sandbox runner is broken (0xC0000142) | DSH 的沙箱运行器在 Electron 下失败；插件已切换到非受限路径 | 参见下面的“沙箱运行器”。会话仍会完成 |
| session ... -> page created | 正常工作 | — |
| session ... -> no open session matched | 已经最终确定，或从未被捕获 | 检查 ai-memory status；如果观测数没有上升，那么问题出在 hooks，而不是这个插件 |
| session ... FAILED | CLI 返回了一个错误 | 消息尾部会被包含在内 |
| sweeper could not read the store | ai-memory 的 schema 发生了变化 | 快速路径仍可工作；只有安全网失效了 |
| sweeper: no abandoned sessions | 正常，大多数清扫都是如此 | — |

如果完全没有输出，说明插件未加载——检查 profile 的 cordis.patch.yml 并重启 DSH。

关于 finalize-session 和 consolidation 的说明。 这个插件调用 finalize-session，它是运行中服务端的一个客户端。它不会调用 LLM，也不会自己写入 wiki 页面；服务端会做这些事。如果页面没有出现，请检查服务端自己的日志。

兼容性

- DSH：针对 DSH Desktop 0.1.7-rc.2 开发和测试（即 @deepseek-ai/dsh-desktop 包），Node 24。

本 README 的早期修订版写的是“DSH Desktop 0.9.1”。那是错的——并不存在这样的 DSH 版本。0.9.1 是从一个无关的 changelog 中读出来的；真实的包版本是 0.1.7-rc.2。

- ai-memory：针对 2.4.1 开发和测试（从 2.4.0 升级， 已端到端验证可正常工作）。这里使用的 finalize-session 标志已在两个版本中验证存在。关于升级改变了什么，请参见下面的兼容性说明。
- 平台：Windows 是经过测试的平台。Linux 和 macOS 的命令构造已实现并经过演练，但作者未端到端运行——请将它们视为未测试。
- 无依赖。 没有 dependencies，没有 peerDependencies，因此没有构建步骤，安装时也不需要 allowBuilds 批准。
- 无工具，无 UI。 该插件不注册任何模型工具，也不绘制任何界面。它只监听并调用外部命令。

ai-memory 2.4.0 → 2.4.1

升级已在作者机器上运行并验证；没有任何东西损坏。存储保留了每个页面、会话和观测，嵌入也有所改善（6 个页面缺失 → 0）。该版本中有两个条目值得在这里了解：

- CRLF 页面再次被正确读取——由 Windows 编辑器保存的页面过去会在加载时丢失其 frontmatter（pinned / expires_at 被静默丢失）。
这在 Windows 上很重要，而 Windows 是经过测试的平台。
- 会话 id 不再按字母大小写拆分——D:\…\Default Project 可能变成两个独立的项目。在受影响的存储上，此版本会将它们合并。

两种 shell API 形态

该插件通过一个辅助函数调用 ctx.shell，该函数接受两种形态：

| Harness | 调用 | 结果 |
| 较旧版本 | shell.run(spec) | { exitCode, stdout, stderr } |
| DSH 0.1.7-rc.2 | shell.execute(spec) | handle，然后 handle.result() |

这是通过能力（typeof ctx.shell.execute）来检测的，绝不通过版本号，因此未来的重命名不会再次悄悄破坏它。这很重要，因为 0.1.7-rc.2 中的 PwshLocalExecutor 仅暴露 execute()：没有那个分支，每次 finalize 都会以 shell.run is not a function 失败——而且由于该失败只会进入日志，看起来像是“插件已加载但什么都没发生”，而不是一个错误。

沙箱运行器

DSH 0.1.7-rc.2 通过 Electron 启动其沙箱运行器，受限的子进程会以 STATUS_DLL_INIT_FAILED（0xC0000142）终止。直接测量，相同命令，正确的 SID：

| 启动器 | 结果 |
| node.exe + runner | exit=0（正常） |
| DeepSeek Harness.exe + runner | exit=3221225794（0xC0000142） |

插件的 ctx.shell 调用不携带会话，因此它们回退到默认的 workspace-write 策略，并且总是走那条损坏的路径。

因此，插件首先尝试正常的、受限的路径，只有在看到 0xC0000142 时才回退，并记住这一切换。一旦 DSH 修复其运行器，finalize 就会恢复为沙箱化，无需在此处做任何更改。

请注意这一权衡： 回退会将 CLI 调用的权限扩大到工作区之外（danger-full-access）。它仅限于 ai-memory finalize-session 调用——而不是 agent 自身的工具——并且插件自身从不写文件。如果在你的环境中这不可接受，请不要在运行器损坏的 harness 上运行它；在 1.0.2 中没有配置开关可以禁用该回退。

如果 ai-memory 发生变化

插件在一处直接读取 ai-memory 的 SQLite 存储，即 sweeper，并且仅用于查找被遗弃的会话。如果未来的 ai-memory 版本更改了该 schema，sweeper 会记录一个错误并停止；快速路径不受影响，因为它完全不使用 SQL。在这种情况下，设置 sweep: false 可将其完全静默。

许可证

MIT——参见 LICENSE。此许可证仅涵盖本插件。
ai-memory 由其自己的作者单独许可（同样是 MIT）。