Memory Bridge (忆桥)

Memory Bridge（忆桥）

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

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

简体中文 · English

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

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

已发布到官方 MCP Registry（io.github.yanglinfeng/mcp-memory-bridge），多架构镜像见 GHCR。

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；如果将模型地址配置为远程服务，相关提示词和上下文会发送到该服务。

什么时候该用忆桥

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

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

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

为什么是忆桥

已实现

检索与问答

• 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 接口文档

记忆治理

• 自然语言记住 / 纠正 / 遗忘的同步快车道；纠正保持稳定 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）。

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

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

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。

MEMORY_BRIDGE_USER_ID=default npx -y mcp-memory-bridge

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

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 头部注释。

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

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

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

{
  "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 改版与时序对照查询：

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。

文档一致性

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

npm run check:docs

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

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

评测

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

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

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

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

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 的支持）。 它们作为独立模块提供商业支持，不影响本仓库的完整可用性——独立部署本仓库就是完整可用的内核。

联系与支持

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

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

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

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

License

Apache-2.0