FuRongJun-1999/dsh-memory · 上手攻略

  • 仓库：FuRongJun-1999/dsh-memory
  • 链接：https://github.com/FuRongJun-1999/dsh-memory
  • 分类：AI Agent 基础设施 · 长期记忆系统
  • 作者：Tom
  • 更新：2026-09-18

这是什么

dsh-memory（项目内名称：灵枢，Lingshu）是一套面向 AI Agent 的高性能、零幻觉、可审计的长期记忆基础设施，以 MCP stdio server 形态工作，可直接接入 DeepSeek Harness（DSH）、CodeBuddy、ZCode、Codex CLI、Claude Code 等任何支持 MCP 的 AI Agent。

它不是又一个"记忆插件"——官方定位是白箱 AGI 架构探索，底层是一套由"智能论 v3.4"协议驱动的记忆引擎，包含五层正交子系统：

层 位置 系统功能
🧠 灵枢大脑 md_cg/ 元认知：对话沉淀为 md 认知图，写什么/取什么/能否写入全由规则裁决
⚙️ Rust 检索引擎 rust/ 检索内核：零第三方依赖，内嵌多线程，支持库内/进程/评测三种形态
🐝 蜂群运行时 swarm/ 自维持：多进程轮次心跳、Gossip 拓扑、 WAL-HMAC、信任聚合
📜 中文编译器 compiler/ 验证·审计：五环确定性编译链 + 封闭指令集结构性沙箱
⬢ 蜂巢并发引擎 hive/ 自我改进：worker 池原子领取、心跳/超时强杀/crash 恢复

核心卖点：记忆一旦落盘就长期留存（写入须过三道闸门并以 committed 字段确认），零静默淘汰，可复现评测，中文检索 hit@1 达 99.0%（六家横评同口径第一）。

解决什么问题

当前 Agent 的跨会话失忆问题靠"归档"插件修补，但存在三个根本缺陷： 1. 黑箱判断：写不写、记不记由 LLM 决定，存在幻觉写入和静默丢失 2. 不可审计：写入了什么、凭什么写入，无法事后追溯 3. 中文弱：主流记忆系统（GraphRAG、mem0、Letta 等）中文检索普遍低于英文 20pp 以上

灵枢用确定性规则引擎替代 LLM 做记忆读写判断，用纯 md 认知图作为唯一真源，用四层证据防火墙剔除弱证据干扰，全程白箱可查。

快速安装

⚠️ 以下为 DSH（DeepSeek Harness）宿主安装步骤；CodeBuddy / ZCode / Codex CLI / Claude Code 用户参考 README 中"多 harness 接入"章节。

前置要求： - Node.js ≥ 22.19 - DSH 内核 ≥ 0.1.2-rc.1（⚠️ 注意：旧版 0.1.1-rc.2 不兼容，必须升级或降级到 0.4.2） - pnpm（npm i -g pnpm）

# ① 克隆并构建插件本体
git clone https://github.com/FuRongJun-1999/dsh-memory.git
cd dsh-memory
npm install && npm run build    # tsc → lib/

# ② 装进 DSH profile（⚠️ 必须用 dsh plugin add，禁止裸 npm install）
dsh plugin --profile web add .

# ③ 在 <profile>/cordis.yml 启用（配置示例见 dsh/cordis.yml.example）
# 手动追加以下内容：

# cordis.yml 中添加：
plugins:
  - id: lingshu-memory
    name: '@furongjun1999/dsh-memory'
    config:
      mdcg:
        root: 'data/mdcg'      # 记忆唯一真源（md 认知图）
        identity: '灵枢'
        tools: 'core'          # 'core'(默认, 仅 cg/stg) | 'brain' | 'all'

⚠️ 重要：profile config override 依赖（2026-09-04 确认）：插件包内 cordis.patch.yml 只有裸 insert（无 config），完整 config 全靠 profile 层的 cordis.patch.yml override 补全。换 profile、重装 profile 或升级插件时，必须确认该 override 仍在 <profile>/cordis.patch.yml，否则插件以默认配置运行（记忆真源错位、tools 回落 core 只剩两基元）。

装后验证

重启 DSH，对 Agent 说"列出你的记忆工具"，应看到 cg / stg（tools: 'all' 时还有 mdcg_*）。

大脑直连验证（独立 MCP 测试）：

python -m md_cg.mcp_server
# 收到 initialize JSON-RPC 应答即正常

核心用法

安装完成后，在 DSH 中直接对话即可，记忆钩子自动挂载：

你说 背后发生什么
"请记住：我们团队发布窗口是每周三" 自动记忆钩子 → cg(op=write) 过三道闸门 → 认知图节点落盘
（新会话）"我们的发布窗口是哪天？" mdcg_recall 检索命中并带入回答
"把上次定的接口约定讲一遍" cg(op=route) 条件路由 + stg(op=timeline) 时间线回溯，跨会话取出

手动调用工具（tools: 'brain' 或 'all' 时）：

# 写入记忆
cg(op=write, content="重要信息内容")

# 召回记忆
cg(op=recall, query="要找什么")

# 条件路由（白箱优先）
cg(op=route, query="用户问的是哪个方面")

# 元认知（认知校准）
cg(op=metacognition)

# 时间线回溯
stg(op=timeline, time_range="过去一周")

# 遗忘（显式触发）
cg(op=forget, memory_id="节点ID")

典型适用场景

  • 多会话 AI 编程：在 DSH/Claude Code 中跨会话记住项目上下文、团队规范、接口约定
  • AI Agent 开发调试：白箱记忆引擎让开发者可逐条审阅"记忆凭什么写入"，用于调试和审计
  • 多智能体协作：同一份 md 认知图被多个 Agent 共享（--serve 进程实例支撑多智能体并发）
  • 中文场景优先：需要高质量中文记忆召回（hit@1 99.0%，六家横评中文第一）
  • 白箱合规需求：记忆写入可审计、规则可解释，不接受 LLM 黑箱决定写入内容的场景

坑与注意

⚠️ 以下为已知限制：

  1. 写入凭据默认关闭：不配置写入凭据时以只读 guest 运行（读得到、写不进）；写入凭据配置见 README 详细版"写入凭据"章节
  2. DSH 内核版本硬性要求：必须 ≥ 0.1.2-rc.1；旧版 0.1.1-rc.2 不兼容，插件加载会失败
  3. profile override 丢失风险：每次升级插件或换 profile 后，必须确认 cordis.patch.yml 中 config override 仍存在
  4. macOS 兼容性：⚠️ 蜂群运行时（swarm/）路径仅有逐步稳定性声明，macOS 上可能存在并发/崩溃恢复路径的未知平台差异，建议按 README 所述开 Issue 并附 hive_doctor 输出
  5. 首次记忆库为空正常：全新安装后第一次对话召回返回空结果属正常现象
  6. 中文检索横评说明：六家中文横评 hit@1 99.0% 是在零干扰 gold 证据上界对照集（locomo-zh-500）上测得；英文侧由 Letta 归档直插（73.0%）和纯向量 RAG（71.0%）领跑，灵枢英文 54.0%（词法+meta）和 37.0%（四路融合）不代表端到端能力上限

与同类对比

系统 中文 hit@1 英文 hit@1 架构特点 记忆形态
灵枢（词法+meta） 99.0% 54.0% 白箱规则引擎 md 认知图
灵枢（四路融合） 81.0% 37.0% 条件桶+实体路+词法+融合 md 认知图
纯向量 RAG 97.0% 71.0% embedding 向量相似 向量数据库
Letta（归档直插） 96.0% 73.0% 归档直插向量库 SQLite
mem0 89.0% 68.0% LLM 层记忆管理 层级向量
GraphRAG 31.0% 18.0% 图索引+全局搜索 图数据库
Graphiti 58.0% 46.0% 时序图谱 Neo4j 类

核心差异：灵枢是唯一把"写入规则"完全交给确定性引擎（而非 LLM）的记忆系统，且中文检索性能显著优于所有已知竞品。代价是生态绑定 DSH/MCP，蜂群层仍在逐步稳定中。

一句话结论

在 DSH/Claude Code 等 MCP Agent 上需要跨会话中文记忆能力的开发者，灵枢是当前中文检索最强的白箱方案——零幻觉、零静默淘汰、全链路可审计；但需要 ≥Node 22.19 和 DSH ≥0.1.2-rc.1，且 macOS 蜂群并发层仍在 alpha 阶段。