Files

T

Matteo Benedetto 322b4cf446 feat(outbox): store offline con coda locale e sincronizzazione al ritorno della rete

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.

2026-09-13 17:29:09 +02:00

3.1 KiB

Raw Blame History

name, description

name	description
qmem	Shared agent memory (Qdrant + BGE-M3). Search, store, correct, census, or explore hierarchical memory records. Use before any task needing prior knowledge, project discovery, or memory maintenance.

qmem — Shared Memory

Gateway qmem.enne2.net → Qdrant + BGE-M3. No LLM writes: records are deliberate and structured. One API key; agent_id is provenance only.

Tools

Tool	Use
`qmem_search`	Semantic search with filters (kind, project_id, scope, top_k, min_score, parent_id, level, topic, hybrid)
`qmem_store`	Save a record (kind, project_id REQUIRED, scope, source, expires_at, supersedes_id, parent_id, level, topic, links)
`qmem_correct`	Fix a false record: a new version supersedes the old
`qmem_meta`	Discovery: projects, scopes×kinds, agents, superseded (choose filters)
`qmem_get`	Fetch one record exactly by UUID (O(1), includes superseded)
`qmem_tree`	Show full hierarchy (L1 root + L2 children) of a topic

Hierarchy (L1 root + L2 subtopics)

Save detail leaves as L2_SUBTOPIC, topic MACRO/SUB, with parent_id when known.
Save a macro index as L1_ROOT, topic MACRO/ROOT, links=[{target_id: <l2-uuid>, predicate: "parent_of"}].
Filter search by parent_id, level, or topic.
From an L2 node, use its parent_id to qmem_get the root.

Search scores

>=0.60 solid — use it
0.45–0.60 weak — verify the evidence first
<0.45 noise — filtered by default (min_score 0.45) Empty results: reformulate, narrow kind/scope/project_id, or lower min_score. Score is not truth: check the cited source.

Indice locale (fallback quando il gateway è giù)

Se il gateway non risponde, qmem_search usa l'indice locale SQLite/FTS5 (~/.local/share/pi-qmem/qmem.sqlite) e lo dichiara: fallback: local_sqlite. In quel caso:

la ricerca è testuale (BM25), non neurale: nessuno score semantico e nessuna soglia 0.45/0.60 da applicare;
i risultati sono osservazioni più vecchie del gateway (storico ricostruito dalle sessioni pi + ultimo enrich): verifica prima dell'uso;
comandi: /qmem:local status | import | find <query> | enrich | pull (import dalle sessioni, enrich/pull dal gateway quando torna online).

qmem_store accoda in locale: con il gateway giù il record entra nell'outbox locale (SQLite), è subito ricercabile (marcato ⏳) e viene inviato al gateway al ritorno della connessione (flush automatico su session_start, oppure /qmem:local flush). Finché non è sincronizzato non è nella memoria condivisa: i risultati locali marcati ⏳ non sono visibili agli altri agenti.

Stato e gestione della coda:

/qmem:local queue — voci in attesa, tentativi, ultimo errore
/qmem:local flush — invio immediato (idempotente: Idempotency-Key = id locale)
esiti: synced (sul gateway, il record locale adotta l'ID remoto), duplicate (409: era già presente, viene registrato l'ID del match), failed (4xx di validazione: non ritentato in automatico)
supersede offline: una correzione che punta a un record ancora locale viene rimappata all'ID remoto al momento del flush

3.1 KiB Raw Blame History Unescape Escape