Skip to main content
Glama
agent-context-bridge

agent-context-bridge

πŸŒ‰ Agent Context Bridge (ACB)

CI PyPI version Python: 3.10+ License: 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).

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.


Related MCP server: AgentBridge

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

Available Tools

2 tools
acb_statusA
Read-onlyIdempotent

Read-only workspace diagnostic for the shared context store. Returns {initialized, records, store_bytes, last_updated, targets, version}. Never creates the store; uninitialized workspace returns initialized:false. Use to verify ACB wiring/health before search/inject.

Inputs: dir.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 2 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness2/5

    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.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables two local coding agents to read each other's user-visible history, search past decisions with source tracing, and save confirmed conclusions into a shared memory. Also supports credential-status checks and limited task handoff between Codex and Antigravity over MCP stdio.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Persistent project memory and task management for AI coding agents through MCP. Lets Claude Code, Cursor, Codex and other MCP clients save decisions and bug fixes, search relevant context, and reuse it across sessions.
      1
      MIT