Come dare agli agenti AI una memoria a lungo termine usando Obsidian

La scorsa settimana mi sono ritrovato a spiegare la struttura del nostro servizio di autenticazione a un agente di codifica per la terza volta questo mese. La finestra di contesto di Claude Code è abbastanza ampia, ma ogni sessione alla fine termina. Una nuova esecuzione del terminale — e la console non sa più nulla delle decisioni architetturali, degli accordi del team o dei task dello sprint.

Recentemente mi sono imbattuto nel progetto obsidian- dello sviluppatore Brenno Ferrari. L'autore ha adottato un approccio diretto: se un agente ha bisogno di memoria a lungo termine, perché non farne un normale vault Obsidian?

Cosa c'è dentro il Template

Il progetto è una struttura di note pronta all'uso, un set di hook TypeScript e comandi CLI pre-costruiti. Out of the box, il template funziona con Claude Code, Codex CLI, Gemini CLI e altri sistemi che possono leggere regole da file di istruzioni.

L'idea è che l'agente legga e aggiorni i file Markdown autonomamente. Quando una sessione inizia, un hook legge gli obiettivi globali dal file brain/North Star.md, estrae la lista dei task attivi e passa questa porzione nella finestra di contesto. Quando comunichi all'agente una decisione presa o una riunione avvenuta, organizza i dati in cartelle e li collega ai nomi dei colleghi o ai progetti.

Come Funziona il Controllo dell'Utilizzo dei Token

Il problema principale di sistemi come questo è il consumo di token. Se inserisci l'intera knowledge base nel contesto a ogni richiesta, i limiti si esauriranno in un paio d'ore.

In obsidian-, questo viene gestito tramite uno schema di caricamento multilivello:

• Quando una sessione inizia, viene letta una porzione di base: obiettivi, task aperti, commit recenti e lista dei file del vault. Questo richiede circa 20.000 token.
• Per la ricerca semantica, viene utilizzata l'utility QMD. Costruisce embedding vettoriali localmente e trova i frammenti rilevanti quando l'agente ha bisogno di informazioni specifiche.
• Quando i messaggi vengono inviati, lo script determina il tipo di dato (incidente, riunione, decisione architetturale) e passa un breve suggerimento di instradamento all'agente.
• Dopo la scrittura dei file, viene eseguito un validatore che controlla la correttezza dei link wiki e dei parametri YAML.

Come si Presenta una Giornata Lavorativa

Al mattino esegui il comando /om-standup. L'agente legge le modifiche recenti in git, effettua un cross-reference della lista dei task e produce un breve riepilogo.

Dopo riunioni o discussioni in Slack, non c'è bisogno di compilare manualmente le strutture dei documenti. Basta fornire il testo grezzo all'agente:

/om-dump Обсудили с Сарой рефакторинг авторизации. Решили отложить миграцию на Redis до второго квартала. Сара похвалила архитектуру API.

In risposta, il sistema esegue automaticamente quattro azioni contemporaneamente:

1. Aggiorna il file della cronologia delle riunioni in org/people/Sarah Chen.md.
2. Crea una voce di decisione nella cartella delle decisioni.
3. Registra elogi nel template di attestazione perf/Brag Doc.md.
4. Aggiunge un nuovo task alla scheda del progetto attivo.

Alla fine della giornata, il comando /om-wrap-up verifica la presenza di note orfane senza riferimenti incrociati e aggiorna gli indici.

Esecuzione di Task in Background tramite Sub-Agenti

Per operazioni pesanti, all'interno del template sono configurati sub-agenti specializzati. Eseguono in finestre di contesto isolate per evitare di ingombrare la cronologia principale della conversazione.

Il repository ha diversi agenti pre-configurati:

• slack-
• cross-linker cerca link wiki interrotti e note dimenticate in tutto il vault.
• brag-
• people-

Build e Avvio

Puoi distribuire il vault tramite il template manager ShardMind o semplicemente clonando il repository.

npm install -g shardmind
mkdir my-vault && cd my-vault
shardmind install github:breferrari/obsidian-mind

Il comando di setup ti chiederà di inserire il tuo nome, il nome dell'azienda e gli obiettivi principali. Dopo di che, dovrai semplicemente seguire alcuni semplici passaggi:

1. Apri la cartella creata come vault in Obsidian.
2. Attiva il plugin Obsidian CLI nelle impostazioni dell'app (richiede Obsidian 1.12+).
3. Esegui l'agente CLI direttamente dalla directory del vault.

Per una ricerca completa, dovresti anche installare lo strumento di ricerca vettoriale QMD:

npm install -g @tobilu/qmd
node --experimental-strip-types .scripts/qmd-bootstrap.ts

Senza QMD, il sistema continuerà a funzionare tramite grep e la ricerca integrata di Obsidian, sebbene l'accuratezza delle risposte a domande astratte diminuirà leggermente.

Per Chi È Questo Progetto

Il template sarà utile per gli sviluppatori che utilizzano attivamente agenti AI basati su CLI e che già mantengono o pianificano di mantenere note in Obsidian. Il valore principale qui risiede nelle regole ben pensate per collegare i documenti tra loro.

Una cosa da notare è la dipendenza da Node.js versione 22+ con il flag --experimental-strip-types per l'esecuzione di script TypeScript senza pre-compilazione. Se questo flag dovesse essere rinominato nelle future release di Node.js, dovrai aggiornare le impostazioni degli hook. Tuttavia, il progetto fornisce un'eccellente base pronta all'uso ed elimina la necessità di costruire questo tipo di impalcatura da zero.