Agent Memory Bridge

简体中文

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.

Why It Exists

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.

What You Get

• Durable memory: decisions, gotchas, procedures, concepts, beliefs, and supporting records.
• Coordination signals: claim -> extend -> ack / expire / reclaim without 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.

Who It Is For

• 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.

Install

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 verify

Local 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 verify

Generate 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 --example

Dockerized 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:local

Client-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.

The First Useful Loop

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.

Client Support

Status labels are intentionally narrow.

MCP Tools

The bridge exposes 10 public MCP tools:

• store, recall, browse, stats
• forget, promote, export
• claim_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.

Static-schema client compatibility

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.

Proof Snapshot

0.14.2 is the service automation hardening patch over the governed learning-candidate release while keeping the public tool surface stable.

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.

Boundaries

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.

Docs

• Client integrations
• Configuration
• Authority contract
• Agent install protocol
• Benchmark and proof harness
• Context assembly
• Memory taxonomy
• Promotion rules
• Client provenance
• Examples
• Contributing
• Security

License

MIT. See LICENSE.