Skip to main content

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


✨ What's new in v0.3.1

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.1 (matches pyproject.toml, __init__.__version__, and tag v0.3.1 — 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   # 73/73 green on v0.3.1

📄 License

Open-source under the MIT License. Authored by shenn667 (lehdev@yandex.com).

Metadata

Release files for agent-context-bridge 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-context-bridge 0.3.1
File Size Uploaded Provenance Actions
agent_context_bridge-0.3.1.tar.gz 365.8 kB With provenance Details for agent_context_bridge-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-context-bridge 0.3.1
File Interpreter ABI Platform Actions
agent_context_bridge-0.3.1-py3-none-any.whl Python 3 none any Details for agent_context_bridge-0.3.1-py3-none-any.whl

Total release size: 392.2 kB

Release files / agent_context_bridge-0.3.1.tar.gz

Download URL agent_context_bridge-0.3.1.tar.gz
Size 365.8 kB
Tags Source
SHA-256 checksum
How to use checksums
841340474d7e684e34e8c6e8d79fb859754df02cdca3009b40deee073233b38e
BLAKE2b-256 checksum
How to use checksums
fba565eb067a057ad121a76d290ba46139e2f98f8c7ed3fc4f47c5aa8cdf3d27
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / agent_context_bridge-0.3.1-py3-none-any.whl

Download URL agent_context_bridge-0.3.1-py3-none-any.whl
Size 26.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
26e4c04a03c4fb65411cefbc75421423cf84115ee85729ae2b901f9347a7c3ee
BLAKE2b-256 checksum
How to use checksums
a95e77cc98b0c5b17d4331c9a8e5ff398b8bc74b16363b4b55c69afaf9c49832
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for agent-context-bridge 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agent_context_bridge-0.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page