From 9cb3008f4d01855623e5b53af06a2bc04edcac02 Mon Sep 17 00:00:00 2001
From: Matteo Benedetto <me@enne2.net>
Date: Sun, 16 Aug 2026 19:01:49 +0200
Subject: [PATCH] docs: aggiungi gateway/README.md con istruzioni di deploy
 (referenziato dal README principale)

---
 gateway/README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 gateway/README.md

diff --git a/gateway/README.md b/gateway/README.md
new file mode 100644
index 0000000..bec9933
--- /dev/null
+++ b/gateway/README.md
@@ -0,0 +1,56 @@
+# 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)
+
+```bash
+# 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.