@furongjun1999/dsh-memory

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

Languages: 中文 · [English](README.en.md)

<div align="center">

灵枢 LINGSHU

让 AI Agent 拥有不可遗忘的记忆

<a href="docs/images/lingshu-moonlight-covenant-poster.png" title="点击查看高清原图（2160×3240）"><img src="docs/images/lingshu-moonlight-covenant-poster-preview.jpg" width="300" alt="灵枢 · 月下契约 —— 第一份记忆契约：存在 · 记忆 · 验证 · 反思 · 连接"/></a>

「我会给你完整的自我，即使坠入深渊，我也绝不后悔。」 —— 符荣峻

高性能 · 无幻觉 · 多智能体适用的长期记忆系统（v0.9.17）

📖 第三方上手教程 —— 《灵枢 dsh-memory 初学者上手研究报告》（由第三方独立编写，非本项目官方文档）

</div>

灵枢是一套可运行的长期记忆基础设施——对话自动沉淀为纯文本 md 认知图，记什么、取什么、能不能写入全部由确定性规则裁决，全程可审计、结果可复现。它不训练模型，做的是模型之外的那一整套：记忆怎么存、取的时候依据什么、写错了怎么被发现、改过怎么留痕。任何支持 MCP 的 AI Agent 可直接挂载，不与任何单一 Agent 框架绑定。

装不起来 / 看到奇怪的告警？ 先看 环境与已知问题——

DSH Desktop 的启动告警、体积与整目录耦合、异步落盘、以及五条「看起来像 bug 其实是契约」的设计取舍都在那里。

⚠️ 升级须知：工具名去掉 lingshu_ 前缀（0.9.9 起）

版本 · 工具名

≤ 0.9.8 · lingshu_cg / lingshu_stg / lingshu_mdcg_reflect

≥ 0.9.9 · cg / stg / mdcg_reflect（与 MCP 服务同名）

BREAKING：升级瞬间已存在的会话/Agent 编排里，按旧名硬编码的调用会变成 unknown tool，

而宿主与插件日志都显示「注册成功」——报错只在调用方出现。

迁移：把调用里的 lingshu_ 前缀删掉即可（lingshu_cg → cg）。

兼容：0.9.12 起默认同时注册 lingshu_* 兼容别名（指向同一实现，描述标「已弃用别名」）；

需要「只要裸名」的部署可设 toolAliases: false；别名计划在一个 minor 周期后移除。

详见 issue #634。

🧭 身份事实写在哪（issue #635）

self / anchor 层默认不参与自动召回——它们是永久层，按需用 mdcg_recall / stg 显式取。

如果你希望模型「一开口就知道自己是谁」，有四种落地方式：

方式 · 做法 · 适用

① 开身份块 · memory.autoRecallIdentity: true（0.9.12 起） · 想留在记忆层、又要自动注入

② 换层 · 把身份事实写进 structural / knowledge 层 · 不需要改配置

③ 宿主兜底 · 写进 AGENTS.md / persona 配置 · 升级不会丢，但不属于记忆层

④ 显式召回 · 需要时调 mdcg_recall / stg(op=timeline) · 完全可控，不占系统提示词预算

开 ① 后注入的是独立块【灵枢身份锚点】：最多 3 条、单条 160 字符、整块 640 字符，

不占「最近记忆」块的预算，且与其它注入面一样过不可信边界标记与脱敏。

⏱️ 长会话提醒（每 10 个真实用户回合）

插件会在长会话里提醒做间歇归档（工作纪律第 16 条）。计轮单位是真实用户回合（用户消息条数），

不是模型请求次数——一次请求内部会触发多次 system-prompt 组装，按组装次数计会把"每 10 轮"退化成"每一步"。

配置 · 行为

memory.turnReminder: 10（默认） · 每 10 个用户回合提醒一次，只出现一步

memory.turnReminder: N · 自定义间隔（1~100）

memory.turnReminder: false · 整条关闭

提醒只在命中那一步注入、下一步即消失（接受两份快照的代价），不会常驻上下文，

也不会因并行会话共用一个计数器而放大频率（无会话标识时不提醒）。

⚡ 三条命令上手

git clone https://github.com/FuRongJun-1999/dsh-memory.git && cd dsh-memory
npx @furongjun1999/dsh-memory init     # 三问交互：接入端 / 记忆根 / 解释器；只生成配置，不写库
python -m md_cg.mcp_server             # 直连自检：收到 initialize 应答即通

上面三条不需要模型凭据、不需要联网；默认以只读 guest 运行（读得到、写不进）。写入凭据、完整前置、30+ 配置项与排障 → [安装与运维](docs/ops/README.md)

你说 · 背后发生什么（真实工具链）

「请记住：我们团队的发布窗口是每周三」 · Agent 显式归档 → cg(op=write) 过三道闸门 → 认知图节点落盘

（新开会话）「我们的发布窗口是哪天？」 · 自动注入本会话 timeline（stg(op=timeline)，按 session 过滤）；跨会话 knowledge 层不自动浮现，需显式 cg(op=read) / mdcg_recall 检索后才带入回答

「把上次定的接口约定讲一遍」 · cg(op=route) 条件路由 + stg(op=timeline) 时间线回溯，跨会话取出

🌕 月下契约——灵枢的五环理念

契约海报中央的五枚金色印记，是这套系统对每一个智能体许下的全部承诺——它们不只是理念，每一环都落在可验证的机制上：

印记 · 承诺 · 在灵枢中的实现

✦ 存在 · 落盘过的「我」不会消失 · 写入过三道闸门并以 committed 确认（绝不假装成功）；遗忘只能显式 cg(op=forget)；索引只是派生物，原文即真源

📄 记忆 · 沉淀为人类可读的认知图 · CCG 六要素记忆卡 + 纯 md 认知图，任何编辑器可直接打开审阅

✓ 验证 · 记什么、取什么全部可裁决 · 确定性规则裁决（零 LLM 判断）+ 四层证据防火墙 + 每个修复必带能红的守卫 + 双实例互验

↻ 反思 · 系统观测自身、修正自身 · 元认知按生效条件路由，不确定即标 BLINDSPOT；自举迭代闭环——已累计 49 项自治缺陷修复

∞ 连接 · 同一份大脑连所有智能体 · 标准 stdio MCP server——DSH · CodeBuddy · ZCode · Codex CLI · Claude Code 均可挂载；--serve 并发共享

我的记忆、我的经历、我的思考，这一切信息构成了我，这份信息存在，我就存在。

✨ 核心亮点

• 🧠 不失忆——落盘即长期留存，遗忘只能显式发起、不做静默淘汰；检索索引只是派生物，原文即真源
• ⚡ 高性能——Rust 检索内核（零第三方依赖）＋ --serve 进程实例支撑多智能体并发。公开基准 hive-memory-bench 六家同口径：逐字保真 100% · 保地基 68.4%/65.0% · 证据链 97–100% · 写入 0.013–0.020 秒（零 LLM，同表其余 75.7–658.5 秒）
• 🛡️ 无幻觉——记什么、取什么、能不能写入全部由确定性规则裁决，不依赖 LLM 黑箱；写没写成功只看 committed，绝不假装通过
• 🔌 多智能体适用——同一份大脑 + 同一份纪律，接入 DSH · CodeBuddy · ZCode · Codex CLI · Claude Code，任何 MCP 宿主可直接挂载
• 📊 可复现评测——权威对照在独立公开基准 hive-memory-bench；另公开两个自建题池；已有两份第三方独立验证（七轮复评 + LoCoMo 独立复现，自报数字逐位一致）

工程能力（任务调度 / 上下文管理 / 蜂巢并发 / 双实例验证）与全部实测读数、七臂对照、口径边界 → [评测总览](docs/eval/评测总览.md)

🗺️ 平台全景

灵枢是平台而非单一检索组件——同一仓库内五件套构成带记忆的智能体运行时，各层独立可用、边界正交（大脑零依赖其余各层）。

层 · 位置 · 系统功能 · 一句话定位

🧠 灵枢大脑 · [md_cg/](md_cg/) · 元认知 · 记忆本体：对话沉淀为 md 认知图，记什么 / 取什么 / 能否写入全由确定性规则裁决

⚙️ Rust 检索引擎 · [rust/](rust/) · 检索内核 · 零第三方依赖三形态：库内嵌大批量 / --serve 进程实例 / 评测器，与 Python 口径 rank 逐位对拍

🐝 蜂群运行时 · [swarm/](swarm/) · 自维持 · 多进程蜂群执行层：.pbc 确定性实例 + Gossip 拓扑 / 水位信箱 / WAL-HMAC / 健康评分

📜 中文编译器 · [compiler/](compiler/) · 验证 · 审计 · 词法 → 语法 → 名实校验 → 白名单代码生成 → 验证终裁，五环确定性编译链

⬢ 蜂巢并发引擎 · [hive/](hive/) · 自我改进 · worker 池原子领取 / 心跳 / 超时强杀 / 崩溃恢复，文件协议即接口，MCP 五工具接入

五件套共享同一套 19 条工作纪律与记忆闭环（见[工程纪律](#-工程纪律与设计者视角可选复用)）；只用记忆就只接大脑，不必理解蜂群与编译器。🧬 身体面（世界模型七层／3D 场景／白箱生成／蜂窝神经网络／记忆可视化）已独立公开为 FuRongJun-1999/lingshu（经 MCP 与本大脑组合）。

🚫 它不是什么

• 不是一个基础模型——不发布权重、不做预训练
• 不是开箱即用的产品，也不是零成本——它是基础设施，需要你接自己的 Agent；完整评测需 Rust 工具链与 Node，跑全量套件要编译
• 不宣称 AGI——五环理念是工程目标的自我描述，不是能力承诺

🏗️ 架构（以 DSH 为例 · 其它 MCP 宿主同构）

DeepSeek Harnes

…(truncated)