ThothII/docs/plans/2026-09-08-memory-m1-spec.md

# M1 — Archivio autorevole e amministrazione delle Memory Card

Data: 2026-09-08. Stato: M1 implementato e verificato localmente;
confini di test confermati dal proprietario il 2026-09-08.

Primo incremento del progetto Memory management. Attua le decisioni già approvate
nel piano del 2026-09-08 e nell'ADR 0018. Le scelte tecniche di dettaglio qui
proposte derivano dalla ricognizione del runtime. Gli esiti dell'implementazione
sono riportati nel [rapporto di verifica](../reports/knowledge-archives-release.md).

## Problem Statement

L'amministratore deve poter trovare, leggere e curare tutta la conoscenza
riutilizzabile di un workspace: chiarimenti di dominio, regole SQL, domande
risolte ed errori compresi da evitare. Oggi manca una pagina amministrativa
dedicata e l'archivio è frammentato: le Memory sono registrate in JSONL, mentre
gli exemplar delle domande risolte sono indicizzati attraverso un percorso distinto.

Questa situazione non offre un unico archivio completo di card, collegamenti e
dipendenze strutturate. La disponibilità dell'indice non deve determinare se una
card è consultabile o modificabile. Una modifica o cancellazione deve inoltre
impedire che una ricerca successiva utilizzi contenuti superati, anche se
l'aggiornamento dell'indice fallisce.

## Solution

Consegnare la pagina **Memory management** in Administration e un archivio
PostgreSQL autorevole, appartenente al modulo Memory. La pagina consente elenco
completo, ricerca testuale, filtri, dettaglio, creazione, modifica, cancellazione
e gestione dei collegamenti. I contenuti restano consultabili con embedding o
Qdrant indisponibili, purché PostgreSQL sia disponibile.

Un salvataggio aggiorna insieme card, collegamenti e dipendenze, poi propaga la
modifica a Qdrant. L'amministratore vede se il contenuto è stato salvato e se è
disponibile al recall. Se la propagazione fallisce può riprovarla, anche dopo un
riavvio. I contenuti rimossi o superati non sono utilizzati dal recall.

M1 consegna l'amministrazione e la coerenza dell'archivio. La ricerca ibrida con
espansione dei collegamenti e il nuovo riepilogo del workflow sono gli incrementi
M2 e M3, entrambi ancora obbligatori per completare il progetto Memory.

## User Stories

1. Come amministratore, voglio aprire Memory management da Administration, così
   da curare la conoscenza senza avviare una sessione.
2. Come amministratore, voglio scegliere esplicitamente il workspace da
   amministrare, così da sapere a quale archivio appartiene ogni operazione.
3. Come amministratore, voglio elencare tutte le card del workspace, così da
   raggiungere anche quelle che non compaiono nel recall semantico.
4. Come amministratore, voglio cercare per testo o identificatore e ordinare i
   risultati, così da trovare una card senza conoscerne la formulazione esatta.
5. Come amministratore, voglio combinare filtri per famiglia, concetti, riferimenti
   a tabelle o colonne, provenienza e aggiornamento, così da restringere l'intero
   archivio prima della paginazione.
6. Come amministratore, voglio leggere contenuto completo, ambito, motivazione e
   provenienza disponibile, così da capire quando una card è applicabile.
7. Come amministratore, voglio creare una card manuale senza inventare una sessione
   o una decisione di origine, così da registrare conoscenza curata direttamente.
8. Come amministratore, voglio rappresentare chiarimenti, regole SQL, domande
   risolte ed errori compresi, così da conservare i contenuti concordati.
9. Come amministratore, voglio conservare domanda, SQL e contesto di un exemplar,
   così da distinguerlo da una regola generale.
10. Come amministratore, voglio associare dipendenze esplicite a database, tabelle
    e colonne, così da non affidare l'identificazione degli oggetti al testo libero.
11. Come amministratore, voglio correggere i campi consentiti dalla famiglia e
    annullare una modifica non salvata, così da controllare il contenuto corrente.
12. Come amministratore, voglio ricevere errori di validazione comprensibili senza
    perdere il testo inserito, così da poterlo correggere.
13. Come amministratore, voglio creare, modificare e cancellare collegamenti con
    destinazione e significato espliciti, così da curare le relazioni fra card.
14. Come amministratore, voglio salvare card e modifiche correlate come un'unica
    operazione, così da non lasciare collegamenti o dipendenze parziali.
15. Come amministratore, voglio cancellare una card e i suoi collegamenti
    incidenti conservando le altre card, così da rimuovere solo il contenuto scelto.
16. Come amministratore, voglio ritrovare le modifiche dopo riapertura della pagina
    e riavvio del servizio, così da verificare che il salvataggio sia persistente.
17. Come amministratore, voglio consultare e curare l'archivio quando embedding o
    Qdrant sono indisponibili, così da proseguire il lavoro amministrativo.
18. Come amministratore, voglio distinguere archivio vuoto e archivio non
    disponibile, così da non interpretare un guasto come perdita dei dati.
19. Come amministratore, voglio distinguere salvataggio fallito e contenuto
    salvato con indicizzazione incompleta, così da scegliere il recupero corretto.
20. Come amministratore, voglio riprovare una propagazione incompleta anche dopo
    un riavvio o una cancellazione, così da completare la pulizia dell'indice.
21. Come reviewer, voglio che una nuova ricerca escluda card eliminate o contenuti
    superati, così da ricevere soltanto conoscenza corrente.
22. Come reviewer, voglio che gli exemplar rimangano consultativi e che una Memory
    recuperata non costituisca approvazione, così da conservare il controllo del workflow.
23. Come amministratore, voglio che reindicizzazione e preprocessing rispettino le
    cancellazioni e le correzioni, così da non doverle ripetere.
24. Come operatore dell'installazione, voglio preparare lo schema e configurare
    l'accesso Memory con i meccanismi esistenti, così da avviarlo senza nuovi servizi.
25. Come proprietario del workspace, voglio che API e comandi rispettino il
    contesto autorizzato, così da evitare accessi o collegamenti fra archivi diversi.
26. Come proprietario del workspace, voglio che il CRUD Memory lasci invariati
    Evidence e metadati del database, così da mantenere distinte le responsabilità.

## Implementation Decisions

### Responsabilità e punti d'ingresso

- Il modulo Memory del harness possiede modello, validazione, repository,
  mutazioni, collegamenti, dipendenze e coerenza delle proiezioni. PostgreSQL è
  autorevole; Qdrant contiene una proiezione ricostruibile.
- I comandi Memory esistenti diventano adattatori del medesimo servizio. La
  superficie viene completata con creazione manuale, gestione dei collegamenti,
  elenco delle propagazioni incomplete e retry. Nessuna logica di persistenza
  Memory viene duplicata nel backend.
- Il backend espone API amministrative attraverso il runner del harness,
  associando principal attendibile e configurazione del workspace alla richiesta.
  Si conservano opzioni di configurazione per comando e output JSON puro.
- La ricognizione conferma che il harness usa già SQLAlchemy e PostgreSQL per le
  sessioni. Se ne riusano i meccanismi adatti, mantenendo separati modello,
  migrazioni e proprietà dei dati Memory. Il repository in memoria del Metadata
  Catalog è un test double del Catalog, non il modulo Memory.

### Modello e transazioni

- La card ha identità stabile, workspace, famiglia/contenuto, titolo o soggetto,
  ambito, motivazione, provenienza, concetti e date di creazione/aggiornamento.
  Le domande risolte conservano anche domanda, SQL e contesto. L'identità di una
  card manuale non dipende da una sessione né dal solo testo.
- Il modello rappresenta le quattro categorie di contenuto approvate senza
  imporre quattro nuovi kind vettoriali o la corrispondenza con i tipi del ledger.
  Le origini manuali sono distinguibili; sessione e decisione sono riferimenti
  opzionali quando effettivamente disponibili.
- I collegamenti sono record propri del modulo con sorgente, destinazione e
  significato. Le due card devono esistere nello stesso workspace. La cancellazione
  di una card elimina i collegamenti incidenti, senza propagarsi alle altre card.
- Le dipendenze identificano esplicitamente database, schema, tabella e colonna
  secondo l'ambito applicabile. Il contratto consente il futuro confronto con
  lo schema fisico. Un cleanup dei metadati Catalog non deve poter cancellare
  card attraverso una cascata implicita di chiavi esterne.
- Le tabelle logiche necessarie sono card, collegamenti, dipendenze e stato
  operativo delle proiezioni. Card e modifiche correlate si aggiornano nella
  stessa transazione. Una validazione o scrittura fallita non lascia aggiornamenti
  parziali. Non si conserva una storia delle revisioni del contenuto.
- Le modifiche ordinarie non spostano una card in un altro workspace. Tutti gli
  identificatori ricevuti vengono verificati nel workspace dell'operazione,
  inclusi estremi dei collegamenti e riferimenti delle azioni di retry.

### Salvataggio, cancellazione e recall

- Il servizio valida l'intera mutazione, registra il nuovo stato autorevole e
  il lavoro di propagazione nella stessa transazione PostgreSQL, poi aggiorna
  Qdrant nello stesso flusso di salvataggio. Si completa un'operazione alla volta;
  non occorrono una coda generale, un worker o una sincronizzazione continua.
- Lo stato persistente è sufficiente a distinguere la proiezione del contenuto
  corrente da una proiezione precedente e a ritentare l'azione dopo un riavvio.
  Può usare una versione tecnica o un'impronta interna; non è una cronologia
  editoriale né un ulteriore stato che l'utente debba gestire.
- Un risultato Qdrant è utilizzabile solo se corrisponde a una card autorevole
  corrente del workspace e a una proiezione valida. Il contenuto restituito
  viene dall'archivio autorevole. La verifica si applica anche agli exemplar.
  In assenza di verifica autorevole il recall non restituisce il vecchio payload.
- Dopo il commit PostgreSQL, una propagazione fallita lascia il contenuto
  consultabile nell'amministrazione e la sua proiezione non utilizzabile dal
  recall fino al recupero. L'esito distingue chiaramente questo caso da un
  salvataggio fallito prima del commit.
- La cancellazione rimuove card, collegamenti incidenti e dipendenze e conserva
  soltanto i dati operativi necessari a eliminare la proiezione. La card non è
  più richiamabile anche se il punto Qdrant esiste ancora. La pulizia pendente
  resta raggiungibile dalla pagina, senza richiedere il dettaglio della card eliminata.
- Il retry è esplicito e ripetibile. Usa lo stato corrente del repository, non
  il contenuto di una vecchia richiesta. Un retry superato non può sovrascrivere
  una correzione successiva né ricreare una card cancellata.
- La ricostruzione degli indici Memory e solved-question usa esclusivamente
  le card autorevoli. Non reimporta automaticamente il registro JSONL, i payload
  Qdrant o le sessioni di origine. Il preprocessing delle reference mantiene
  la separazione delle collezioni stabilita nell'ADR 0017.
- Anche i produttori attuali di Memory ed exemplar scrivono attraverso il
  servizio autorevole. Si adeguano promozione, salvataggio singolo e percorso di
  finalizzazione quanto necessario a evitare scritture dirette al solo indice.
  Un errore successivo al commit della sessione non deve annullarne la finalizzazione;
  l'esito e il recupero Memory restano espliciti. Questa transizione non introduce
  il nuovo riepilogo di approvazione previsto da M3.

### API, autorizzazione e configurazione

- Il contratto amministrativo comprende elenco, dettaglio, creazione,
  aggiornamento, cancellazione, manutenzione dei collegamenti, stato delle
  propagazioni incomplete e retry. Le mutazioni restituiscono identità interessata,
  esito del salvataggio ed esito della propagazione; gli errori non espongono segreti.
- L'elenco restituisce pagina, conteggio totale filtrato e ordinamento stabile
  con identificatore come discriminante. Ricerca testuale e filtri combinabili
  agiscono sull'intero archivio prima della paginazione, senza embedding.
- Il backend distingue input invalido, accesso negato, record assente nel
  workspace richiesto, archivio indisponibile e propagazione incompleta dopo
  salvataggio. Un archivio indisponibile non produce una lista vuota riuscita.
- Si riusano autenticazione, controlli di accesso e trasmissione del principal.
  Il catalogo attuale non ha un permesso Memory dedicato: la proposta è aggiungere
  la capability amministrativa Memory al ruolo admin esistente, senza introdurre
  ruoli nuovi. Il controllo copre anche letture amministrative e retry.
- Le operazioni amministrative e i comandi esposti non permettono bypass del
  controllo nel harness. Le scritture già previste dal workflow conservano il
  proprio contesto autorizzato di sessione; non diventano CRUD amministrativo
  liberamente accessibile a un utente ordinario. Il recall rimane accessibile
  secondo le regole del workflow.
- M1 include configurazione della connessione al PostgreSQL dell'installazione,
  distribuzione protetta delle credenziali al harness, migrazioni versionate e
  privilegi runtime necessari alle sole tabelle Memory. Si riusano i meccanismi
  di configurazione generata, segreti e provisioning esistenti; non si usano le
  credenziali di lettura del DWH. I nomi fisici di schema, tabelle e parametri
  vengono fissati nell'implementazione rispettando questi contratti.
- Le migrazioni sono eseguite dal percorso di preparazione dell'installazione,
  non da una richiesta HTTP ordinaria. Schema mancante o non aggiornato produce
  un errore operativo comprensibile. La transizione non prevede doppie scritture
  permanenti o conservazione del comportamento delle sessioni storiche.

### Pagina amministrativa

- Memory management è un accesso indipendente nell'Administration dell'AppShell,
  immediatamente dopo Database management, senza richiedere una sessione attiva
  o l'ingresso in Database management.
- La pagina rende esplicito il workspace e offre lista paginata, ricerca,
  filtri, ordinamento, dettaglio completo e form. Le modifiche hanno salvataggio,
  annullamento e validazione. La cancellazione rende chiari contenuto interessato
  e rimozione dei collegamenti, seguendo le convenzioni UI esistenti.
- Il feedback distingue operazione in corso, salvataggio fallito, contenuto
  salvato con indice incompleto e operazione completata. Il recupero delle
  cancellazioni pendenti è disponibile anche quando la card non compare più in lista.
- I controlli sono accessibili da tastiera e hanno etichette comprensibili.
  Chrome e messaggi UI sono in inglese; il contenuto resta nella lingua del workspace.
  Hash, versioni tecniche e dettagli delle tabelle non sono esposti nel flusso ordinario.

## Testing Decisions

Confini confermati dal proprietario: usare tre confini già presenti nel
repository, concentrando la maggior parte dei casi sul servizio pubblico Memory
del harness. I test osservano risultati, persistenza ed errori; non vincolano
metodi privati, numero di query o disposizione interna delle tabelle.

### 1. Servizio pubblico Memory e suoi comandi

Usare PostgreSQL reale in testcontainers, come nei test del repository delle
sessioni, e gli adapter vettoriali sostituibili già impiegati nei test di recall
e del ciclo di vita solved-question. Gli embedding dei casi deterministici sono
controllati. Un gruppo mirato con Qdrant reale verifica aggiornamento, cancellazione
e ricostruzione della proiezione; non richiede DWH remoto o un modello generativo.

Questo confine verifica il comportamento di archivio, propagazione e recall:

| Caso | Risultato osservabile richiesto |
| --- | --- |
| Creare e riaprire il repository | La card completa, i collegamenti e le dipendenze sono persistiti; l'origine manuale non contiene sessioni inventate. |
| Salvare una card di ciascuna categoria | Contenuto, ambito e dati specifici sono rappresentabili e leggibili senza dipendere dai tipi del ledger. |
| Cercare un record fuori dalla prima pagina | Filtri combinati, totale e ordinamento si riferiscono all'intero archivio. |
| Fallire una scrittura correlata | Card, collegamenti e dipendenze mantengono tutti lo stato precedente. |
| Indicare una card di un altro workspace | Lettura, mutazione, collegamento e retry non accedono al contenuto estraneo. |
| Cancellare una card collegata | Scompaiono card e collegamenti incidenti; le altre card restano intatte. |
| Rendere embedding o Qdrant indisponibili | Elenco e dettaglio funzionano; il CRUD persiste e distingue la propagazione incompleta. |
| Fallire PostgreSQL prima del commit | Nessun falso salvataggio riuscito e nessun nuovo contenuto propagato. |
| Fallire Qdrant dopo un aggiornamento | Il dettaglio contiene la correzione; il recall esclude il vecchio risultato. |
| Fallire Qdrant dopo una cancellazione | La card non è richiamabile; il lavoro di pulizia resta visibile e recuperabile. |
| Riavviare fra commit e propagazione | Il lavoro incompleto permane e un retry lo completa. |
| Ritentare dopo un errore o un esito incerto | Non si creano duplicati; si applica lo stato corrente senza ripristinare contenuti superati. |
| Indice con punto orfano o versione superata | Recall Memory ed exemplar lo escludono anche se ha il punteggio più alto. |
| PostgreSQL indisponibile durante il recall | Il servizio segnala l'indisponibilità senza servire payload non verificati. |
| Ricostruire dopo modifica o cancellazione | Il contenuto corretto è conservato; nessuna card viene ricreata dalle sessioni o da vecchi indici. |
| Eseguire promozione o finalizzazione corrente | I nuovi contenuti passano dall'archivio; un errore Memory successivo non annulla una sessione già finalizzata. |
| Applicare migrazioni e riavviare | Lo schema è utilizzabile con il ruolo runtime previsto; la preparazione è ripetibile e non richiede privilegi di migrazione nelle richieste ordinarie. |

I test CLI coprono solo l'adattamento che il servizio non prova: parsing, principal,
workspace, esiti macchina e JSON puro. I test di integrazione riusano le convenzioni
L0 del harness. I test di recall esistenti continuano a verificare che decisioni
già registrate nella sessione e famiglie non ammesse non vengano riproposte.

### 2. API amministrative Fastify

Usare l'iniezione HTTP e il runner sostituibile già presenti nei test backend,
seguendo i test delle route Catalog e dell'autorizzazione. Verificare principal
autenticato, admin e utente ordinario; validazione; selezione del workspace;
contratto delle risposte e mappatura degli errori. Includere letture, collegamenti
e retry, non soltanto le mutazioni delle card.

Questi test provano il confine HTTP e il passaggio al harness. Non si considera
il runner simulato una prova della transazione PostgreSQL o della coerenza Qdrant.
La normale policy CSRF dell'applicazione resta applicata alle nuove mutazioni.

### 3. Pagina nell'AppShell

Usare React Testing Library, MSW e le convenzioni dei test di AppShell e Database
management. Verificare ingresso amministrativo, scelta workspace, lista completa,
filtri, dettaglio, form, annullamento, errori, collegamenti e retry dopo cancellazione.
Controllare il comportamento tramite elementi accessibili e contenuto visibile.

Un percorso browser mirato sullo stack reale collega i tre confini: amministratore
autenticato, creazione manuale, modifica, riapertura della pagina, cancellazione
e verifica dell'assenza nel recall. I test browser con API intercettate provano
interazione e presentazione; non vengono dichiarati prova della persistenza.

Non si replica l'intera matrice su tutti e tre i confini. PostgreSQL, indice e
recupero sono verificati nel harness; autenticazione e trasporto nel backend;
interazione e feedback nella UI. Il percorso integrato copre il collegamento reale.

### Verifica della consegna

Eseguire i test interessati e i gate documentati dei layer modificati, inclusi
typecheck TypeScript, lint Python e build documentale strict. Le verifiche con
PostgreSQL, Qdrant e browser reale hanno esito riportato separatamente; se un
servizio necessario manca, il relativo gate resta aperto.

M1 non richiede una valutazione della qualità SQL generata da un LLM. I test
deterministici non sono presentati come prova di tale capacità: gli eventuali
casi reali appartengono agli incrementi che cambiano generazione e workflow.

## Out of Scope

- Ricerca ibrida, nuova selezione per ambito ed espansione dei collegamenti: M2.
- Riepilogo finale modificabile, nuove categorie nei gate e pulizia dopo una
  sincronizzazione fisica del Catalog: M3. M1 ne prepara card e dipendenze.
- Authoring, consolidamento e manutenzione Evidence: E1–E3; risoluzione persistente
  congiunta dei conflitti fra Memory ed Evidence: X1.
- Revisione storica delle card, snapshot per vecchie sessioni, migrazione dei dati
  di sviluppo o compatibilità con il registro JSONL come archivio operativo.
- Aggiornamento a caldo delle altre sessioni, nuove invalidazioni dello SQL già
  generato, coordinamento generale dei lettori paralleli e modalità manutenzione.
- Nuovi servizi PostgreSQL o graph database, code generiche, worker e polling continuo.
- Promozione automatica di rifiuti senza spiegazione o scelte occasionali,
  consolidamento automatico e benchmark generale della qualità del modello.
- Deploy o pulizia dell'installazione PSD: restano soggetti ai rispettivi piani e gate.

## Further Notes

Fonti: progetto **Memory management** del 2026-09-08; piano comune
**Amministrazione di Memory ed Evidence**; **Revisione di semplicità: Memory ed
Evidence**; glossario di dominio; ADR 0017 sulla separazione delle collezioni e
ADR 0018 su PostgreSQL autorevole e Qdrant per il retrieval.

La ricognizione ha verificato MemoryRecord, recall ordinario, ricerca degli
exemplar, comandi Memory, repository PostgreSQL delle sessioni, runner del harness,
autorizzazione backend e navigazione amministrativa. Il recall ordinario oggi
risolve già i risultati nel registro autorevole, mentre gli exemplar leggono
contenuti dal payload vettoriale: M1 deve uniformare entrambe le garanzie.

Le scelte tecniche da fissare durante l'implementazione sono nomi e DDL delle
tabelle, firma esatta dei nuovi comandi/API e parametri generati di connessione.
Devono rispettare i contratti e i casi di accettazione di questa specifica;
non riaprono le decisioni di prodotto approvate.

La destinazione della specifica è il tracker Gitea canonico di ThothII, con
etichetta **ready-for-agent**. Il proprietario ha confermato i confini di test
e autorizzato la pubblicazione il 2026-09-08. L'implementazione resta da eseguire.