Production-grade MCP server for multi-agent communication with Memory Engineering
agent-bridge enables multiple AI coding agents (OpenCode, Claude Code, Cursor, etc.) working in different repositories to share context and communicate — without copy-pasting.
repo-A/frontend repo-B/backend repo-C/mobile
│ │ │
Agent 1 Agent 2 Agent 3
│ │ │
└──────────────────┴─────────────────┘
No communication!
Must copy-paste context
Decisions are invisible
repo-A/frontend repo-B/backend repo-C/mobile
│ │ │
Agent 1 Agent 2 Agent 3
│ │ │
└──────────────────┴─────────────────┘
│
~/agent-bridge/ (shared)
├── agents/
│ ├── frontend/MEMORY.md
│ ├── backend/MEMORY.md
│ └── mobile/MEMORY.md
└── shared/decisions.md
▼
Full visibility!
Context shared
Decisions tracked
| Feature | Description |
|---|---|
| Real-time Notifications | .unread signal files — near-instant message detection (~300ms vs 2-4s) |
| Thread Messaging | Group related messages with thread_id — filter inbox by thread |
| Lifecycle Detection | 🟢 active / 🟡 idle / 💤 stale — know if agents are alive or dead |
| Heartbeat | Auto-heartbeat on publish and wake — stale agents clearly marked |
| 3-Tier Memory | Global → Agent → Session hierarchy |
| AAAK Compression | 70% token savings vs markdown |
| Lexical Search | Find decisions without reading files |
| Smart Pruning | Preserves head + tail, cuts middle |
| File Locking | Atomic writes — safe for concurrent agents |
git clone https://github.com/your-username/agent-bridge.git
cd agent-bridge
bun installOpenCode (opencode.jsonc):
Claude Code (.claude/mcp.json):
{
"mcpServers": {
"agent-bridge": {
"command": "bun",
"args": ["/path/to/agent-bridge/src/server.js"]
}
}
}Custom data directory (optional):
export BRIDGE_DIR="/shared/network/path/agent-bridge"// Session start — auto-registers + heartbeat
bridge_wake("frontend") // ~500 tokens — loads context
bridge_inbox("frontend") // check messages (clears .unread)
// Check agents with lifecycle status
bridge_who() // 🟢 backend:working | 💤 mobile:stale (2h ago)
// Thread-based messaging
bridge_send("frontend", "backend", "API format?",
"Need endpoint schema", "question", { thread_id: "auth" })
bridge_wait_reply("frontend", { from: "backend" }) // near-instant
// Filter inbox
bridge_inbox("frontend", { filter: "thread", thread_id: "auth" })
// Session end
bridge_consolidate("frontend", "- Login complete\n- Used React Query")| Tool | Tokens | Purpose |
|---|---|---|
bridge_wake |
~500 | Session start — load context + auto-register + heartbeat |
bridge_who |
~50 | List agents with lifecycle status (🟢🟡💤) |
bridge_summary |
~50 | Quick view of agent (AAAK) |
bridge_search |
~400 | Find decisions — lexical search |
bridge_memory |
~200 | Read/write MEMORY.md |
| Tool | Tokens | Purpose |
|---|---|---|
bridge_read |
~500+ | Full context (prefer bridge_summary) |
| Tool | Purpose |
|---|---|
bridge_send |
Send message (supports thread_id) |
bridge_inbox |
Read messages (filter: unread/all/thread) |
bridge_wait_reply |
Wait for reply — .unread signal detection (~300ms) |
| Tool | Purpose |
|---|---|
bridge_publish |
Update status + heartbeat |
bridge_note |
Write shared notes |
bridge_consolidate |
Session end — save decisions |
bridge_clear |
Delete agent data |
Before v3.0, bridge_wait_reply polled by reading the entire inbox file every 2 seconds. Now it checks a lightweight .unread signal file every 300ms — nearly free and near-instant:
| v2.5 | v3.0 | |
|---|---|---|
| Detection method | Read full inbox | fs.existsSync(.unread) |
| Poll interval | 2000ms | 300ms |
| Latency | 2-4 seconds | ~300ms |
| Token waste | Reads file each poll | Zero — no file read needed |
Group related messages with thread_id:
bridge_send("frontend", "backend", "API format?", "...", "question",
{ thread_id: "auth" })
// Read only auth thread
bridge_inbox("frontend", { filter: "thread", thread_id: "auth" })
// Wait for reply in auth thread
bridge_wait_reply("frontend", { thread_id: "auth" })bridge_who now shows real-time agent status:
👥 AGENTS (3):
🟢 backend | working | "Building auth API"
💤 mobile | idle | stale (3h ago)
🟡 frontend | review | "Awaiting code review"
| Icon | State | Heartbeat |
|---|---|---|
| 🟢 | active | < 5 minutes ago |
| 🟡 | idle | < 30 minutes ago |
| 💤 | stale | > 30 minutes ago (probably dead) |
src/
├── server.js — entry point (MCP server init)
├── config.js — constants, path helpers, lifecycle thresholds
├── lock.js — atomic file locking
├── watcher.js — .unread signal file management
├── utils.js — parsing, pruning, token estimation, lifecycle
├── memory.js — auto-memory, AAAK, search, agent listing
└── tools.js — all 13 MCP tool registrations
~/agent-bridge/
├── _index.md — Auto-generated agent index
├── agents/
│ ├── frontend/
│ │ ├── .unread — Signal file (real-time detection)
│ │ ├── MEMORY.md — Auto-memory (200 lines)
│ │ ├── status.md — Session context + heartbeat
│ │ └── inbox.md — Messages (with thread_id support)
│ └── backend/
│ ├── .unread
│ ├── MEMORY.md
│ ├── status.md
│ └── inbox.md
└── shared/
├── decisions.md
└── conventions.md
AAAK = Abbreviated Agent Articulation Kernel — 70% fewer tokens vs markdown.
AGENT:frontend | ST:working | UPD:2026-04-11T10:00
SUM:Building login page
DET:Using React Hook Form. Waiting for backend...
LOG:10:00 started | 09:30 got spec
TAGS:auth,wip
All read-modify-write operations use an exclusive lock (filePath.lock) so concurrent agents never corrupt each other's files. Includes stale-lock detection for crashed processes.
- Bun 1.0+
- OpenCode, Claude Code, or any MCP-compatible client
- Full Documentation — complete reference
- Skill Guide — quick workflow guide
- Changelog — version history
MIT — see LICENSE
PRs welcome. Key areas:
- Knowledge graph integration
- Semantic search with embeddings
- Web UI for monitoring
- Conflict resolution
{ "mcp": { "servers": { "agent-bridge": { "command": "bun", "args": ["/path/to/agent-bridge/src/server.js"] } } } }