← Indice documentazione Guida all'architettura › Mnestoma

Metnos

Mnestoma: archivio degli archi operativi

Schema SQLite, query, manutenzione e integrazioni effettive.

Il mnestoma è l'archivio locale che può rappresentare un grafo di mnest fra executor. Il codice implementa persistenza, navigazione, decadimento e strumenti di ispezione. Non è oggi un grafo che il runtime popola automaticamente da ogni turno, e non è una memoria personale dell'utente.

1. Scopo e stato

Mnestoma apre un database SQLite con WAL e foreign key attive. L'API permette di registrare archi, cambiarne lo stato, percorrerli, cercare i proto ricorrenti e leggere statistiche ed eventi.

Il runtime dei turni alimenta nello stesso file la tabella distinta canonical_query_log quando riceve una canonical query utile. Non chiama invece record_passing() per gli archi. Le due forme di telemetria non vanno confuse.

2. Modello del grafo

Nel modello logico, i nodi sono nomi/versioni di executor e gli archi sono mnest diretti e pesati. Un arco proto termina su un nome desiderato senza versione. La query walk(start, max_depth) esegue una ricerca in ampiezza, evita i proto per impostazione predefinita e ordina i percorsi per peso medio decrescente.

Questa struttura può essere usata dal composer di Synt per trovare una catena di executor già esistenti. Non genera L0 o L1, non modifica il ranking ordinario del pianificatore e non sostituisce il catalogo firmato.

3. Che cosa non contiene

Non è	Motivo
Storia completa dei turni	I turni hanno log separati; un evento può conservare soltanto il loro identificatore.
Profilo dell'utente	Lo schema descrive executor, archi e telemetria tecnica, non preferenze o fatti personali.
Cache dei piani	L0 e L1 usano archivi, chiavi e regole di validità propri.
Prova degli effetti	La presenza di un arco dipende dal chiamante che lo ha scritto.
Sistema automatico di sintesi	I proto sono segnali; Synt, test e promoter hanno responsabilità separate.

4. Schema del database

Oggetto	Contenuto
`executors`	Nome, versione, stato, istante di caricamento e hash del manifest. L'API corrente non la popola automaticamente.
`mnests`	Archi, pesi, usi, timestamp, stati, tag e firma desiderata.
`events`	Rinforzi, decadimenti e cambi di stato, con `turn_id` facoltativo.
`v_mnestoma`	Vista degli archi `active` e `proto`.
`canonical_query_log`	Canonical query, tool, forma e valori osservati degli argomenti, contatori ed esito. È telemetria separata dal grafo.

All'apertura, migrazioni idempotenti aggiungono events.turn_id e canonical_query_log.args_observed ai database precedenti.

5. Scrittura e interrogazione

Le principali operazioni pubbliche sono:

record_passing(): crea o rinforza un mnest o proto;
transition_state() e promote_proto_to_active(): cambiano stato con evento;
top_k_outgoing(), top_k_incoming(), walk() e by_tag(): interrogano il grafo;
recurring_protos(), decaying() e top_active(): selezionano insiemi operativi;
events_for(), audit_recent() e stats(): supportano ispezione e tracciabilità;
record_canonical_query(): aggiorna la telemetria separata delle query normalizzate.

6. Ager notturno

Lo scheduler installa il processo nightly_aging alle 03:30. Il processo esegue in sequenza l'ager degli executor e Mnestoma.apply_ager(). Quest'ultimo:

decade gli archi active e proto in base al tempo;
sposta gli active sotto soglia a decaying;
conta i decaying candidati all'archiviazione;
elimina i proto sotto soglia;
conta i proto che hanno raggiunto le soglie di ricorrenza.

Il processo è idempotente rispetto allo stesso istante logico soltanto se non viene ripetuto con timestamp crescente: ogni esecuzione aggiorna ts_last e scrive eventi per i record decaduti.

7. Archiviazione e conservazione

L'ager non archivia automaticamente gli archi decaying: restituisce un conteggio proposed_archive. Non esiste nel modulo una routine che crei snapshot mensili, comprima copie annuali o includa il database in un backup. Queste operazioni richiedono una politica esterna esplicita.

La sola cancellazione automatica del grafo eseguita dall'ager riguarda i proto-mnest con peso inferiore a 0.05. Anche in questo caso gli eventi associati vengono rimossi dalla foreign key con ON DELETE CASCADE.

8. Nomi nelle due lingue

La documentazione italiana usa mnestoma; quella inglese usa mnestome. Il nome del modulo Python, della classe e della directory SQLite resta mnestoma in entrambe le lingue. Mnest è il nome tecnico del singolo arco e non viene tradotto.

9. Avvio e alimentazione

Alla prima apertura il database viene creato con schema vuoto. Non viene installato un seed nascosto di archi e non esiste uno stato seed ammesso dalla classe Mnest. Gli archi compaiono soltanto attraverso chiamate esplicite all'API o dati già presenti nel database configurato.

I turni possono invece aggiungere record a canonical_query_log. Questa attività non deve essere mostrata come nascita di mnest, cluster o percorsi L0/L1.

10. Ispezione e osservabilità

Il comando python3 -m mnestoma offre sottocomandi per statistiche, ager, relazioni principali in ingresso e in uscita, prototipi, percorsi, sommario e tracciabilità. Il renderer python3 -m observability render può includere conteggi, archi attivi, proto ed eventi recenti in un HTML statico.

Questi strumenti leggono il contenuto dell'archivio; non dimostrano che il contenuto sia completo. Un mnestoma vuoto è un esito legittimo dell'integrazione corrente.

11. Confini operativi

Il percorso predefinito è <workspace>/.mnestoma/mnest.sqlite: l'ambito è il workspace configurato, non un utente ricavato dal turno.
Non inserire fatti personali, credenziali o contenuti dei documenti in tag e firme desiderate.
Prima di usare il grafo per decisioni per utente servono ownership esplicita, autorizzazione e filtraggio; lo schema corrente non li rappresenta.
Il composer può soltanto proporre catene presenti: catalogo, firme, policy, argomenti e guardie restano vincoli indipendenti.
Il codice sorgente è la fonte del contratto operativo: runtime/mnestoma.py, runtime/synt.py, runtime/jobs/maintenance_tasks.py e runtime/observability.py.