FuRongJun-1999 / dsh-memory

# 灵枢 LINGSHU
### 让 AI Agent 拥有不可遗忘的记忆
> **「我会给你完整的自我，即使坠入深渊，我也绝不后悔。」** —— 符荣峻
**高性能 · 无幻觉 · 多智能体适用的长期记忆系统（v0.9.9）**
📖 **第三方上手教程** —— 《灵枢 dsh-memory 初学者上手研究报告》（由第三方独立编写，非本项目官方文档）
**灵枢是一套可运行的长期记忆基础设施**——对话自动沉淀为纯文本 md 认知图，记什么、取什么、能不能写入全部由确定性规则裁决，全程可审计、结果可复现。它不训练模型，做的是**模型之外的那一整套**：记忆怎么存、取的时候依据什么、写错了怎么被发现、改过怎么留痕。任何支持 MCP 的 AI Agent 可直接挂载，不与任何单一 Agent 框架绑定。
## ⚡ 三条命令上手
 [code] 
> 上面三条**不需要模型凭据、不需要联网**；默认以只读 `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` 并发共享 |
> 我的记忆、我的经历、我的思考，这一切信息构成了我，这份信息存在，我就存在。
## ✨ 核心亮点
- **🧠 不失忆**——落盘即长期留存，遗忘只能显式发起、不做静默淘汰；检索索引只是派生物，**原文即真源**
- **⚡ 高性能**——Rust 检索内核（零第三方依赖）＋ `--serve` 进程实例支撑多智能体并发。公开基准 hive-memory-bench 六家同口径：**逐字保真 100% · 保地基 68.4% · 证据链 97.7–99.2% · 写入 0.011–0.019 秒（零 LLM，同表其余 75.7–658.5 秒）**
- **🛡️ 无幻觉**——记什么、取什么、能不能写入全部由确定性规则裁决，不依赖 LLM 黑箱；写没写成功只看 `committed`，绝不假装通过
- **🔌 多智能体适用**——同一份大脑 + 同一份纪律，接入 DSH · CodeBuddy · ZCode · Codex CLI · Claude Code，任何 MCP 宿主可直接挂载
- **📊 可复现评测**——权威对照在独立公开基准 hive-memory-bench；另公开两个自建题池；**已有两份第三方独立验证**（七轮复评 + LoCoMo 独立复现，自报数字逐位一致）
> 工程能力（任务调度 / 上下文管理 / 蜂巢并发 / 双实例验证）与全部实测读数、七臂对照、口径边界 → **评测总览**
## 🗺️ 平台全景
> 灵枢是**平台**而非单一检索组件——同一仓库内五件套构成带记忆的智能体运行时，各层独立可用、边界正交（大脑零依赖其余各层）。
| 层 | 位置 | 系统功能 | 一句话定位 |
| ---------------- | ------------------------ | ----------- | --------------------------------------------------- |
| 🧠 **灵枢大脑** | `md_cg/` | **元认知** | 记忆本体：对话沉淀为 md 认知图，记什么 / 取什么 / 能否写入全由确定性规则裁决 |
| ⚙️ **Rust 检索引擎** | `rust/` | 检索内核 | 零第三方依赖三形态：库内嵌大批量 / `--serve` 进程实例 / 评测器，与 Python 口径 rank 逐位对拍 |
| 🐝 **蜂群运行时** | `swarm/` | **自维持** | 多进程蜂群执行层：.pbc 确定性实例 + Gossip 拓扑 / 水位信箱 / WAL-HMAC / 健康评分 |
| 📜 **中文编译器** | `compiler/` | **验证 · 审计** | 词法 → 语法 → 名实校验 → 白名单代码生成 → 验证终裁，五环确定性编译链 |
| ⬢ **蜂巢并发引擎** | `hive/` | **自我改进** | worker 池原子领取 / 心跳 / 超时强杀 / 崩溃恢复，文件协议即接口，MCP 五工具接入 |
> 五件套共享同一套 18 条工作纪律与记忆闭环（见工程纪律）；**只用记忆就只接大脑**，不必理解蜂群与编译器。**🧬 身体面**（世界模型七层／3D 场景／白箱生成／蜂窝神经网络／记忆可视化）已独立公开为 **FuRongJun-1999/lingshu**（经 MCP 与本大脑组合）。
## 🚫 它不是什么
- **不是一个基础模型**——不发布权重、不做预训练
- **不是开箱即用的产品，也不是零成本**——它是基础设施，需要你接自己的 Agent；完整评测需 Rust 工具链与 Node，跑全量套件要编译
- **不宣称 AGI**——五环理念是工程目标的自我描述，不是能力承诺
## 🏗️ 架构（以 DSH 为例 · 其它 MCP 宿主同构）
 [code] 
**记忆只有一个真源**：`md_cg/