Agent Memory Bridge

简体中文

一个面向编码智能体的 MCP 原生内存层，将真实会话转化为可复用的工程记忆。

首选为 Codex 构建。

Agent Memory Bridge 捕获了聊天记录通常会丢失的内容：

• 持久化决策

• 已知修复方案

• 跨会话交接

• 可复用的避坑指南 (gotchas)

• 精简的领域知识

核心理念很简单：保持内存层小巧、可靠且可审查。让更高层的编排位于其上。

有趣的部分不仅仅是持久化，而是自动化的内存塑造：

• 会话变为可复用的 learn（学习记录）

• 重复的失败变为 gotcha（避坑指南）

• 知识点集群变为精简的 domain-note（领域笔记）

为什么存在这个项目

大多数智能体内存系统往往会陷入以下三种模式之一：

• 内存被困在单个应用或单个模型中

• 在检索基础尚未验证前就引入沉重的托管基础设施

• 仅仅是转录转储，而非可复用的操作知识

Agent Memory Bridge 采取了一条更窄的路径：

• 从第一天起就是 MCP 原生的

• 本地优先的运行时

• 使用 SQLite + FTS5 而非更沉重的基础设施

• 从会话追踪自动提升为可复用的内存

它不仅仅是存储，而是一个内存塑造流水线：

session -> summary -> learn -> gotcha -> domain-note

定位

Agent Memory Bridge 的定位是有意收窄的。

如果你想要一个包含 SDK、仪表板、连接器和多界面应用支持的更广泛的内存平台，像 OpenMemory 或 Mem0 这样的项目更符合那种形态。

本项目刻意有所不同：

1. 它是为编码智能体工作流构建的，而非通用的笔记存储。

2. 它有意保持 MCP 接口极简：仅有 store 和 recall。

3. 它将原始会话输出提升为精简的机器可读内存，而不是将摘要视为最终产物。

4. 它是本地优先的，且默认可审查。

关于更详细的定位说明，请参阅 docs/COMPARISON.md。

工作原理

运行时包含四个主要部分：

1. MCP 服务器

   • 暴露 store 和 recall 接口

2. 观察者 (watcher)

   • 观察 Codex 的 rollout 文件

   • 写入 session-seen、checkpoint 和 closeout

3. 反射 (reflex)

   • 将摘要提升为 learn、gotcha 和 signal

4. 整合 (consolidation)

   • 将重复出现的 learn 和 gotcha 记录合成为领域笔记

这使得系统易于理解：

• 原始会话不是最终内存

• 摘要不是最终内存

• 持久化内存是机器优先的

• 合成发生在提升之后

快速开始

要求：

• Python 3.11+

• 启用了 MCP 的 Codex

• 支持 FTS5 的 SQLite

1. 安装

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .[dev]

2. 创建桥接配置

将 config.example.toml 复制到：

$CODEX_HOME/mem-bridge/config.toml

推荐设置：

• 在每台机器上保持实时的 SQLite 数据库为本地存储

• 如果需要，将共享配置文件或源代码库放在 NAS 或共享存储上

• 如果需要真正的多机实时写入，后续可迁移到托管后端

3. 在 Codex 中注册 MCP 服务器

将此内容添加到 $CODEX_HOME/config.toml：

[mcp_servers.agentMemoryBridge]
command = "D:\\path\\to\\agent-memory-bridge\\.venv\\Scripts\\python.exe"
args = ["-m", "agent_mem_bridge"]
cwd = "D:\\path\\to\\agent-memory-bridge"

[mcp_servers.agentMemoryBridge.env]
CODEX_HOME = "%USERPROFILE%\\.codex"
AGENT_MEMORY_BRIDGE_HOME = "%USERPROFILE%\\.codex\\mem-bridge"
AGENT_MEMORY_BRIDGE_CONFIG = "%USERPROFILE%\\.codex\\mem-bridge\\config.toml"

4. 启动服务

启动 MCP 服务器：

.\.venv\Scripts\python.exe -m agent_mem_bridge

运行后台桥接服务：

.\.venv\Scripts\python.exe .\scripts\run_mem_bridge_service.py

仅运行一个周期：

$env:AGENT_MEMORY_BRIDGE_RUN_ONCE = "1"
.\.venv\Scripts\python.exe .\scripts\run_mem_bridge_service.py

可选的启动安装：

.\scripts\install_startup_watcher.ps1

可选：构建本地 Docker 镜像

docker build -t agent-memory-bridge:local .
docker --context desktop-linux run --rm -i agent-memory-bridge:local

容器入口点使用 python -m agent_mem_bridge 启动 stdio MCP 服务器。

核心 API

MCP 接口有意保持极简：

• store

• recall

常见的 store 字段：

• namespace

• content

• kind

• tags

• session_id

• actor

• title

• correlation_id

• source_app

常见的 recall 字段：

• namespace

• query

• kind

• tags_any

• session_id

• actor

• correlation_id

• since

• limit

典型命名空间

• project:<workspace>

• global

• domain:<name>

• 当团队需要时导入的配置文件命名空间

该框架与配置文件无关。特定的操作员配置文件可以叠加在上面，但桥接器本身并不绑定于某一个角色或协议。

日常使用

预期的分层结构是：

• 系统级操作员配置文件

• 系统级内存基底：agentMemoryBridge

• 项目级覆盖：AGENTS.md

启动协议记录在 docs/STARTUP-PROTOCOL.md 中。

简而言之：

1. 回忆全局操作内存

2. 回忆相关的专业化内存

3. 如果存在工作区，回忆 project:<workspace>

4. 对于类似问题的处理，在外部搜索前先检查本地内存和避坑指南

5. 在信任回忆的实现细节之前，先检查实时代码

有用命令

运行测试：

.\.venv\Scripts\python.exe -m pytest

运行 stdio 冒烟测试：

.\.venv\Scripts\python.exe .\scripts\verify_stdio.py

运行基准测试：

.\.venv\Scripts\python.exe .\scripts\run_benchmark.py

运行桥接健康检查：

.\.venv\Scripts\python.exe .\scripts\run_healthcheck.py --report-path .\examples\healthcheck-report.json

从最新的 rollout 强制执行检查点：

.\.venv\Scripts\python.exe .\scripts\sync_now.py

项目结构

仓库有意保持小巧：

src/agent_mem_bridge/   canonical implementation
scripts/                operational entrypoints
tests/                  verification
docs/                   design and roadmap
examples/               sanitized demo artifacts

最重要的文件：

• src/agent_mem_bridge/server.py

• src/agent_mem_bridge/storage.py

• src/agent_mem_bridge/watcher.py

• src/agent_mem_bridge/reflex.py

• src/agent_mem_bridge/consolidation.py

• src/agent_mem_bridge/service.py

设计选择

小巧的 MCP 接口

桥接器仅暴露 store 和 recall。这使得契约保持稳定且易于集成。

本地优先的运行时

实时数据库默认保持在本地，因为共享网络存储上的 SQLite 是一个可靠性陷阱。

机器优先的内存

智能体是主要读者，因此内存偏向于：

• 精简的字段

• 稳定的标签

• 低 Token 成本

而不是润色的散文。

分层提升

系统尝试向上移动：

• summary

• learn

• gotcha

• domain-note

而不是将原始摘要视为最终产物。

状态

当前基础已经可以工作：

• MCP 自动加载在 Codex 中有效

• 项目和会话同步有效

• 回忆优先的工作流有效

• 反射提升有效

• 第一轮领域整合有效

现状检查和路线图：

• docs/PRODUCTION-STATUS.md

• docs/ROADMAP.md

配置文件导入

该框架可以托管导入的操作员配置文件，但框架本身保持与配置文件无关。

文档

• README.zh-CN.md

• CONTRIBUTING.md

• AGENTS.md

• docs/COMPARISON.md

• docs/STARTUP-PROTOCOL.md

• docs/MEMORY-TAXONOMY.md

• docs/PROMOTION-RULES.md

• docs/MODEL-ROUTING.md

• docs/ROADMAP.md

许可证

MIT。请参阅 LICENSE。