Files

T

Matteo Benedetto 1832562a7f feat: indice locale SQLite/FTS5 + fallback testuale offline per qmem

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.

2026-09-13 15:53:56 +02:00

2.4 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 non ha coda locale: con il gateway giù il record non viene salvato. Annota il contenuto e riscrivilo quando il gateway è raggiungibile.

2.4 KiB Raw Blame History Unescape Escape