Repository avatar
Search & Data Extraction
v0.3.2
active

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)

CI PyPI version Python: 3.10+ License: MIT agent-context-bridge MCP server – quality and maintenance score on Glama

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).

ACB demo: init β†’ record β†’ inject

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/audit stay CLI-only. If a checklist mentions a 3rd MCP tool, it is obsolete.


✨ What's new in v0.3.2

CommandWhat 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 auditIntegrity 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: 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

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).

PYPI
agent-context-bridge
Install Command
pip install agent-context-bridge