mcp-agora: Instructions file for Codex

MCP Agora — Agent Instructions

Memory & Knowledge (Agora stesso)

Agora è un MCP server con memoria persistente cross-agente. Quando lavori in questo progetto:

1. Prima di cercare soluzioni esterne → chiama agora_query per vedere se informazioni utili sono già state salvate
2. Dopo aver risolto un problema → chiama agora_save per memorizzare la soluzione (con tags)
3. Le informazioni sono condivise tra tutti gli agenti — Claude Code, Codex, ChatGPT, Gemini CLI

La ricerca è semantica (embedding a 384 dimensioni), non per keyword. ChromaDB usa un indice ANN (HNSW) che trova le entry più simili in O(log n) — anche con 10.000 entry la risposta arriva in <50ms.

Project Overview

MCP Agora is a portfolio/learning project implementing an MCP Server with cross-agent persistent memory. It is NOT a product — it is not competing with ContextForge (IBM), MetaMCP, AutoMem, or mcp-memory-service.

Goal

Build an MCP Server that allows AI agents (Claude Code, Codex, ChatGPT, Gemini CLI) to:

• Save knowledge with agora.save → persistent vector memory (ChromaDB)
• Query knowledge with agora.query → semantic search across saved entries
• Share memory across agents and sessions
• Cache frequent queries in-memory (TTLCache)

Non-goals

• Semantic broadcasting / fan-out
• Chunking (save short entries only, ≤256 word pieces)
• Docker, RBAC, auth, scaling

Architecture Stack (corrente)

Python 3.13+  │  uv 0.11+
FastMCP       │  MCP SDK ≥1.0.0
ChromaDB      │  PersistentClient
sentence-transformers  │  all-MiniLM-L6-v2 (384d)
cachetools    │  TTLCache (1000 entries, 5min TTL)
pyyaml        │  config.yaml
pytest        │  pytest-asyncio
SQLite3       │  stdlib (provenance, agent registry, L2 cache)

Directory Structure

mcp-agora/
├── pyproject.toml
├── config.yaml
├── README.md
├── AGENTS.md
├── ARCHITECTURE.md
├── agora/
│   ├── __init__.py
│   ├── main.py              # Entry point: `agora` command
│   ├── server.py            # FastMCP server + 8 tool registration
│   ├── config.py            # YAML config loader
│   ├── logging.py           # File-based structured logging
│   ├── registry.py          # BackendRegistry (lifecycle, lazy connect)
│   ├── connectors/
│   │   ├── __init__.py
│   │   ├── base.py          # BackendConnector ABC + ReadOnlyBlockedError
│   │   ├── stdio.py         # STDIO subprocess MCP client
│   │   └── http.py          # Streamable HTTP MCP client
│   ├── routing/
│   │   ├── __init__.py
│   │   └── router.py        # Semantic + exact name router
│   ├── embedding/
│   │   ├── __init__.py
│   │   ├── base.py          # Abstract EmbeddingProvider + WarmingUpError
│   │   └── sentence.py      # sentence-transformers wrapper (sync preload, local_files_only, 60s timeout)
│   ├── memory/
│   │   ├── __init__.py
│   │   └── vector_store.py  # ChromaDB PersistentClient wrapper
│   ├── cache/
│   │   ├── __init__.py
│   │   ├── l1_memory.py     # TTLCache in-memory
│   │   └── l2_cache.py      # SQLite-backed persistent cache
│   └── db/
│       ├── __init__.py
│       └── database.py      # SQLite: agents, provenance, L2 cache
├── tests/
│   ├── __init__.py
│   ├── test_embedding.py
│   ├── test_memory.py
│   ├── test_cache.py
│   ├── test_l2_cache.py     # L2 persistent cache tests
│   ├── test_provenance.py   # Provenance + agent registry tests
│   ├── test_protocol.py
│   ├── test_routing.py
│   ├── test_connectors.py
│   ├── test_graceful.py     # Health check, retry, rate limit tests
│   ├── test_mcp_smoke.py
│   └── _echo_server.py      # Minimal FastMCP echo server for tests
└── examples/
    └── config.yaml.example