Agent Memory Bridge

简体中文

Give coding agents one shared, governed record of project decisions across tools and sessions.

Agent Memory Bridge is shared engineering memory for developers and teams that use more than one coding agent. It complements AGENTS.md, CLAUDE.md, and client-native preference memory rather than replacing them. SQLite/WAL is the durable authority, with FTS5 and optional local embeddings as derived indexes for lexical, semantic, or hybrid retrieval.

Current source release: 0.27.4

This is a local, unpublished source candidate; it does not assert a tag, push, publication, remote CI result, host certification, or productivity result. The candidate carries schema v12 and exactly 17 MCP tools. Governed-v2 episode authority, watcher continuity, credit/consolidation closure, and their existing shadow-only boundaries remain unchanged. The new internal Dynamic State MVP is an exact-key release-state lane over SQLite/WAL: typed status transitions, owner assignment, optimistic version and database-epoch preconditions, lifecycle idempotency, immutable mutation/request-outcome history, and a rebuildable state-head projection. It adds no MCP tools and does not change semantic-memory, embedding, FTS, ranking, policy, prompts, ordinary memory, or automatic writeback behavior.

Codex is the reference workflow, not the product boundary. AMB uses local stdio MCP; client integrations are documented or locally verified only where labeled below.

<p align="center"> <img src="examples/diagrams/v0.22-shared-memory-hero.png" alt="Rendered workspace scene with three code workstations connected by bridges to a central cabinet holding cards and a scroll." width="900"> </p> <p align="center"><em>Conceptual visual only: a shared-memory workspace metaphor for AMB. It is not product evidence, identity evidence, certification, distribution, or use proof.</em></p>

Try it locally after install: <venv-python> -m agent_mem_bridge first-run --client generic --example

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 starts cold or gets a stale context dump
• 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, capability-labeled retrieval, 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.
• Review-first writeback: learning candidates can be staged for human review before explicit promotion into durable records.
• Context assembly: startup and task-time context can be rendered from procedures, concepts, beliefs, gotchas, and linked support without adding more MCP tools.
• Governed change: explicit deletion, supersession, changed premises, and task-domain applicability are checked before guidance becomes actionable.
• Cross-client activation receipts: a read-only CLI receipt can show that two distinct declared client labels participated in one memory loop without exposing paths, content, session IDs, or model IDs.
• Retrieval feedback: callers can append a receipt-bound vote, correction, or retraction while AMB exposes at most one current effective vote without changing ranking or memory.
• Episode ledger: callers can create explicit server-minted runs/work items, append structured events, recover state after reconnect or compaction, and record evidence-backed outcomes without changing ranking or policy.
• Evidence context: recall can sign bounded SHA-256 digests for optional caller-declared model, harness, and chat_template labels without including raw values or treating them as authenticated identity.
• Proof discipline: release contract checks, public-surface checks, onboarding checks, benchmark snapshots, visual inventory checks, and targeted receipt/feedback regressions.

How It Works

AMB keeps the runtime path small: MCP-compatible coding agents call 17 public MCP tools, including four explicit episode tools; SQLite/WAL remains the durable authority; FTS5 and optional local embeddings are derived indexes; governed context and CLI reports are rendered without automatic durable writeback. Release checks, benchmarks, and the visual claim inventory stay outside that runtime path.

Who It Is For

• You use more than one coding agent and want project decisions, gotchas, and handoffs to remain shared across them.
• You already use AGENTS.md, CLAUDE.md, or native preference memory and need a governed cross-agent layer alongside it.
• 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
• optional uv / uvx for a pinned one-command GitHub smoke test

Pinned GitHub install with Python:

python -m venv .amb-venv
python -c "import os; from pathlib import Path; print((Path('.amb-venv') / ('Scripts/python.exe' if os.name == 'nt' else 'bin/python')).absolute())"

Treat the printed value as <venv-python>. Keep that resolved local path out of commits and issue reports. In a POSIX shell, shell-quote that path when needed. In Windows PowerShell, invoke it as & "<venv-python>". Then run:

The pinned GitHub tag route is the published v0.27.0 baseline. The local source candidate has no release tag; use a source checkout with <venv-python> -m pip install -e . to evaluate it.

<venv-python> -m pip install "https://github.com/zzhang82/Agent-Memory-Bridge/archive/refs/tags/v0.27.0.zip"
<venv-python> -m agent_mem_bridge doctor
<venv-python> -m agent_mem_bridge verify

An optional smoke test against the published baseline with uvx is:

uvx --from git+https://github.com/zzhang82/Agent-Memory-Bridge@v0.27.0 agent-memory-bridge verify

Quick Start: Unified First-Run

Use first-run when you want a complete copy/paste setup guide for a client. It renders install steps, a placeholder-safe config snippet, verification commands, and a first Task Brief preview. It does not write client config files or durable memory records.

<venv-python> -m agent_mem_bridge first-run --client generic --example
<venv-python> -m agent_mem_bridge first-run --client codex --example
<venv-python> -m agent_mem_bridge first-run --client opencode --example
<venv-python> -m agent_mem_bridge first-run --client hermes --example

If you only need the config snippet, use config directly:

<venv-python> -m agent_mem_bridge config --client generic --example
<venv-python> -m agent_mem_bridge config --client codex --example
<venv-python> -m agent_mem_bridge config --client opencode --example
<venv-python> -m agent_mem_bridge config --client hermes --example
<venv-python> -m agent_mem_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>", consumer="reviewer-a")

For polling, use an empty query with kind="signal" and pass the previous next_since value back as since. Polling returns later insertions in ascending order. Missing, deleted, or cross-namespace anchors fail explicitly. The cursor does not report later claim or ack transitions on older Signals. Text and memory recall return next_since: null.

For a cross-client activation receipt, keep one correlation id across both clients:

# Client A stores one reviewed project memory.
store(
  namespace="project:demo",
  kind="memory",
  title="Reviewed SQLite guidance",
  content="record_type: gotcha\nclaim: Use WAL mode for concurrent SQLite readers.",
  tags=["workflow:cross-client-activation", "activation-role:writer", "reviewed:true"],
  correlation_id="activation-demo-001",
  source_client="client-a"
)

# Client B recalls it, then records and acknowledges the read signal.
recall(namespace="project:demo", query="SQLite concurrent readers", correlation_id="activation-demo-001")
store(
  namespace="project:demo",
  kind="signal",
  content="{\"observed_memory_id\":\"<writer_memory_id>\"}",
  tags=["workflow:cross-client-activation", "activation-role:reader"],
  correlation_id="activation-demo-001",
  source_client="client-b"
)
ack_signal(id="<reader_signal_id>")

Then render the local receipt:

<venv-python> -m agent_mem_bridge activation-receipt --namespace project:demo --correlation-id activation-demo-001 --format markdown

The receipt reports hashes and pass/review status. It does not print raw memory content, private paths, session ids, model ids, or authenticated identity claims.

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.

Task Briefs do not require Agent Memory Harness (AMH). The AMB CLI can render a derived task context report over recalled records, including what context was used, ignored, or marked for review. That brief is a derived view over AMB memory; it is not a second durable store and does not add MCP tools.

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.

| Client | Status | Notes | |---|---|---| | Generic stdio MCP | sup