pi-qmem/README.md

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

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, project_id obbligatorio, scope, source, expires_at, supersedes_id, supersede_reason). Se il gateway è giù il record viene accodato localmente (outbox) e inviato automaticamente al ritorno della connessione
qmem_search	Ricerca semantica su tutta la conoscenza condivisa (query, kind, project_id, scope, top_k, include_superseded, min_score). Se il gateway non risponde degrada all'indice locale SQLite/FTS5 (testuale, etichettato fallback: local_sqlite)
qmem_correct	Corregge una memoria falsa: crea un nuovo record che supersede il vecchio (che resta in archivio marcato superseded)
qmem_meta	Discovery: panoramica di scope×kind, progetti, agenti e superseduti (per scegliere i filtri di ricerca)

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):

{
  "url": "https://qmem.enne2.net",
  "apiKey": "...",
  "localDbPath": "~/.local/share/pi-qmem/qmem.sqlite",
  "localFallback": true,
  "offlineQueue": true,
  "connectTimeoutMs": 2500,
  "timeoutMs": 30000,
  "breakerBaseMs": 120000,
  "breakerMaxMs": 600000,
  "breakerTripAfter": 2
}

localFallback: false disabilita il fallback in lettura; offlineQueue: false disabilita l'accodamento offline in scrittura (lo store torna a fallire come prima).

Circuit breaker (fast-fail quando il gateway è irraggiungibile)

Due timeout distinti, per non confondere "gateway giù" con "elaborazione lunga":

Fase	Chiave	Default	Significato
connect + headers	connectTimeoutMs	2500	nessuna risposta entro questo tempo → gateway non raggiungibile (fallimento definitivo)
body (dopo gli header)	timeoutMs	30000	budget per il rerank/export/ricerca: un superamento è un fallimento ambiguo

Comportamento:

• Connessione fallita/nessuna risposta (ECONNREFUSED, DNS, timeout di connect): nessun retry, il circuit breaker si apre subito e resta aperto breakerBaseMs (2 min), con escalation esponenziale fino a breakerMaxMs (10 min).
• 5xx o body lento: fallimenti ambigui → retry con Retry-After e breaker solo dopo breakerTripAfter (default 2) fallimenti consecutivi.
• Breaker aperto: le chiamate ritornano in ~0 ms senza toccare la rete (error: "gateway_unreachable", breaker_open: true, retry_in_ms), quindi i tool passano subito al fallback locale e l'outbox accoda senza attese.
• Stato persistente: ~/.local/share/pi-qmem/breaker.json (env QMEM_BREAKER_FILE) → vale anche per nuove sessioni, /reload e processi CLI. Cambiando url il breaker riparte chiuso.
• Reset manuale: /qmem:local breaker reset oppure node scripts/qmem-sqlite.mjs breaker --reset; un successo lo richiude da solo. Stato: /qmem:local breaker o qmem-sqlite breaker.

Indice locale (fallback offline)

Il gateway remoto non è sempre raggiungibile (VPN giù, nodi offline). L'estensione mantiene quindi un indice locale SQLite + FTS5 che permette di cercare testualmente la conoscenza senza gateway, senza modelli, senza dipendenze:

• DB: ~/.local/share/pi-qmem/qmem.sqlite (override: localDbPath in ~/.config/pi-qmem/config.json oppure env QMEM_SQLITE)
• Ricostruzione: dalle sessioni pi (~/.pi/agent/sessions/<cwd>/*.jsonl), incrociando toolCall ↔ toolResult: qmem_store e qmem_correct forniscono l'ID del gateway e il testo integrale, qmem_get il payload completo, qmem_search i record visti (anche creati da altri agenti)
• Ricerca: FTS5 unicode61 remove_diacritics 2 (accenti e prefissi), ranking BM25, filtro dei superseduti/privati di default; se la query in AND non trova nulla si ripiega su OR (match parziale, dichiarato)
• Fallback automatico: qmem_search/qmem_get usano l'indice locale quando il gateway risponde 0/429/5xx, etichettando i risultati come non neurali
• Outbox (store offline): qmem_store con gateway irraggiungibile accoda il record in SQLite: è subito ricercabile (marcato ⏳ pending) e viene inviato a POST /v1/memories al ritorno della connessione — Idempotency-Key = id locale (retry senza duplicati), poi il record locale adotta l'ID del gateway. Esiti: synced · duplicate (409, con l'ID del match) · failed (4xx di validazione). Le correzioni che puntano a un record ancora locale vengono rimappate all'ID remoto al flush. Trigger: session_start (background, non blocca l'avvio), dopo uno store riuscito, o /qmem:local flush
• Arricchimento e pull: quando il gateway torna online, enrich completa testo/project_id/private/stato supersede via GET /v1/memories/{id}, e pull sincronizza dall'export paginato (GET /v1/memories:export, disponibile dal gateway 2.12.0 insieme al soft delete): i tombstone (deleted_at) arrivano col record e vengono esclusi dall'indice locale (visibili con /qmem:local find --deleted)

Comandi (TUI) e CLI standalone:

/qmem:local status                  # record, copertura, lag, duplicati
/qmem:local import                  # ricostruisce/aggiorna dalle sessioni pi
/qmem:local find "circuit breaker"  # ricerca testuale locale
/qmem:local queue                   # stato della coda (in attesa/sync/dup/fallite)
/qmem:local flush                   # invia subito la coda al gateway
/qmem:local enrich [--all]          # arricchisce dal gateway
/qmem:local pull                    # pull incrementale dall'export

# equivalente standalone (stesso core, nessuna dipendenza)
node scripts/qmem-sqlite.mjs status|import|find "query"|enrich|pull
node scripts/qmem-sqlite.mjs store --project P --text "..." [--queue-only]
node scripts/qmem-sqlite.mjs queue|flush
node scripts/test-local.mjs         # suite di test (37 controlli, HOME temporanea)

Nota: un body non completato non viene più restituito come "successo con dati vuoti" (prima res.json().catch(() => ({})) mascherava il timeout: l'agente vedeva "nessun risultato" invece del fallback locale).

Limiti dichiarati: è uno storico osservato (più vecchio del gateway), la ricerca è lessicale (nessuno score 0.45/0.60: non applicare le soglie semantiche) e un record in coda (⏳) non è ancora nella memoria condivisa: sarà visibile agli altri agenti solo dopo il flush. La coda è locale alla macchina (nessuna sincronizzazione tra macchine diverse).

Regole comportamentali (autocontenute)

Le regole vincolanti (obbligo project_id, punteggi, correzione/supersede, discovery, identificazione macchina nei record locali) sono distribuite con l'estensione, senza toccare AGENTS.md:

• promptGuidelines sui 4 tool (bullets nel Guidelines del system prompt, solo quando i tool sono attivi)
• before_agent_start → blocco "Regole pi-qmem" iniettato nel system prompt a ogni turno (solo se i tool qmem sono attivi); include la sezione Identificazione macchina con MACCHINA CORRENTE rilevata dinamicamente dall'estensione (os.hostname() + /etc/os-release)
• Skill qmem (skills/qmem/SKILL.md, standard agentskills.io) → procedura completa on-demand, caricabile con /skill:qmem
• Manifest: pi.skills nel package.json

Gateway (componente server)

Il Memory Gateway FastAPI + Qdrant non è più duplicato in questo package: la fonte unica è il repository dedicato

git:git.enne2.net/enne2/qmem-gateway      (privato)

che contiene il codice (gateway/), il deploy (docker-compose.yml con Qdrant 1.19 + gateway, .env, .gitignore), la suite di test e il README operativo. Su questa macchina è clonato in ~/dev/qmem-gateway.

Motivo della dedup: la copia qui dentro era byte-identica al repo canonico (GATEWAY_VERSION 2.11.0 / guardrail similarity-v2) e manteneva due fonti potenzialmente divergenti. Storia completa del codice rimossa: git log -- gateway/ (ultimo commit prima della rimozione).

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
• Correzioni: i record sono immutabili; correggere una memoria falsa = nuovo record che supersede il vecchio (qmem_correct o qmem_store con supersedes_id). Il vecchio resta in archivio con superseded_by, escluso dalla ricerca di default (include_superseded=true per la lineage)

Licenza

MIT