内容
# 中Mem知识库存储与LLM维基路由器
一个自包含的**LLM维基中间层**：一个单一的知识来源 - 真相存储，具有**混合检索（词典+向量）**，分层内存，类型化知识图，声明出处，**关闭失败治理**，以及通过**模型上下文协议（MCP）**，CLI和编程API向LLM代理暴露的Obsidian投影。
它是AI代理与其知识之间的代理：代理通过路由器`摄取`、`查询`和`记住`；知识存储位于其后。适用于OpenClaw + Hermes双栈，但纯核心和模块化 - 它通过三个表面运行：CLI，MCP和`bin/hook.mjs`的前/后转缝。参见[集成](#integration)+`docs/INTEGRATION-MODES.md`。
> **状态（2026-07-02）：** 基础 + 跨代理范围 + 原生→中间层桥 + 检索升级（信任，三元组，令牌预算，图增强，维度守护）+ 可选Qdrant向量后端 + 交接内存门 + 自主生命周期（衰减/使用赚取的提升/自动投影）+ 无触发器`主动回忆`+ DELEGATE-52提取接地 + **工作内存事件与确定性自动摄取和分类**（大脑适应）+ **P4时间/工作流排名提升** + **P5概念节点嵌入，社区和查询路由** + **P6声明取代/矛盾/当前（）** + **P7离线大脑式基准** + **概念规范化（大小写/复数重复，精选`合并概念`，别名感知检索）** + **保险库投影修剪（删除过期页面;不区分大小写的共享安全slug）** + **实际路径摄取保护** + **日志/审计/向量保留**。测试：烟雾**90/90** + 绿色长椅（`npm run verify`）。在Node上运行，**零外部依赖**（Node≥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（计划→调度构建→质量保证）和持久记录 - 由**中Mem技能库**装备，该技能库在[`skills/`](skills/)中提供。
- **`state.db` 是真相来源**；markdown保险库是其确定性投影。
- **混合检索**：SQLite FTS5/BM25（令牌词典）⊕ FTS5-三元组（子字符串词典）⊕ 向量余弦（语义），通过互惠排名融合，加上信任 + 图参考链提升和可选的令牌预算。向量是增量 - 词典工作独立。
- **向量后端可插拔**：`sqlite`（默认，基于JSON余弦，无依赖）或`qdrant`（外部近似最近邻）。持有id→向量；`state.db`保持元数据。
- **层级**：`fact`（原始，7天TTL）→ `memory`（综合，30天）→ `wisdom`（精选，∞），具有信任评分。
- **范围**：每个条目都是`openclaw` | `hermes` | `shared` — 私有工作内存 + 共享公共空间。
- **交接门（“firstware”）**：将内存简报推送到代理交接中，以便接收者不会忽略它。
---
## 抽象层
中间层由可交换的层组成。**必需**层必须存在才能作为LLM维基中间层功能；**推荐**层添加功能，是可以延迟的。
| 层 | 模块 | 必需？ | 目的 | 交换/配置 |
| --- | --- | --- | --- | --- |
| **集成/传输** | `bin/mcp-server.mjs`（MCP stdio）· `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` | **必需** | 可插拔的ANN：`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核心捕获**实时**；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），对每个结果进行质量保证，并持久记录 - 因此Claude Code和Hermes紧密围绕一个共享的知识存储集成：Claude Code决定和验证，Hermes构建，两者都读写相同的分层内存。
- **注册**MCP服务器以适用于Claude Code（如任何消费者一样）（`MIDMEM_AGENT_SCOPE=shared`，或多堆栈部署中的专用范围），或直接使用`midmem` **CLI**。
- **装备**它使用[中Mem技能库](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/`） | 前沿模型（计划 + 质量保证）；Hermes/qwen + gpt-5.5通过看板 | 多卡构建，每个卡都有质量保证门 |
| **`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，并对每个卡进行质量保证；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`。中Mem技能库（`skills/`，随此仓库发布）包含`midmem-orchestrator` + `midmem-ingest-review` — 将它们符号链接到`~/.claude/skills/`（参见`skills/README.md`）。
---
## 快速开始
```bash
# 无需安装（Node ≥ 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生成前，它不共享上下文），因此接收模型不会忽略先前的知识。两个配置文件： **`local`** （小型模型 - 紧凑、权威、仅推送）和 **`frontier`** （云模型 - 更丰富、来源 + ID、推送简报 + 拉取深度）。门户 *调用* 存储；它不取代存储（middleware-on-firstware）。
### 配置（环境变量）
| 变量名 | 默认值 | 用途 |
|---|---|---|
| `MIDMEM_DB_PATH` | `<repo>/state.db` | 单一真实来源数据库 |
| `OBSIDIAN_VAULT_PATH` | `~/Obsidian` | 保险库根目录（投影目标） |
| `WIKI_PATH` | `LLM Wiki` | 保险库中的 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` | 仓库/工作空间/保险库目录 | 允许的摄取根目录（真实路径遍历保护） |
| `MIDMEM_GROUNDING_MIN_OVERLAP` | `0.5` | DELEGATE-52 接地阈值（隔离低于此阈值） |
| `MIDMEM_AUTO_INGEST` | `1` | maintain() 自动桥接代理工作/会话目录 |
| `MIDMEM_MAINTENANCE` | `1` | 自主生命周期（衰减/提升/投影） |
| `MIDMEM_RETENTION_DAYS` | `90` | 强制 maintain 剪辑日志/审计行和孤立向量（0 = 关闭） |
| `MIDMEM_WORK_MEMORY` | `1` | 工作内存事件（`record_work`，任务跟踪） |
| `MIDMEM_CONCEPT_ROUTING` | `1` | P5 概念节点路由 + 强制 maintain 中的规范化去重 |
---
## 推荐的嵌入模型
`BAAI/bge-m3`（1024 维，8192 上下文，混合稠密 + 稀疏）— 适用于混合 Wiki RAG 和 Qdrant。
更轻量的替代方案：`nomic-embed-text-v1.5`（768 维）。在首次摄取前选择一个 **并在整个矢量存储迁移过程中保持一致**（无需重新嵌入；维度保护强制一致性）。
## 路线图
- ✅ ~~保险库 → NAS 共享~~ — 已于 2026-06-29 完成（`OBSIDIAN_VAULT_PATH=/mnt/OpenDuck-Vault`；投影使用规范化小写 slug + 过时页面修剪，因此不区分大小写的 CIFS 共享是安全的）。
- ✅ ~~衰减扫描器 + 近似重复报告~~ — 已完成：生命周期衰减是自主的；`lint` 报告 `dupeConcepts` 候选项（精选 `merge-concepts` 应用它们）+ `lowTrustWisdom`。
- 矢量存储 → **Qdrant**（已决定优于 ChromaDB；`MIDMEM_VECTOR_BACKEND=qdrant`，适配器已构建 — 运行实例待定，终态与 Proxmox 上的 vLLM 操作符配对）。
- **研究波推广 + 主题标签**（2026-07-01 审查）：确定性触发器（N 个相同社区摄取在 M 天内）使波在 `brief` 中浮现；合成保持精选。
- **微调 LLM `wisdom` 层**，从精选智慧（权重空间长期记忆）训练。
- 预 LLM 调用内存门（每轮简报，类似于交接门）；TypeScript 迁移；双向保险库同步。扩展注意：每查询概念扫描在 ~250 条目时表现良好；将概念索引到约 50K 的表中。
## 仓库布局
```
packages/core/ # ← 活动基础（本 README 描述）
src/ # db, memory, retrieval, vectorstore, embeddings, extract, graph, claims,
# verify, governance, project, bridge, handoff, workmemory, concepts,
# orchestrator, config
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
连接信息
猜你喜欢
暂无推荐服务器