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](../reports/knowledge-archives-release.md).

La [revisione di semplicità](2026-09-08-memory-evidence-simplification-review.md)
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](2026-09-08-memory-evidence-administration.md)
e rimane distinto dal [progetto Evidence management](2026-09-08-evidence-management.md).

## 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](https://qdrant.tech/documentation/search/hybrid-queries/)
e i [filtri sui metadati](https://qdrant.tech/documentation/search/filtering/)
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](../adr/0018-use-postgres-for-memory-and-qdrant-for-retrieval.md).

### 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.