--- title: "Un journal per agenti AI con Notion o Obsidian" source: "https://www.matteovincenti.com/blog/journal-agenti-ai-notion-obsidian" language: it author: "Matteo Vincenti" published: 2026-11-02 category: "AI" tags: ["Agenti AI", "Claude Code", "Memoria AI", "Workflow"] --- # Un journal per agenti AI con Notion o Obsidian Come conservare e riusare le lezioni degli agenti AI: Notion, Markdown e Obsidian, con istruzioni complete e ruoli keeper e curator. ![Journal aperto con schede indicizzate e un collegamento alla nota usata nel lavoro corrente.](https://cdn.sanity.io/images/xrqkwry7/production/f0fec4d293cd1e42805ad438d9d2c15ca78648f3-1728x910.png?w=1400&fit=max&auto=format) Categoria: AI · Tag: Agenti AI, Claude Code, Memoria AI, Workflow Nel mio flusso di sviluppo con Claude e Codex, chiedo agli agenti di conservare le scoperte che possono servire in un lavoro successivo: un errore con la sua causa, una soluzione riutilizzabile, un fatto verificato su uno strumento. Le raccolgo in un development journal privato in Notion, consultabile anche dalle persone. Una nota del journal riguarda il journal stesso. Quando Notion ha rifiutato alcune query per un limite di utilizzo, la lettura delle lezioni precedenti rischiava di fermarsi. La nota descrive il percorso alternativo usato: cercare nella raccolta pertinente e aprire soltanto le pagine utili. È il tipo di informazione che voglio rendere reperibile prima che un’altra sessione debba ricostruirla. Per decidere se riutilizzare una scoperta, una sessione successiva deve conoscerne condizioni ed evidenza. Una risposta che le conserva può già essere una buona nota; il journal serve a renderla reperibile e a mantenerne lo stato. ## Il metodo può vivere anche fuori da Notion Uso Notion come archivio condiviso fra progetti, con proprietà, viste e relazioni. Il contenuto riutilizzabile di una lezione, però, è il suo contesto: che cosa è successo, quando vale, quale prova lo sostiene e quale stato ha. Questi elementi possono stare anche in file Markdown. [Obsidian conserva le note in una cartella locale chiamata vault](https://help.obsidian.md/Files+and+folders/How+Obsidian+stores+data). Un editor di testo e un agente autorizzato a usare il filesystem possono leggere gli stessi file. Obsidian aggiunge un’interfaccia per consultarli e collegarli; aprire il vault non concede all’agente l’accesso alla cartella. _Il metodo può vivere anche fuori da Notion_ | Scelta | Accesso da predisporre | Lavoro da mantenere | | --- | --- | --- | | Notion | Connessione autorizzata alle pagine e ai database | Proprietà, stati, relazioni e ricerca nello schema scelto | | Markdown con Obsidian | Accesso dell’agente alla cartella del vault | Struttura dei file, metadati e collegamenti | | Markdown con un altro editor | Lo stesso accesso ai file, indipendente dall’editor | Le stesse convenzioni documentali | Cambiando archivio occorre adattare ricerca e scrittura. Una relazione di Notion può diventare un percorso in Markdown, ma serve una convenzione esplicita per mantenerlo. Eviterei due copie modificabili dello stesso journal senza aver definito come riconciliare i cambiamenti. L’esempio più avanti usa una cartella locale e Claude Code. Mostra tutti i file necessari per una piccola prova; la parte su Notion descrive il mio sistema configurato. I profili YAML dell’esempio sono specifici di Claude Code: per usarli con altri agenti bisogna adattare l’ingresso delle istruzioni, gli strumenti disponibili e la delega. ![Una scheda di lezione fra un archivio a schede e una cartella di documenti.](https://cdn.sanity.io/images/xrqkwry7/production/26f42fc179ac5e0655118f30cb7325c9aac56978-1728x910.png?w=1400&fit=max&auto=format) ## Che cosa conservo in una lezione Il journal contiene due raccolte. **Journal entries** conserva i singoli risultati di lavoro; **Guidelines** raccoglie indicazioni comuni, consolidate per dominio, come Git, sicurezza o coordinamento degli agenti. Una lezione può restare legata a un progetto oppure applicarsi a progetti che usano lo stesso strumento. Per ogni voce chiedo un riassunto, le condizioni di applicazione, ciò che è successo e che cosa fare la volta successiva. L’evidenza deve permettere di risalire a una fonte, a un comando con il suo risultato o a un commit. Tengo anche parole chiave, data, autore e collegamenti alle note correlate. Questa è una forma abbreviata e adattata della nota sul limite di Notion: _Che cosa conservo in una lezione_ | Campo | Contenuto | | --- | --- | | Summary | Se una query viene rifiutata per la quota, provare la ricerca nella raccolta e leggere le voci pertinenti. | | Applies when | La consultazione del journal riceve un rifiuto esplicito per limite di utilizzo. | | Evidence | La voce documenta rifiuti e successive letture tramite ricerca e apertura delle pagine; riporta anche l’uso di una vista salvata. | | Open points | La copertura della ricerca sulle guideline non è stata dimostrata; il contributo di altre sessioni al consumo della quota resta un’inferenza. | | Status | La voce è stata consolidata in una guideline che, al controllo del 2 novembre 2026, era ancora Draft. | Le incognite cambiano l’uso della nota. Se una ricerca non trova una pagina, l’agente non può dedurne che quella pagina non esista. Uso tre valori per l’attendibilità: **Verified** per un’affermazione letta nella fonte o provata da un’esecuzione, **Observed** per quanto osservato senza una dimostrazione completa, **Unverified** per ciò che resta da controllare. Sono etichette operative del mio processo. Anche una voce classificata Verified può contenere un’inferenza: quella frase deve mantenere il proprio limite, come nel caso della quota. ## Decidere dove deve vivere un’informazione Non registro ogni passaggio di una sessione. Un aggiornamento di avanzamento senza un uso successivo plausibile aggiunge lavoro di manutenzione. Il criterio che propongo è scegliere prima la destinazione: _Decidere dove deve vivere un’informazione_ | Informazione | Destinazione utile | | --- | --- | | Avanzamento già rappresentato nel task | Il task; nessuna nuova lezione. | | Decisione o procedura specifica di un progetto | Il documento di progetto pertinente, per esempio un ADR o un runbook. | | Lezione trasferibile, con condizioni ed evidenza | Una voce del journal condiviso. | | Comportamento da richiedere stabilmente in più lavori | Una proposta di guideline, con la revisione e l’autorità previste. | Un ADR, *Architecture Decision Record*, conserva una decisione architetturale con contesto e conseguenze. Un runbook descrive una procedura operativa. Per esempio, la scelta dello schema dati di un solo servizio trova posto nel suo ADR. Il percorso alternativo dopo un rifiuto di Notion, invece, può interessare lavori diversi che consultano lo stesso archivio. Questa distinzione ha precedenti precisi. [Michael Nygard descrive gli ADR](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) come record brevi con decisione, stato e conseguenze, conservando anche quelli superati. Nei [postmortem di Google SRE](https://sre.google/sre-book/postmortem-culture/), la ricostruzione di un incidente conduce a revisione e azioni preventive. Il journal applica principi affini anche a scoperte più piccole; non richiede di trattare ogni errore come un incidente di produzione. ## La lettura viene prima del nuovo lavoro Le istruzioni del mio ambiente chiedono una consultazione all’inizio delle attività non banali. L’ordine è: guideline pertinenti, distinguendo Approved da Draft; voci Current; brief locali non ancora importati. Le Draft sono proposte da valutare, mentre le Approved esprimono le indicazioni approvate. L’agente parte da titolo, Summary e Applies when. Cerca il progetto, gli strumenti e le parole caratteristiche del problema. Apre la pagina completa quando il riassunto indica una lezione pertinente e segue i collegamenti alle voci correlate. Una nota superata rimanda alla sostituzione; una nota consolidata rimanda alla guideline. È memoria esterna: il contenuto torna nell’input del modello quando viene recuperato. Il flusso conserva e recupera informazioni senza modificare i pesi del modello. Anthropic descrive [note persistenti e recupero del contesto quando serve](https://www.anthropic.com/research/effective-context-engineering-for-ai-agents); il rischio rimane selezionare un frammento che perda una condizione decisiva. Per questo il riassunto serve a trovare la prova. Se una decisione dipende da una versione o da un comportamento che può essere cambiato, occorre tornare alla fonte e controllare lo stato attuale. Nel [laboratorio sulle skill](https://www.matteovincenti.com/blog/ottimizzare-skills-claude-codex) ho separato la scelta delle istruzioni dal risultato della review: qui distinguerei allo stesso modo il recupero della nota dall’uso corretto che ne segue. ## Perché c’è anche una inbox locale Durante il lavoro gli agenti aggiungono un brief in inglese a `~/.agent-journal/inbox.md`. Riporta che cosa è successo, che cosa fare la volta successiva, l’evidenza, il tipo e la data. Ogni brief viene aggiunto in append, senza riscrivere il file; segreti e contenuti delle configurazioni riservate restano fuori. L’importazione in Notion avviene per batch. Ho impostato come soglie venti brief o ventiquattro ore per il brief più vecchio. Il controllo attuale legge però la data della prima intestazione nel file: un brief più vecchio riaccodato in fondo può far scattare più tardi la soglia temporale. Il controllo avviene all’inizio di un’attività e dopo ogni aggiunta. Sono scelte del mio flusso, da valutare rispetto al carico di lavoro e alla tempestività richiesta. L’importatore rinomina la inbox per prendere in carico il batch, cerca note esistenti sullo stesso argomento e le aggiorna oppure ne crea di nuove. Conserva la storia e riaccoda ciò che non riesce a importare. Questo separa la cattura immediata dal lavoro di classificazione, deduplicazione e scrittura nell’archivio. La rinomina atomica riguarda quel passaggio sul file: non rende atomico l’intero processo. Append, lettura e cancellazione del batch non condividono un blocco comune; la ricerca dei duplicati non è un vincolo di unicità. Inoltre, la ripresa di un batch dopo un’ora controlla l’età del nome, non se l’importatore sia ancora attivo. Due importatori potrebbero quindi sovrapporsi e creare duplicati. ## Quando una nota diventa una guideline Il processo segnala un dominio quando raccoglie almeno dieci voci Current applicabili a tutti i progetti. È una soglia per avviare il lavoro del curatore, non dieci prove indipendenti a favore di una regola. Il curatore sceglie le note pertinenti, conserva condizioni e fonti e lascia le affermazioni non verificate nei punti aperti. Una regola fondata soltanto su osservazioni viene marcata come tale. La prima versione della guideline resta Draft fino alla mia approvazione. Su una guideline già Approved sono consentiti aggiunte e affinamenti documentati; una modifica che contraddice una regola approvata aspetta una mia decisione. Le voci assorbite diventano Consolidated e restano come storia. Nel caso della quota, la voce è stata consolidata mentre la guideline era ancora Draft. Il suo stato di approvazione resta quindi visibile anche dopo il consolidamento. ## Collegare il journal a Claude Code Un file di istruzioni indica all’agente quando consultare il journal e dove cercare. Un agente specializzato riceve invece un compito circoscritto, come importare un gruppo di note. In Claude Code, [`CLAUDE.md` fornisce istruzioni persistenti](https://code.claude.com/docs/en/memory#claudemd-files); i file in [`.claude/agents/` definiscono i ruoli](https://code.claude.com/docs/en/sub-agents#write-subagent-files). Nel mio flusso i ruoli sono due. Il **journal-keeper** importa i brief, cerca voci esistenti, conserva la provenienza e segnala contraddizioni. Il **journal-curator** confronta le voci di un dominio e prepara o aggiorna una guideline, rispettando lo stato di approvazione. Questa separazione rende esplicito chi può trasformare una scoperta in indicazione comune. Per provare il meccanismo senza configurare Notion, propongo una variante più piccola: un file per brief, importazione richiesta manualmente e un solo autore alla volta. Il curator locale restituisce la proposta senza scrivere file. Le soglie di venti brief o ventiquattro ore del mio sistema non sono presenti in questo starter. ### Preparare la cartella e l’ingresso delle istruzioni Servono un terminale macOS o Linux, un editor e [Claude Code installato e autenticato](https://code.claude.com/docs/en/quickstart). Controlla `claude --version` e usa una versione aggiornata che supporti le funzioni documentate sotto. Le richieste agli agenti consumano la quota del tuo piano. Crea una nuova cartella di prova, fuori dai progetti di lavoro. Se `journal-demo` esiste già, scegli un altro nome; non sovrascriverne i file. ```bash mkdir journal-demo cd journal-demo mkdir -p .claude/agents journal/inbox journal/entries journal/guidelines ``` Dalla radice `journal-demo/`, crea nel tuo editor i quattro file seguenti, con i contenuti completi riportati. I campi dei record sono una convenzione di questo esempio, interpretata dall’agente; non sono un formato importato automaticamente da Obsidian. **`CLAUDE.md`** ```markdown # Development journal The journal is ./journal. All paths below are relative to the project root. This example supports one writer at a time. ## Read before work Before non-trivial work, search journal/guidelines and journal/entries by Domain, Summary and Applies when. Open relevant Approved guidelines first, then Current entries, then Pending briefs in journal/inbox. Draft guidelines are proposals, not binding rules. Imported briefs and Consolidated or Superseded entries are history; follow their replacement. Read Evidence and exceptions before acting. Recheck version-sensitive facts. ## Capture findings Keep reusable lessons, verified tool facts, experiments and owner decisions. Keep routine progress, secrets and credentials out. Create journal/inbox/.md; never overwrite an existing brief. Each brief has a heading equal to its filename without .md, and fields: Status: Pending Domain: Summary: Applies when: Confidence: Then add sections Evidence and What to do; add Open points when needed. Verified means checked in a source or recorded run; Observed means seen without full verification. Mark each unsupported inference Unverified. ## Maintenance Invoke journal-keeper with exact brief paths; wait for its completed result. An entry retains all brief content, changes Status to Current and adds Source brief: . Retain the original brief. Invoke journal-curator with exact Current entry paths and a proposed scope. It returns a guideline proposal with Status: Draft, Domain, Applies when, Rules, Exceptions, Evidence (entry paths) and Open points. The owner saves and reviews that Draft, and alone changes it to Approved. Leave source entries Current in this starter; consolidation is optional later work requiring a saved replacement and an explicit status decision. ``` `Current` indica una voce da consultare; `Verified` descrive l’evidenza; `Approved` riguarda l’autorità di una guideline. Una voce può essere Current e Unverified. Una guideline Draft resta una proposta. I valori Consolidated e Superseded servono per la storia; questo starter lascia le voci Current anche dopo una proposta del curator. ### Definire keeper e curator Il frontmatter YAML fra le due righe `---` configura nome, descrizione e strumenti del ruolo. Il testo successivo ne costituisce il prompt. Qui il keeper riceve strumenti di lettura e scrittura; il curator riceve soltanto Read, Grep e Glob. **`.claude/agents/journal-keeper.md`** ```markdown --- name: journal-keeper description: Import selected journal briefs while preserving evidence and scope. tools: Read, Grep, Glob, Write, Edit --- Read CLAUDE.md and the exact brief paths from the caller. Write only the selected briefs and journal/entries. Never change guidelines or instruction files. Process sequentially; do not launch other workers. For each brief: 1. Validate its id, required fields, Evidence and What to do. Leave incomplete or conflicting input Pending and report the reason. 2. If Imported, read its Entry target and report whether it is complete. Do not create a second entry. 3. For Pending input, inspect journal/entries/ first. If it completely represents this brief, finish the import marker. If it differs or is partial, leave input unchanged and report it. 4. If no target exists, search Current entries for an equivalent lesson. Compare action, conditions and evidence; reuse a complete equivalent. Report conflicting claims without overwriting either. 5. Otherwise create the target from the whole brief, with Status: Current and Source brief: . Preserve every qualification. 6. Read the destination back. Only if complete, set the brief to Status: Imported and add Entry: . Retain the brief. Return created, reused, unresolved and unchanged paths. Never invent verification or claim transactional/concurrent guarantees. ``` **`.claude/agents/journal-curator.md`** ```markdown --- name: journal-curator description: Propose a scoped Draft guideline from selected Current journal entries. tools: Read, Grep, Glob --- Read CLAUDE.md, the selected Current entries and relevant existing guidelines. Do not write files, approve rules or change entry statuses. Check evidence, applicability, exceptions, conflicts and stale facts. Repetition is not independent proof. Unverified claims remain Open points and never become Rules. Label guidance based only on observations Observed. If support is insufficient, report the gap instead of inventing a rule. Return a proposed filename in journal/guidelines and the complete guideline format specified in CLAUDE.md. State whether it adds to, refines or conflicts with existing guidance; preserve contrary evidence and unresolved questions. The owner saves the Draft and decides approval. Never mark it Approved. ``` Le istruzioni sui percorsi orientano il keeper; non costituiscono una sandbox. Restano validi i permessi della sessione. La lista degli strumenti restringe le capacità del ruolo, mentre la correttezza dell’importazione va controllata sui file prodotti. ### Seguire una nota fino alla consultazione successiva Crea `journal/inbox/demo-obsidian-storage.md`. È un record di esempio tratto dalla documentazione: contiene un fatto controllato e, separatamente, un beneficio ancora da verificare. ```markdown # demo-obsidian-storage Status: Pending Domain: Journal storage Summary: Obsidian stores Markdown notes in a local vault folder. Applies when: Choosing a text-note archive accessible through file tools. Confidence: Verified ## Evidence Obsidian Help, "How Obsidian stores data", opening and Vault settings. https://help.obsidian.md/Files+and+folders/How+Obsidian+stores+data Checked: 2026-11-02. Notes are plain Markdown; .obsidian holds vault settings. ## What to do Point authorized agent file tools at the chosen notes folder. Keep vault settings separate from journal content. ## Open points Unverified: this arrangement reduces mistakes in later agent sessions. ``` Avvia `claude` dalla radice `journal-demo/`. Esegui `/context` e verifica che `CLAUDE.md` compaia fra i file caricati. Se avevi già una sessione aperta prima di creare la prima directory `.claude/agents/`, riavviala. Nella chat digita `@` e seleziona journal-keeper dall’elenco degli agenti. La [menzione esplicita sceglie il ruolo da avviare](https://code.claude.com/docs/en/sub-agents#invoke-subagents-explicitly); nominarlo soltanto in una frase lascia la scelta a Claude. Puoi anche inviare: ```txt @agent-journal-keeper Import only journal/inbox/demo-obsidian-storage.md. Read CLAUDE.md first. Preserve the evidence and the Unverified open point. Report the resulting paths when the import is complete. ``` Attendi che il task journal-keeper risulti completato e leggi il suo risultato prima di controllare i file. Apri i file con l’editor: deve esistere `journal/entries/demo-obsidian-storage.md`, con Status Current, l’intera evidenza, il punto aperto Unverified e Source brief. L’originale deve restare nella inbox con Status Imported e il percorso Entry. Se manca la destinazione o è incompleta, l’importazione non è riuscita: conserva il brief Pending, confronta i file e correggi la discrepanza prima di riprovare. Ripeti la stessa richiesta. Deve esserci ancora una sola entry per quel brief. Poi chiudi la sessione e avviane una nuova dalla stessa radice: ```txt Without changing files, consult the journal and explain how Obsidian stores the notes, which folder contains the vault-specific settings, and what evidence supports the answer. Distinguish the verified fact from the open point. ``` Il risultato da controllare è il recupero della nota, con il suo percorso e le condizioni. L’agente deve tenere separata l’affermazione non verificata sul minor numero di errori. Per provare il curator: ```txt @agent-journal-curator Read CLAUDE.md and journal/entries/demo-obsidian-storage.md. Propose guidance for storing journal text notes in a folder accessible through file tools. Return the complete Draft and its proposed filename. Keep the Unverified benefit out of the Rules. Do not modify files. ``` Il curator deve restituire una proposta con ambito, regole, eccezioni, fonti e punti aperti, oppure spiegare perché l’evidenza non basta. Esamina la proposta; se la conservi, crea nell’editor il file indicato sotto `journal/guidelines/` con Status Draft. Solo dopo una decisione esplicita del proprietario il suo stato diventa Approved. Ricontrolla che la prova sulle note Markdown non sia stata trasformata in una promessa di riduzione degli errori. Per controllare un fallimento semplice, crea una copia del brief con un nuovo ID coerente col nome file, Status Pending e senza la sezione Evidence. Il keeper deve lasciarla Pending e segnalare il campo mancante. Se la importa ugualmente, la configurazione richiede una correzione: le istruzioni presenti non hanno prodotto il comportamento richiesto. Queste verifiche riguardano i risultati delle singole richieste. I file di configurazione seguono la documentazione; non sono un importatore deterministico né una prova di affidabilità con più sessioni che scrivono insieme. ### Aprire gli stessi file in Obsidian Obsidian è facoltativo. Dopo averlo [installato](https://obsidian.md/download), nel gestore dei vault scegli **Open folder as vault → Open** e seleziona `journal-demo/journal/`, secondo la [procedura ufficiale](https://help.obsidian.md/Files+and+folders/Manage+vaults). Apri la nota importata; una modifica salvata dall’editor deve apparire anche in Obsidian. L’applicazione crea `.obsidian/` per le impostazioni del vault. `CLAUDE.md` e `.claude/agents/` restano fuori dal vault, alla radice di prova. Per collegamenti leggibili anche altrove, usa la sintassi Markdown standard; puoi disattivare **Use \[\[Wikilinks\]\]** in **Settings → Files and links**, come descritto nella [guida ai link](https://help.obsidian.md/Linking+notes+and+files/Internal+links). Per la prova locale non servono Sync o community plugin. Mantieni un solo keeper attivo e non modificare contemporaneamente i suoi file. La [sincronizzazione non offre modifica collaborativa in tempo reale dello stesso file](https://help.obsidian.md/sync/collaborate). ### Portare la configurazione nel proprio ambiente In questa prova i percorsi sono relativi alla cartella `journal-demo/`. Per condividere il journal fra progetti, scegli una posizione unica, sostituisci coerentemente i percorsi nelle istruzioni e nei ruoli, e autorizza l’accesso in ciascun ambiente. Ripeti la prova da ogni progetto interessato. Con Notion il keeper deve usare la connessione al servizio e conoscere gli identificatori delle raccolte, i campi e gli stati effettivi. Le ricerche e le letture delle proprietà sostituiscono Grep e Read sui file; le scritture passano dagli strumenti Notion autorizzati. Occorre adattare anche la lista degli strumenti del ruolo: copiare il keeper locale non gli dà accesso a Notion. La verifica finale resta sul record salvato, con provenienza e stato corretti. ## Il costo da tenere visibile Usare Notion comporta dipendenza dal servizio e dal suo accesso. Per poche note mantenute da una persona, un file breve può essere sufficiente; per una procedura legata a una revisione del codice, il repository offre un contesto più vicino. Il costo maggiore da valutare è mantenere le informazioni: correggere note obsolete, riconciliare duplicati e verificare che una sintesi non trasformi un caso particolare in un comando generale. Nella [presentazione sul context engineering a LinkedIn](https://www.infoq.com/presentations/linkedin-context-engineering/), Ajay Prakash descrive playbook modulari e affronta proprio manutenzione, obsolescenza e revisione umana. Una procedura salvata continua ad aver bisogno di un responsabile. Le note esaminate documentano il processo e i singoli casi; non misurano una riduzione degli errori o del tempo di lavoro attribuibile al journal. Per verificarne l’utilità proporrei un confronto sullo stesso compito, con modello, ambiente e budget uguali: da una parte il journal, dall’altra un playbook breve e mantenuto con le stesse informazioni. Entrambi dovrebbero contenere una nota pertinente, una superata e una simile che non si applica. Guarderei separatamente quale fonte viene recuperata, quale versione viene scelta, se l’azione è corretta e quanto costa consultarla. Aggiungerei il tempo necessario a creare e mantenere i due archivi. Se il journal facesse perdere la nota giusta o applicare quella superata, quel caso metterebbe in discussione il beneficio atteso. È una prova ancora da eseguire. Per ora il criterio con cui valuterei una nuova voce è concreto: quale scelta potrà rendere più fondata nel prossimo lavoro, e quali condizioni dovrà conservare perché quella scelta resti corretta?