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 with SQLite/WAL as the durable store, FTS5 for lexical recall, and an optional local embedding sidecar for semantic or hybrid retrieval. 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 authority, explicit namespaces, inspectable records, benchmarked lexical/hybrid 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: runtime learning can be staged as policy-gated learning candidates before promotion into durable records.
- 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
289 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; optional local embeddings are derived indexes, not durable authority
- 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, signal contention checks, and learning-candidate review queues. There are no separate task_packet, startup_packet, or learning_candidate MCP tools.
For normal always-on service use, Codex-log watcher capture, reflex promotion, and strong consolidation are disabled by default. That lets multi-runtime installs run governance checks and embedding sidecar maintenance without silently promoting raw session/process chatter into durable memory.
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.14.2 is the service automation hardening patch over the governed learning-candidate release 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 |
| Learning candidates | policy-gated staging records are suppressed from normal recall, browse, export, and stats unless explicitly queried with review tags; candidates are not durable authority until reviewed/promoted |
| 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 | 289 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 durable writeback path from raw transcripts. 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
- Benchmark and proof harness
- Context assembly
- Memory taxonomy
- Promotion rules
- Client provenance
- Examples
- Contributing
- Security
MIT. See LICENSE.