Agent Memory Bridge

简体中文

An MCP-native memory layer for coding agents that turns coding sessions into reusable engineering memory.

Built for Codex-first workflows.

Agent Memory Bridge captures what chat history usually loses:

• durable decisions
• known fixes
• cross-session handoffs
• reusable gotchas
• compact domain knowledge

The core idea is simple: keep the memory layer small, reliable, and inspectable. Let higher-level orchestration sit on top.

The system reshapes session output into durable memory:

• sessions become reusable learn
• repeated failures become gotcha
• clusters of lessons become compact domain-note

Why This Exists

Most agent memory systems drift into one of three patterns:

• memory trapped inside one app or one model
• heavier hosted infrastructure before retrieval basics are proven
• transcript dumping instead of reusable operational knowledge

Agent Memory Bridge takes a narrower path:

• MCP-native from day one
• local-first runtime
• SQLite + FTS5 instead of heavier infrastructure
• automatic promotion from session traces into reusable memory

At its core, it is a memory shaping pipeline:

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

Positioning

Agent Memory Bridge is intentionally narrow.

If you want a broader memory platform with SDKs, dashboards, connectors, and multi-surface application support, projects like OpenMemory or Mem0 are closer to that shape.

This project is different on purpose:

1. It is built for coding-agent workflows, not generic note storage.
2. It keeps the MCP surface intentionally small: store and recall.
3. It promotes raw session output into compact machine-readable memory instead of treating summaries as the final artifact.
4. It is local-first and inspectable by default.

For a longer positioning note, see docs/COMPARISON.md.

How It Works

The runtime has four main pieces:

1. MCP server
   • exposes store and recall
2. watcher
   • observes Codex rollout files
   • writes session-seen, checkpoint, and closeout
3. reflex
   • promotes summaries into learn, gotcha, and signal
4. consolidation
   • synthesizes recurring learn and gotcha records into domain notes

This keeps the system understandable:

• raw sessions are not final memory
• summaries are not final memory
• durable memory is machine-first
• synthesis happens after promotion

Quick Start

Requirements:

• Python 3.11+
• Codex with MCP enabled
• SQLite with FTS5 support

1. Install

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

2. Create bridge config

Copy config.example.toml to:

$CODEX_HOME/mem-bridge/config.toml

Recommended setup:

• keep the live SQLite database local on each machine
• keep shared profile or source vaults on NAS or shared storage if needed
• move to a hosted backend later if you want true multi-machine live writes

3. Register the MCP server in Codex

Add this to $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. Start the service

Start the MCP server:

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

Run the background bridge service:

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

Run one cycle only:

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

Optional startup install:

.\scripts\install_startup_watcher.ps1

Optional: build a local Docker image

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

The container entrypoint starts the stdio MCP server with python -m agent_mem_bridge.

Core API

The MCP surface is intentionally small:

• store
• recall

Common store fields:

• namespace
• content
• kind
• tags
• session_id
• actor
• title
• correlation_id
• source_app

Common recall fields:

• namespace
• query
• kind
• tags_any
• session_id
• actor
• correlation_id
• since
• limit

Typical Namespaces

• project:<workspace>
• global
• domain:<name>
• imported profile namespaces when a team wants them

The framework is profile-agnostic. A specific operator profile can be layered on top, but the bridge itself is not tied to one persona or one protocol.

Day-to-Day Usage

The intended layering is:

• system-level operator profile
• system-level memory substrate: agentMemoryBridge
• project-local overrides: AGENTS.md

The startup protocol is documented in docs/STARTUP-PROTOCOL.md.

In short:

1. recall global operating memory
2. recall relevant specialization memory
3. if a workspace exists, recall project:<workspace>
4. for issue-like work, check local memory and gotchas before external search
5. inspect live code before trusting recalled implementation details

Useful Commands

Run tests:

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

Run the stdio smoke test:

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

Run the benchmark:

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

Run the bridge health check:

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

Force a checkpoint from the latest rollout:

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

Project Structure

The repo is intentionally small:

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

The files that matter most:

• 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

Design Choices

Small MCP surface

The bridge exposes only store and recall. This keeps the contract stable and easy to integrate.

Local-first runtime

The live DB stays local by default because SQLite on shared network storage is a reliability trap.

Machine-first memory

Agents are the primary readers, so memory favors:

• compact fields
• stable tags
• low token cost

over polished prose.

Layered promotion

The system tries to move upward:

• summary
• learn
• gotcha
• domain-note

instead of treating raw summaries as the final artifact.

Status

The current foundation is working:

• MCP autoload works in Codex
• project and session sync work
• recall-first workflows work
• reflex promotion works
• first-pass domain consolidation works

Reality check and roadmap:

• docs/PRODUCTION-STATUS.md
• docs/ROADMAP.md

Profile Imports

The framework can host imported operator profiles, but the framework itself stays profile-agnostic.

Documentation

• 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

License

MIT. See LICENSE.