agent-memory-bridge

One bridge. Every AI coding agent. One shared, searchable memory.

English · 简体中文

Mirrors — Gitee · GitHub · npm: agent-memory-bridge · npm: @camplus360/agent-memory-bridge-opencode · npm: @camplus360/agent-memory-bridge-dsh

✨ Why you need this

Run several AI coding agents — OpenCode, CodeBuddy, Codex CLI, pi, Hermes, DeepSeek Harness (dsh) — and each one invents its own memory capture: different hooks, different payloads, different corner cases. Maintaining six separate hacks means the protocol drifts, and one broken hook silently stops remembering anything.

agent-memory-bridge collapses all of that into one source of truth — a single, shared, searchable memory across every agent you use.

🎯 Highlights

Features

• One repository, pick your agents — install adapters for OpenCode, CodeBuddy, Codex CLI, pi, Hermes and/or dsh with a single ./install.sh --agent <name>.
• One protocol, six adapters — session id namespacing (<agent>-<sessionId>) prevents cross-agent collisions; payload fields are identical everywhere.
• npm-installable adapters — pi (npm:agent-memory-bridge), opencode (npm:@camplus360/agent-memory-bridge-opencode) and dsh (npm:@camplus360/agent-memory-bridge-dsh) ship as installable npm packages; one command to add, one to enable.
• Pluggable backends — claude-mem (session-based, LLM summaries), mem0 (flat, server-side fact extraction), or both (dual-write), switched with one environment variable.
• Hook-safe by design — short timeouts, retries with backoff, and a silent exit 0 when the worker is down. Your editor never hangs on a memory call.
• Correct JSON — built with jq / python3, so quotes, backslashes and multiline tool output cannot corrupt a payload.
• Tested — the OpenCode plugin ships with 8 mocked tests; test-hooks.sh runs every shell hook against a local mock worker.
• Cross-platform — pure bash + curl + python3, no compiled dependencies; runs on Linux, macOS and WSL.

Architecture

flowchart LR
    subgraph Agents
        OC[OpenCode<br/>native plugin]
        CB[CodeBuddy<br/>hooks.json]
        CD[Codex CLI<br/>hooks.json]
        PI[pi<br/>npm extension]
        HM[Hermes<br/>engine.py snippet]
        DSH[dsh<br/>npm Cordis plugin]
    end

    OC --> W
    CB -->|hook JSON on stdin| W
    CD -->|hook JSON on stdin| W
    PI --> W
    HM -->|subprocess| W
    DSH --> W

    W["claude-mem-worker.py<br/>(single source of truth)<br/>init / observation / summarize / search"]

    W -->|CLAUDE_MEM_BACKEND=claude-mem| CM["claude-mem worker :37701<br/>LLM summary + embeddings"]
    W -->|CLAUDE_MEM_BACKEND=mem0| M0["mem0 :8000<br/>POST /memories + /search"]
    W -->|CLAUDE_MEM_BACKEND=both| CM
    W --> M0

    CM --> DB[("SQLite + Chroma")]

All six agents share one memory store, so something you told OpenCode can be recalled from CodeBuddy — or Codex, pi, Hermes, or dsh.

Quick start

Prerequisites

• bash, curl, jq, python3
• a running memory backend:
  • claude-mem (default): install and start the worker, then verify curl -s http://127.0.0.1:37701/api/health returns "status":"ok";
  • mem0 (optional): a mem0 server on port 8000.

# Gitee (faster in mainland China)
git clone https://gitee.com/camplus/agent-memory-bridge.git
# or GitHub
git clone https://github.com/camplus360/agent-memory-bridge.git
cd agent-memory-bridge

Install

./install.sh --all                 # every supported agent
./install.sh --agent codebuddy     # just one
./install.sh --agent codex         # Codex CLI (merges ~/.codex/hooks.json)
./install.sh --dry-run             # preview every action without writing

The installer copies claude-mem-worker.py to ~/.local/share/claude-mem/, writes a .env / .env.example template, and places each chosen adapter in the agent's real config location. Override the root with --prefix or CLAUDE_MEM_INSTALL_ROOT.

Verify

python3 ~/.local/share/claude-mem/claude-mem-worker.py health   # backend reachable
./test-hooks.sh                                              # exercise every hook with a mock worker

Then follow the one-time enable step for your agent (register the plugin, merge hooks into settings.json, etc.) — see docs/INSTALL.md.

Supported agents

Agents with a native HTTP client call the worker directly; agents that can only execute external commands go through the shell wrapper. Both produce the exact same protocol.

Choosing a memory backend

Set CLAUDE_MEM_BACKEND (default claude-mem):

CLAUDE_MEM_BACKEND=mem0 python3 claude-mem-worker.py observation codebuddy s1 "..." /tmp user_prompt codebuddy
CLAUDE_MEM_BACKEND=both python3 claude-mem-worker.py search "keyword" 5

mem0-worker.py is a thin wrapper equivalent to CLAUDE_MEM_BACKEND=mem0. mem0 variables: MEM0_HOST (localhost), MEM0_PORT (8000), MEM0_API_KEY (optional), MEM0_USER_ID ($USER), MEM0_INFER (true), or a full MEM0_BASE_URL.

mem0 tenancy pitfall: an API key is bound to a specific user view. Writes and searches must use the same view, or a stored memory will never show up in search.

Unified script reference

python3 claude-mem-worker.py init        <agent> <sessionId> [cwd] [project] [prompt]
python3 claude-mem-worker.py observation <agent> <sessionId> <text> [cwd] [toolName] [platformSource]
python3 claude-mem-worker.py summarize   <agent> <sessionId> [lastAssistantMessage] [platformSource]
python3 claude-mem-worker.py turn        <agent> <sessionId> <transcriptPath> [cwd] [platformSource]
python3 claude-mem-worker.py search      <query> [limit]
python3 claude-mem-worker.py health
python3 claude-mem-worker.py hook        <agent>   # reads Claude Code/CodeBuddy/Codex hook JSON from stdin

hook maps stdin events automatically:

Environment overrides: CLAUDE_MEM_WORKER_HOST (127.0.0.1), CLAUDE_MEM_WORKER_PORT (37701), CLAUDE_MEM_HTTP_TIMEOUT (8s), CLAUDE_MEM_HTTP_RETRIES (2), CLAUDE_MEM_QUIET (0).

Documentation

• docs/INSTALL.md — full step-by-step install and per-agent enablement
• docs/CONFIG-REFERENCE.md — copy-ready config snapshots + pitfalls per agent
• docs/AGENT-RUNTIME-ARCH.md — the worker's two data paths (REST storage vs. Claude-CLI-based compression)
• docs/REGRESSION-TEST-STANDARD.md — acceptance baseline: hook events, recall and summaries
• agents/pi/DEPLOY.md — deploying the pi memory extension

Chinese originals of the four guides are kept under docs/zh/.

Roadmap

• more agent adapters (Claude Code CLI, Gemini CLI, Cursor, ...)
• a packaged release with checksums
• end-to-end tests against an ephemeral worker container

Contributing

Issues and PRs are welcome. A new agent adapter needs only two things: capture its lifecycle events (session start, user prompt, tool calls, assistant reply, session end) and map them to the unified script or the equivalent JSON payload. Please add a mock-based test or a test-hooks.sh case.

License

This is a multi-licensed repository (see NOTICE for the full component inventory):

• the unified worker client, installer, tests, and the CodeBuddy / Codex / Hermes / OpenCode / dsh adapters are original work under the MIT License — LICENSE;
• the agents/pi/ adapter is a derivative fork kept under GNU AGPL-3.0-or-later (it derives from the AGPL-era claude-mem / pi-agent-memory) — agents/pi/LICENSE and agents/pi/NOTICE.

The components communicate only by spawning separate processes and over local HTTP; they are separate programs aggregated in one repository, so the AGPL component does not propagate to the MIT-licensed parts. The claude-mem and mem0 workers are external Apache-2.0 programs, merely interoperated with and not bundled in this repository.