Matteo Benedetto
c4bfa1d5bf
INCIDENTE 2026-08-16: l'upsert parziale in Qdrant sostituisce l'intero punto, cancellando payload e vettori densi di tutti i record. update_vectors aggiorna solo il vettore specificato. Recovery: 278/330 record ricostruiti dalle sessioni pi (qmem_store/qmem_correct con memory_id), 52 persi (agenti su altre macchine).
Memory Gateway — deploy
Componente server di pi-qmem: FastAPI + Qdrant 1.19 + Ollama (BGE-M3). Nessun LLM in scrittura: l'agente salva record deliberati e strutturati.
pi (estensione pi-qmem) ──HTTPS/VPN──▶ Memory Gateway (FastAPI:8082) ──▶ Qdrant 1.19 (6333)
│
└──▶ Ollama BGE-M3 (11434, nativo host)
Deploy (Docker Compose)
# 1. Prepara l'ambiente (vedi qmem-gateway/docker-compose.yml come riferimento)
cp .env.example .env
chmod 600 .env
# genera le chiavi:
# QDRANT_ADMIN_API_KEY=$(openssl rand -hex 32)
# QDRANT_READ_ONLY_API_KEY=$(openssl rand -hex 32)
# API_KEYS=$(openssl rand -hex 32) # chiave condivisa per gli agenti
# 2. Avvia
docker compose up -d --build
# 3. Verifica
curl http://127.0.0.1:8082/v1/status
Requisiti: Docker + Compose v2, Ollama con modello bge-m3 sul host
(ollama pull bge-m3), porta 8082 libera sull'interfaccia VPN.
API
| Endpoint | Descrizione |
|---|---|
POST /v1/memories |
Crea record (text, kind, agent_id, scope, project_id obbligatorio, source, expires_at, supersedes_id, supersede_reason) |
POST /v1/memories:search |
Ricerca semantica (query, kind, project_id, scope, top_k, include_superseded, min_score) |
GET /v1/memories/{id} |
Recupera per UUID |
DELETE /v1/memories/{id} |
Elimina per UUID |
GET /v1/meta/overview |
Discovery: scope×kind, progetti, agenti, superseduti (cache 60s) |
GET /v1/status |
Health + statistiche |
Auth: header X-API-Key (chiave condivisa, accesso completo). Rate limit 120 req/min per chiave. Audit log in JSON lines (docker logs).
Sicurezza
- Qdrant bindato su 127.0.0.1; gateway solo su interfaccia VPN
- Chiavi in
.env(0600), mai committate - JWT RBAC su Qdrant (admin + read-only)
- Backup: snapshot Qdrant + rotazione 7 giorni (cron:
0 3 * * * /opt/memory/backup.sh)
Dettagli operativi
Procedure complete (teardown, restore, nginx, troubleshooting): vedi
docs/playbook.md nel repo pi-qmem.