ThothII/docs/plans/2026-09-08-memory-management.md

Progetto: Memory management

Data del piano: 2026-09-08. Aggiornamento 2026-09-09: M1–M3 implementati, con integrazione X1 per le correzioni persistenti dei conflitti. Risultati e limiti sono raccolti nel rapporto X1.

La revisione di semplicità mantiene il perimetro Memory e precisa un salvataggio sequenziale e una pulizia diretta dopo sincronizzazione. Non si progetta l'amministrazione contemporanea all'attività core.

Il progetto realizza il CRUD amministrativo previsto dalla discussione sull'evoluzione della Memory. Segue le decisioni comuni di Administration e rimane distinto dal progetto Evidence management.

Risultato richiesto

Un amministratore apre Memory management direttamente da Administration, cerca e filtra l'intero archivio di un workspace e gestisce le card senza avviare una sessione. La voce è immediatamente sotto Database management, allo stesso livello.

L'elenco comprende le Memory riutilizzabili e gli exemplar solved_question, distinguibili per famiglia. La modifica di un exemplar non riscrive gli artefatti della sessione da cui deriva e non lo trasforma in una decisione applicabile al gate.

Contenuti ammessi: decisione del proprietario

Il perimetro concordato il 2026-09-08 comprende quattro categorie di contenuto. La classificazione descrive il valore della conoscenza; non impone quattro nuovi kind tecnici o una corrispondenza con i tipi delle decisioni del ledger.

Contenuto	Cosa conserva	Esempio inventato
Chiarimento di dominio	Significato riutilizzabile di un termine, con il suo ambito	«In questo workspace, ordine evaso significa che tutte le righe sono state spedite.»
Regola SQL	Regola corretta per join, filtri o aggregazioni, con condizioni e motivazione	«Il codice commessa è univoco solo all'interno dell'esercizio: collegare movimenti e commesse usando codice ed esercizio.»
Domanda risolta	Domanda, SQL approvato e contesto, come exemplar consultativo	«Totale degli ordini del 2024 per cliente», con la query che lo calcola.
Errore da evitare	Errore compreso, motivo e comportamento corretto approvato	«Il join fra ordini e righe moltiplica il totale di testata: calcolare il totale una sola volta per ordine.»

Il criterio di ammissione è l'utilità per altre domande nello stesso ambito. Una scelta come «questa volta usa il 2024» non è una regola riutilizzabile; il 2024 può rimanere nel contesto della domanda risolta. Analogamente, la selezione di una tabella per una domanda non diventa automaticamente una regola di schema linking.

La categoria «errore da evitare» richiede una spiegazione verificata e approvata. Un timeout, una query rifiutata senza motivo o una proposta non selezionata non bastano a produrre conoscenza. Quando errore e correzione esprimono la stessa regola, una sola card conserva la regola e la sua motivazione.

Formazione, aggiornamento e uso delle card

Decisioni del primo round di grill-with-docs

Il proprietario ha approvato le tre raccomandazioni il 2026-09-08:

• Q1, approvazione del salvataggio: riepilogo finale modificabile, preparato durante il lavoro. Il reviewer corregge le card e sceglie quali salvare; la creazione manuale da Administration resta sempre disponibile.
• Q2, operazioni proposte dal core: aggiunte e aggiornamenti espliciti. Il riepilogo distingue una nuova card dalla modifica di una card esistente e ne spiega il cambiamento. La sostituzione richiede la selezione del reviewer; la cancellazione semantica resta un'operazione del CRUD amministrativo. La pulizia automatica dei riferimenti invalidi è disciplinata separatamente da Q5.
• Q3, momento del consumo: i chiarimenti sono proposti all'inizio, le regole di collegamento durante lo schema linking e le regole di calcolo durante la costruzione SQL. Le approvazioni entrano nei gate pertinenti, senza una domanda separata per ciascuna card; gli exemplar rimangono consultativi.

Queste sono decisioni di prodotto; i contratti runtime non sono ancora aggiornati.

Decisioni del secondo round di grill-with-docs

Il proprietario ha approvato i chiarimenti su Q4–Q6 il 2026-09-08:

• Q4, risoluzione persistente dei conflitti: il gate propone azioni chiuse e specifiche per il caso, mostrando record interessati, azione e testo o ambito risultante. Le opzioni possono confermare l'Evidence e correggere la Memory, confermare la Memory e preparare una correzione dell'Evidence, oppure precisare gli ambiti distinti di entrambe. È sempre disponibile «Nessuna proposta è adeguata», che richiede una riformulazione. Le modifiche Memory confluiscono nel riepilogo finale; quelle Evidence seguono l'authoring e la pubblicazione del rispettivo modulo. Come approvato in Q12, accettare la correzione Evidence con le autorizzazioni necessarie avvia anche l'attivazione automatica, senza un ulteriore Publish. Il sistema distingue proposte da approvare, aggiornamenti in corso o falliti e archivio già aggiornato. La sola risoluzione della domanda corrente non esaurisce il flusso.
• Q5, cancellazione dopo modifiche allo schema: dopo una sincronizzazione riuscita dello schema fisico, il backend comunica al modulo Memory gli elementi rimossi. Il modulo identifica tramite dipendenze strutturate le card non più valide e cancella record e proiezioni ricercabili. Non si introduce lo stato «Needs review» per conservarle. Il controllo avviene alla sincronizzazione, senza scansione continua del DWH o interrogazioni aggiuntive a ogni domanda. Un cleanup manuale del Catalog o un errore di accesso al database non prova una rimozione fisica e non avvia questa pulizia. Essa è distinta dalle proposte semantiche del core in Q2. Oggi mancano sia i riferimenti strutturati a colonne nelle Memory sia il collegamento fra sincronizzazione e pulizia: devono essere implementati.
• Q6, verifiche concrete: lo sviluppatore prepara ed esegue test automatici funzionali per CRUD, filtri, approvazioni, aggiornamenti e cancellazioni. Quando cambia la ricerca, verifica casi mirati con card necessarie e card fuori ambito; quando emerge un errore SQL riproducibile, aggiunge una regressione su dati controllati confrontando i risultati, senza richiedere un identico testo SQL. L'esperto di dominio conferma inizialmente regola e risultato atteso soltanto per i casi reali che lo richiedono. La verifica della generazione necessita di un modello reale ed è separata dalla suite deterministica: una query scritta a mano non prova che il modello sappia generarla. Non si introduce una valutazione umana permanente o un benchmark generale con percentuali di miglioramento promesse.

Terzo round: direzione tecnica e capacità di ricerca

• Q7, deciso: il proprietario ha approvato l'evoluzione interna di ThothII. Il modulo riusa l'infrastruttura dell'installazione e integra card, CRUD, mutazioni e recall con i gate; non adotta un framework esterno per governare la Memory.
• Q8, deciso: il proprietario ha approvato ricerca ibrida in Qdrant e collegamenti espliciti fra card gestiti dal core, senza un database a grafi aggiuntivo. Entrambe le capacità sono incluse nella pianificazione attuale; la presenza dei collegamenti non è rinviata alla futura comparsa di casi concreti.

La configurazione approvata comprende:

• ricerca semantica e lessicale ibrida in Qdrant, con filtri sull'ambito;
• collegamenti espliciti fra card, proposti e revisionabili, percorsi nel core con espansione limitata e riordinamento dei risultati insieme a quelli della ricerca;
• persistenza dei collegamenti coordinata con le card, con rimozione dei riferimenti a contenuti cancellati e rispetto dei confini fra workspace e dei gate;
• nessun servizio di database a grafi aggiuntivo.

La scelta include il grafo logico, senza introdurre un servizio di graph DB. La qualità non è garantita dalla scelta di un motore: mantenere queste capacità evita una rinuncia architetturale ai collegamenti, ma non dimostra equivalenza qualitativa con qualsiasi soluzione basata su graph DB. Qdrant è il motore di ricerca; l'archivio autorevole è PostgreSQL, scelto in Q9.

Le query ibride di Qdrant e i filtri sui metadati coprono le capacità di ricerca indicate. La logica dei collegamenti di dominio nel core è lavoro applicativo da implementare.

Decisioni del quarto round di grill-with-docs

• Q9, archivio autorevole: il proprietario ha approvato PostgreSQL, già presente nell'installazione, con tabelle proprie del modulo Memory per card, collegamenti e dipendenze dallo schema. Sostituisce il registro JSONL; Qdrant è l'indice rigenerabile. Le modifiche correlate vengono coordinate in PostgreSQL e la propagazione a Qdrant deve gestire esplicitamente errori e cancellazioni.
• Q10, gestione dei collegamenti: il core propone i collegamenti insieme alle card, indicando destinazione e significato. Il reviewer li approva nello stesso riepilogo finale, senza un gate aggiuntivo. Administration ne consente creazione, modifica e cancellazione manuali. Quando una card è cancellata vengono rimossi anche i collegamenti che la coinvolgono, conservando le altre card. I collegamenti contribuiscono al recupero e non applicano automaticamente i contenuti.

La decisione architetturale è registrata nell'ADR 0018.

Flusso da implementare

Il flusso seguente traduce le decisioni approvate. I payload e l'integrazione con i gate sono dettagli da definire nell'implementazione, senza altre decisioni di prodotto pendenti.

1. Durante il lavoro il core individua possibili conoscenze riutilizzabili a partire da decisioni e artefatti registrati. Una candidata esplicita cosa afferma, dove vale, perché è utile e su quale correzione o decisione si basa.
2. Prima di proporne il salvataggio confronta la candidata con le card correnti. Un doppione esatto non richiede una nuova card; una somiglianza semantica non autorizza da sola a eliminare o sovrascrivere una conoscenza.
3. Alla conclusione del lavoro presenta un riepilogo editabile delle aggiunte e degli aggiornamenti proposti. Il reviewer può correggere il contenuto, restringere l'ambito e scegliere cosa salvare; approvare la query non equivale ad approvare ogni generalizzazione ricavata dalla query.
4. Una correzione alla stessa regola nello stesso ambito propone un aggiornamento esplicito della card esistente. Regole valide in ambiti diversi restano distinte; un conflitto irrisolto non viene risolto silenziosamente dal modello.
5. Le card salvate sono subito consultabili in Memory management; la loro disponibilità al recall segue lo stato di indicizzazione. La scrittura sostituisce il contenuto corrente senza introdurre una cronologia delle Memory.

La creazione manuale da Memory management resta disponibile in qualsiasi momento e non dipende dal riepilogo finale di una sessione. La form richiede contenuto e ambito adeguati alla famiglia e identifica l'origine amministrativa.

Gli exemplar conservano domanda e soluzione approvata come materiale consultativo. Il loro salvataggio non applica le scelte di quella soluzione a domande successive. La distribuzione del consumo nei passaggi pertinenti è decisa in Q3. Restano da definire i payload e l'integrazione con i gate esistenti, compreso il contesto necessario a proporre una regola di collegamento o di calcolo e a registrarne l'approvazione.

Scenari per verificare il design

Evento	Esito atteso
Il reviewer corregge un join perché il codice commessa si ripete fra esercizi e approva la spiegazione.	Proporre la regola con entrambe le chiavi e l'ambito delle tabelle interessate.
Il reviewer chiede di limitare solo la domanda corrente al 2024.	Nessuna regola generale; mantenere il periodo nell'eventuale exemplar.
Una query conta più volte lo stesso ordine e la correzione viene spiegata e approvata.	Proporre una card che descrive la granularità corretta e il rischio di duplicazione.
Una query fallisce per timeout o una memory non viene selezionata.	Nessuna nuova regola dedotta automaticamente dall'evento.
La candidata ripete esattamente una regola già presente nello stesso ambito.	Evitare una nuova card duplicata.
Una nuova regola corregge una card dello stesso ambito.	Mostrare la sostituzione proposta prima del salvataggio; conservare poi solo il contenuto corrente.
Due regole differenti valgono per processi o tabelle differenti.	Conservare entrambe con ambiti espliciti, senza generalizzarle al workspace intero.
Il reviewer risolve un contrasto fra Memory ed Evidence.	Mostrare una correzione esplicita degli archivi; applicare i percorsi distinti per Memory ed Evidence. L'accettazione autorizzata della correzione Evidence avvia anche l'attivazione; indicare esito, operazione in corso o errore.
Una sincronizzazione riuscita accerta la rimozione di una colonna da cui dipende una card.	Cancellare la card dipendente e rimuoverla dai risultati di ricerca.
La connessione al DWH fallisce oppure vengono puliti solo metadati del Catalog.	Non interpretare l'evento come prova di rimozione della colonna e non cancellare Memory per quel motivo.

Differenza rispetto al runtime corrente

harness/tht/memory/core.py limita REUSABLE_TYPES a concept_clarified. Anche il contratto Pi di F2 ammette soltanto questi chiarimenti; gli exemplar solved_question hanno già un percorso distinto di consultazione.

Il perimetro concordato amplia quindi il modulo Memory. Il design deve distinguere la conoscenza riutilizzabile dall'evento di workflow che l'ha originata, e aggiornare insieme estrazione, validazione, persistenza, recall e gate. Aggiungere alla whitelist tutti i tipi delle decisioni SQL o sulle tabelle promuoverebbe anche scelte occasionali e non realizza il requisito.

Funzioni

• Elenco paginato e ordinabile, ricerca per testo o identificatore.
• Filtri combinabili per workspace, famiglia/kind, concetti, tabelle e colonne quando presenti, provenienza e data di aggiornamento.
• Dettaglio completo: titolo, contenuto, ambito, motivazione e provenienza disponibile.
• Creazione manuale di una card, distinguibile da una card prodotta dal workflow; la creazione manuale non inventa una sessione o una decisione di origine.
• Modifica dei campi consentiti dalla famiglia, con validazione e annullamento.
• Cancellazione del record e rimozione delle sue proiezioni ricercabili.
• Indicazione di contenuti salvati ma non ancora disponibili al recall, con retry dell'operazione necessaria a renderli disponibili.

L'elenco amministrativo legge i record persistiti senza richiedere embedding o ricerca per similarità. Un'indisponibilità dell'archivio deve produrre un errore esplicito, distinguibile da un elenco vuoto. I filtri sono applicati sull'intero archivio, prima della paginazione, e non sui soli risultati del recall.

Comportamento delle modifiche

Una modifica sostituisce il contenuto corrente. Non si introducono revisioni storiche, snapshot dedicati alle vecchie sessioni o migrazioni per conservarne il comportamento. La cancellazione toglie la card dall'archivio e dal recall ordinario.

La mutazione deve aggiornare o invalidare ogni proiezione interessata. Un errore dell'indice non può essere presentato come piena disponibilità del nuovo contenuto, né permettere di usare silenziosamente il contenuto eliminato o sostituito. La strategia di consistenza e di retry appartiene al design tecnico del modulo.

Il salvataggio esplicito dell'amministratore cura il contenuto condiviso. Il suo successivo consumo nel core mantiene la semantica della famiglia: le Memory vengono proposte secondo i gate del workflow, gli exemplar restano consultativi.

Piano esecutivo

M1 — Archivio e CRUD amministrativo

Definire nel modulo harness/tht/memory/ il contratto delle card: identità stabile, workspace, contenuto, famiglia, ambito, motivazione, provenienza e dati specifici delle domande risolte. I riferimenti allo schema identificano database, tabella e colonna senza affidarsi alla sola presenza di nomi nel testo. Le card manuali non richiedono sessioni inventate.

Implementare un repository PostgreSQL del modulo con card, collegamenti e dipendenze. La transazione aggiorna insieme il contenuto e le modifiche correlate; la propagazione a Qdrant avviene nello stesso flusso di salvataggio. Conservare un'indicazione persistente dell'operazione incompleta, sufficiente anche a ripulire cancellazioni dopo un riavvio; il recupero usa un retry esplicito. Non servono una coda generale, un nuovo worker o una sincronizzazione continua. Un risultato indicizzato con contenuto superato o privo di card autorevole non può essere usato dal recall. Gli exemplar passano anch'essi dall'archivio autorevole. La transizione dal registro JSONL non introduce scritture doppie permanenti o compatibilità storica delle sessioni.

Esporre attraverso il backend elenco filtrato prima della paginazione, dettaglio, creazione, aggiornamento, cancellazione, gestione dei collegamenti ed esito della propagazione. Le operazioni chiamano la logica del harness e applicano controllo amministrativo e isolamento del workspace. La UI legge il repository attraverso queste API anche quando il servizio di embedding o Qdrant è indisponibile.

Consegnare Memory management nell'AppShell con form, contenuto completo, gestione dei collegamenti e feedback di salvataggio/indicizzazione. Verificare persistenza PostgreSQL, rollback delle mutazioni correlate, aggiornamento e rimozione dal recall, retry dopo errore dell'indice, filtri sull'intero archivio e autorizzazioni. Una cancellazione elimina i collegamenti incidenti conservando le altre card.

M2 — Ricerca ibrida e collegamenti

Estendere l'adapter Qdrant alla ricerca dense e lessicale della Memory e applicare l'ambito anche ai risultati raggiunti attraverso collegamenti. Le card iniziali alimentano l'espansione limitata nel core; deduplicazione, gestione dei cicli e limiti espliciti impediscono una visita incontrollata dell'archivio. I risultati vengono riordinati insieme e risolti contro il contenuto autorevole corrente.

Verificare card attese, esclusioni per ambito, cicli, collegamenti verso card rimosse e rigenerazione dell'indice da PostgreSQL. Quando si verifica il recupero effettivo, usare il percorso di embedding e ricerca configurato su un indice isolato: un fake che restituisce gli ID predisposti verifica soltanto il contratto applicativo. La separazione fra le collezioni Reference e Memory rimane quella degli ADR 0017 e 0018.

M3 — Workflow e sincronizzazione fisica

Aggiornare insieme contratti, CLI, regole Pi e widget necessari al riepilogo finale modificabile. Il salvataggio applica soltanto card e collegamenti selezionati; le nuove categorie entrano nei gate pertinenti. Il recupero di una regola non ne costituisce approvazione, e l'exemplar continua a essere consultativo.

Collegare la sincronizzazione fisica del Catalog alla pulizia delle dipendenze nel modulo Memory con una chiamata diretta dopo l'applicazione riuscita dello schema, con copertura del controllo e riferimenti rimossi. Per recuperare un'interruzione fra applicazione e pulizia, conservarne lo stato pendente oppure verificare di nuovo le dipendenze contro lo snapshot fisico riuscito e il suo ambito: il nuovo diff da solo perderebbe le rimozioni già applicate. La pulizia è ripetibile e non richiede un sistema generale di consegna eventi. Un confronto parziale non prova la rimozione di elementi fuori dall'ambito controllato. La pulizia aggiorna archivio, collegamenti e proiezioni senza un'azione manuale ulteriore.

Verificare selezioni e rifiuti nel riepilogo, contenuto manuale, categorie ammesse, notifica di rimozione fisica, errore di connessione e cleanup del solo Catalog. Integrare le correzioni che riguardano Evidence nell'incremento congiunto X1, dopo il completamento del relativo servizio di authoring e attivazione.

L'evoluzione interna è decisa in Q7; ricerca ibrida e grafo nel core in Q8; PostgreSQL autorevole in Q9; gestione dei collegamenti in Q10. I contratti tecnici di persistenza, indicizzazione e API devono attuare queste decisioni. Apprendimento automatico da rifiuti non spiegati e consolidamento automatico restano fuori dal perimetro concordato; gli errori compresi e approvati rientrano nei contenuti decisi.

Criteri di completamento

• Accesso amministrativo indipendente da sessioni e da Database management.
• Tutti i record sono raggiungibili con elenco, filtri e paginazione, senza dipendere dalla disponibilità di embedding e recall semantico.
• Creazione, modifica e cancellazione persistono dopo riapertura della pagina.
• Dopo una mutazione completata il recall usa il contenuto corrente; i record cancellati non riappaiono dopo reindicizzazione o preprocessing.
• Errori di salvataggio e indicizzazione sono distinguibili e recuperabili.
• API e interfaccia rispettano isolamento dei workspace e accesso amministrativo.
• Nessuna operazione del CRUD modifica Evidence o metadati del database.
• Non vengono richieste compatibilità storica o conservazione delle sessioni esistenti.
• Le quattro categorie concordate sono rappresentabili senza promuovere le scelte occasionali a regole generali; gli scenari di ammissione verificano il confine.
• La rimozione fisica accertata di una dipendenza elimina le card interessate; errori di connessione e cleanup del Catalog non vengono scambiati per rimozioni.
• Le scelte sui conflitti producono correzioni persistenti esplicite secondo Q4.
• La verifica rispetta Q6, separando contratti funzionali e casi di generazione reale.
• Il recupero combina ricerca ibrida, filtri d'ambito e collegamenti espliciti fra card; la gestione del grafo non richiede un servizio di database aggiuntivo.
• Card, collegamenti e dipendenze hanno un'unica fonte autorevole PostgreSQL; la rigenerazione di Qdrant conserva il contenuto corrente e le cancellazioni.
• I collegamenti sono curabili nel riepilogo e in Administration; cancellare una card elimina i suoi collegamenti senza cancellare altre card.