Agent-Memory-Bridge

Purpose

Agent-Memory-Bridge (AMB) is an engineering memory system for coding agents that provides persistent project memory through the MCP (Model Context Protocol) protocol. It aims to solve a problem: a project is not just its current set of 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 may be missing the reasons that make the project work sensibly. AMB provides a persistent place for these decisions, allowing coding agents to remember the decisions that truly matter across sessions, across tools, and across time.

Main Capabilities

• Persistent engineering memory: Provides a local stdio server through MCP, connecting compatible coding clients so agents can store and recall project decisions and their reasons.
• Project initialization and resolution: Project Init detects the local Git repository, suggests a namespace (such as project:my-app), waits for confirmation, and then derives the current repository baseline; project resolve . can resolve the namespace once already bound, without reinitializing.
• Explicit memory and trust boundaries: AMB does not infer decisions from code, nor does it archive conversation logs. Memory must be explicitly taught through the public store tool.
• WHAT/WHY separation: Repository facts (WHAT) come from clean Git commits and can be rebuilt; persistent project knowledge (WHY) remains explicit, reviewable, and governed.
• Locally inspectable: Explore answers "What does AMB currently know about this project?", and Inspect answers "Why did this piece of information surface for this question?", both of which are local and read-only.
• Governance model: Supports operations such as forget, feedback, promote, annotate, revise, and export, as well as run records and signal lease mechanisms, helping maintain the credibility of memory.
• Public MCP tools: A fixed set of 17 public MCP tools, including store, recall, browse, stats, forget, feedback, promote, annotate, revise, export, begin_run, record_run_event, get_run, complete_run, claim_signal, extend_signal_lease, ack_signal.

How to Use

1. Installation requirements: Requires Python 3.11+, Git, and an MCP-compatible coding client capable of starting a local stdio server or connecting via Streamable HTTP.
2. Recommended setup: You can install amb (daily memory recall, storage, revision, annotation) and amb-connect (host capability discovery, stdio/Streamable HTTP MCP, tool configuration) from the official companion skill Agent-Memory-Skills, for example by running npx skills add zzhang82/Agent-Memory-Skills --skill amb or --skill amb-connect in an agent CLI that supports skills. Skill descriptions can be read directly in SKILL.md.
3. Manual quick start: Use a virtual environment (.amb-venv) to get a stable Python launcher, replacing <venv-python> with the Python executable for the corresponding operating system.
4. Initialize or resolve a project: Project Init detects the Git repository, suggests a namespace, and waits for confirmation, then derives the baseline of the current repository; after binding, you can use project resolve . to resolve the namespace.
5. Run the generic MCP server: Run AMB as a standard MCP stdio server, with the command <venv-python>, the argument -m agent_mem_bridge, and a persistent AGENT_MEMORY_BRIDGE_HOME set so it is shared by all clients accessing that project's memory.
6. Use or inspect memory: Through the connected client, use the store tool to explicitly teach project decisions, for example "remember that we merge pull requests only after CI passes on the target branch, because main was broken this month and blocked two releases." The agent stores the explicit decision and reason under the project namespace. In a new session, ask "what needs to be satisfied before merging a pull request?", and the new session will answer with the stored decision and reason.
7. View memory: Use Explore to see what AMB currently knows about the project, and use Inspect to see why the information surfaced; both are local and read-only. Refreshing repository facts requires explicitly re-running the primitives, and refreshing does not change the persistent project WHY.

Applicable Scenarios

Suitable for projects that use coding agents for cross-session development, especially scenarios that need to preserve architectural decisions, gotchas, and domain knowledge to avoid re-explaining project context in every new session. Also suitable for teams that want a memory system that is local-first, reviewable, and traceable to sources.

Limitations

• AMB does not learn automatically, does not infer decisions from code, and does not automatically turn conversation records into persistent facts.
• Client connections are outside the scope of AMB Core; AMB does not discover, write to, or authenticate Codex, Claude, Cursor, OpenCode, Hermes, Cline, VS Code, or Antigravity. Clients need to independently configure AMB as a standard MCP stdio server pointing to the same local AMB home to share project memory.
• If an existing bridge is located at ~/.codex/mem-bridge, v0.36 will not automatically open it; you need to set AGENT_MEMORY_BRIDGE_HOME to point to that directory, or copy it to ~/.local/share/agent-memory-bridge.
• The current version is 0.36.0, the Schema is v12, and the public MCP tool surface is exactly 17, with no 18th MCP tool and no automatic learning.
• Health checks (such as doctor and verify) test server prerequisites and do not prove that the coding client has loaded the MCP configuration.
• The local protocol cache contract is discovery 300000/public, tool list 0/private; see MCP Compatibility for details.
• The license is MIT. Development and public surface expectations are in CONTRIBUTING.md, and vulnerability reports are in SECURITY.md.
• Some configuration details, specific installation commands, and lifecycle hook inputs are in Integrations; content not provided in this article is not yet available.