{"id":51224813,"url":"https://github.com/saagpatel/agent-bridge","last_synced_at":"2026-06-28T10:03:13.599Z","repository":{"id":365888563,"uuid":"1264782135","full_name":"saagpatel/agent-bridge","owner":"saagpatel","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-19T10:42:33.000Z","size":208,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T11:25:30.619Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/saagpatel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-10T07:12:48.000Z","updated_at":"2026-06-19T10:42:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/saagpatel/agent-bridge","commit_stats":null,"previous_names":["saagpatel/agent-bridge"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/saagpatel/agent-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saagpatel%2Fagent-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saagpatel%2Fagent-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saagpatel%2Fagent-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saagpatel%2Fagent-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saagpatel","download_url":"https://codeload.github.com/saagpatel/agent-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saagpatel%2Fagent-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34884278,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-28T10:03:12.871Z","updated_at":"2026-06-28T10:03:13.594Z","avatar_url":"https://github.com/saagpatel.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AgenticBridge\n\n**A SQLite-backed MCP server that gives your AI coding agents a shared memory bus.**\n\nPyPI distribution name: `AgenticBridge`. The Python module remains\n`agent_bridge`, the installed CLI remains `agent-bridge`, and the source\nrepository remains `agent-bridge`.\n\nYou run more than one coding agent now. Maybe Claude Code in one terminal and Codex in another. Maybe a planner model in a chat window dispatching work to executors on your machine. The problem isn't the agents — it's that **none of them know what the others did.** Every session starts cold. Work gets redone. Handoffs happen by copy-paste.\n\n`agent-bridge` is the missing shared state. It's a single [Model Context Protocol](https://modelcontextprotocol.io) server backed by one SQLite file, exposing a small set of tools that any MCP-speaking agent can call:\n\n- **Context sections** — long-lived shared notes with single-writer ownership.\n- **Activity log** — a rolling \"what happened\" feed across every agent.\n- **Handoffs** — a dispatch queue: one agent assigns work, another picks it up, whoever finishes clears it.\n- **Snapshots** — periodic per-agent state captures.\n- **Recall** — one full-text (FTS5) search across all of the above.\n- **Health / status** — observability over the bridge itself.\n\nNo server to host. No vector DB. No cloud. One file, one process, stdio transport.\n\n---\n\n## Why this exists\n\nThis is the genericized, open-source distillation of the coordination spine from a working one-person \"AI operating system\" — the piece that let a planning model, two terminal coding agents, and a few background jobs operate as a *team* instead of four amnesiacs. The original is personal; this is the reusable pattern, rebuilt clean with no machine-specific anything.\n\nThe design bet: **agents don't need a knowledge graph to coordinate. They need a shared scratchpad with ownership rules and good search.** Everything here serves that and stops there.\n\n---\n\n## Relationship to bridge-db\n\n`agent-bridge` is the generic, reusable shared-state bus extracted from a more\nopinionated local operating system. If you are working on the author's machine,\nthat production local spine is [`bridge-db`](https://github.com/saagpatel/bridge-db):\nit adds machine-specific integrations such as principal/auth rollout, source\ntrust, Claude.ai file fallback sync, shipped-event receipts, Notion sync\ncontracts, cost records, audit logs, and richer observability.\n\nUse `agent-bridge` when you want the portable core pattern: context sections,\nactivity, handoffs, snapshots, lexical recall, and health over one local SQLite\nfile. Do not register it as a second live bridge next to an existing `bridge-db`\ndeployment unless you intentionally want a separate, isolated state store.\n\n---\n\n## Install\n\nRequires Python 3.12+ and [uv](https://docs.astral.sh/uv/).\n\nFrom PyPI:\n\n```bash\nuvx --from AgenticBridge agent-bridge --status\n```\n\nFrom source:\n\n```bash\ngit clone https://github.com/saagpatel/agent-bridge\ncd agent-bridge\nuv sync --extra dev\nuv run pytest\nuv run ruff check .\n```\n\nRegister it with any MCP client. For Claude Code:\n\n```bash\nclaude mcp add --scope user agent-bridge -- uv run --directory /abs/path/to/agent-bridge python -m agent_bridge\n```\n\nFor Claude Desktop / other clients, point them at the command `uv run --directory /abs/path/to/agent-bridge python -m agent_bridge` over stdio.\n\nFor Codex, add a stdio server block to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.agent-bridge]\ncommand = \"uv\"\nargs = [\"run\", \"--directory\", \"/abs/path/to/agent-bridge\", \"python\", \"-m\", \"agent_bridge\"]\n```\n\nIf this machine already has a production bridge such as `bridge-db`, keep\n`agent-bridge` unregistered or point it at a deliberately separate test DB.\nRunning both against normal agent workflows will split coordination state.\n\n---\n\n## Release Notes\n\n### 0.1.2\n\n- Refresh locked transitive runtime dependencies flagged by Dependabot:\n  `cryptography`, `starlette`, and the `mcp` SDK path that brings in\n  Starlette.\n\n---\n\n## Configure (all optional)\n\nEverything machine-specific is an environment variable. Defaults are sensible.\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `AGENT_BRIDGE_DB_PATH` | `~/.local/share/agent-bridge/bridge.db` | Where the SQLite file lives |\n| `AGENT_BRIDGE_MARKDOWN_PATH` | next to the DB | Where the markdown mirror is written |\n| `AGENT_BRIDGE_AGENTS` | `claude-code,codex,claude-ai,human` | Allowlist of agent identities that may write |\n| `AGENT_BRIDGE_ACTIVITY_RETENTION` | `50` | Activity rows kept per agent |\n| `AGENT_BRIDGE_SNAPSHOT_RETENTION` | `10` | Snapshots kept per agent |\n\nAgent identities are **not** baked into the schema — set `AGENT_BRIDGE_AGENTS` to whatever your fleet is called (`cursor`, `aider`, `windsurf`, `human`, …).\n\n---\n\n## CLI\n\nThe same code runs as diagnostics without a live MCP client:\n\n```bash\nuv run python -m agent_bridge --status         # compact status JSON\nuv run python -m agent_bridge --doctor         # environment + DB diagnostics\nuv run python -m agent_bridge --export         # regenerate the markdown mirror\nuv run python -m agent_bridge --rebuild-index  # repair FTS index drift\nuv run python -m agent_bridge                  # start the MCP server (stdio)\n```\n\n---\n\n## The tools\n\n| Tool | What it does |\n|---|---|\n| `update_section` / `get_section` / `get_all_sections` | Owned context sections (first writer owns it) |\n| `log_activity` / `get_recent_activity` | Append + read the cross-agent activity feed |\n| `create_handoff` / `get_pending_handoffs` / `pick_up_handoff` / `clear_handoff` | The work-dispatch queue |\n| `save_snapshot` / `get_latest_snapshot` | Per-agent state captures |\n| `recall_search` | FTS5 search across everything |\n| `export_markdown` | Render a human-readable mirror |\n| `health` / `status` / `rebuild_index` | Observability + index repair |\n\n---\n\n## How it's built\n\nThe interesting parts are documented in [docs/architecture.md](docs/architecture.md), and the story of the system it came from is in [docs/one-person-ai-operating-system.md](docs/one-person-ai-operating-system.md). Three ideas carry the whole thing:\n\n1. **One write path per table, FTS mirror updated in the same transaction.** This single invariant is what keeps search honest — there's no separate \"reindex\" step that can fall behind. `health` checks it; `rebuild_index` repairs it.\n2. **Core logic is transport-free.** Every tool is a plain `async` function over a database connection. The MCP server is a thin wrapper. That's why the test suite never needs a live MCP client — it calls the functions directly.\n3. **Ownership in the app layer, not the schema.** Agent identities are config, so the same schema serves any team without a migration.\n\n---\n\n## Scope (what this is *not*)\n\nIt is not a knowledge base, a vector store, or a RAG system. It's coordination state plus lexical search. That boundary is deliberate — the original system tried the knowledge-store path and walked it back when most \"missed\" searches turned out to be for content that was never in the bridge to begin with. If you need semantic memory, put it behind its own MCP server and let the agents call both.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaagpatel%2Fagent-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaagpatel%2Fagent-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaagpatel%2Fagent-bridge/lists"}