Agent Memory Bridge

Carry project decisions into the next coding session.

AMB helps coding agents remember the decisions that matter — across sessions, tools, and time.

简体中文

pip install agent-memory-bridge

Install once; connect each coding client separately. Installing the package does not register AMB with every coding agent. Each client you want to use must be configured to launch AMB as an MCP stdio server. Clients that should share memory need to use the same configured local AMB home.

Your project should not start over with every session

A project is more than its current files. Over time, useful context gets scattered across repositories, chats, coding agents, reviews, fixes, and one-off decisions. A new session can see the code but still miss the reasons that make the project make sense.

AMB gives those decisions a durable place to live. The first win is simple: teach one real decision, close the session, open a fresh coding-agent session, and hear the same decision come back from AMB.

AMB is local-first and inspectable. It does not silently archive every conversation or treat every remembered statement as equal authority.

Quick Start

AMB requires Python 3.11+, Git, and an MCP-compatible coding client that can launch a local stdio server.

Current package/source version: 0.33.0.

Published releases: see GitHub Releases.

The first win happens inside the coding agent, in a fresh session. CLI Explore/Inspect and doctor/verify are later checks, not that win.

1. Install AMB

For the Quick Start, use a virtual environment so every coding client can point at one stable Python launcher. Replace <venv-python> with the Python executable inside .amb-venv for your operating system.

python -m venv .amb-venv
<venv-python> -m pip install agent-memory-bridge==0.33.0

For development or audit work against an exact source checkout, use:

<venv-python> -m pip install -e .

2. Connect the coding client you actually use

Installation and client registration are separate. Preview the setup for one client first:

<venv-python> -m agent_mem_bridge setup --client <client>

setup is read-only by default: it detects or inspects only bounded client configuration locations and shows the exact AMB fragment or action it recommends. Use a supported client name such as codex, claude-code, vscode, cursor, cline, opencode, or another client listed in Integrations. Codex is the reference workflow.

If the preview marks that client as eligible for safe automatic configuration, you can explicitly apply it after review:

<venv-python> -m agent_mem_bridge setup --client <client> --apply

Some clients remain preview/manual because AMB will not guess or rewrite an unsafe configuration format or path. In that case, copy the rendered fragment or follow the client-specific Integration guide. Repeat this step for every coding client you want to connect. To share the same project memory across clients, keep them pointed at the same configured AGENT_MEMORY_BRIDGE_HOME, then reload each client after registration.

Connection is proven when the coding client itself lists AMB tools such as store and recall. doctor and verify do not prove that an external client loaded MCP config.

3. Initialize the project

<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 confirmation. It then derives a current repository baseline. It does not automatically learn decisions.

4. Teach one real project decision

In the connected coding agent, teach a decision you actually made. For example:

Remember that we merge pull requests only after CI is green on the target branch, because broken main blocked two releases this month.

The connected agent uses AMB's public store tool to persist the explicit decision and reason. AMB does not infer a durable decision from the code or archive the whole conversation.

Another valid example is a stack choice, such as staying local-first instead of adding Redis. The win is the decision plus reason, not any one technology.

5. Close the session, then ask again in a fresh one

End the first agent session completely. Open a new session against the same project, same client registration, and same AMB home. Ask a generic question:

What is required before we merge a pull request?

The first win is when the new session answers with the stored decision and reason because AMB recalled it. Seeing the same fact in CLI Explore or Inspect is useful review, not the success check.

Exact Codex observation steps live in First-win acceptance.

After the first win

Once one decision survives a fresh session, you can inspect what AMB knows, keep repository facts current, and use the governance model below.

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

<venv-python> -m agent_mem_bridge inspect \
  --namespace project:my-app \
  --query "What is required before we merge a pull request?"

CODE / WHAT                     CONVERSATION / WHY
────────────────────            ──────────────────────────
Runtime: Python >=3.11          Decision: Merge only after
Package: my-app                 CI is green
Tests: pytest                   Reason: broken main blocked
                                two releases

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

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

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

Integrations

AMB works through local stdio MCP. Generic MCP clients are 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 labels are deliberately narrow and do not imply client certification. See Integrations for current setup instructions and boundaries.

Why the memory stays trustworthy

The useful part of long-lived project memory is not simply remembering more. It is being able to tell where knowledge came from, whether it is still current, and how it changed.

AMB therefore keeps several boundaries explicit:

This is where the earlier WHAT / WHY model belongs: it explains one of the mechanisms that keeps memory trustworthy, rather than defining the entire product.

What AMB is — and is not

AMB is a governed local project-memory layer for coding agents. It is designed to preserve useful context across sessions and tools while keeping durable knowledge, derived repository facts, provenance, and corrections distinguishable.

It is not a transcript archive, a promise that an agent will remember everything, or a system that silently converts every conversation into durable truth. There is no automatic learning.

Want the details?

Technical model

The product story above intentionally postpones implementation vocabulary. Internally, AMB keeps derived_repository data separate from governed durable memory so one cannot silently become the other. For maintainers and reviewers, the current authority flow is:

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]

SQLite/WAL rows are durable authority. Repository snapshots, FTS rows, embedding sidecars, compiled context, reports, and Explorer views are derived. Context bodies are rendered in process and are not durably persisted by the compiler.

Trust and privacy

AMB is local-first. It does not require a hosted memory service. It separates durable memory from coordination Signals and mutable Dynamic State, keeps provenance visible, and rejects raw transcripts, hidden reasoning, and inline artifact bodies from the durable episode path.

Read the Trust Boundary, Authority Contract, and Closed-Loop Episode Authority for the exact boundaries.

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 tool surface stays small. Setup, Project Init, Explore, Inspect, context assembly, and review reports remain CLI or internal derived workflows rather than becoming more MCP tools.

The local protocol cache contract is 300000/public for discovery and 0/private for the tool list; see MCP Compatibility for details.

Current maturity

Current package/source version is 0.33.0. Schema remains v12 and the public MCP surface remains exactly 17 tools. There is no automatic learning and no MCP tool #18. project init is the preferred first-project path. Default Explore is a Human-first view over existing repository-derived context and governed project knowledge. Current evidence and non-claims live in Production Status; published artifacts live in GitHub Releases.

Contributing

Read CONTRIBUTING.md for development and public-surface expectations, and SECURITY.md for vulnerability reporting.

Licensed under MIT.