pi-qmem: memoria centralizzata condivisa per agenti AI (estensione pi + gateway)

README.md

@@ -0,0 +1,66 @@
+# pi-qmem
+
+Memoria centralizzata e condivisa per agenti AI — estensione per pi.
+
+Salva e cerca record semantici (fatti, decisioni, preferenze, episodi) in un
+Memory Gateway (FastAPI + Qdrant + BGE-M3) ospitato su un server remoto
+raggiungibile via VPN. Nessun LLM in scrittura: l'agente salva record
+deliberati e strutturati; il retrieval è vettoriale + filtri metadata.
+
+## Installazione
+
+```bash
+pi install git:git.enne2.net/enne2/pi-qmem
+```
+
+Oppure copia `extensions/index.ts` in `~/.pi/agent/extensions/pi-qmem/`.
+
+## Tool
+
+| Tool | Descrizione |
+|---|---|
+| `qmem_store` | Salva un record di memoria (text, kind, agent_id, scope, project_id, source, expires_at) |
+| `qmem_search` | Ricerca semantica su tutta la conoscenza condivisa (query, kind, project_id, scope, top_k) |
+
+## Comando
+
+`/qmem:config` — menu interattivo (TUI):
+
+- 🌐 Imposta URL gateway
+- 🔑 Cambia API key
+- 🔌 Test connessione (verifica URL + validità chiave)
+- 📋 Mostra configurazione
+- ↩️ Annulla
+
+Modalità CLI rapida: `/qmem:config url <URL> | apikey <KEY> | test`
+
+Config salvata in `~/.config/pi-qmem/config.json` (0600):
+
+```json
+{
+  "url": "http://10.8.0.3:8082",
+  "apiKey": "..."
+}
+```
+
+## Gateway (componente server)
+
+La cartella `gateway/` contiene il Memory Gateway FastAPI da deployare sul
+server (Docker Compose con Qdrant 1.19 + Ollama BGE-M3). Vedi
+`gateway/README.md` per il deploy.
+
+## Architettura
+
+```
+pi (estensione) ──HTTPS/VPN──▶ Memory Gateway (FastAPI) ──▶ Qdrant 1.19
+                                      │
+                                      └──▶ Ollama BGE-M3 (embedding locale)
+```
+
+- Accesso condiviso: una chiave API con accesso completo in lettura/scrittura
+- `agent_id` è solo metadata di provenienza, non isolamento
+- Rate limit, audit log, cleanup automatico dei record scaduti
+
+## Licenza
+
+MIT