┌──────────────┐   stdio / MCP    ┌──────────────────┐   HTTP :8765   ┌──────────────────┐
│  Assistant   │ ◄──────────────► │  Serveur MCP     │ ─────────────► │   API REST        │
│  (opencode,  │                  │  mcp_server/     │  (MEMORY_API_URL)│  memory_tool/    │
│  VS Code…)   │                  │  server.py       │ ◄───────────── │  (FastAPI)       │
└──────────────┘                  └──────────────────┘   HTTP :8765   └────────┬─────────┘
                                                                               │
                                                                       ┌───────┴────────┐
                                                                       │  SQLite        │
                                                                       │  /data/memory.db│
                                                                       └────────────────┘
                                ┌──────────────────┐  HTTP :11434
                                │  Ollama          │ ◄────── embeddings (nomic-embed-text)
                                │  (conteneur)     │
                                └──────────────────┘

cd memory_tool/
cp .env.example .env          # définir MEMORY_API_KEY
docker compose up -d --build  # démarre API :8765 + embeddings Ollama
curl http://localhost:8765/api/v1/health

cd memory_tool/
python -m venv .venv
source .venv/bin/activate          # Windows : .venv\Scripts\activate
pip install -e ".[dev]"
# Pour le NLP (spaCy) : python -m spacy download en_core_web_sm
MEMORY_API_KEY=changeme MEMORY_EMBED_MODEL=mock uvicorn memory_tool.app:app --port 8765

{
  "mcp": {
    "llm-memory-tool": {
      "type": "local",
      "command": ["python", "-m", "mcp_server.server"],
      "environment": {
        "MEMORY_API_URL": "http://localhost:8765/api/v1",
        "MEMORY_API_KEY": "changeme",
        "MEMORY_DEFAULT_PROJECT": "default"
      },
      "enabled": true
    }
  }
}

# Stocker une mémoire
curl -X POST http://localhost:8765/api/v1/memories \
  -H "X-API-Key: changeme" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "my-project",
       "content": "On utilise FastAPI pour tous les endpoints REST, pydantic v2 pour la validation.",
       "memory_type": "procedural",
       "tags": ["architecture", "fastapi"]}'

# Récupérer le contexte
curl -X POST http://localhost:8765/api/v1/retrieve \
  -H "X-API-Key: changeme" \
  -H "Content-Type: application/json" \
  -d '{"query": "quel framework pour les APIs ?", "project_id": "my-project", "token_budget": 600}'

from memory_tool.sdk import MemoryClient, get_context

client = MemoryClient(api_key="changeme")
client.create_memory(
    project_id="my-project",
    content="Convention : snake_case pour toutes les fonctions Python.",
    tags=["conventions"],
)

context = get_context("conventions de nommage", project_id="my-project")
prompt = f"Contexte :\n{context}\n\nUtilisateur : {user_message}"

cd memory_tool/
pytest tests/ -q            # 38 tests (SQLite en mémoire, aucun service externe requis)

# Avec couverture
pytest --cov=memory_tool --cov-report=term-missing

# Lint
ruff check memory_tool/

memory_tool/
├── mcp_server/          # Serveur MCP (stdio) : server.py, client.py
├── memory_tool/         # API FastAPI
│   ├── app.py           # Point d'entrée FastAPI
│   ├── auth.py          # Authentification par clé API
│   ├── config.py        # Paramètres (pydantic-settings, env MEMORY_*)
│   ├── dependencies.py  # Injection de dépendances
│   ├── sdk.py           # Client SDK Python
│   ├── adapters/        # Embeddings (Ollama/mock), graphe
│   ├── db/              # Schéma SQLite + migrations + repository
│   ├── domain/          # Modèles métier purs + exceptions
│   ├── routers/         # Endpoints REST (memories, retrieve, admin, graph, infra)
│   └── services/        # mémoire, recherche hybride, politiques, NLP, clustering, skills
├── scripts/             # Synchronisation de l'index des skills, évaluation Recall@K
├── tests/               # Suite pytest
├── docs/                # Documentation (skill-index)
├── Dockerfile
├── docker-compose.yml   # API :8765 + embeddings Ollama + UI :8766
├── pyproject.toml
└── requirements.txt