1. Scopo e confini

Questo documento definisce cosa è un mnest: la traccia, conservata nel mnestoma, di un passaggio di output fra due executor. È il secondo dei tre doc canonici introdotti dal Dialogo sugli executor e la memoria distribuita. Il mnest registra un passaggio di dati osservato fra due executor, non una semplice concomitanza passiva.

Confini

Il documento copre:

• il contratto strutturale di un mnest (campi, vincoli, transizioni);
• quando e come un mnest nasce, si rinforza, decade;
• il proto-mnest: come si rappresenta un desiderio non soddisfatto;
• la persistenza e gli snapshot.

Non copre, e demanda altrove:

• la struttura globale del mnestoma e le sue interrogazioni (vedi mnestoma.html);
• la sintesi che usa proto-mnest ricorrenti (vedi executor.html, cap. 7);
• i criteri del Vaglio (vedi vaglio.html: guardia binaria + giudice graduato, reale dal 27/4);
• la fenomenologia del decadimento (vedi ager, doc futuro).

2. Cos'è un mnest

Un mnest è un nodo del mnestoma che registra un fatto specifico:

Il mnest è quindi una traccia di co-attivazione osservata: non un'inferenza statistica a posteriori, non una dichiarazione di intenti, ma una constatazione di un evento davvero accaduto, registrato dal gateway al termine del turno.

Da qui derivano tutte le sue proprietà importanti:

• È diretto: A → B non è lo stesso di B → A.
• È pesato: più volte si ripete, più il peso cresce; col disuso, decade.
• È ancorato al tempo: porta il timestamp del primo e dell'ultimo uso.
• È distinto per coppia di versioni: read_files → read_files_pdf v2.0 è un mnest, read_files → read_files_pdf v3.0 è un altro.

3. Semantica del mnest

Il mnest registra un passaggio di dati («l'output di A è stato l'input di B»), generato in modo deterministico dal gateway alla chiusura del turno: o c'è stato il passaggio o non c'è stato. Un mnest forte verso un executor che non esiste (proto-mnest, cap. 8) è un buco operativo concreto, non un'analogia.

Il mnest vede dati che si sono mossi, non solo eventi che si sono accesi. Un grafo di mnest è un grafo di flussi reali.

4. Anatomia di un mnest

Un mnest, in forma serializzata, contiene questi campi obbligatori:

{
 "id": "mnest_01HW...", // ULID
 "src_executor": "read_files", // nome canonico del chiamante
 "src_version": "1.0.0",
 "dst_executor": "read_files_pdf", // nome canonico del chiamato
 "dst_version": "2.0.0",
 "weight": 0.42, // [0..1], normalizzato
 "uses": 17, // contatore d'uso totale
 "ts_first": "2026-03-12T18:04:00Z",
 "ts_last": "2026-04-23T09:21:00Z",
 "decay_lambda": 0.018, // /giorno, vedi cap. 6
 "tags": ["fattura", "pdf"], // facoltativi
 "state": "active" // active | proto | decaying | superseded
}

Tre invarianti valgono sempre:

• (src_executor, src_version, dst_executor, dst_version) è chiave: può esistere al massimo un mnest attivo per quella tupla.
• weight è sempre in [0, 1], calcolato come funzione esponenziale del numero di usi recenti (vedi formula al cap. 6).
• ts_last >= ts_first; uses >= 1.

Tag, in breve

I tag sono un'aggiunta opzionale che non influenza il calcolo del peso, ma serve all'ager e al synt per identificare cluster di mnest che vivono nello stesso dominio applicativo (per esempio «fattura», «foto», «email lavoro»). I tag vengono propagati dal contesto del turno al mnest in nascita; l'utente li può ribattere o cancellare in fase di rilettura.

5. Generazione automatica

Un mnest non si dichiara, si osserva. La regola operativa, applicata dal gateway alla chiusura di ogni turno:

1. Per ogni coppia di chiamate A → B all'interno del turno in cui l'output di A è stato passato come input a B:
   1. cerca nel mnestoma un mnest attivo con la chiave (A, ver_A, B, ver_B);
   2. se esiste, incrementa uses, aggiorna ts_last, ricalcola il peso;
   3. se non esiste, ne crea uno nuovo con uses=1, weight iniziale, state="active".
2. Se nel turno c'è stata una richiesta di passaggio verso un executor che non esiste, registra invece un proto-mnest (cap. 8).
3. Se nel turno c'è stata una catena lunga (A → B → C), registra due mnest separati: A→B e B→C. Il mnestoma non rappresenta archi di lunghezza maggiore di uno.

6. Rinforzo e decadimento

Il peso di un mnest è aggiornato a ogni evento secondo una formula con due componenti:

weight(t) = clamp01( weight(t-Δt) * exp(-λ * Δt) + reinforcement(t) )

• Δt è il tempo (in giorni) trascorso dall'ultimo aggiornamento.
• λ è il decay lambda, parametrizzabile per tag (default 0.018/giorno: dimezzamento in ~38 giorni).
• reinforcement(t) è +0.15 per ogni uso registrato nel turno corrente, saturato dal clamp01.

La curva è ispirata al modello di Ebbinghaus, ma il valore di λ è conservativo: a parità d'uso, un mnest non si dimentica mai del tutto in tempi rapidi. La gradualità serve a evitare oscillazioni dovute a periodi di vacanza, malattia, distrazione: l'utente vuole che, quando torna, Metnos ricordi.

Soglie operative

7. Stati di vita

8. Il proto-mnest

Il proto-mnest è un mnest in stato proto: registra che, in un turno, Metnos ha desiderato passare l'output di un executor a un secondo executor che non esiste ancora. La struttura è quasi identica a quella di un mnest normale, con due differenze:

• dst_executor è un «nome desiderato», non un nome risolvibile (per esempio: extract_invoice_number);
• dst_version è null;
• è presente un campo desired_signature con la sintesi della firma attesa: che cosa l'executor dovrebbe fare, quale forma di output, quali errori tipici.

{
 "id": "mnest_01HW...",
 "src_executor": "read_files",
 "src_version": "1.0.0",
 "dst_executor": "extract_invoice_number", // non esiste
 "dst_version": null,
 "desired_signature": {
 "summary": "Estrarre il numero fattura da un PDF.",
 "inputs": ["bytes (pdf)"],
 "outputs": ["str (codice alfanumerico)"],
 "errors": ["NotFound", "Unparseable"]
 },
 "weight": 0.34,
 "uses": 4,
 "state": "proto"
}

La differenza con «una richiesta di feature» nel senso classico è importante: il proto-mnest non è chiesto dall'utente, è constatato dal gateway. Roberto non ha formulato il bisogno: il bisogno è emerso dal fatto che l'avrebbe voluto più volte. Il proto-mnest, quando ricorre, è l'innesco della sintesi (vedi executor.html cap. 7).

9. Chi consulta i mnest

10. Persistenza e snapshot

I mnest vivono in workspace/.mnestoma/mnest.sqlite:

• una sola tabella mnests con i campi del cap. 4 + indici su (src_executor, dst_executor) e weight;
• una tabella events append-only con i singoli rinforzi, per poter ricostruire lo storico del peso (utile per debug e per ager);
• una vista v_mnestoma che proietta lo stato corrente del grafo (active + proto), per le query di lettura.

Il sistema fa uno snapshot mensile del file SQLite in workspace/.mnestoma/snapshots/YYYY-MM.sqlite. Lo snapshot serve a tre cose: rollback in caso di danneggiamento del file vivo, analisi storica del grafo, traccia per chi vuole capire come si è mosso Metnos nel tempo. Gli snapshot più vecchi di 12 mesi sono compressi in .zst ma non eliminati.

Backup

Il file SQLite vivo è incluso nel backup notturno del workspace con le stesse politiche di tutto il resto del workspace. La perdita del mnestoma non è catastrofica (il sistema riparte vuoto e si ricostruisce dall'uso) ma è uno dei dati più preziosi: contiene la storia operativa che Metnos ha imparato a riconoscere.

11. Esempio: la sequenza fattura

Per fissare i concetti, ecco una sequenza tipica di mnest che si forma attorno al flusso «archivia una fattura PDF»:

1. read_files → read_files_pdf v2.0 (peso 0.85, uses 47, "fattura")
2. read_files_pdf v2.0 → invoice_classify (peso 0.78, uses 41, "fattura")
3. invoice_classify → workspace_save (peso 0.81, uses 44, "fattura")

# proto-mnest che ricorre ma non è ancora un executor:
4. read_files_pdf v2.0 → extract_invoice_number (peso 0.34, uses 4, "fattura")

Il quarto, se continua a ripetersi, alzerà il peso fino alla soglia di sintesi e il synt proporrà a Roberto la sintesi del nuovo executor extract_invoice_number. Una volta approvato e firmato, il proto-mnest passerà ad active con il dst_version reso concreto.

12. Domande aperte

1. Garbage collection del file SQLite. Quando si ricicla lo spazio dei mnest archiviati nel file vivo? Mai (storico completo) o periodicamente (per dimensioni)? Aperta.
2. Tag suggeriti dall'LLM. Il gateway può far suggerire tag dall'LLM in fase di chiusura turno. Quanto fidarsi di questi tag? L'utente li deve ratificare? Aperta.
3. Mnest cross-utente. Quando in futuro Metnos avrà più sender pairati (ospiti), i mnest sono per-sender o globali? Probabilmente globali con tag di provenienza, ma da decidere.
4. Decadimento differenziato per categoria. Conviene avere λ diverso per executor side-effect-free vs side-effect-pieni? Aperta.

Metnos — mnest microprogettazione
Doc canonico.