agent-context-bridge
# π Agent Context Bridge (ACB)
[](https://github.com/shenn667/agent-context-bridge/actions/workflows/ci.yml)
[](https://pypi.org/project/agent-context-bridge/)
[](https://www.python.org/)
[](https://opensource.org/licenses/MIT)
> **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:
```json
{
"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):
```bash
# 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
```
```json
// 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`/`audit` stay 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 |
```bash
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: `inject` cost stays **flat** as the store grows; naive re-reading grows linearly. `search` returns 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):
1. **Each agent starts blind**: context learned by one agent is lost to the next.
2. **Token waste**: agents re-read entire repos to rediscover decisions already made (see benchmark above).
3. **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-mcp` stdio server, readonly tools for Claude.
- **Human-Readable & Machine-Parseable**: `records.jsonl` + `SHARED_CONTEXT.md` maintained automatically.
---
## π¦ Installation
```bash
pip install agent-context-bridge
```
Or from source:
```bash
git clone https://github.com/shenn667/agent-context-bridge.git
cd agent-context-bridge
pip install -e .
```
---
## π Quickstart
```bash
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:
```bash
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
```bash
pytest -v # 92/92 green on v0.3.2
```
---
## π License
Open-source under the [MIT License](LICENSE).
Authored by **shenn667** ([lehdev@yandex.com](mailto:lehdev@yandex.com)).
<!-- mcp-name: io.github.shenn667/agent-context-bridge -->
TDQS
Scored across 2 tools
The two tools are clearly distinct: acb_search queries records, while acb_status reports workspace/store health. There is no plausible overlap in selection, and the descriptions reinforce the boundary between search and diagnostics.
Both tools use the same acb_ prefix and a consistent lowercase snake_case noun/verb style. The naming pattern is predictable and easy to extend.
Two tools is thin for a bridge/server that implies shared context lifecycle operations beyond read-only search and diagnostics. The small surface is coherent but leaves the server feeling like a partial read-only facade.
The surface lacks write/append/inject/list/prune operations despite references to an 'inject' workflow and a shared context store. Agents can inspect or search existing context but cannot create or manage records, which is a significant lifecycle gap.