Dati e archiviazione

Dove si trovano le cose, chi può leggere cosa e le regole che l'agente segue in modo che le pagine rivolte ai clienti non vedano mai accidentalmente dati interni.

Tre posti in cui vivono le cose

1. La tua area di lavoro (~/workspace/)

Il filesystem in cui viene eseguito l'agente. Le bozze in Markdown, le risorse generate, le Skills personalizzate, i job, lo spazio di lavoro temporaneo e questi documenti si trovano tutti qui.

• Proprietario: l'utente Linux agent (l'agente stesso).
• Raggiungibile dalla chat. NON raggiungibile dal processo Console o dal processo del sito pubblico.
• Due percorsi convenzionali:
• ~/workspace/uploads/: i file che incolli nella chat finiscono qui.
• ~/workspace/downloads/: i file che l'agente registra per il download tramite l'interfaccia dell'area di lavoro. Serviti da nginx a un URL protetto.

2. PostgreSQL (tre database)

Stato persistente per qualsiasi cosa strutturata. Mai SQLite, mai JSON su disco per lo stato dell'applicazione.

Cosa va dove:

• console_db: stato solo interno. Liste di clienti, fasi delle trattative, tabelle di punteggio interne, log di audit. Il sito pubblico non può accedervi; il REVOKE è a livello di ruolo del database, non solo per convenzione.
• site_db: contenuti che il sito pubblico renderizza. Report pre-calcolati, pagine di documentazione, tutto ciò che dovrebbe essere economico da leggere durante il rendering di una pagina. La Console scrive qui, il sito legge.
• console_site_db: un canale esplicito tra le superfici. La Console scrive una coda di moderazione; il sito renderizza le voci approvate; il sito scrive segnali di interazione; la Console li legge.

3. Memoria e progressi

Due file speciali nella tua area di lavoro:

• ~/workspace/.memory.md: letto all'inizio di ogni chat. Usa "remember this: X" per aggiungere.
• ~/workspace/progress.md: registro delle modifiche. L'agente aggiunge voci dopo modifiche significative; puoi leggerlo per ricostruire cosa è successo.

Sono markdown di proposito: puoi cercarli con grep, versionarli, modificarli manualmente e cercarli di nuovo con grep.

Perché tre database invece di uno

Due motivi.

1. Separazione delle superfici. Un visitatore del sito pubblico potrebbe, in linea di principio, trovare un modo per interrogare il ruolo del database con cui il sito si autentica. Se quel ruolo ha accesso solo a site_db, il raggio d'azione di qualsiasi fuga di dati è limitato ai dati che hai già deciso fossero pubblici.
2. Chiarezza dell'intento. Quando l'agente scrive un'app Console, sa di usare console_db. Quando scrive una pagina del sito, site_db. Quando costruisce un workflow cross-surface, console_site_db. Nessun dubbio accidentale del tipo "questa tabella dovrebbe essere pubblica?"

L'agente non cerca di aggirare queste regole. Se chiedi "esponi pubblicamente questa pagina della Console", ti dirà che deve spostare i dati attraverso console_site_db e ricostruire il percorso di lettura sul sito, invece di accedere a console_db dal sito.

Lavorare con il database

Lo schema, ogni volta:

• Sessione SQLAlchemy importata da src/db.py (modulo condiviso per app).
• I modelli Pydantic proteggono ogni input e ogni confine API.
• psycopg2 raw solo quando SQLAlchemy è eccessivo (ricerche di sola lettura protette da token, script semplici).

Vedrai le istruzioni CREATE TABLE IF NOT EXISTS all'inizio delle nuove app. L'agente tratta lo schema come codice: ogni app dichiara le proprie tabelle. Non esiste un sistema di migrazione della piattaforma; le nuove colonne vengono aggiunte con ALTER TABLE e l'agente registra la modifica.

E ClickHouse?

ClickHouse è disponibile localmente per carichi di lavoro analitici in cui PostgreSQL sarebbe lento: rollup di serie temporali su milioni di righe, aggregazioni colonnari, cose del genere. L'agente legge la skill di ClickHouse prima di usarla, la sceglie deliberatamente e ti spiega perché. Il default rimane PostgreSQL.

Dove le cose NON vivono

• Nessun object storage gestito dalla piattaforma. Se vuoi archiviare un PDF da 50 MB o un video, salvalo come file in ~/workspace/downloads/ (controllato da nginx) o come colonna BYTEA in Postgres (va bene per artefatti piccoli).
• Nessuna variabile d'ambiente per i segreti. Le credenziali risiedono nel secret store tipizzato, con ambito limitato a superfici e connettori. L'agente non le copia mai in un file o in una colonna del database.
• Nessuna pagina "impostazioni della piattaforma" oltre a ciò che espone l'interfaccia dell'area di lavoro. Pianificazioni, modalità e approvazioni sono tutte opzioni esplicite.

Ciclo di vita dei dati

• I file che crei rimangono fino a quando non li elimini. L'agente non esegue la garbage collection della tua area di lavoro.
• Le righe del database rimangono fino a quando non le rimuovi tu (o un job di pulizia esplicito). L'agente scrive job di pulizia quando glielo chiedi: "elimina le righe di vsg_runs più vecchie di 90 giorni ogni domenica."
• I file di memoria e di avanzamento crescono nel tempo. L'agente suggerisce occasionalmente di fare pulizia quando la memoria diventa troppo piena.
• I log di audit del connettore vengono conservati dalla piattaforma; puoi consultarli ma non eliminarli.

Sotto il cofano. Ogni ruolo Postgres si autentica tramite autenticazione peer su socket Unix (l'utente del sistema operativo corrisponde al nome del ruolo). Non c'è nessuna password da far trapelare, nessuna stringa di connessione da configurare male. I GRANT e i REVOKE sono espliciti e visibili. Il database system_db esiste per gli elementi interni della piattaforma (l'api-proxy, il servizio dei connettori, il bridge); nessuna superficie si connette mai ad esso.