Antonio Cioffi
Torna al blog
3 min di letturamcp-agorapythonai-agentschromadbarchitettura

MCP Agora: Memoria Persistente Cross-Agente per Fleet di AI Agent

Come ho costruito un MCP Server con ChromaDB, routing semantico e cache L1/L2 per permettere a agenti AI di condividere conoscenza tra sessioni e strumenti diversi.

Il problema

Gli AI agent — Claude Code, Codex, ChatGPT, Gemini CLI — lavorano in sessioni isolate. Ognuno parte da zero, senza memoria di ciò che un altro agente ha scoperto nella sessione precedente.

Il risultato?

  • Lavoro duplicato
  • Informazioni perse tra sessioni
  • Impossibile costruire conoscenza nel tempo

MCP Agora nasce per risolvere esattamente questo: un server MCP che funge da memoria persistente e router tra agenti.

Architettura in 7 layer

Transport → Protocol → Router → Memory → Cache → Backend Connector → Embedding

1. Transport Layer

STDIO per uso locale (default) e Streamable HTTP per connessioni remote.

2. Protocol Layer

Implementa le primitive MCP standard: tools/list, tools/call.

3. Router Layer

Routing semantico + esatto verso backend MCP esterni (GitHub, Playwright).

Quando chiami agora_route("github", ...):

  1. Exact match (case-insensitive) — se trovi un backend chiamato "github", usa quello
  2. Semantic match (cosine similarity ≥ 0.5) — altrimenti cerca per similarità semantica nel nome/descrizione
def cosine_similarity(a: list[float], b: list[float]) -> float:
    dot = sum(x * y for x, y in zip(a, b))
    na = sum(x * x for x in a) ** 0.5
    nb = sum(y * y for y in b) ** 0.5
    return dot / (na * nb) if na * nb > 0 else 0.0

4. Memory Layer

ChromaDB con collezione "knowledge" e embedding a 384 dimensioni (all-MiniLM-L6-v2).

5. Cache Layer

Due livelli:

  • L1: TTLCache in-memory (1000 entry, 300s TTL)
  • L2: SQLite persistente (10000 entry, 86400s TTL)

Cascata: L1 → L2 → ChromaDB. Popolamento automatico su miss.

6. Backend Connector Layer

  • StdioConnector: subprocess MCP client
  • HttpConnector: streamable HTTP MCP client
  • Read-only enforcement: prefix heuristic (list_, get_, fetch_, read_, search_, ...)

7. Embedding Layer

sentence-transformers all-MiniLM-L6-v2, lazy load con warmup all'avvio.

API Tools

Tool Cosa fa
agora_save Salva conoscenza con provenienza (agente, sessione)
agora_query Ricerca semantica con cache cascade
agora_route Routing a backend MCP esterno
agora_broadcast Invia tool call a tutti i backend in parallelo
agora_backends Lista backend configurati
agora_crossref Correlazioni cross-agente
agora_forget Elimina memoria con dry-run preview
agora_status Statistiche complete

Cosa ho imparato

Costruire MCP Agora mi ha insegnato più di qualsiasi corso:

  1. I layer pagano. L'architettura a 7 layer sembra overkill all'inizio, ma quando devi sostituire ChromaDB con un altro vector store, cambi una riga.
  2. Test senza mock. 55 test con ChromaDB e SQLite reali in directory temporanee isolate. Zer0 mock.
  3. La cache è difficile. Gestire invalidazione e consistenza tra L1 e L2 è stato il pezzo più delicato.
  4. Windows è un cittadino di seconda classe nell'ecosistema MCP. Timeout, path, lock di processo — tutto va testato su Windows separatamente.

Stack

  • Runtime: Python 3.13+, uv 0.11+
  • MCP Framework: FastMCP
  • Vector Store: ChromaDB PersistentClient
  • Embeddings: sentence-transformers all-MiniLM-L6-v2 (384d)
  • Cache: cachetools (L1) + SQLite3 (L2)
  • Test: pytest + pytest-asyncio (55 test)

Dove trovarlo

Il progetto è open source (MIT) e ha completato tutte e 5 le fasi di sviluppo, con install script per Windows e Unix, CI su Ubuntu+Windows, e documentazione completa in italiano e inglese.