Il default di 2,5 s per connect+headers è troppo stretto su percorsi VPN/AP:
misurati GET /v1/status 1,23 s e POST /v1/memories:search 1,98 s, talvolta
oltre 2,5 s. In quelle condizioni il breaker si apriva pur con gateway
raggiungibile e tutte le chiamate successive andavano in fast-fail per 2–10
minuti, spingendo di fatto ogni operazione sul solo fallback locale e
lasciando l'outbox non sincronizzata.
- extensions/shared.ts: connectTimeoutMs 2500 → 15_000 (default, fallback nel
path di richiesta e commento), breakerTripAfter 2 → 3
- README.md: default aggiornati + motivazione nella tabella dei timeout
- skills/qmem/SKILL.md: default aggiornato e sintassi CLI del reset breaker
(`qmem-sqlite.mjs breaker --reset`)
Verifica sul campo: con connectTimeoutMs=60000 l'outbox (18 record) è stata
sincronizzata completamente e il breaker è rimasto chiuso.
extensions/local-db.ts: né il tipo di ritorno né i return di successo/fallthrough
di submitOrQueue prevedevano il campo `ok`. store.ts fa
`const { ok, status, data } = submitted; if (!ok)` → ok=undefined ⇒ !ok ⇒
stampava "Errore 200: {memory_id...}" anche quando il record era stato creato
sul gateway, saltando la conferma "Memoria salvata: <id>" e l'avviso duplicati
(score >= 0.92). Regressione introdotta in 9dd2429.
Ora: ok:true nel return di successo, ok:false in quello accodato e nel
fallthrough, `ok: boolean` nel tipo di ritorno.
Verifica (bun, gateway http://127.0.0.1:8082):
kind valido → ok:true, status 200, remote_id c3733a1a-… → "Memoria salvata: …"
kind invalido → ok:false, status 422 → "Errore 422: …"
(prima del fix ogni esito non-accodato stampava "Errore 200").
Il gateway irraggiungibile costava ~30s x4 tentativi (fino a ~2 minuti) per ogni
chiamata: ora si distinguono i due casi e le chiamate successive sono immediate.
- due timeout separati: `connectTimeoutMs` (default 2500, connect+headers) e
`timeoutMs` (default 30000, budget per il body). Nessuna risposta entro il
primo = "gateway non raggiungibile"; body lento = "elaborazione lunga"
- circuit breaker persistente in ~/.local/share/pi-qmem/breaker.json
(env QMEM_BREAKER_FILE): fallimento definitivo (connessione rifiutata/DNS/
connect timeout) → nessun retry e apertura immediata per `breakerBaseMs`
(default 120000 = 2 min) con escalation fino a `breakerMaxMs` (10 min);
5xx/body lento sono ambigui → retry con Retry-After e apertura dopo
`breakerTripAfter` (default 2). Un successo lo richiude; cambiando `url` lo
stato riparte chiuso (endpoint-aware)
- con breaker aperto gatewayRequest ritorna in ~0 ms senza rete
(`gateway_unreachable`, `breaker_open`, `retry_in_ms`): i tool passano subito
al fallback locale e l'outbox accoda
- fix di due bug scoperti durante i test:
* `res.json().catch(() => ({}))` trasformava un body non completato in
"successo con dati vuoti" → l'agente vedeva "nessun risultato" invece del
fallback locale. Ora è `timeout_body` (fallimento, ambiguo)
* `submitOrQueue` passava un AbortSignal esterno, che con la nuova semantica
sarebbe stato letto come annullamento utente (eccezione invece di coda)
- messaggi dei tool con lo stato del breaker e come forzare un tentativo;
`details.breaker` per l'osservabilità
- comandi: `/qmem:local breaker [reset]` e `qmem-sqlite breaker [--reset]`;
lo stato compare in `/qmem:local status` e nella CLI
- budget interni per enrich/pull/flush (niente AbortSignal esterni)
Misure: connessione rifiutata → 4-8 ms (prima: 4 x 30 s); front che risponde
503 dopo ~40 s → 3,5 s alla prima chiamata, poi 0 ms di rete a breaker aperto;
server che accetta e non risponde → 708 ms (connect timeout); body lento →
1,2 s senza aprire il breaker; persistenza verificata fra processi distinti.
Test: scripts/test-local.mjs 38/38 (nuova fase dedicata al breaker).
Prepara il client al gateway 2.12.0 (export + soft delete), mantenendo la
compatibilità con la 2.11.0 in produzione fino al redeploy.
- tombstone: colonna `deleted_at` (+ migrazione), monotona nel merge, esclusa
dalle ricerche locali di default; `--deleted` in CLI e /qmem:local find;
conteggio nel report/status; marker 🗑 nei risultati di qmem_get
- `pull` usa `include_deleted=true` e mappa l'intero payload dell'export
(incluso deleted_at), così il mirror impara le cancellazioni
- rate limit: pace del flush 600 ms (100 req/min < 120/min del gateway) e
messaggio dedicato su 429 (prima 300-400 ms → possibile 429 con code grandi)
- `qmem_get`: fallback sull'indice locale anche sul 404 (un id in coda non è
ancora sul gateway) con etichetta "non presente sul gateway"
- test: 27 controlli (nuovi: pull con tombstone, esclusione/visibilità
tombstone, ricerca del record esportato)
Verificato con la suite locale completa: 27/27.
La cartella gateway/ era un duplicato byte-identico (sha256 su 14 file) del
repository canonico privato enne2/qmem-gateway (GATEWAY_VERSION 2.11.0,
guardrail similarity-v2): due fonti dello stesso codice, rischio di divergenza.
- la fonte unica del gateway + deploy (docker-compose.yml, .env, test, README
operativo) è git:git.enne2.net/enne2/qmem-gateway, clonata in ~/dev/qmem-gateway
- gli artefatti presenti SOLO qui (README.md, requirements-dev.txt, tests/)
sono stati spostati in quella repo prima della rimozione (commit locale
15cc9d3, nessun push): nessuna perdita di contenuto
- backup integrale della cartella rimossa:
~/archive/backups/pi-qmem-gateway-copy-20260913-173728.tar.gz
- README aggiornato con il puntatore al repo canonico
Il package pi-qmem ora contiene solo estensione, skill, tool CLI e test
dell'indice locale (il gateway si deploya dal repo dedicato).
Prima qmem_store falliva se il gateway non era raggiungibile: la conoscenza
andava persa. Ora il record entra in una coda locale persistente e viene
inviato automaticamente quando la connessione torna.
Core (extensions/local-db.ts):
- tabella `pending` (local_id, payload JSON, attempts, last_error, status,
remote_id) + colonna `records.pending` (migrazione automatica dei DB esistenti)
- queueStore(): accoda e crea subito il placeholder locale ricercabile (⏳)
- flushQueue(): POST /v1/memories con Idempotency-Key = local_id (retry senza
duplicati), FIFO, pacing sotto il rate limit, timeout 12s per richiesta
- esiti: synced (il record locale adotta l'ID remoto, niente duplicati) ·
duplicate (409: registra l'ID del match e NON sovrascrive il testo locale
autorevole) · failed (4xx di validazione, non ritentato) · 0/429/5xx: resta in
coda e il flush si ferma
- supersede offline: supersedes_id che punta a un local_id viene rimappato al
remote_id al flush (se il genitore non è sincronizzato → failed esplicito)
- submitOrQueue(): online → gateway + indicizzazione locale; offline → coda
- maybeBackgroundFlush() (single-flight) e flushQueueIfPending() per session_start
- stato/report: queued/synced/duplicate/failed, più vecchio, ultimo errore,
last_flush, record pendenti in indice
Estensione:
- qmem_store: gateway giù → accoda e risponde con id locale, dimensione coda e
spiegazione (details.queued/local_id/queue_size)
- fallback offline di session_start: flush in background (non blocca l'avvio)
- /qmem:local queue|flush; status con la coda; marker "⏳ in coda" nei risultati
locali di qmem_search/qmem_get
- regole e skill: un record in coda NON è ancora nella memoria condivisa
CLI: store [--queue-only], queue, flush (+ status con la coda).
Test: scripts/test-local.mjs ora copre anche outbox → 24 controlli (flush con
2 sync + 1 duplicato 409 + 1 fallito 422, Idempotency-Key, rimappatura del
supersede, ricerca del record con l'ID remoto dopo il sync).
Verifiche: 24/24 test superati; demo reale su DB temporaneo: store accodato,
queue con local_id, flush con gateway giù → "fermato: HTTP 0" e voce che resta
in coda con l'errore registrato.
Il gateway remoto non è sempre raggiungibile (VPN/nodi giù): finora le ricerche
fallivano e la conoscenza non era consultabile. Ora l'estensione mantiene un
indice locale testuale e vi degrada automaticamente.
Core (extensions/local-db.ts):
- schema SQLite con FTS5 (unicode61 remove_diacritics 2), trigger di sync,
tabella meta per cursori/stato; usa node:sqlite (Node >= 22.5, nessuna
dipendenza esterna), con soppressione del warning "experimental"
- import idempotente dalle sessioni pi (tutte le directory di progetto):
qmem_store/qmem_correct (ID + testo integrale), qmem_get (payload completo),
qmem_search (record osservati, anche creati da altri agenti)
- merge senza regressioni: le osservazioni povere (es. search senza
project_id) non azzerano i campi già noti; superseded_by monotono
- ricerca FTS5 con filtri (kind/project/scope/level/topic), esclusione di
superseduti e privati, ranking bm25, snippet, ripiego AND -> OR dichiarato
- enrich dal gateway (GET /v1/memories/{id}, pacing < rate limit, timeout 8s
per richiesta, stop al primo guasto) e pull da /v1/memories:export (endpoint
lato gateway previsto: se assente lo segnala senza errore)
- localGet per il recupero puntuale offline
Estensione:
- qmem_search: su 0/429/5xx degrada all'indice locale, risultati etichettati
"INDICE LOCALE, ricerca testuale non neurale" + details.fallback=local_sqlite
- qmem_get: fallback locale per UUID
- qmem_store: avviso esplicito che il record NON è salvato (nessuna coda)
- rendering arricchito con project_id e flag privato (anche per il gateway)
- comando /qmem:local status|import|find|enrich|pull
- regole e skill aggiornate: quando si usa l'indice locale non applicare le
soglie 0.45/0.60 (sono semantiche)
CLI standalone (stesso core): scripts/qmem-sqlite.mjs status|import|find|
enrich|pull (+ --json). Test: scripts/test-local.mjs (14 controlli, HOME
temporanea, sessioni sintetiche, gateway black-hole e stub HTTP).
Verifiche: 14/14 test superati; import reale 185 sessioni -> 1046 record unici
(1032 con testo, 986 attivi, 60 superseduti, 672 con project_id, 20 gruppi di
duplicati) in 2,8 MB; enrich con gateway giù si ferma in ~16s con messaggio
chiaro invece di restare appeso.
- gateway/rerank.py: catena da RERANK_CHAIN (JSON, per-nodo key+timeout),
cooldown 60s sui nodi falliti, score sigmoide [0,1], degrada con grazia
all'ordine di fusione se tutti i nodi sono giù
- routes: /v1/memories:search applica il rerank post-fusione (fetch esteso a
RERANK_CANDIDATES), risposta con rerank{used,backend,took_ms}, flag
per-query rerank=false; /v1/version espone lo stato rerank
- store: search() accetta limit esteso; models: SearchIn.rerank
- metrics: qmem_rerank_calls_total + durata per backend
- test: 10 nuovi (fallback, cooldown, degradazione, integrazione) — 46 pass
- gateway: campo private (bool) in MemoryIn; filtro must_not private=true
di default in search_filter; include_private in SearchIn per ricerche
esplicite; campo private esposto in format_results
- estensione: parametro private in qmem_store, include_private in qmem_search
(con descrizioni e avvertenze sui prompt dei modelli)
- testato su brain: record private invisibile alla ricerca standard,
visibile solo con include_private=true; topic esplicito da solo non sblocca
- deploy: /opt/memory/gateway ricostruito (container memory-gateway)
- gateway: nel blocco supersede, i figli attivi (parent_id == vecchio UUID,
superseded_by vuoto) vengono ri-parentati al nuovo UUID; audit action
'reparent'; risposta con campo 'reparented'. Un solo livello: i nipoti
puntano agli UUID dei figli, invariati. I figli superseduti restano
storici ancorati alla vecchia lineage.
- estensione: qmem_tree con fallback lineage (cerca figli anche per
supersedes_id del root) per gli orfani pre-fix; qmem_correct riporta
il numero di figli ri-parentati.
- test: 2 nuovi (ri-parenta figli attivi; ri-parenta solo attivi con
figlio già superseduto). 34 pass.
- deploy su brain (10.8.0.3): main.py aggiornato, container ricreato,
smoke test end-to-end OK (reparented=1).
Regola auto-miglioramento: lezioni strutturate TRIGGER→CAUSA→AZIONE→VERIFICA
dopo fallimenti/successi sorprendenti; promozione a fact procedurale per
operazioni ricorrenti; consolidamento periodico. Vietate lezioni vaghe e
promozioni senza evidenza (anti-drift). Solo prompt: nessun cambiamento
server/API.
Aggiunge qmem_get (GET /v1/memories/{id}) per recuperare un record
esatto per memory_id: usato quando un puntatore/playbook cita un ID.
La ricerca semantica (qmem_search) non garantisce di trovare record
lunghi con query generiche; qmem_get lo risolve in modo deterministico.
Restituisce anche record superseduti (lineage/audit).
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).
- descrizione parametro expires_at in qmem_store: chiarisce che il default è permanente
- skill qmem: sezione Igiene dei record con la garanzia di permanenza
- comportamento verificato sul server: record senza expires_at non selezionato dal filtro cleanup
- raccolta in-memory: richieste per endpoint, latenza (sum/count), errori per status, search queries/hits, punti
- push periodico (30s) a VM via /api/v1/import/prometheus (pattern energy engine, timestamp ms)
- VM_PUSH_URL/VM_PUSH_INTERVAL/METRICS_ENABLED configurabili; default host.docker.internal:8428
- endpoint /v1/metrics (auth) per verifica manuale
- dashboard Grafana versionata in monitoring/qmem-dashboard.json (provisioning: /home/enne2/domotics/grafana/dashboards/)
- verificato sul server: /v1/metrics OK, 6 serie qmem_* in VM
- prima di salvare: ricerca top-3 con min_score 0.92 e stesso project_id
- se trovati: avviso nella risposta con id/score/testo dei candidati e suggerimento qmem_correct
- il salvataggio non viene bloccato
- verificato sul server: record quasi identici trovati con score 1.0/0.9908
- gateway: MemoryIn + payload + risultati search; 422 su valore invalido
- estensione: confidence in qmem_store e qmem_correct (eredita dal superseduto), mostrato nei risultati
- backward compatible: record esistenti → confidence null
- verificato sul server: high/medium/default, 422 su invalida (istanza di test)
- middleware: genera o accetta X-Request-ID, lo restituisce in header
- contextvar letto da _audit: correlazione richieste nei log
- verificato sul server: header + audit correlati (istanza di test)
- _get_http(): creazione lazy, keep-alive riusato tra le chiamate
- lifespan shutdown: aclose del client
- verificato sul server: status + search OK (istanza di test)
- startup (collection+indici) e cleanup task nel context manager lifespan
- shutdown: cancel del cleanup task
- verificato sul server: startup OK, scrittura OK (istanza di test)
- rifiuta il supersede se lo score del top-1 è sotto soglia (evidenza debole/rumorosa)
- messaggio guida: verifica con qmem_search e riprova con memory_id esplicito
- soglia configurabile in ~/.config/pi-qmem/config.json
- gatewayRequest: max 3 retry su 429/5xx/timeout/errore rete, backoff esponenziale + jitter, rispetta Retry-After (cap 10s)
- AbortError (annullamento utente) propagato, mai ritentato
- timeoutMs dalla config usato come fallback quando pi non fornisce signal
- testato: 503→200, sempre-503 (4 tentativi), 429+Retry-After, rete giù, abort
- gateway: tabella in-memory con TTL 24h, hash canonico del payload, scoped per API key
- estensione: crypto.randomUUID() per operazione (store e correct), riusata su retry
- from __future__ import annotations (forward-reference _payload_hash)
- promptGuidelines sui 4 tool (qmem_store/search/correct/meta): 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) — regole vincolanti versionate con l'estensione
- skills/qmem/SKILL.md: procedura completa (punteggi, project_id, supersede, discovery) standard agentskills.io, distribuita via pi.skills nel manifest
- AGENTS.md ridotto a puntatore (riepilogo essenziale + rinvio a skill/tool)
- README aggiornato
- gateway: supersedes_id validato (404/409), backlink superseded_by+superseded_at+supersede_reason sul vecchio record, indici keyword, search esclude i superseduti di default (include_superseded per lineage), risposta con lineage
- estensione: tool qmem_correct (memory_id o query), qmem_store con supersedes_id/supersede_reason, qmem_search con include_superseded
- README/playbook aggiornati, versione 1.1.0
Matteo Benedetto