Skip to main content
Glama
agent-context-bridge

agent-context-bridge

README.md
# πŸŒ‰ Agent Context Bridge (ACB)

[![CI](https://github.com/shenn667/agent-context-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/shenn667/agent-context-bridge/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/agent-context-bridge.svg)](https://pypi.org/project/agent-context-bridge/)
[![Python: 3.10+](https://img.shields.io/badge/python-3.10%2B-brightgreen.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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).

![ACB demo: init β†’ record β†’ inject](docs/demo.gif)

*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

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