
agent-context-bridge
io.github.shenn667/agent-context-bridge
Shared context bridge for coding agents. 2 read-only tools: search past notes, check store health.
Documentation
π Agent Context Bridge (ACB)
Universal, zero-dependency context & memory bridge for autonomous coding agents. Share project decisions, architectural constraints, and task progress between Hermes Agent, Claude Code, OpenCode, and Codex.
β±οΈ The 10-second version: every AI coding tool starts blind β decisions made in one agent are lost to the next. ACB records them once (
acb record) and replays them in each agent's native format (acb inject, hook, or MCP tool).

50s, no audio: init β record β list β inject for Claude & Hermes. One store (.agent_bridge/) β every agent.
π Claude-native: MCP server acb-mcp (readonly)
Claude Code / Claude Desktop can query shared context directly via stdio MCP β no hook needed. The server exposes 2 strictly readonly tools: acb_search and acb_status. (prune stays CLI-only and never runs inside MCP.)
Copy-paste into claude.json (Claude Code) or Claude Desktop MCP config:
{
"mcpServers": {
"acb": {
"command": "acb-mcp",
"args": ["--dir", "/path/to/your/project"],
"transport": "stdio"
}
}
}
Then ask Claude: "search ACB for the auth decision" β acb_search returns the matching records. Verify with acb_status.
Prefer hooks? One command each β acb hooks claude --install writes .claude/settings.json (SessionStart β acb inject --target claude), --print previews it.
π Glama Gateway: seed usage in 2 minutes
Glama counts No recent usage when no tool call is observed in 30 days. Two copy-paste ways to generate usage (local counts for dev, Gateway counts for Discovery):
# A. Local stdio smoke test (no network, proves 2 readonly tools)
acb init --dir /tmp/acb-demo
acb record --dir /tmp/acb-demo --agent hermes-dev --topic "Gateway" --summary "Smoke OK"
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"acb_search","arguments":{"query":"smoke"}}}' \
'{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"acb_status","arguments":{}}}' \
| acb-mcp --dir /tmp/acb-demo
# expect: tools=[acb_search, acb_status], search count>=1, status initialized:true
// B. Via Glama Gateway (once a Glama release is published)
// 1. Glama page β Deploy on Glama β healthy β copy endpoint:
// https://glama.ai/endpoints/<your-connection-profile>/mcp
// 2. Paste into any MCP client:
{
"mcpServers": {
"acb-gateway": {
"command": "npx",
"args": [
"mcp-remote",
"https://glama.ai/endpoints/<your-connection-profile>/mcp"
]
}
}
}
// 3. Or click "Try in Browser" on the Glama server page β call acb_status.
// Every call through the Gateway URL is logged + counted as usage.
Note: only 2 MCP tools exist by design (
acb_search,acb_status, both readonly).prune/auditstay CLI-only. If a checklist mentions a 3rd MCP tool, it is obsolete.
β¨ What's new in v0.3.2
| Command | What it does |
|---|---|
acb search "query" | Full-text search over shared context, newest-first (--limit, --json) |
acb status [--json] | Store health: record count, size, agent targets covered |
acb audit | Integrity check of records.jsonl (corrupt lines, missing fields) |
acb prune --keep-last N [--dry-run] | Keep the N most recent records, drop the rest |
acb search "SQLite auth" # 2 hits, most recent first
acb status # 3 records, 1642 bytes, hermes/claude/opencode/codex
acb prune --keep-last 20 --dry-run # preview before trimming
π Measured token savings: β98.7%
Real benchmark from
QA_REPORT_v0.3.0.md(v0.3.0, 30-record store, tokens β chars/4, measured not estimated):
Scenario ~Tokens Naive: re-read sources at agent switch (7 .py, 60 768 chars) 15 192 ACB inject(bounded to 5 latest, constant cost)198 (15 192 β 198) / 15 192 = 98.7% saved. Also β95.7% vs re-reading decision docs (4 555 β 198) and β90.5% vs full context file (2 078 β 198).
Key property:
injectcost stays flat as the store grows; naive re-reading grows linearly.searchreturns only relevant hits.
π‘ The Problem: Multi-Agent Context Fragmentation
When switching between modern AI developer tools (e.g., Claude Code in terminal, Hermes swarm in background, OpenCode in IDE):
- Each agent starts blind: context learned by one agent is lost to the next.
- Token waste: agents re-read entire repos to rediscover decisions already made (see benchmark above).
- No persistent audit trail: critical architectural choices disappear with session resets.
ACB solves this with a lightweight, file-backed offline store (.agent_bridge/) and native adapters per agent.
β¨ Features
- Zero Runtime Dependencies: pure stdlib (
argparse,json,dataclasses,datetime). - Offline & Local-First: no daemon, no database, no network. Works 100% offline.
- Multi-Agent Adapters: native formatters for Hermes, Claude Code, OpenCode, Codex.
- MCP-native:
acb-mcpstdio server, readonly tools for Claude. - Human-Readable & Machine-Parseable:
records.jsonl+SHARED_CONTEXT.mdmaintained automatically.
π¦ Installation
pip install agent-context-bridge
Or from source:
git clone https://github.com/shenn667/agent-context-bridge.git
cd agent-context-bridge
pip install -e .
π Quickstart
acb init
acb record \
--agent hermes-dev \
--topic "Database Engine" \
--summary "Adopted SQLite WAL mode for local agent state storage" \
--details "PostgreSQL required Docker; SQLite gives zero-latency offline access." \
--tag db --tag architecture
acb list
acb search "SQLite"
acb inject --target claude # Claude Code SessionStart hook
acb inject --target hermes # Hermes system context
acb inject --target opencode # OpenCode
β Local demo (3 commands)
Reproducible from a fresh clone β proves install + record/inject + consistent version:
pip install -e .
acb init --dir /tmp/acb-demo && acb record --dir /tmp/acb-demo --agent hermes-dev --topic "Demo" --summary "Bridge OK" && acb inject --dir /tmp/acb-demo --target hermes
acb --version
Expected: agent-bridge 0.3.2 (matches pyproject.toml, __init__.__version__, and tag v0.3.2 β release.yml refuses publish on mismatch).
ποΈ Architecture
ββββββββββββββββββββββββ
β Your Project Repo β
ββββββββββββ¬ββββββββββββ
β
.agent_bridge/SHARED_CONTEXT.md
.agent_bridge/records.jsonl
β
βββββββββββββββββββββββΌββββββββββββββββββββββ
βΌ βΌ βΌ
βββββββββββββ βββββββββββββ βββββββββββββ
β Hermes β βClaude Codeβ β OpenCode β
β Adapter β β Adapter β β Adapter β
βββββββββββββ βββββββββββββ βββββββββββββ
Claude Desktop/Code βββ acb-mcp (stdio, readonly)
π§ͺ Running Tests
pytest -v # 92/92 green on v0.3.2
π License
Open-source under the MIT License. Authored by shenn667 (lehdev@yandex.com).
agent-context-bridgepip install agent-context-bridge