内容
# 中Mem知识库存储与LLM维基路由器
自包含的 **LLM维基中间层**：单一知识真相来源，混合检索（词汇 + 向量），分层内存，类型化知识图谱，声明出处，**关闭故障治理**，以及通过 **模型上下文协议（MCP）**、命令行界面（CLI）和编程API向LLM代理暴露的Obsidian投影。
它是AI代理与其知识之间的代理：代理通过路由器`摄取`、`查询`和`记忆`；知识库位于其后。对于OpenClaw + Hermes双栈构建，但核心纯净且模块化 - 它通过三种表面（CLI，MCP和`bin/hook.mjs`预/后转缝）以**4种模式**（独立策划 · OpenClaw插件 · Hermes插件 · 桥接）运行。参见 [集成](#integration) + `docs/INTEGRATION-MODES.md`。
> **状态（2026-07-02）：** 基础 + 跨代理范围 + 原生→中间层桥接 + 检索升级（信任，三元组，令牌预算，图增强，维度守护）+ 可选Qdrant向量后端 + 交接内存门 + 自主生命周期（衰减/使用赚取的晋升/自动投影）+ 无触发器`主动回忆`+ DELEGATE-52提取接地 + **带有确定性自动摄取和分类的工作内存事件**（大脑适应）+ **P4时间/工作流排名提升** + **P5概念节点嵌入，社区和查询路由** + **P6声明取代/矛盾/当前（）** + **P7离线大脑式基准** + **概念规范化（大小写/复数重复，策划`合并概念`，别名感知检索）** + **保险库投影修剪（删除过时页面;不区分大小写的共享安全slug）** + **真实路径摄取保护** + **日志/审计/向量保留**。测试：烟雾 **90/90** + 绿色基准（`npm run verify`）。可在节点上运行，**零外部依赖**（仅需节点≥22.13内置模块：`node:sqlite`，`crypto`，`fetch`）。`packages/core/`是唯一的软件包 - 活跃的，自包含的基础（已删除过时的中间脚手架;如果需要，它仍然在git历史记录中）。
---
## 为什么
单一的始终加载的内存文件无法扩展 - 它占用了每个回合的上下文窗口。这种中间层将 **容量** 与每回合上下文分开：代理持有微小的规范索引，并在需要时通过混合检索从无边界的共享存储中拉取相关切片。
## 架构
```mermaid
flowchart TB
src([来源]) -->|摄取| extract["LLM提取 — 概念 · 声明 · 嵌入<br/>(确定性离线备用)"]
extract -->|事务写入| DB[("state.db — 单一真相来源<br/>条目 · entries_fts（FTS5/BM25）· 向量<br/>节点 · 边 · 声明 · 日志")]
DB -->|"项目（LLM拥有）"| vault[["Obsidian保险库（投影）"]]
verify["验证（确定性，一个图）"] -->|"一致性检查"| DB
DB <-->|"查询：FTS5⊕三元组⊕向量（RRF）+信任/图提升"| mcp{{"MCP服务器（21种工具）· CLI · 钩子缝隙"}}
mcp <--> oc["OpenClaw<br/>(日常驱动器)"]
mcp <--> hz["Hermes代理<br/>(构建工作马)"]
mcp <--> cc["Claude Code<br/>(前沿编织器)"]
cc -->|"计划 · 问答 · 通过看板/ACP驱动"| hz
skills["中Mem技能库（Claude Code）<br/>midmem-dev · midmem-orchestrator<br/>midmem-ingest-review · midmem-record"] -.->|装备| cc
```
三个消费者共享一个`state.db`，通过相同的MCP/CLI/钩子表面。**Claude Code**是前沿编织叠加层：它驱动Hermes（计划→调度构建→QA）和持久记录 - 由**中Mem技能库**装备，该技能库在[`skills/`](skills/)中提供。
- **`state.db` 是真相来源**; markdown保险库是其确定性投影。
- **混合检索**：SQLite FTS5/BM25（令牌词汇）⊕ FTS5-三元组（子字符串词汇）⊕向量余弦（语义），通过互惠排名融合，加上信任+图参考链提升和可选的令牌预算。向量是增量的 - 词汇检索独立工作。
- **向量后端可插拔**：`sqlite`（在DB中JSON余弦，零依赖，默认）或`qdrant`（外部近似邻近搜索索引）。持有ID→向量; `state.db`保存元数据。
- **层级**：`fact`（原始，7天TTL）→ `memory`（综合，30天）→ `wisdom`（策划，无限），具有信任评分。
- **范围**：每个条目都是`openclaw` | `hermes` | `shared` — 私有工作内存 + 共享公共空间。
- **交接门（“firstware”）**：将内存简介推送到代理交接中，以便接收者不会忽略它。
---
## 抽象层
中间层由可交换的层组成。**必需**层必须存在才能作为LLM维基中间层功能; **推荐**层添加功能，是安全的，可以延迟。
| 层 | 模块 | 必需？ | 目的 | 交换/配置 |
|---|---|---|---|---|
| **集成/传输** | `bin/mcp-server.mjs`（MCP标准输入/输出）· `bin/cli.mjs` · `src/orchestrator.mjs`（API） | **必需** | 代理交互的契约。MCP是主要的; CLI + API是替代品。 | 按堆栈注册（如下） |
| **存储** | `src/db.mjs`（`state.db`） | **必需** | 真相的单一来源 + 统一索引。 | `MIDMEM_DB_PATH`; 移动到共享路径/NAS |
| **检索** | `src/retrieval.mjs` | **必需** | 混合FTS5 ⊕ 三元组 ⊕ 向量（RRF）+ 信任/图提升 + 令牌预算。 | `fusionWeights`，`rrfK`，`trustWeight` |
| **向量存储** | `src/vectorstore.mjs` | **必需** | 可插拔的近似邻近搜索索引：`sqlite`（默认）\| `qdrant`。持有ID→向量; `state.db`保存元数据。 | `MIDMEM_VECTOR_BACKEND`，`MIDMEM_QDRANT_URL` |
| **嵌入** | `src/embeddings.mjs` | **必需\*** | 语义通道的向量 + 维度守护。*如果没有模型，则确定性备用。* | `MIDMEM_EMBED_MODEL`，`MIDMEM_LLM_ENDPOINT` |
| **治理** | `src/governance.mjs` | **必需** | 每次变异的关闭策略门控。 | 扩展`defaultPolicies（）` |
| **分层内存** | `src/memory.mjs` | 推荐 | fact→memory→wisdom生命周期（TTL，促进，存档）。 | 配置中的`tier` |
| **提取** | `src/extract.mjs` | 推荐 | LLM概念/声明提取。*启发式备用。* | `MIDMEM_EXTRACT_MODEL` |
| **图** | `src/graph.mjs` | 推荐 | 类型化实体/边; 维基链接; 图上下文。 | - |
| **声明/出处** | `src/claims.mjs` | 推荐 | 合成文档样式声明审计轨迹。 | - |
| **验证** | `src/verify.mjs` | 推荐 | 确定性矛盾/身份检查。 | `sigmaStrictMode` |
| **投影** | `src/project.mjs` | 推荐 | 渲染`state.db`→Obsidian markdown。 | `OBSIDIAN_VAULT_PATH`，`WIKI_PATH` |
| **范围** | （在存储/检索/治理中） | 必要 **对于双**，否则可选 | 多代理私有 + 共享分区。 | `MIDMEM_AGENT_SCOPE` |
| **桥接** | `src/bridge.mjs`（`midmem bridge`） | 推荐 | 将每个堆栈的平面原生内存拉入存储。 | `bridgeSources` |
| **信任/反馈** | （内存 + 检索） | 推荐 | `trust_score` + 使用/反馈循环; 提升排名。 | `trustWeight`，`feedback`工具 |
| **交接门** | `src/handoff.mjs`（`handoff_brief`） | 推荐 | 将范围内存简介推送到代理交接（firstware）。 | 配置文件`local` / `frontier` |
\* 嵌入层对于语义回忆是必需的，但系统**在没有实时模型的情况下运行**，通过确定性哈希嵌入器（词汇检索仍然有效）。在生产摄取之前加载一个真正的模型，以便向量具有语义意义。
---
## 集成
中间层使用MCP，因此任何具有MCP能力的代理都可以使用它。支持三种拓扑结构：
> **每堆栈捕获知识的方式**（OpenClaw · Hermes · Claude Code），可靠和不可靠的内容在 **[`docs/STACK-CAPTURE.md`](docs/STACK-CAPTURE.md)**中。打包的，可重用的每回合捕获代码 + 诚实的部署状态在 **[`integrations/`](integrations/)**（Hermes核心捕获是LIVE; OpenClaw插件已退休/参考）中。工程 + 接地规则： **[`docs/DEVELOPMENT-GUIDELINES.md`](docs/DEVELOPMENT-GUIDELINES.md)**。
### 选项A — 仅OpenClaw（1:1）
在OpenClaw中注册MCP服务器; 它是唯一的消费者。单个代理不需要范围分区，因此使用`MIDMEM_AGENT_SCOPE=shared`。
```bash
openclaw mcp set middleware-memory '{
"command": "node",
"args": ["/path/to/midmem-kb-store/packages/core/bin/mcp-server.mjs"],
"env": {
"MIDMEM_DB_PATH": "/path/to/midmem-kb-store/state.db",
"OBSIDIAN_VAULT_PATH": "/path/to/vault",
"WIKI_PATH": "LLM Wiki",
"MIDMEM_LLM_ENDPOINT": "http://localhost:1234/v1",
"MIDMEM_EMBED_MODEL": "bge-m3",
"MIDMEM_AGENT_SCOPE": "shared"
}'
'
```
### 选项B — 仅Hermes（1:1）
在`~/.hermes/config.yaml`中注册; Hermes是唯一的消费者。`MIDMEM_AGENT_SCOPE=shared`。
```yaml
mcp_servers:
middleware-memory:
command: node
args:
- /path/to/midmem-kb-store/packages/core/bin/mcp-server.mjs
env:
MIDMEM_DB_PATH: /path/to/midmem-kb-store/state.db
OBSIDIAN_VAULT_PATH: /path/to/vault
WIKI_PATH: LLM Wiki
MIDMEM_LLM_ENDPOINT: http://localhost:1234/v1
MIDMEM_EMBED_MODEL: bge-m3
MIDMEM_AGENT_SCOPE: shared
```
### 选项C — 双重集成（OpenClaw + Hermes，共享存储）
在**两者**中注册，指向**相同的`MIDMEM_DB_PATH`** — 一个共享的知识存储。为**每个堆栈设置不同的`MIDMEM_AGENT_SCOPE`**（`openclaw` / `hermes`），以便每个堆栈都有私有工作内存 + 共享公共空间：
- OpenClaw注册：`MIDMEM_AGENT_SCOPE=openclaw`
- Hermes注册：`MIDMEM_AGENT_SCOPE=hermes`
行为：写入默认为调用者的范围; 读取返回调用者的范围 **+ `shared`**; 使用`scope: "shared"`发布跨代理知识。治理阻止代理写入另一个的私有范围。两个服务器进程之间的并发由SQLite WAL + `busy_timeout`处理。 （这是当前的OpenDuck部署。）
| | 选项A | 选项B | 选项C |
|---|---|---|---|
| 消费者 | OpenClaw | Hermes | 两者 |
| `MIDMEM_AGENT_SCOPE` | `shared` | `shared` | `openclaw` / `hermes` |
| 私有 + 共享内存 | — | — | ✅ |
| 共享 `state.db` | n/a | n/a | ✅（相同路径） |
### Claude Code叠加层 — 前沿编织，紧密Hermes集成
上述任何选项都可以通过 **Claude Code**作为第三个消费者使用相同的`state.db`驱动。Claude Code不是第四个存储模式 — 它通过相同的 **CLI + MCP + 钩子**表面访问核心 — 但它扮演着不同的角色：**前沿编织器**。它计划MidMem工作，调度构建到 **Hermes**（通过看板/ACP），对每个结果进行QA，并持久记录 - 因此Claude Code和Hermes围绕一个共享的知识存储紧密集成：Claude Code决策和验证，Hermes构建，两者都读写相同的分层内存。
- **注册**MCP服务器类似于任何消费者（`MIDMEM_AGENT_SCOPE=shared`，或多堆栈部署中的专用范围），或直接使用`midmem` **CLI**。
- **装备**它与 [MidMem技能库](skills/) — `midmem-dev`（更改核心），`midmem-orchestrator` + `midmem-ingest-review`（策划 + 审计），`midmem-record`（持久捕获）。
- **保证捕获**：Claude Code的`Stop`钩子可以在回合结束前阻止，直到写入MidMem的记录更改（最可靠的捕获路径，见 [`docs/STACK-CAPTURE.md`](docs/STACK-CAPTURE.md)和`midmem-record`技能）。
### 技能 — 每个集成使用哪一个
两个技能前置存储; 根据驱动堆栈的方式选择：
| 技能 | 位于 | 驱动 | 用途 |
|---|---|---|---|
| **`midmem-ops`** | OpenClaw（`workspace/skills/`） | OpenClaw代理 | 通过MCP工具直接调用/存储/摄取/主动回忆/反馈 |
| **`hermes-build-orchestrator`** | Claude Code（`.claude/skills/`） | 前沿模型（计划+QA）; Hermes/qwen + gpt-5.5构建通过看板 | 多卡构建带有每个卡的QA门控 |
| **`midmem-dev`** | **此仓库**（`skills/`） | 前沿模型（Claude Code） | 更改**核心**代码：添加/调整功能并使用测试→验证→提交→记录循环 + 护栏 |
| **`midmem-orchestrator`** | **此仓库**（`skills/`） | 相同的循环，MidMem专用 | 批量知识策划：批量摄取，重新接地，重复，保险库验证 |
| **`midmem-ingest-review`** | **此仓库**（`skills/`） | 前沿模型 | 摄取 + 审计知识质量和**跨检查OpenClaw vs Hermes理解**（编造/漂移/矛盾/范围） |
| **`midmem-record`** | **此仓库**（`skills/`） | 前沿模型（Claude Code） | 持久捕获：蒸馏的课程→智慧层级 + 提交 + `Stop`-钩子保证的记录模式 |
- **仅OpenClaw（选项A）：** 使用 **`midmem-ops`** — OpenClaw代理直接操作内存（调用/存储/摄取）; 不需要Hermes。
- **仅Hermes / 构建（选项B）：** 使用 **`hermes-build-orchestrator`** — 它计划，调度卡到Hermes，并对每个进行QA; Hermes通过相同的MCP工具读取/写入存储。
- **OpenClaw + Hermes（选项C）：** OpenClaw使用 **`midmem-ops`**进行自己的调用和 **`hermes-router`**将研究/构建路由到Hermes; 在ACP边界预先添加 **`handoff_brief`**，以便持久内存随行（本地模型不会自行拉取）。构建通过 **`hermes-build-orchestrator`**运行。两个堆栈共享一个`state.db`。
> 长期完整性：`hermes-build-orchestrator` 限制交互/卡片，约束工具，QA每次写入（DELEGATE-52缓解措施）; 摄取应用确定性**接地检查**，以便编造的提取永远不会持续下去。支持Claude Code操作技能：`openduck-doctor`（诊断/ RCA），`openduck-record`（更改日志+midmem+提交），`openduck-config`，`openduck-security-audit`。 **MidMem技能库**（`skills/`，随此仓库提供）持有`midmem-orchestrator` + `midmem-ingest-review` — 将它们符号链接到`~/.claude/skills/`（见`skills/README.md`）。
---
## 快速开始
```bash
# 无需安装（仅需节点≥22.13内置模块 — node:sqlite从22.13开始无标记）
cd packages/core
node test/smoke.mjs # 终端自测试（离线）→ 90/90
npm run verify # 烟雾 + 大脑式回归基准测试
node bin/cli.mjs init # 显示解析的配置
node bin/cli.mjs ingest <file> --type note # 将源编译到存储中（有根据）
node bin/cli.mjs query "..." --graph # 混合查询（+ 图形上下文，--maxTokens预算）
node bin/cli.mjs remember "..." --scope shared
node bin/cli.mjs brief # 层级/声明/图形 + 向量健康计数
node bin/cli.mjs lint # 审计：矛盾，孤立，重复概念
# 候选人，低信任智慧
node bin/cli.mjs project # 渲染Obsidian保险库（修剪过时页面）
node bin/cli.mjs bridge # 将原生代理内存拉入存储
node bin/cli.mjs handoff "<task>" --profile local|frontier # 构建交接内存简介
node bin/cli.mjs work --kind task_attempt --task "..." ... # 记录工作内存事件
node bin/cli.mjs tasks # 持续请求（打开任务节点）
node bin/cli.mjs claims "..." # 当前（最新的，非超前）声明
node bin/cli.mjs contradictions # 确定性声明矛盾候选人
node bin/cli.mjs merge-concepts "<from>" "<to>" # 精心策划的近似概念合并
node bin/cli.mjs refresh-concepts # 重建概念嵌入 + 社区 + 重复
node bin/cli.mjs maintain --force # 完整的生命周期通过（衰减/促进/保留/项目）
```
### MCP 工具（21）
`ingest` · `query` · `remember` · `recall` · `brief` · `audit` · `forget` · `archive` ·
`promote` · `project` · `feedback` （信任）· `handoff_brief` （内存门控）· `maintain` ·
`proactive_recall` · `record_work` · `list_tasks` · `claims` · `claim_supersede` ·
`claim_contradictions` · `refresh_concepts` · `concept_merge`
**交接内存门控（“firstware”）：** `handoff_brief` 构建一个范围限定、预算合理的内存简介，注入代理交接中（例如，在ACP spawn之前，它不共享上下文），因此接收模型不会忽略先前的知识。两个配置文件： **`local`** （小型模型 - 紧凑、权威、仅推送）和 **`frontier`** （云模型 - 更丰富、来源+ID、推送简介+拉取深度）。门控 *调用* 存储; 它不取代它（middleware-on-middleware）。
### 配置（环境变量）
| 变量名 | 默认值 | 用途 |
|---|---|---|
| `MIDMEM_DB_PATH` | `<repo>/state.db` | 单一真实来源数据库 |
| `OBSIDIAN_VAULT_PATH` | `~/Obsidian` | Vault 根目录（投影目标） |
| `WIKI_PATH` | `LLM Wiki` | Vault 中的 Wiki 子文件夹 |
| `MIDMEM_LLM_ENDPOINT` | `http://localhost:1234/v1` | OpenAI 兼容端点（嵌入 + 提取） |
| `MIDMEM_EMBED_MODEL` | `bge-m3` | 嵌入模型（在服务器上加载） |
| `MIDMEM_VECTOR_BACKEND` | `sqlite` | 向量存储：`sqlite`（数据库内，无依赖）或 `qdrant` |
| `MIDMEM_QDRANT_URL` | `http://localhost:6333` | Qdrant 端点（当后端为 qdrant 时） |
| `MIDMEM_EXTRACT_MODEL` | （聊天模型） | 提取模型 |
| `MIDMEM_AGENT_SCOPE` | `shared` | 此消费者的范围：`openclaw`/`hermes`/`shared` |
| `MIDMEM_LLM_ENABLED` | `1` | 设置为 `0` 以强制离线/确定性回退 |
| `MIDMEM_SOURCE_ROOTS` | 仓库/工作空间/Vault 目录 | 允许的摄入根目录（真实路径遍历保护） |
| `MIDMEM_GROUNDING_MIN_OVERLAP` | `0.5` | DELEGATE-52 地面实证阈值（隔离低于此阈值的项） |
| `MIDMEM_AUTO_INGEST` | `1` | maintain() 自动桥接代理工作/会话目录 |
| `MIDMEM_MAINTENANCE` | `1` | 自主生命周期（衰减/晋升/投影） |
| `MIDMEM_RETENTION_DAYS` | `90` | 强制维护清除日志/审计行和孤立向量（0 表示关闭） |
| `MIDMEM_WORK_MEMORY` | `1` | 工作内存事件（`record_work`，任务跟踪） |
| `MIDMEM_CONCEPT_ROUTING` | `1` | P5 概念节点路由 + 强制维护中的规范去重 |
---
## 推荐的嵌入模型
`BAAI/bge-m3`（1024 维，8192 上下文，混合稠密 + 稀疏）— 适用于混合 Wiki RAG 和 Qdrant。
更轻量级的替代方案：`nomic-embed-text-v1.5`（768 维）。在首次摄入前选择一个模型，并在任何向量存储迁移时保持一致（无需重新嵌入；维度保护强制一致性）。
## 路线图
- ✅ ~~Vault → NAS 共享~~ — 已于 2026-06-29 完成（`OBSIDIAN_VAULT_PATH=/mnt/OpenDuck-Vault`；投影使用规范小写斜杠 + 旧页面修剪，因此大小写不敏感的 CIFS 共享是安全的）。
- ✅ ~~衰减扫描器 + 近似重复报告~~ — 已完成：生命周期衰减是自主的；`lint` 报告 `dupeConcepts` 候选项（精选 `merge-concepts` 应用它们）+ `lowTrustWisdom`。
- 向量存储 → **Qdrant**（优于 ChromaDB；`MIDMEM_VECTOR_BACKEND=qdrant`，适配器已构建 — 在 NAS 上运行实例后待上线；最终状态与 Proxmox 上的 vLLM 操作符配对）。
- **研究波晋升 + 主题标签**（2026-07-01 审查）：确定性触发器（N 个相同社区摄入在 M 天内）使波在 `brief` 中浮现；合成保持精选。
- **微调 LLM `wisdom` 层级**，从精选智慧（权重空间长期记忆）中训练。
- 预 LLM 调用内存门（每回合简介，移交门的兄弟）；TypeScript 迁移；双向 Vault 同步。规模注意：每查询概念扫描在 ~250 条记录中表现良好；将概念索引到约 ~50K 的表中。
## 仓库布局
```
packages/core/ # ← 活跃的基础（本 README 描述它）
src/ # 数据库、内存、检索、向量存储、嵌入、提取、图、主张、
# 验证、治理、项目、桥接、移交、工作内存、概念、
# 调度器、配置
bin/ # cli.mjs、mcp-server.mjs、hook.mjs（每回合前/后缝隙 — 4 模式调用者）
test/ # smoke.mjs（90 个检查）+ bench.mjs（Brain 风格的回归门控）
config/ # tier-config.json（可调参数）+ AGENTS.md（代理指令）
skills/ # MidMem 技能库（Claude 代码）— 参见 skills/README.md
integrations/ # 打包的可重复使用的每回合捕获代码 + 状态 — 参见 integrations/README.md
docs/ # 设计笔记 — INTEGRATION-MODES、STACK-CAPTURE、DEVELOPMENT-GUIDELINES
RESEARCH.md # 研究 → 架构决策记录（DELEGATE-52，…）
```
## 子文件夹指南
- [`packages/core/README.md`](packages/core/README.md) — 引擎：模块、如何运行、环境变量。
- [`skills/README.md`](skills/README.md) — MidMem 技能库（`midmem-dev`、`midmem-orchestrator`、`midmem-ingest-review`、`midmem-record`）+ 安装。
- [`docs/README.md`](docs/README.md) — 设计笔记索引。
- [`RESEARCH.md`](RESEARCH.md) — 为什么存储按照这种方式构建，基于论文。
## 许可证
[Apache License 2.0](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器