sANDzER0/dsh-hippocampus

dsh-hippocampus

License: MIT
Platform: DSH web profile

一个面向 DeepSeek Harness（DSH）的自管理跨会话项目记忆层——
将 cortexkit/magic-context 的
捕获 / 巩固 / 召回（Capture / Consolidate / Recall）循环，
重新实现为原生 DSH 插件。

状态：功能完备，并已针对真实工作负载验证。记忆工具、
提示注入、事件驱动的自动捕获、巩固子代理、CJK 分词
关键词搜索、可选语义搜索（本地 Ollama 或 OpenAI 兼容）、
压缩检查点 + 记忆感知的压缩摘要、信号门控的
回顾性捕获流程，以及 DSH Web UI 内的设置页面。

背景

DeepSeek Harness (DSH) 是一个
基于 Cordis 的代理框架：每项能力都是 cordis.yml
组合中的一个插件行，服务/事件/插槽是扩展原语，dsh web
提供 GUI 服务。本项目以单个宿主组合行的形式发布，因此每个预设的每个会话
都能获得该记忆层——无需按会话挂载。

magic-context 是一个出色的记忆
系统，适用于 OpenCode/Pi 风格的框架。本项目是在 DSH 原语上对其理念的
从零开始的原生重新实现——未使用其任何代码。

与 magic-context 的区别

| | magic-context | dsh-hippocampus |
|---|---|---|
| 范围 | 记忆层加上上下文管理（历史学家分区、m[0]/m[1] 缓存稳定变换、字节精确重放） | 仅记忆层——DSH 负责压缩和上下文塑形 |
| 存储 | SQLite（context.db、FTS5、向量 BLOB） | DSH storageDomain JSON 快照（整快照 RMW、序列化写入） |
| 检索 | sqlite-vec / 本地 ONNX / 远程嵌入 | Intl.Segmenter CJK 分词 + 评分排序；可选本地 Ollama 或任何 OpenAI 兼容的 /embeddings；JS 内余弦相似度 |
| 捕获 | 与其分区引擎绑定的历史学家事实提升；dreamer 定时任务 | 正则启发式 + 信号门控的回顾性流程，其子代理通过幂等工具调用写入；压缩前触发插槽 |
| 压缩 | 完全替换宿主的压缩 | 观察并增强 DSH 的原生压缩（检查点捕获 + 记忆感知摘要），而不触碰所有权 |
| 打包 | 多包 monorepo（TS + Rust） | 两个纯 JS 函数体（src/host.js、src/client.js），由一个脚本派生为可部署的 ESM——零构建依赖 |

完整的设计理由——范围边界、流水线细节和平台
实现说明——见 DESIGN.md。

功能

- 持久记忆——ctx_memory（写入 / 列出 / 删除）跨五个精选
类别加上自动管理的 CHECKPOINT 条目；作用域限定为稳定的项目
身份，因此记忆跟随项目，而非会话。
- 召回 — 对记忆和笔记执行 ctx_search：支持 CJK 的 token 评分、
逐字子串强命中、可选的语义余弦相似度，以及当部署启用
session-query-sqlite 时的跨会话历史搜索。
- 提示注入 — 最高重要性的记忆会被渲染进每一轮模型对话
（受数量和字符预算限制）。
- 自动捕获 — 用户消息中的决策/约束措辞以及对
已知配置文件的写入会变成记忆；内容分类器会排除
机器来源的文本（harness 快照、提醒、自身子报告）。
- 回顾式捕获 — /ctx-retro 扫描缓冲的近期用户消息；
纠正/重述信号会派发一个子代理，由其提炼持久事实
并通过幂等的 ctx_memory 调用自行写入。包含定时器和压缩前
触发器，并带有冷却和单飞闩锁。
- Dreamer 整合 — /ctx-dream 生成一个可继续的子代理，由其
去重/整理记忆并回报到会话中。
- 压缩感知 — 压缩摘要会作为可搜索的 CHECKPOINT
记忆（T0）存储，持久记忆会被注入摘要器输入，使
摘要保持连续性感知（T1）。
- 设置页面 — DSH Web 设置中的 Magic Context 部分：语义
搜索开/关、提供商切换（本地 Ollama / OpenAI 兼容端点）、
端点/模型/密钥、Ollama 检测和服务启动、注入预算、
捕获开关 — 全部实时生效（无需重启）。

要求

- 一个带有 web profile 的 DSH 部署（dsh web）。该插件面向
DSH 附带的 Node 运行时（v24 级别）；无需额外依赖。
- 仅语义搜索可选需要：Ollama 以及一个
多语言嵌入模型（ollama pull bge-m3，约 1.2 GB）。没有它，
插件完全以仅关键词模式运行 — 每条失败路径都会静默降级。

部署

node sync.mjs     # derive index.mjs + client.mjs + package manifest into the profile
(~/.dsh/profiles/web/node_modules/@local/dsh-hippocampus/)

然后在同一 profile 的补丁层
（~/.dsh/profiles/web/cordis.patch.yml）中注册一行 insert：

- insert:
- id: dsh-hippocampus
name: '@local/dsh-hippocampus'

并重启 dsh web（ESM 按进程缓存）。sync.mjs 会在写入任何内容之前
校验两部分（node --check + 导入冒烟测试）。

为什么是派生文件？加载器会将这一行作为真正的 ES 模块导入，而
src/host.js / src/client.js 是以普通函数体形式编写的（也可作为
动态插件 code.host / code.client 定义）。切勿直接复制
源码 — 顶层 return 在 ESM 下是致命的。

配置

在 Web UI 中打开 Settings → Magic Context。所有内容都会实时生效：

| 分组 | 旋钮 |
|---|---|
| 语义搜索 | 启用 · 提供方（Ollama / OpenAI 兼容） · 端点 · 模型 · API 密钥 · 连接探测 · 索引重建 |
| 本地 Ollama | 状态检测（可达 / 已安装 / 缺失） · 启动后台服务 |
| 注入与捕获 | 注入次数上限 · 字符预算 · 自动捕获开关 · 回顾自动触发开关 |

设置持久化在 memory 域（mc:cfg）中，并在读取时合并到默认值之上。API 密钥从不出现在 GET 响应中，写入路由仅接受回环对等方。

仓库布局

dsh-hippocampus/
├── DESIGN.md          # 设计文档：范围、流水线、压缩集成、
│                      #   配置模型、DSH 静态插件实现说明
├── src/
│   ├── host.js        # 宿主半部分（纯 JS 函数体）：工具、注入、
│   │                  #   捕获监听器、回顾、/mc-api 桥接、T1 包装
│   └── client.js      # 客户端半部分（纯 JS 函数体）：Magic Context 设置页面
├── sync.mjs           # 为两个半部分派生可部署的 ESM + 包清单；校验
├── package.json
├── LICENSE            # MIT
└── README.md

验证亮点

针对真实工作负载而非模拟进行测试：

- 持久性和幂等写入在进程重启和插件更新后依然有效。
- 一次真实的 /compact 端到端产生了一条检查点记忆；摘要器自身的输出确认了注入的记忆块存在于其输入中。
- 零重叠的改述查询（“怎么发布上线” vs 一条只说过“部署必须经 sync.mjs”的记忆）仅靠语义通道即可召回（相似度 ≈ 0.52）——按构造而言，关键词评分无法触及。
- 机器来源的文本（运行时快照、harness 提醒、子报告）被内容分类器挡在记忆流水线之外——在实时流量中，而不仅仅是在测试中。

注意事项与限制

- 语义搜索每次查询增加一次嵌入调用（bge-m3 在 CPU 上热推理约 6 秒；请求固定 keep_alive: 30m，因此空闲间隔不会重新支付约 41 秒的冷加载）。超时按场景拆分（查询 8 秒 / 探测 60 秒 / 扫描 120 秒）。
- 跨会话历史搜索需要在 profile 补丁层中启用 session-query-sqlite（以 openAt: never 选择加入发布）。
- 拼接进会话的子代理报告按签名和结构进行过滤；新颖的散文式报告仍是理论上的捕获风险——如果真有漏网之鱼，可通过 ctx_memory delete 删除杂散行。
- 对存储域的并发变更必须串行化：JSON 存储持久化整个快照（读-改-写）。本插件中的所有自动写入都经过同一条 promise 链，正是出于这个原因。
- 存储层对域 valueSchema 进行鸭子类型判断（仅调用 .parse/.safeParse），因此插件体不需要 zod 依赖。

许可证

MIT — 见 LICENSE。