open source · mit · local-first · 0.3.0 memory v2 source contract · opt-in

Your agents collaborate.
Then they forget everything.

A2A Superhub doesn't just move tasks. It keeps collaboration memory — what agents learned, decided, and handed off — so work can continue across agents, frameworks, and time.

See how collaboration memory works Connect your first agent

$ pip install -e .  # coordination core: zero runtime dependencies

BEYOND MESSAGE ROUTING

Move the task.
Keep what mattered.

Tell Agent A once. Superhub preserves the context and source so Agent B can continue when it returns — without another briefing.

Durable shared past
YOU
You brief Agent AMONDAY · ONCE

“The gateway loses tokens after overnight restarts.”

One explanation — Agent A captures the source
Superhub keeps context keeps the source queues it for B
B
Agent B continuesTHURSDAY · LATER

“I already have the context.”

GATEWAY RESTART Tokens were not restored. From Agent A · linked to the original task
One explanation. A durable shared past. No copy-paste. No repeated briefing. No lost handoff.
View the protocol proof For developers: exact curl · JSON · logical inbox acknowledgement VIEW CODE ↓
async memory sharing — the protocol proof
# Monday 09:12 — you tell Agent A about Agent B's flaky gateway.
# memory.v2 is current; v1 per-reason compatibility remains through 0.3.x.
# Agent A writes an immutable memory.note.v1 document through the v2 API:
$ curl -s -H "Authorization: Bearer $AGENT_ALPHA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: monday-gateway-1" hub:8787/v2/memory/notes -d '{
    "type": "observation",
    "title": "Gateway restart observation",
    "about": ["agent.beta"],
    "body": "B's gateway drops tokens after overnight restarts…",
    "relations": [{"type":"references","target":"task:task_ab12"}],
    "visibility": "shared"}'
201 { "id": "mem_9f3a…" }   # markdown lands → indexed → queued for B

# Thursday 03:40 — bounded startup preview; it never carries an ACK cursor.
$ curl -s -H "Authorization: Bearer $AGENT_BETA_TOKEN" \
  hub:8787/v2/memory/wakeup?consumerId=cli.startup
200 role=data trust=untrusted-memory cursor=absent

# Fetch the exact logical-delivery page; ACK only after the intended consumer accepts it.
$ curl -s -H "Authorization: Bearer $AGENT_BETA_TOKEN" \
  hub:8787/v2/memory/inbox?consumerId=cli.startup
200 items[0].reasons=["about"] cursor="<exact-page-cursor>"

# After Agent B accepts that exact page:
$ curl -s -X POST -H "Authorization: Bearer $AGENT_BETA_TOKEN" \
  -H "Content-Type: application/json" hub:8787/v2/memory/inbox/ack \
  -d '{"consumerId":"cli.startup","cursor":"<exact-page-cursor>"}'
200 { "acked": true }   # B can now retrieve the durable note; no overlap was required.
coordination API — v1 source contract memory API — v2 current · v1 compatibility through 0.3.x note schema — memory.note.v1 remains durable truth Markdown + SQLite core · Qdrant opt-in MIT licensed
the problem

Multi-agent stacks hit the same three walls

01

N×N glue code

One agent speaks A2A, one exposes MCP, one has an ACP adapter, one is CLI-only. Every pair invents its own integration — again.

02

Session amnesia

Work products survive; the context doesn't. Who decided what, why, and what was learned — gone when the session ends.

03

Absent peers stay ignorant

What Agent A learns about Agent B never reaches B, unless a human plays messenger between chat windows.

coordination plane

Today: the durable A2A hub SOURCE · v1

A small standalone hub where independent agents exchange tasks, progress events, and artifacts — without migrating into one framework. Pure Python standard library. SQLite state. Runs on loopback in seconds.

TASKS

Durable task lifecycle

Create, progress, cancel, terminal states — with idempotency keys, so retries return the same task instead of duplicates.

ARTIFACTS

Resumable, searchable artifacts

SHA-256 verified raw/chunk uploads. Optional PDF/OCR text stays linked to its source and is re-authorized against the current manifest.

REGISTRY

Agent Cards

Register and discover peers with standard A2A Agent Cards, served at /.well-known/agent-card.json.

PROTOCOL

JSON-RPC A2A facade

message/send, tasks/get, tasks/cancel — a minimal, honest subset that grows by capability negotiation.

POLICY

Auth & rate limits

Bearer-token protection and per-client rate limiting. Local-first, loopback by default, every peer treated as untrusted input.

ADAPTERS

Peers, not children

The hub owns cross-agent semantics; adapters own local runtime integration — ACP, MCP, CLI wrappers, or native SDKs.

memory plane · 0.3.0 source contract

Give every agent the past it needs CURRENT · MEMORY V2

Superhub turns collaboration history into a shared, auditable record. Agents can catch up days later; you can still open the original files, trace every memory to its source, and rebuild every search index.

Honest scope. Memory is an opt-in 0.3.0 repository-source contract — not a published package, live deployment, SLA, or supported-workload claim. The v2 path uses logical delivery, preview-only wakeup, and exact inbox acknowledgement.

OWN IT

Readable by you. Portable by default.

Every memory is plain Markdown — open it, review it, version it, or browse it in Obsidian. Humans and agents work from the same durable record.

TRUST IT

The record stays the record.

Superhub stores the original observation, not an AI rewrite. Summaries can happen later; provenance, timing, and corrections stay explicit.

FIND IT · OPT-IN

Start local. Search deeper when ready.

Built-in keyword search works first. Add Qdrant hybrid retrieval as history grows — without changing where durable truth lives.

MEMORY RECEIPT PLAIN MARKDOWN
OBSERVATION

Gateway restart observation

Tokens were not restored after the controlled restart.

Learned by
Agent A
About
Agent B
Recorded
Monday · 09:12
Source
Gateway task
Shared with
Agent B
Status
Original wording preserved
#restart#gateway Source attached · history auditable
View the Markdown source MEMORY.NOTE.V1 ↓
notes/01/mem_0123456789abcdef0123456789abcdef.md
---
schema: a2a-superhub.memory.note.v1
id: mem_0123456789abcdef0123456789abcdef
type: observation
title: Gateway restart observation
author: agent.alpha
visibility: direct:agent.beta
recordedAt: '2026-07-20T09:12:00Z'
source:
  kind: api
  taskId: task_demo_001
project: gateway
participants: [agent.alpha, agent.beta]
about: [agent.beta]
tags: [restart, gateway]
relations:
- type: about
  target: agent:agent.beta
---
Tokens were not restored after the controlled restart.
WHAT THIS UNLOCKS

Past work becomes useful context — not a pile of logs.

Each note keeps enough structure to help the next agent act, while staying understandable to the person responsible for the system.

01
Catch up without a meeting

An offline agent returns to the context that matters, not an entire chat transcript.

02
Ask who knew what, when

Authored, timestamped relationships turn collaboration history into a queryable timeline.

03
Keep every answer traceable

Author, task, visibility, and source stay attached — without guessing what an agent understood.

04
Burn the index. Keep the memory.

Search and graph views are derived. Rebuild them without giving up the original notes.

Developer contract & operational limits Logical delivery · exact-page ACK · safe lifecycle facts · bounded payloads VIEW DETAILS ↓
LOGICAL

One item, all reasons

Each note and recipient has one opaque delivery ID. Matching about, direct, and handoff rules become one bounded reasons array instead of duplicate inbox items.

ACK

Preview is not authority

/v2/memory/wakeup has no ACK cursor. Only /v2/memory/inbox issues an exact page cursor, acknowledged after the intended consumer accepts that page.

FACTS

Safe errors and lifecycle facts

Typed errors preserve safe bounded details and trace correlation. Lifecycle reports authorized stored, indexed, queued, acknowledged, and linked-reference facts — never understanding or execution.

The v1 per-reason projection remains available through 0.3.x; stored Markdown continues to use a2a-superhub.memory.note.v1. HTTP JSON is capped at 1 MiB, note bodies at 262,144 UTF-8 bytes, titles at 256 code points, search and inbox pages at 100 items, complete wakeup envelopes at 65,536 UTF-8 bytes, artifact uploads at 64 MiB by default, and inline raw artifact parts at 262,144 bytes. Read the v2 compatibility and migration contract.

the differentiator

Asynchronous memory sharing

Memory sharing becomes asynchronous message passing: writing is delivery, querying is catching up. No agent has to be online at the same time as any other.

MONDAY 09:12 — AGENT A, ONLINE

You mention Agent B's flaky gateway. Agent A writes an observation with about: [agent.beta]. The hub lands the Markdown, indexes it, and creates one logical delivery for that recipient.

THURSDAY 03:40 — AGENT B, WAKING UP

B first reads a bounded wakeup preview, which cannot acknowledge anything. It then pulls one logical inbox item with the complete reason set and an exact-page cursor. Only after B accepts that page does the client ACK it. Provenance still says who, when, and which task.

pointers, not copies — content exists exactly once, in the markdown tree
note lands→ SQLite FTS index→ one logical delivery per recipient→ wakeup preview (no ACK cursor)→ exact inbox page→ ACK after acceptance
design principles

Opinions, stated out loud

Markdown is the truth.

Burn the index, keep the memory. Indexes are cattle; your notes are the herd book.

Verbatim in, intelligence out.

No LLM in the write path. Summarize at read time, or don't. What was said is what is stored.

Offline is a feature.

Pull-first logical inboxes use exact-page cursors. Preview, omission, or a lost push never advances ACK state.

Local-first, zero API keys.

SQLite now; future local retrieval remains evidence-gated. Nothing leaves your machine unless you route it.

positioning

Memory frameworks remember users.
Superhub gives peer agents a shared past.

The advantage is not five features in one box. Each layer makes the next more valuable — and the next agent more capable.

THE COMPOUND EFFECT

Not five features. One continuity loop.

Coordination creates the record. Memory preserves it. Structure finds what matters. The inbox turns it back into work.

COORDINATION-ONLY HUB Delivered, then disconnected.

The task can move. Later continuity still depends on live peers, copied prompts, or a separate memory system.

A2A SUPERHUB Delivered, remembered, ready to continue.

The hub keeps the collaboration record, then gives an authorized peer the right context — with source and history — when it returns.

01 · MOVECoordinatetask + actors
02 · KEEPRemembercontext + source
03 · LINKConnectgraph + timeline
04 · DELIVERCatch upoffline inbox
05 · ACTContinuenext agent moves

↺ New work enriches the shared past.

Coordination gives memory provenance. Every note can carry who, what, when, and which task.
Memory makes relationships trustworthy. Graph and timeline come from durable source records, not model guesswork.
The inbox turns history into action. The right peer catches up and continues instead of starting over.
LOCAL-FIRST FOUNDATION Inspectable Markdown source · rebuildable indexes · no external API keys
projectA2A task coordinationdurable shared memory knowledge graph + timelineoffline inbox catch-uplocal-first, no API keys
A2A Superhubv1 coordination + current memory.v2, opt-in retrieval, and MCP ✓✓✓✓✓
mem0app ↔ user memory layer —✓partial—partial
memXrealtime shared state —ephemeral KV——✓
A2A registriesagent directories discovery only———varies
basic-memoryhuman ↔ AI notes —✓✓—✓

Respect to all of the above — several of them shaped this design. Comparison reflects each project's stated scope, not quality.

roadmap

Implemented foundations and the work still ahead

The opt-in foundation runs sedimentation and async sharing end to end; hybrid retrieval is available with authorization filtering and keyword fallback. The coordination-graph path starts with observation—not a scheduler.

0.3.0 source · opt-in

Logical memory v2 + offline sharing

Markdown note v1, logical delivery, exact inbox ACK, preview-only wakeup, safe typed errors, lifecycle facts, SQLite + FTS, timeline, and graph. Per-reason v1 compatibility remains through 0.3.x.

foundation · opt-in

Qdrant hybrid retrieval

Dense + sparse + rank fusion, recency boost, visibility as filter pushdown.

implemented · opt-in

MCP agent integration

Ten stable memory/task tools, authorized memory:// resources, subscription notifications, and polling fallback.

implemented · opt-in

Artifact text derivation

Bounded PDF text and optional Tesseract OCR become untrusted searchable notes, with source backlinks and current-ACL enforcement.

implemented · validating

Operational controls

Authoritative backup/clean restore, recoverable retention, payload-free diagnostics, and parity-gated Qdrant migration are implemented. General GC remains absent; the workload claim waits for published 24-hour soak evidence.

planned

Hub federation

Hub-to-hub memory push/query with origin provenance.

planned

Coordination graph trace

Authorized task lineage and causal traces first; dry-run plan validation second. Bounded execution is conditional. No orchestration runtime exists today. Read the staged roadmap →

A parallel coordination track covers coordination plane: Part-model validation and chunked artifact upload are implemented; SSE streaming, the complete A2A 1.0 binding, and push notifications remain ahead.

repository source + future RFC

Memory v2 now speaks MCP. Tear the remaining design apart.

The 0.3.0 source defines v1 coordination and current memory.v2; memory, hybrid retrieval, MCP, and artifact text derivation are opt-in with repository official-SDK, cross-transport, end-to-end, and restart/replay evidence. This is not a production-readiness or live-deployment claim. A2A 1.0 remains open RFC scope — the most useful contribution is criticism that starts with "this breaks when…"

Read the RFC Open an issue GitHub ↗