Agent Memory Bridge

简体中文

Agent Memory Bridge (AMB) is a local-first shared project memory layer for AI coding agents. Code tells AMB what the project is; conversations teach AMB why it is that way. Repository-derived WHAT and governed durable project WHY remain distinct and are available across tools and sessions through a small local MCP surface.

Current source version: 0.32.0

Published releases: see GitHub Releases

AMB complements AGENTS.md, CLAUDE.md, and client-native preference memory; it does not replace them. It is not a hosted agent runtime, scheduler, queue, or general-purpose memory platform.

Why AMB

Coding agents often lose useful engineering knowledge between sessions, clients, and handoffs. A plain summary can become stale; opaque retrieval can hide why an item was selected; and mutable operational state should not be mistaken for durable knowledge.

AMB keeps those concerns separate. It stores inspectable engineering memory, applies lifecycle-aware governance before task context is assembled, maintains exact-key mutable state through a distinct authority boundary, and keeps prompt-facing context transient.

What AMB Provides

AMB does not automatically write lessons back to memory, change ranking from feedback, promote self-generated reflection, or acquire skills autonomously.

How It Works

flowchart LR
    A[Durable Memory / WHY] --> C[Lifecycle-aware Recall]
    B[Repository Knowledge / WHAT] --> D[Context Compiler]
    S[Dynamic State Authority] --> D
    C --> E[Governed Task Memory]
    E --> D
    D --> F[Transient Bounded Context]
    F --> G[Metadata-only Context Attestation]
    G --> H[Episode and Run Authority]
    H --> I[Verification Receipt]
    I --> J[Current Verified Outcome]

Context bodies are rendered in process and are not durably persisted by the compiler. An attestation stores bounded metadata and digests, not the prompt-facing body. A selected context does not prove memory application, and memory application does not prove causality.

Read the complete authority and data-flow story in Architecture.

Quick Start

AMB runs locally with Python 3.11+, SQLite with FTS5, and an MCP-compatible client that can launch a local stdio server.

The current source/package version is 0.32.0. Use a source checkout with <venv-python> -m pip install -e . to evaluate this exact checkout. Published release availability and pinned archives are listed in GitHub Releases. GitHub Release publication status is determined by that live Releases page; there is no pip install agent-memory-bridge==0.32.0 route.

1. Connect AMB to your coding client

python -m venv .amb-venv
<venv-python> -m pip install -e .
<venv-python> -m agent_mem_bridge setup --client generic

Use the rendered client configuration and reload the client. setup owns connection and configuration planning.

2. Initialize repository WHAT

<venv-python> -m agent_mem_bridge project init .

Project Init detects the local Git repository, proposes a namespace such as project:my-app, and waits for explicit confirmation before writing. After confirmation it reuses existing bootstrap-repo to bind derived repository WHAT, then shows Human-first Explore. It does not automatically learn decisions.

The explicit primitive remains available:

<venv-python> -m agent_mem_bridge bootstrap-repo . \
  --namespace project:my-app

AMB derived a bounded, rebuildable view of this repository.

Code tells AMB WHAT the project is.

3. Teach one project WHY naturally

In the connected coding agent, say something like:

Remember that we decided not to add Redis because this project is intentionally local-first and single-node.

The connected agent uses AMB's existing public memory tools to persist that explicit decision and reason. You do not fill in internal record schemas in this human Quick Start.

Conversations teach AMB WHY it is that way.

AMB does not infer a durable decision from repository code, automatically promote chat text, or archive transcripts.

4. Prove it in a fresh session

Start or reopen a coding-agent session that uses the same AMB home and database. Ask a related question, then use Inspect and Explore.

Inspect answers: why did this information surface for this question?

<venv-python> -m agent_mem_bridge inspect \
  --namespace project:my-app \
  --query "Should we add Redis?"

Inspect explains the governed result for that question. It does not list every durable record, change memory, or prove the model used a memory.

Explore answers: what does AMB currently know about this project, and how is it connected?

<venv-python> -m agent_mem_bridge explore \
  --namespace project:my-app

Explore is a local, read-only, derived projection over existing project knowledge. Default Markdown is a human-readable project one-pager. Use --format markdown --technical for the detailed graph/audit view. JSON is unchanged. Explore is CLI-only, not MCP tool #18, and it does not rank context for the model.

Project knowledge mental model

This is a conceptual view, not verbatim CLI output:

PROJECT: MY APP

CODE / WHAT                  CONVERSATION / WHY
───────────                  ──────────────────
Runtime: Python >=3.11       Decision: Avoid Redis
Tests: pytest                Reason: single-node,
CI: GitHub Actions           local-first project
Container: Docker
Guidance: AGENTS.md

Repository WHAT is derived from current clean code. It is rebuildable and is not durable human decision authority.

Conversation WHY is an explicit decision or constraint stored through AMB. It is governed durable project memory.

Explorer is a read-only projection over existing knowledge. It is not a new source of authority.

Detailed authority language lives in Project Knowledge Activation and Architecture.

If repository WHAT is unavailable

Dirty worktree. Repository WHAT is temporarily unavailable because the checkout has uncommitted changes. AMB will not attribute those changes to the current Git commit. Commit, stash, or restore the worktree, then explicitly rerun bootstrap-repo.

Changed clean HEAD. Repository WHAT is temporarily stale because HEAD changed since the saved snapshot.

Previous snapshot: <old SHA>

Current clean HEAD: <new SHA>

AMB will not present the previous snapshot as current repository truth. Explicitly rerun:

<venv-python> -m agent_mem_bridge bootstrap-repo . \
  --namespace project:<name>

Then repository WHAT is refreshed and durable project WHY is unchanged. Refresh is not automatic.

Missing binding. No current repository binding was found for this project namespace. Run project init . to detect the checkout and confirm a suggested namespace, or choose the namespace yourself and run:

<venv-python> -m agent_mem_bridge bootstrap-repo . \
  --namespace project:<name>

One demo on this repository

After connecting AMB to a client that shares the same AMB home:

<venv-python> -m agent_mem_bridge project init . --namespace project:amb --yes

Teach naturally:

Remember that we decided not to use a graph database for Knowledge Explorer because Explorer should remain a derived read-only projection.

Start a fresh session, ask “Should Knowledge Explorer use a graph database?”, then run Inspect and Explore. This proves recovery of an explicit decision. It does not claim productivity or that the model used the memory.

Optional guided memory loop

first-run remains available as secondary guided durable-memory help. It is not the modern Project Learning entrypoint.

<venv-python> -m agent_mem_bridge first-run --namespace project:my-app --query "What should I check before submitting changes?"

If setup health is uncertain

doctor and verify are optional health and troubleshooting checks. They are not required before bootstrap.

<venv-python> -m agent_mem_bridge doctor
<venv-python> -m agent_mem_bridge verify

For the detailed agent workflow, use Install for Agents, Installation Notes, Integrations, and Configuration.

Integrations

AMB is a local stdio MCP server. Generic stdio MCP is supported; Codex is the reference workflow; Claude Code, Claude Desktop, Cursor, and Cline are documented; and Antigravity, OpenCode, and Hermes have locally tested configuration paths. Integration status labels are intentionally narrow and do not imply host certification.

See Integrations for client-specific configuration and boundaries.

Trust and Privacy

SQLite/WAL is the durable local authority. FTS5 and optional local embeddings are derived indexes, not memory authority. Dynamic State is separate from semantic memory. Run artifacts retain bounded metadata only, and AMB rejects raw transcript, hidden-reasoning, and inline artifact-body fields from the durable episode path.

Detailed boundaries are in the Authority Contract, Trust Boundary, and Closed-Loop Episode Authority.

MCP Tools

AMB exposes 17 public MCP tools:

• store, recall, browse, and stats
• forget, feedback, promote, annotate, revise, and export
• begin_run, record_run_event, get_run, and complete_run
• claim_signal, extend_signal_lease, and ack_signal

The public surface is intentionally small. Context assembly, review reports, and other derived views evolve behind these tools rather than adding separate task-packet or context-compiler tools. The local protocol cache contract is 300000/public for discovery and 0/private for the tool list; see MCP Compatibility for detail.

Documentation

Current Maturity

The current source is 0.32.0, uses schema v12, and retains the frozen 17-tool MCP surface. Default Explore is a Human-first project one-pager over existing WHAT and WHY. project init is the preferred first-project path; bootstrap-repo remains the explicit lower-level primitive. Checked-in source facts, validation evidence, and non-claims are maintained in Production Status. For live CI, use GitHub Actions or the CI badge above; for published versions, use GitHub Releases or the release badge above.

Roadmap

Future direction is capability-based and deliberately conservative. See the Roadmap; historical announcements remain evidence, not required reading for the current product story.

Contributing and Security

Read CONTRIBUTING.md for development and public-surface expectations, and SECURITY.md for the local-first security model and vulnerability reporting process.

Licensed under MIT.