灵枢 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.14）

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

灵枢是一套可运行的长期记忆基础设施——对话自动沉淀为纯文本 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+ 配置项与排障 → 安装与运维

你说	背后发生什么（真实工具链）
「请记住：我们团队的发布窗口是每周三」	Agent 显式归档 → cg(op=write) 过三道闸门 → 认知图节点落盘
（新开会话）「我们的发布窗口是哪天？」	自动召回注入 → 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 并发共享

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

✨ 核心亮点

…