Your coding agent should not rediscover the same project decisions every session.
Agent Memory Bridge is persistent engineering memory for coding agents: a local-first MCP memory layer and context compiler backed by SQLite + FTS5. It captures durable repo decisions, gotchas, procedures, and handoffs while keeping short-lived coordination separate.
Codex is the reference workflow, not the product boundary. If a client can launch a local stdio MCP server, it can use Agent Memory Bridge.
Most agent memory either feels too shallow or too heavy:
- summaries become stale blobs
- vector stores hide why something was recalled
- every new session re-learns the same gotchas
- handoff state turns into ad hoc notes or a queue you did not want to build
AMB takes a smaller path: local SQLite, explicit namespaces, inspectable records, benchmarked recall, and a signal lifecycle for lightweight coordination.
- Durable memory: decisions, gotchas, procedures, concepts, beliefs, and supporting records.
- Coordination signals:
claim -> extend -> ack / expire / reclaimwithout pretending to be a scheduler. - Governed learning: session output can move through
summary -> learn / gotcha -> domain-note -> belief -> concept-note. - Context assembly: startup and task-time context can be compiled from procedures, concepts, beliefs, gotchas, and linked support without adding more MCP tools.
- Proof discipline: release contract checks, public-surface checks, onboarding checks, benchmark snapshots, and
201 passed.
- You use Codex, Claude, Cursor, Cline, Antigravity, or another MCP client and keep re-explaining the same project conventions.
- You want memory that is local and inspectable instead of a hosted platform or opaque vector stack.
- You run review, handoff, or multi-agent workflows and need coordination signals without building a full task queue.
Requirements:
- Python 3.11+
- SQLite with FTS5 support
- any MCP-compatible client that can launch a local stdio server
One-command GitHub smoke test with uvx:
uvx --from git+https://github.com/zzhang82/Agent-Memory-Bridge agent-memory-bridge verifyLocal editable install:
python -m venv .venv
# Activate the virtual environment for your shell, then:
python -m pip install -e .
agent-memory-bridge doctor
agent-memory-bridge verifyGenerate a placeholder-safe client config:
agent-memory-bridge config --client generic --example
agent-memory-bridge config --client codex --example
agent-memory-bridge config --client cursor --exampleDockerized stdio works too when you want an isolated runtime:
docker build -t agent-memory-bridge:local .
docker run --rm -i -e AGENT_MEMORY_BRIDGE_HOME=/data/agent-memory-bridge -v /path/to/bridge-home:/data/agent-memory-bridge agent-memory-bridge:localClient-specific notes live in docs/INTEGRATIONS.md. Runtime configuration lives in docs/CONFIGURATION.md. Authority and correction rules live in docs/AUTHORITY-CONTRACT.md. Security guidance lives in SECURITY.md. Agents that are installing the bridge should start with INSTALL_FOR_AGENTS.md.
Session 1 discovers a project rule:
store(
namespace="project:demo",
kind="memory",
content="claim: Use WAL mode for concurrent SQLite readers."
)
Session 2 asks about the same project:
recall(namespace="project:demo", query="SQLite concurrent readers")
The agent gets the rule back without the user typing it again.
For coordination, use signals:
store(namespace="project:demo", kind="signal", content="release note review ready")
claim_signal(namespace="project:demo", consumer="reviewer-a", lease_seconds=300)
extend_signal_lease(id="<signal_id>", consumer="reviewer-a", lease_seconds=300)
ack_signal(id="<signal_id>")
The short version:
WITHOUT AMB
user> We hit this last time too: run the generator after schema edits.
WITH AMB
agent> I found the previous gotcha: run the generator after schema edits.
The terminal demo and the before/after gotcha story are in examples/demo, with the story source at examples/demo/before-after-gotcha.cast.md.
Status labels are intentionally narrow.
| Client | Status | Notes |
|---|---|---|
| Generic stdio MCP | supported | Any client that can launch a local stdio server |
| Codex | verified | Reference workflow and deepest dogfood path |
| Claude Code | documented | CLI or project-level stdio MCP config |
| Claude Desktop | documented | Local stdio server config; remote/extension flows are separate |
| Cursor | documented | JSON mcpServers config |
| Cline | documented | JSON mcpServers config |
| Antigravity | locally tested | Exercised in a local setup; UI/config details can vary |
The bridge exposes 10 public MCP tools:
store,recall,browse,statsforget,promote,exportclaim_signal,extend_signal_lease,ack_signal
The richer behavior stays behind that surface: reflex promotion, consolidation, startup/task-time assembly, procedure governance, telemetry summaries, and signal contention checks. There are no separate task_packet or startup_packet MCP tools.
Some MCP clients generate one static input schema per tool and may send signal-only fields on kind="memory" paths: for example ttl_seconds or expires_at on store, and signal_status on recall, browse, or export. AMB drops those fields at the MCP transport boundary before creating or querying memory records. The lower-level memory store contract stays strict: durable memory and coordination signals remain separate lanes, and real signal lifecycle fields still belong only to kind="signal" operations.
0.13.1 is a launch-surface polish release over the 0.13 coordination runtime while keeping the public tool surface stable.
| Track | Current signal |
|---|---|
| Retrieval | memory_expected_top1_accuracy = 1.0, file_scan_expected_top1_accuracy = 0.636 |
| Calibration | classifier_exact_match_rate = 0.875, fallback_exact_match_rate = 0.062 |
| Procedure governance | governed_case_pass_rate = 1.0, governed_blocked_procedure_leak_rate = 0.0 |
| Signal contention | signal_contention_case_pass_rate = 1.0, duplicate_active_claim_count = 0 |
| Adversarial memory governance | adversarial_case_count = 6, adversarial_task_count = 7, adversarial_governed_task_pass_rate = 1.0, adversarial_governed_blocked_record_leak_rate = 0.0 |
| Test suite | 201 passed |
Release contract facts
Snapshot facts checked by the release contract:
question_count = 11
memory_expected_top1_accuracy = 1.0
memory_mrr = 1.0
file_scan_expected_top1_accuracy = 0.636
file_scan_mrr = 0.909
sample_count = 16
classifier_exact_match_rate = 0.875
fallback_exact_match_rate = 0.062
classifier_better_count = 13
fallback_better_count = 2
classifier_filtered_low_confidence_count = 2
case_count = 7
flat_case_pass_rate = 0.429
governed_case_pass_rate = 1.0
flat_blocked_procedure_leak_rate = 1.0
governed_blocked_procedure_leak_rate = 0.0
governed_governance_field_completeness = 1.0
signal_contention_case_count = 5
signal_contention_case_pass_rate = 1.0
unique_active_claim_rate = 1.0
duplicate_active_claim_count = 0
active_reclaim_block_rate = 1.0
stale_ack_blocked_rate = 1.0
stale_reclaim_success_rate = 1.0
pending_under_pressure_claim_rate = 1.0
initial_hard_expiry_cap_rate = 1.0
adversarial_case_count = 6
adversarial_task_count = 7
adversarial_governed_task_pass_rate = 1.0
adversarial_governed_blocked_record_leak_rate = 0.0
Full proof details are in benchmark/README.md.
AMB is not a graph database, hosted memory platform, scheduler, worker runtime, distributed lock, exactly-once coordination system, packet API, or automatic procedure learner. It is a small local bridge for reusable engineering memory and lightweight coordination.
For alternatives and trade-offs, see docs/COMPARISON.md.
- Client integrations
- Configuration
- Authority contract
- Agent install protocol
- Harness design
- Benchmark and proof harness
- Context assembly
- Memory taxonomy
- Promotion rules
- Client provenance
- Examples
- Contributing
- Security
MIT. See LICENSE.