Memory Bridge (忆桥)

Memory Bridge（記憶ブリッジ）

MCP 向けのローカルファーストで、根拠に基づくナレッジ・メモリレイヤーです。

社内ネットワーク向け AI ナレッジベースエンジン —— 企業文書への質問応答／規程・契約の検索／プライベートデプロイに対応し、すべての回答に一文ごとの出典と再生可能な traceId が付属します。また、特定のクライアントに依存しない MCP 長期記憶ミドルウェアでもあります。

簡体字中国語 · 英語

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 は、ほとんどの RAG／メモリスタックが見落とす 3 つの問いに答えます。この一文の出典はどこか、その出典は現在も有効か、誰がそれを閲覧できるか。すべての回答には出典との対応付けと検索の traceId が付属し、すべての変更が監査され、すべての名前空間が分離されています。デフォルトでは、モデルへのリクエストはローカルの Ollama に送信されます。リモートのモデルエンドポイントを設定した場合、関連するプロンプトとコンテキストがそこに送信されます。

AI ナレッジベースの最大のリスクは、答えられないことではなく、捏造と廃止済みファイルの引用です。記憶ブリッジは回答に出典を付け、変更の監査記録を残し、部門ごとにデータを分離します。デフォルト設定ではローカルの Ollama を使用します。モデルのアドレスにリモートサービスを設定すると、関連するプロンプトとコンテキストがそのサービスに送信されます。

記憶ブリッジを使うべき場面

社内ナレッジベースを構築していて、次のいずれかに当てはまる場合です。

利用シーン	記憶ブリッジが提供する機能
従業員が質問するのは、規程、手順、契約、アフターサービス記録のように、バージョンと所有者がある文書です	文書レベルのバージョンチェーン。内容の変更に応じて自動的に切り替わり、旧バージョンはデフォルトの検索対象から外れますが、監査は引き続き可能です
「この結論はどのファイルのどの段落に基づいていますか」と答えるよう求められます	一文ごとの出典との対応付けと、再生可能な traceId
異なる部門が互いの資料を閲覧できてはいけません	ユーザー／名前空間／スコープの 3 層分離と、信頼されたセッションの発行
データを社内ネットワークの外に出せません	ローカルファースト。デフォルトでローカルの Ollama を使用し、外部依存はありません

つまり、企業ナレッジベース／社内ネットワーク内の文書への質問応答／規程・契約の検索／プライベートデプロイ、およびこうした場面での長期記憶レイヤーに適しています。記憶ブリッジは特定のクライアントに依存しない MCP メモリーミドルウェアでもあり、Claude Desktop、Cline、Cursor などのクライアントに直接接続できます。

一方、AI に自分のコーディングスタイルの好みを覚えさせたいだけの場合や、クラウドでホストされるメモリーサービスをお探しの場合、記憶ブリッジは最適な選択肢ではありません。強みは監査可能であることであり、その代わりに自分でデプロイする必要があります。

記憶ブリッジが選ばれる理由

企業導入で避けて通れない課題	記憶ブリッジの仕組み
この文の出典は、どのファイルのどの段落ですか？	非破壊的な統合によって一文ごとに出典を紐付けます。検索のたびに traceId が付与され、「クエリの書き換え → 候補 → 融合 → 再ランキング → 選択 → 注入」の全過程を再生できます
ファイルが改版された場合、古い回答が引用され続けますか？	文書レベルのバージョンチェーン：内容の変更時に自動で supersede し、旧バージョンはデフォルトの検索対象から外れます。過去のバージョンは引き続き監査・追跡できます
誰が閲覧でき、誰が変更しましたか？	ユーザー／名前空間／スコープの 3 層分離、信頼されたセッションの発行と認可マトリックス、すべての操作の監査ログ

実装済みの機能

検索と質問応答

• FTS5 + Dense ANN + 概念逆引きインデックス + 厳密な再ランキングによる、全コーパスを対象としたハイブリッド検索。「直近 N 件」による事前切り捨ては行いません
• クロスエンコーダーによる再ランキング：bge-reranker-v2-m3 Python サイドカーを使用し、コーパスのドメイン（policy / open）に応じて関連性のしきい値を設定します
• 関連性が不十分な場合は、粗いランキングのスコアで補完（filler）し、複数ステップにわたる証拠チェーンを保持します
• 回答拒否ポリシー：コーパスに情報がなければ、はっきりと「ありません」と回答し、無理に作り上げません
• 回答ツール：calculator / date_diff / date_shift——算術と日付の計算はコードに任せ、モデルに暗算させません
• 双時点検索：検索期間を 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 のブロックに対応します——推論を自動確定するスイッチはありません
• 非破壊的な統合：出典の変更後、または忘却後に要約が自動で無効化され、再構築できます
• デフォルトではユーザーデータを保持します。自動減衰はなく、証拠の秘匿化も行いません

エンジニアリング基盤

• SQLite（node:sqlite）+ outbox / jobs：リース、再試行、dead letter、クラッシュ後の再生、冪等な実行
• すべての操作の監査 + 検索 JSONL ログ（メタデータ／診断のレベル分け、秘匿化、ローテーション、保持期間後のクリーンアップ）
• Memory Doctor による読み取り専用の診断：重複、競合、孤立データ、無効な要約、サイズ超過のメモリー、検索結果がゼロの頻出クエリ
• モデルはすべて設定可能です。デフォルトの生成モデルは qwen2.5:14b、埋め込みモデルは 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 不主张任何分数——这是本项目「可信层」定位的一部分。

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

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

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

Roadmap

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

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

联系与支持

事项	走哪个通道
缺陷报告	Issues · 缺陷报告模板
功能建议	Issues · 功能建议模板
私有化部署实施 / 商业支持与 SLA / 定制开发	Issues · 商业合作模板 或 Discussions 的 Commercial 分类
用法讨论、部署求助、调优经验	Discussions
安全漏洞	Security Advisories —— 请勿为安全问题开公开 Issue，处理流程见 SECURITY.md

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

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

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

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

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

License

Apache-2.0