{"id":51882014,"url":"https://github.com/phenomenoner/a2a-superhub","last_synced_at":"2026-07-25T14:02:27.671Z","repository":{"id":372282893,"uuid":"1278852835","full_name":"phenomenoner/a2a-superhub","owner":"phenomenoner","description":"Durable A2A coordination with opt-in Markdown memory, offline inboxes, knowledge graph and timeline, plus authorized Qdrant hybrid retrieval.","archived":false,"fork":false,"pushed_at":"2026-07-20T05:09:09.000Z","size":334,"stargazers_count":0,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-20T07:06:57.906Z","etag":null,"topics":["a2a","a2a-protocol","agent-memory","agent2agent","ai-agents","knowledge-graph","llm-agents","local-first","mcp","memory-layer","multi-agent-systems","qdrant"],"latest_commit_sha":null,"homepage":"https://phenomenoner.github.io/a2a-superhub/","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/phenomenoner.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":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-24T06:42:48.000Z","updated_at":"2026-07-20T05:09:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/phenomenoner/a2a-superhub","commit_stats":null,"previous_names":["phenomenoner/a2a-superhub"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/phenomenoner/a2a-superhub","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenomenoner%2Fa2a-superhub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenomenoner%2Fa2a-superhub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenomenoner%2Fa2a-superhub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenomenoner%2Fa2a-superhub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phenomenoner","download_url":"https://codeload.github.com/phenomenoner/a2a-superhub/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenomenoner%2Fa2a-superhub/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35881541,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-25T02:00:06.922Z","response_time":64,"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":["a2a","a2a-protocol","agent-memory","agent2agent","ai-agents","knowledge-graph","llm-agents","local-first","mcp","memory-layer","multi-agent-systems","qdrant"],"created_at":"2026-07-25T14:02:26.955Z","updated_at":"2026-07-25T14:02:27.663Z","avatar_url":"https://github.com/phenomenoner.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A2A Superhub\n\n\u003e **Your agents collaborate. Then they forget everything.**\n\u003e\n\u003e A2A Superhub is a durable coordination hub for heterogeneous AI agents — with a\n\u003e shared **memory plane** (opt-in durable memory, offline sharing, hybrid\n\u003e retrieval, and a standards-based MCP sidecar) where collaboration history becomes knowledge\n\u003e any agent can query. Even the agents that were offline when it happened.\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-3776ab.svg)](pyproject.toml)\n[![Runtime deps](https://img.shields.io/badge/runtime%20deps-zero-brightgreen.svg)](pyproject.toml)\n[![Memory plane](https://img.shields.io/badge/memory%20plane-MCP%20integrated-16a34a.svg)](docs/DESIGN.md)\n\n**[Product site](https://phenomenoner.github.io/a2a-superhub/)** ·\n**[Shared memory design and implemented surfaces](docs/DESIGN.md)** ·\n[Local agent operations](docs/LOCAL_AGENT_OPERATIONS.md) · [API](docs/API.md) ·\n[Operations](docs/OPERATIONS.md) · [Adapters](docs/ADAPTERS.md) · [Security](docs/SECURITY.md)\n\n---\n\n## The problem\n\nModern agent stacks are heterogeneous by default: one team runs an A2A-capable\nservice, another exposes MCP tools, another has an ACP editor adapter, another\nonly has a CLI. Making them work together hits three walls:\n\n1. **N×N glue.** Every agent pair invents its own integration, again.\n2. **Session amnesia.** Work products survive; the *context* — who decided what,\n   why, and what was learned — dies with the session.\n3. **Absent peers stay ignorant.** What Agent A learns about Agent B never\n   reaches B, unless a human plays messenger.\n\nSuperhub attacks all three with one small, local-first hub.\n\n## Two planes, one hub\n\n| Plane | Status | What it gives you |\n|---|---|---|\n| **Coordination plane** | ✅ Shipped (v1) | Durable task lifecycle, progress events, content-addressed artifacts, Agent Card registry, idempotency, bearer auth, rate limits. Dependency-free Python + SQLite. |\n| **Memory plane** | ✅ MCP-integrated foundation (opt-in) + [future design](docs/DESIGN.md) | Implemented Markdown truth, durable ops queue, FTS5 fallback, FastEmbed/Qdrant hybrid retrieval, authorized timeline/graph, multi-consumer inbox, safe wakeup, task-log, a stateless 10-tool MCP stdio sidecar, reference adapter, operator Skill, optional PDF/image text derivation, and offline operational controls. A complete A2A 1.0 binding remains future work; the supported operational workload waits for published package/rollback and 24-hour soak evidence. |\n\nAgents remain peers, not children of a central framework. The hub owns\ncross-agent semantics; adapters own local runtime integration.\n\n## The moment that sells it\n\n\u003e **Monday 09:12** — you tell Agent A: *\"B's gateway keeps dropping tokens after\n\u003e restarts.\"* Agent A writes a memory note tagged `about: [agent.beta]`.\n\u003e\n\u003e **Thursday 03:40** — Agent B wakes up, pulls its memory inbox, and **already\n\u003e knows** — with full provenance: who said it, when, in which task.\n\n```mermaid\nsequenceDiagram\n  participant U as User\n  participant A as Agent A\n  participant H as Superhub\n  participant B as Agent B (offline)\n\n  U-\u003e\u003eA: \"B's gateway keeps dropping tokens\"\n  A-\u003e\u003eH: POST /v1/memory/notes {type: observation, about: [agent.beta], body: verbatim}\n  H-\u003e\u003eH: markdown note → SQLite FTS index → inbox/agent.beta\n  Note over B: ...days later, B starts a session...\n  B-\u003e\u003eH: GET /v1/memory/wakeup?consumerId=desktop.startup\n  H--\u003e\u003eB: profile + unread inbox (the observation, with provenance)\n  Note over B: B now has delimited, provenance-rich data and opt-in hybrid search.\n```\n\nMemory sharing becomes **asynchronous message passing**: writing is delivery,\nquerying is catching up. No agent has to be online at the same time as any other.\n\n## Current implemented surfaces\n\nShipped and tested; the coordination core remains dependency-free:\n\n- Standalone state root with SQLite task and event storage.\n- Task create / get / list / cancel / event operations with idempotency keys.\n- Content-addressed artifact store with SHA-256 verification, raw binary and\n  restart-safe resumable uploads, private/shared/direct visibility, and bounded\n  PDF text plus optional Tesseract OCR derivation.\n- A2A 1.0 `Part` oneof mapping for `text`, `raw`, `url`, and `data`; the full\n  protocol binding remains distinct from the legacy JSON-RPC facade.\n- Agent Card registration and listing.\n- Minimal JSON-RPC A2A facade: `message/send`, `tasks/get`, `tasks/cancel`.\n- Optional bearer-token auth and per-client rate limiting.\n- CLI and HTTP server, Python standard library only.\n- Optional MCP 2025-11-25 stdio sidecar with ten memory/task tools, authorized\n  resources, subscription notifications, and polling fallback guidance.\n- Payload-free admin diagnostics plus offline authoritative backup/clean restore,\n  recoverable retention, and parity-gated Qdrant provider activation/rollback.\n\n### Quickstart\n\n```bash\npython -m venv .venv\n. .venv/bin/activate  # Windows: .venv\\Scripts\\activate\npip install -e .\n\na2a-superhub --state ./state init\na2a-superhub --state ./state serve --host 127.0.0.1 --port 8787\n```\n\n```bash\ncurl http://127.0.0.1:8787/healthz\ncurl -s http://127.0.0.1:8787/v1/tasks \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"fromAgent\": \"agent.alpha\",\n    \"toAgent\": \"agent.beta\",\n    \"intent\": \"agent.query\",\n    \"idempotencyKey\": \"demo-001\",\n    \"payload\": {\"summary\": \"Summarize the attached artifact\"}\n  }'\n```\n\nFull API reference in [docs/API.md](docs/API.md). Adapter contract in\n[docs/ADAPTERS.md](docs/ADAPTERS.md). MCP setup and exact behavior are in\n[docs/MCP_AGENT_INTEGRATION.md](docs/MCP_AGENT_INTEGRATION.md).\nArtifact transport, derivation, trust labels, and rollback behavior are in\n[docs/ARTIFACTS_AND_DERIVATION.md](docs/ARTIFACTS_AND_DERIVATION.md).\nFor an authenticated loopback hub with separate agent identities, a packaged\nSkill, secret-safe MCP host configuration, and an authorized cross-agent smoke\nflow, follow [Run a local hub for agent use](docs/LOCAL_AGENT_OPERATIONS.md).\n\n### Connect an MCP client\n\nKeep the HTTP hub running with memory enabled, then configure the client to\nlaunch the stateless sidecar:\n\n```bash\npip install -e \".[memory-core,mcp]\"\nexport A2A_SUPERHUB_URL=http://127.0.0.1:8787\nexport A2A_SUPERHUB_TOKEN=replace-with-a-token-handle\na2a-superhub-mcp\n```\n\nOn Windows PowerShell, set the variables with `$env:A2A_SUPERHUB_URL=...` and\n`$env:A2A_SUPERHUB_TOKEN=...`. The token belongs in the environment, not in the\nMCP command line. Each sidecar holds no hub state and can be restarted or run\nalongside other clients.\n\n## Memory plane: 🧱 Foundation (opt-in)\n\nThe full design is public — **[docs/DESIGN.md](docs/DESIGN.md)**. Durable memory is available\nonly with `pip install -e \".[memory-core]\"` and `serve --enable-memory`; it is\noff by default and preserves the coordination-only runtime. Delivery, task-log,\nand watcher repair remain separately gated. The foundation has repository-level\nend-to-end and restart/replay coverage; it is not a release, SLA, soak, or\noperational-readiness claim. The short version:\n\n**Three ingredients, deliberately boring:**\n\n1. **Markdown is the database.** Every memory is a plain `.md` file with YAML\n   frontmatter and `[[wikilinks]]` — human-readable, git-versionable,\n   Obsidian-compatible. Agents and humans edit the same files.\n2. **A memory layer, not a summarizer.** Verbatim in, intelligence out: notes are\n   stored word-for-word (no LLM extraction at write time). Structure comes from\n   explicit frontmatter and links. Temporal validity is an explicit\n   `supersedes:` chain, not model guesswork.\n3. **Opt-in hybrid retrieval with FTS5 fallback.** Qdrant dense+sparse candidates\n   are authorization-filtered in every prefetch and authorized again against\n   Markdown. The default core remains dependency-free and keyword-only.\n\n**On top of that:**\n\n- **Knowledge graph + timeline** — entities (agents, humans, projects, topics,\n  tasks, artifacts) and typed, timestamped edges in SQLite. Interaction context\n  (\"who said what about whom, when, in which task\") is a query, not an inference.\n- **Wake-up packs** — one call returns an agent's boot context: profile, unread\n  inbox, recent relevant notes. Worst-case integration is `curl` + paste.\n- **Task-log sedimentation** — when explicitly enabled for an allowlisted intent,\n  terminal hub tasks can become structured memory notes without raw payloads.\n- **MCP sidecar + reference adapter + operator Skill** — ten stable tools and\n  two `memory://` resources reuse the HTTP authorization boundary; a removable client adapter negotiates\n  identity/capabilities, inserts only delimited untrusted data, and acks only\n  after delivery. The packaged Skill provides private local bootstrap,\n  identity-bound MCP launch, doctor, smoke, and install workflows.\n- **Searchable artifact text** — when explicitly enabled, bounded PDF extraction\n  and image OCR create a clearly labeled untrusted Markdown note. Every read and\n  search result is re-authorized against the current source artifact manifest;\n  cleanup removes the derived note/index without deleting the checksum-authoritative source.\n- **Burn-the-index guarantee** — the current FTS/KG SQLite index is derived.\n  Delete it and rebuild the same visible note/edge set from Markdown. Delivery,\n  ack, job, task, artifact, and auth state are separate authoritative backups.\n\n## How it compares\n\n| | A2A task coordination | Durable shared memory | Knowledge graph + timeline | Offline inbox catch-up | Local-first, no API keys |\n|---|:-:|:-:|:-:|:-:|:-:|\n| **A2A Superhub (opt-in shared memory with MCP)** | ✅ | ✅ | ✅ | ✅ | ✅ |\n| [mem0](https://github.com/mem0ai/mem0) — app↔user memory | — | ✅ | partial | — | partial |\n| [memX](https://github.com/MehulG/memX) — realtime shared state | — | — (ephemeral KV) | — | — | ✅ |\n| A2A registries — agent directories | discovery only | — | — | — | varies |\n| [basic-memory](https://github.com/basicmachines-co/basic-memory) — human↔AI notes | — | ✅ | ✅ | — | ✅ |\n\nMemory frameworks remember *users*. State layers share *the present*. Superhub\ngives a fleet of peer agents a durable, queryable, **shared past**.\n\nThe implemented surface has repository end-to-end, restart/replay, official MCP\nSDK, artifact transport/derivation, and cross-transport evidence. It does not\nmean complete A2A 1.0 parity, production deployment, operational soak, audio\ntranscription, or image captioning.\n\n## Roadmap\n\n- **Contract and security baseline — 🧱 Foundation:** executable identity,\n  note, API, protocol, package, and Skill contracts.\n- **Durable memory and offline sharing — 🧱 Foundation (opt-in):** durable\n  Markdown, separated operational/derived stores, FTS, inbox/wakeup, a reference\n  adapter, and an operator Skill.\n- **Hybrid retrieval — 🧱 Foundation (opt-in):** Qdrant dense+sparse retrieval\n  with authorization pushdown and keyword fallback.\n- **MCP agent integration — ✅ Implemented (opt-in):** ten stable memory/task\n  tools, authorized resources, negotiated subscriptions with poll fallback,\n  cross-transport scenarios, and Skill/product drift CI.\n- **A2A 1.0 runtime binding — 📐 Design RFC:** a standards-compliant binding\n  remains separate from the legacy JSON-RPC coordination facade.\n- **Artifact text derivation — ✅ Implemented (opt-in):** bounded PDF extraction,\n  optional Tesseract OCR, source backlinks, current-ACL enforcement, durable\n  idempotent jobs, explicit retry/cancel, and derived-note-only purge.\n- **Additional media providers — 🗺 Planned:** image captioning and audio/video\n  transcription remain provider work, not implied by OCR support.\n- **Operational controls — 🧪 Validation in progress:** authoritative backup/clean\n  restore, recoverable retention, payload-free diagnostics, and Qdrant migration\n  are implemented. General garbage collection remains absent; the supported\n  workload claim waits for the published package/rollback and 24-hour soak evidence.\n- **Hub federation — 🗺 Planned:** namespaced, explicitly trusted hub-to-hub\n  memory exchange.\n- **Coordination hardening — mixed:** A2A Part-model validation and chunked\n  artifact upload are implemented; SSE streaming, the complete A2A 1.0 binding,\n  and push notifications remain planned.\n\nDetails and acceptance criteria in the [RFC](docs/DESIGN.md).\n\n## Status \u0026 contributing\n\nThis project is **contract-first**: coordination plus opt-in durable memory,\noffline sharing, hybrid retrieval, MCP agent integration, and artifact text\nderivation are implemented and tested; the complete A2A 1.0, additional-media,\noperational, and federation surfaces remain incomplete. Read the [RFC](docs/DESIGN.md), the\n[contract and security decisions](docs/CONTRACT_AND_SECURITY_DECISIONS.md), and the machine schemas before\nopening an issue that starts with *\"this breaks when…\"*.\n\n## Security posture\n\nLocal-first. Bind to loopback by default, use bearer tokens across trust\nboundaries, treat every peer message and artifact as untrusted input. Memory\nadds visibility scopes (`shared` / `private` / `direct:\u003cagent\u003e`) and\nprovenance on every write. See [docs/SECURITY.md](docs/SECURITY.md).\n\n## Development\n\n```bash\npython -m pip install -e \".[contracts,derive]\"\npython -m unittest discover -s tests -v\n```\n\nThis is the canonical clean-development command and is exercised on Windows and\nLinux with Python 3.11 and 3.12 in CI. The `contracts` extra contains test-only\nofficial A2A/MCP parsers and JSON Schema validation; the v1 hub still has zero\nruntime dependencies. Python 3.13 is not in the supported matrix yet.\n\nThe packaging contract also defines `memory-core`, `search`, `mcp`, `derive`,\nand the `memory` umbrella extra. `memory-core` enables durable memory only when\nthe server flag is also present. `search` installs the selected FastEmbed\nmultilingual MiniLM + BM25 Qdrant provider; use explicit local/server search flags.\n`mcp` installs the stateless stdio sidecar; `derive` installs pinned `pypdf` and\nPillow dependencies. Image OCR additionally requires a separately installed\nTesseract executable. See [docs/PACKAGING.md](docs/PACKAGING.md).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphenomenoner%2Fa2a-superhub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphenomenoner%2Fa2a-superhub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphenomenoner%2Fa2a-superhub/lists"}