# Memory Bridge（忆桥）

**Local-first, evidence-backed knowledge & memory layer for MCP.**

**内网 AI 知识库引擎 —— 企业文档问答 / 制度与合同检索 / 私有化部署，每个答案带逐句出处与可回放 traceId；同时是不绑定任何客户端的 MCP 长记忆中间件。**

[简体中文](README.md) · [English](README.en.md)

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
![Node](https://img.shields.io/badge/node-%E2%89%A524-green)
![Schema](https://img.shields.io/badge/schema-v44-blue)
![MCP](https://img.shields.io/badge/protocol-MCP-purple)
[![ghcr.io](https://img.shields.io/badge/ghcr.io-memory--bridge-blue)](https://github.com/yanglinfeng/memory-bridge/pkgs/container/memory-bridge)
![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.yanglinfeng%2Fmcp--memory--bridge-purple)

**30 秒跑起来**（无需本机 Node，无需构建）：

```bash
docker run -i --rm -v memory-bridge-data:/data ghcr.io/yanglinfeng/memory-bridge:latest
```

已发布到官方 MCP Registry（`io.github.yanglinfeng/mcp-memory-bridge`），多架构镜像见
[GHCR](https://github.com/yanglinfeng/memory-bridge/pkgs/container/memory-bridge)。

> **EN** — Memory Bridge answers three questions most RAG / memory stacks skip: *where did this sentence come from*, *is the source still valid*, and *who can see it*. Every answer carries source bindings and a retrieval `traceId`; every change is audited; every namespace is isolated. By default, model requests go to local Ollama. If you configure a remote model endpoint, the relevant prompts and context are sent there.

AI 知识库最大的风险不是答不出，是**编造**和**引用已废止的文件**。忆桥给回答配出处、给变更留审计、给部门数据上隔离。默认配置使用本机 Ollama；如果将模型地址配置为远程服务，相关提示词和上下文会发送到该服务。

## 什么时候该用忆桥

你在搭**企业内部知识库**，并且满足下面任意一条：

| 你的场景 | 忆桥对应的能力 |
|---|---|
| 员工问的是**制度、流程、合同、售后记录**这类有版本、有归属的文档 | 文档级版本链，内容变更自动轮替，旧版本退出默认检索但仍可审计 |
| 你被要求回答「**这条结论出自哪份文件哪一段**」 | 逐句来源绑定 + 可回放的 `traceId` |
| **不同部门不能看到彼此的资料** | 用户 / 命名空间 / 作用域三层隔离 + 可信会话签发 |
| 数据**不能出内网** | 本地优先，默认本机 Ollama，无外部依赖 |

也就是说：**企业知识库 / 内网文档问答 / 制度与合同检索 / 私有化部署**，以及在这些场景下的**长记忆层**——忆桥同时是不绑定任何客户端的 MCP 记忆中间件，可直接接进 Claude Desktop、Cline、Cursor 等客户端。

反过来，如果你只是想让 AI 记住你的代码风格偏好，或者想要一个托管在云上的记忆服务，忆桥不是最优选择——它的强项是**可审计**，代价是要你自己部署。

## 为什么是忆桥

| 企业落地绕不开的问题 | 忆桥的机制 |
|---|---|
| 这句话的出处是哪份文件的哪一段？ | 非破坏式巩固逐句绑定来源，每次召回带 `traceId`，可回放「查询改写 → 候选 → 融合 → 重排 → 选择 → 注入」全程 |
| 文件改版了，旧答案还会被引用吗？ | 文档级版本链：内容变更自动走 `supersede`，旧版本退出默认检索，历史版本仍可审计回溯 |
| 谁能看见、谁改过？ | 用户 / 命名空间 / 作用域三层隔离 + 可信会话签发与授权矩阵 + 全操作审计日志 |

## 已实现

**检索与问答**

- FTS5 + Dense ANN + 概念倒排 + 严格重排的全库混合检索，不按「最近 N 条」预截断
- Cross-encoder 重排：`bge-reranker-v2-m3` Python sidecar，按语料域（policy / open）分档相关性门槛
- 相关性不足时按粗排分填充（filler），保留多跳证据链
- 弃答策略：语料里没有就明确说没有，不硬编
- 答案工具：`calculator` / `date_diff` / `date_shift`——算术与日期交给代码算，不让模型口算
- bi-temporal 召回：检索窗口同时受 `valid_from` / `valid_to` 约束

**接入面**

- **10 个 MCP 工具**：记忆读写 7 个 —— `memory_remember` · `memory_recall` · `memory_get_context` · `memory_update` · `memory_forget` · `memory_list` · `memory_stats`；确定性求解 3 个 —— `answer_calculator` · `answer_date_diff` · `answer_date_shift`
- HTTP API + OpenAI 兼容接口 + React 管理台（候选审核、版本证据、召回解释、索引水位、系统健康）
- 知识库 / RAG 应用层直写通道，字段级契约见 [API 接口文档](docs/api-接口文档.md)

**记忆治理**

- 自然语言记住 / 纠正 / 遗忘的同步快车道；纠正保持稳定 UUID 并追加版本，遗忘先写 tombstone
- 跨多轮推断固定进入待确认，支持确认 / 拒绝 / 阻止未来等价 claim——没有 inference 自动提交开关
- 非破坏式巩固：来源变化或遗忘后摘要自动失效并可重建
- 默认保留用户数据：无自动衰减、无证据脱敏

**工程底座**

- SQLite（`node:sqlite`）+ outbox / jobs：租约、重试、dead letter、崩溃重放、幂等执行
- 全操作审计 + 检索 JSONL 日志（元数据 / 诊断分级、脱敏、轮转、保留清理）
- Memory Doctor 只读体检：重复、冲突、孤儿、失效摘要、超大记忆、零结果热点
- 模型全可配置：默认生成 `qwen2.5:14b`、embedding `bge-m3:latest`（Ollama），无需云服务

## Quick Start

前置：Node.js ≥ 24，Ollama 已运行（Docker 方式不需要本机 Node）。

```bash
ollama pull qwen2.5:14b
ollama pull bge-m3:latest
```

**方式 A —— 官方镜像（推荐，零构建）**

```bash
docker run -i --rm -v memory-bridge-data:/data ghcr.io/yanglinfeng/memory-bridge:latest
```

镜像同时提供 `linux/amd64` 与 `linux/arm64`（Apple Silicon 原生运行，不走模拟）。

**方式 B —— npx（只接 MCP 客户端）**

> 注：npm 包 `mcp-memory-bridge` 尚在发布准备中。若此命令报 404，请改用方式 A 或 C。

```bash
MEMORY_BRIDGE_USER_ID=default npx -y mcp-memory-bridge
```

**方式 C —— 从源码运行（管理台 / 开发）**

```bash
git clone https://github.com/yanglinfeng/memory-bridge.git
cd memory-bridge
npm install
npm run build
npm start          # HTTP 服务 + 管理台：http://127.0.0.1:3789
```

首次启动为空记忆库——没有演示数据，管理台只展示真实写入的内容。

> **容器里跑 HTTP 模式要注意**：忆桥只监听回环地址（`127.0.0.1` / `::1`），这是有意的安全
> 契约——服务信任 loopback 上的无令牌请求。所以容器里**不能**用 `-p 3789:3789` 做端口映射
> （映射到的是容器自己的回环，宿主机连不上），请改用 `--network host`（Docker Desktop 需先
> 在设置里启用 host networking）。完整说明见 [Dockerfile](Dockerfile) 头部注释。

接入任意 MCP 客户端（Claude Desktop / Cline / …），用官方镜像最省事：

```json
{
  "mcpServers": {
    "memory-bridge": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "memory-bridge-data:/data",
        "ghcr.io/yanglinfeng/memory-bridge:latest"
      ]
    }
  }
}
```

从源码运行时改用绝对路径：

```json
{
  "mcpServers": {
    "memory-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/memory-bridge/dist/server/mcp-stdio.js"],
      "env": {
        "MEMORY_BRIDGE_USER_ID": "default"
      }
    }
  }
}
```

`MEMORY_BRIDGE_USER_ID`（或改用 `MEMORY_BRIDGE_MCP_TOKEN`）是必填项——两者都缺时服务会拒绝
启动。镜像里已内置 `MEMORY_BRIDGE_USER_ID=default`，所以 Docker 方式无需再配。
npm 包发布后，也可改用 `"command": "npx"` 与 `"args": ["-y", "mcp-memory-bridge"]`。

### 接入示例

三个**零构建、可直接运行**的最小示例（curl / Node / Java），覆盖写入（含 `corpusDomain` /
`classification`）、幂等重放、召回、`supersede` 改版与时序对照查询：

```bash
export MB_TOKEN=你的令牌        # 见 examples/README.md §1

bash examples/curl/quickstart.sh
node examples/node/quickstart.mjs
java examples/java/QuickStart.java      # JDK 17+，零依赖
```

详见 [examples/README.md](examples/README.md)。

### 文档一致性

文档里声明的 schema 版本、环境变量、npm 脚本、HTTP 路由与配置默认值，可以和代码事实一键对撞：

```bash
npm run check:docs
```

它会把「文档说的」与「代码里的」逐项比对并在不一致时以非零退出码失败，适合在发布前与每次
大改后重跑。见 [CONTRIBUTING.md](CONTRIBUTING.md)。

完整安装、运维、接口与排障文档从 [docs/README.md](docs/README.md) 进入；
基准评测的条件与一键复现见 [BENCHMARKS.md](BENCHMARKS.md)。

## 评测

忆桥自带评测与压测链路（`scripts/` 下 40+ 个可执行脚本，覆盖检索、重排、巩固、命名空间隔离、上下文反思、规模、可靠性与崩溃恢复），并在 [`docs/acceptance-report-*.md`](docs/) 中保留带日期与环境的证据快照。

**公开基准（英文知识库问答、中文自建集）的条件与一键复现脚本已列在 [`BENCHMARKS.md`](BENCHMARKS.md)。** 其中包含数据准备与运行限制；大规模延迟压测仍是项目内部评测，不作为公开基准。在数字可复现之前，README 不主张任何分数——这是本项目「可信层」定位的一部分。

## 和主流方案的区别（按维度，不按体量）

| 维度 | 忆桥 | mem0 | Zep / Graphiti | RAGFlow | AnythingLLM |
|---|---|---|---|---|---|
| 引用可验证（来源绑定 + `traceId`） | ✅ | — | — | ✅ | 部分 |
| 时序有效性（版本替代退出检索） | ✅ 文档级 | — | ✅ 事实级 | — | — |
| 全操作审计日志 | ✅ | 企业版 | ✅ | — | — |
| 命名空间 / 部门隔离 | ✅ 可信会话 + 授权矩阵 | 企业版 | ✅ | 团队级 | Workspace |
| 遗忘与纠正（tombstone / 版本追加） | ✅ | ✅ | ✅ | — | — |
| 可配置为全离线（模型端点也在本机） | ✅ | 部分 | — | ✅ | ✅ |
| MCP 原生 | ✅ 7 工具 | ✅ | 社区封装 | ✅ | — |

> 本表只列**架构上有无**，不评分数高低。各项目迭代都很快，请以各自仓库为准。

## Roadmap

- [x] `BENCHMARKS.md`：公开基准的完整条件与一键复现（`npm run bench:cn` / `bench:cmrc` / `bench:hotpotqa`）
- [x] 社区四件套：`CONTRIBUTING.md` / `SECURITY.md` / `CHANGELOG.md` / `CODE_OF_CONDUCT.md`，附 `.env.example` 与 `examples/`（curl / Node / Java）
- [x] 文档 ↔ 代码一致性门禁 `npm run check:docs`（发布前与每次大改后重跑）
- [x] `supersede` 时补写 `valid_to`，并补 as-of 查询的回归测试
- [x] 清掉 3 例预存在的失败用例：迁移备份与写锁顺序那 1 例已修（改为取锁后复检文件家族）；
  `test:lifecycle` 的 2 例 doctor 经查是 Node 版本低于 `engines >= 24` 所致，**非代码缺陷**
- [x] 英文入口 `README.en.md`（核心指南英文版仍待补）
- [ ] `pretest` 加 Node 版本守卫：`engines` 在 npm 里只是警告、不阻断执行，
  Node < 24 跑 `npm test` 会稳定看到 2 例假红灯
- [ ] 文档解析深度：推荐接入 RAGFlow / Docling 等上游，忆桥专注其上的可信层

> **关于开源边界的说明。** 忆桥的定位是「可信层」，而可信必须可被验证——所以证据绑定、版本链、
> 审计日志、命名空间隔离这些构成可信层的能力，**全部在本仓库、全部 Apache-2.0、且不会改为闭源**。
> 只有两类东西不在本仓库内：企业内网的**文档摄取与权限落地**（解析、章节切分、ACL 裁剪、审核流、
> 图像链路），以及**交付与运维工程**（离线交付包、升级回滚、合规审计导出、带 SLA 的支持）。
> 它们作为独立模块提供商业支持，不影响本仓库的完整可用性——独立部署本仓库就是完整可用的内核。

## 联系与支持

| 事项 | 走哪个通道 |
|---|---|
| 缺陷报告 | [Issues · 缺陷报告模板](https://github.com/yanglinfeng/memory-bridge/issues/new?template=bug_report.yml) |
| 功能建议 | [Issues · 功能建议模板](https://github.com/yanglinfeng/memory-bridge/issues/new?template=feature_request.yml) |
| 私有化部署实施 / 商业支持与 SLA / 定制开发 | [Issues · 商业合作模板](https://github.com/yanglinfeng/memory-bridge/issues/new?template=commercial_inquiry.yml) 或 [Discussions](https://github.com/yanglinfeng/memory-bridge/discussions) 的 Commercial 分类 |
| 用法讨论、部署求助、调优经验 | [Discussions](https://github.com/yanglinfeng/memory-bridge/discussions) |
| 安全漏洞 | [Security Advisories](https://github.com/yanglinfeng/memory-bridge/security/advisories/new) —— **请勿为安全问题开公开 Issue**，处理流程见 [SECURITY.md](./SECURITY.md) |

维护者是个人开发者（[@yanglinfeng](https://github.com/yanglinfeng)），不开空头 SLA；缺陷会按「是否影响
出处可验证 / 版本可追溯 / 权限可隔离」排序，商务类咨询优先回复。

本项目以 **Apache-2.0** 授权。公司内部自用、二次开发、集成进内部系统，乃至**打包进你们对外销售的产品**，都不需要向我们申请授权——这是 Apache-2.0 已经给到你的权利，我们不会事后收回。

既然如此，什么情况下才需要联系？答案是需要**责任**，而不是许可：

| 你需要的是 | 怎么走 |
|---|---|
| 私有化部署实施、模型选型与调优、历史数据迁移 | 商业合作表单 |
| 带明确响应时间的 SLA、年度维护与升级保障 | 商业合作表单 |
| 企业内网场景的文档摄取、章节切分与权限落地 | 商业合作表单 |
| 只是想用起来 | 不必联系，`git clone` 即可 |

「忆桥 / Memory Bridge」名称与标识不在 Apache-2.0 的授权范围内（见许可证第 6 条）。二次分发请使用你自己的产品名，不要让人误以为出自本项目官方。

## License

[Apache-2.0](./LICENSE)