MEM: Memoria Persistente e Auto-Aggiornante per AI Agent Strumento per dotare i progetti AI di un layer di memoria operativa leggibile, indicizzato e persistente, pensato per preservare il contesto e documentare il lavoro svolto

Gli AI agent stanno diventando sempre più utili nei progetti software, ma hanno ancora una debolezza molto concreta: perdono troppo facilmente il contesto operativo. Una sessione può produrre buon codice, analisi utili, un percorso di troubleshooting o una decisione architetturale; poi gran parte di quel valore scompare, a meno che qualcuno non lo trasformi in documentazione di progetto durevole.

MEM, acronimo di Markdown Embedded Memory, è un progetto pensato per risolvere questo problema con un approccio volutamente trasparente: una memoria operativa leggibile, indicizzata e persistente per AI agent, archiviata in Markdown e mantenuta come parte integrante del progetto.

Il progetto è disponibile su GitHub all’indirizzo github.com/Ryadel/MEM. Al suo centro c’è un file di bootstrap, MEM.md, che indica all’agente come caricare la memoria del progetto, come interpretare la knowledge base, quando aggiornarla, come preservare gli activity log e come gestire le regole specifiche del progetto.

MEM introduce inoltre due concetti importanti: il supporto per una sorgente MEM remota e un modello di estensioni per comportamenti operativi specifici. Queste aggiunte rendono il progetto più interessante, perché lo portano oltre la documentazione locale e lo avvicinano a un vero layer operativo riutilizzabile per workflow agentici.

Cosa è MEM

MEM è un sistema di memoria di progetto basato su Markdown per AI agent. Fornisce all’agente un layer di contesto stabile, che può essere letto, revisionato, versionato e aggiornato nel tempo.

L’idea è semplice: un progetto non dovrebbe dipendere dalla cronologia delle chat per ricordare come funziona. Note architetturali, convenzioni, decisioni, voci di troubleshooting, stato delle attività e attività giornaliera dovrebbero vivere in una knowledge base strutturata, consultabile sia dagli esseri umani sia dagli agenti.

MEM usa normali file Markdown per questo scopo. Il file principale, MEM.md, agisce come memoria di bootstrap dell’agente. Quando un agente avvia un lavoro significativo, legge prima quel file, poi carica l’eventuale MEM.config.md e quindi usa la root configurata della knowledge base come memoria tecnica persistente del progetto.

In questo modo l’agente dispone di un contesto operativo prima di iniziare a modificare codice, rispondere a domande sul progetto o scrivere documentazione. Ancora più importante, il progetto ottiene un luogo in cui la conoscenza utile può accumularsi senza restare intrappolata dentro una singola conversazione.

Compatibilità

MEM è compatibile con qualsiasi AI coding assistant o LLM agent capace di leggere file Markdown e lavorare su un repository. Può essere usato con Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Visual Studio Code con estensioni AI, Visual Studio con estensioni chat o coding assistant, e con agenti custom basati su modelli GPT, Claude, Gemini, Llama o equivalenti.

Non richiede SDK, runtime o integrazioni proprietarie: basta rendere disponibile il file MEM.md e chiedere all’agente di leggerlo e applicarlo come memoria operativa persistente del progetto.

Come is usa

Installare e usare MEM è estremamente semplice: è possibile scegliere tra installazione automatica, guidata dall’LLM, o manuale, gestita dall’utente.

Installazione automatica

Il modo più rapido consiste nel fornire al tuo AI coding assistant o LLM agent l’URL dell’ultima versione del file MEM.md e chiedergli di installare MEM nel tuo progetto.

Un prompt tipico può essere:

L’agente dovrebbe creare la cartella di destinazione se non esiste, salvare il file localmente e quindi usarlo come memoria di bootstrap del progetto.

Installazione manuale

Se preferisci controllare direttamente il flusso di installazione, esegui questi passaggi:

• Scarica l’ultima versione del file MEM.md dal repository GitHub di MEM.
• Posizionalo in una cartella di primo livello adatta all’interno del tuo progetto, ad esempio MEM.
• Apri il tuo AI coding assistant o LLM agent preferito.
• Chiedi all’agente di leggere e applicare il file MEM.md prima di svolgere qualsiasi attività non banale sul progetto.
• Lascia che l’agente inizializzi o aggiorni la knowledge base del progetto man mano che il lavoro procede.

Un primo prompt tipico può essere:

Da quel momento in poi, l’agente può usare MEM come layer di contesto persistente del progetto: può leggere la documentazione esistente, aggiornare i daily log, registrare decisioni, preservare note di troubleshooting e mantenere la knowledge base allineata al codice sorgente effettivo.

Source of Truth

MEM introduce una distinzione importante: il codice sorgente resta la source of truth dell’implementazione, mentre la Knowledge Base alimentata da MEM è il layer esplicativo.

Questa separazione è una delle caratteristiche distintive più rilevanti di MEM: una “memoria” di progetto può diventare pericolosa se comincia a sostituire l’ispezione dell’implementazione reale. MEM evita questo rischio richiedendo all’agente di ispezionare il codice sorgente effettivo prima di fare affermazioni sull’implementazione. La documentazione può spiegare come funziona il progetto, perché sono state prese certe decisioni e quali convenzioni si applicano, ma non deve allontanarsi dal codebase. La memoria aiuta l’agente a lavorare più velocemente e con maggiore continuità, ma non giustifica assunzioni superficiali. Se un comportamento viene dedotto dal codice, MEM richiede riferimenti alle sorgenti; se qualcosa è incerto, l’incertezza va indicata esplicitamente.

Una MEM-KB strutturata

Una MEM-KB (shortcut per MEM Knowledge Base) predefinita ha una struttura compatta:

La struttura è piuttosto lineare: MEM.index.md è il punto di ingresso per la navigazione; MEM.project.md descrive identità del progetto, dominio, stack e vincoli; architecture/ spiega come funziona attualmente il sistema; docs/ ospita documentazione tecnica o funzionale più ampia.

Le altre cartelle coprono la conoscenza che tende a perdersi tra una sessione e l’altra: logs/ registra l’attività, tasks/ traccia gli elementi di lavoro, troubleshooting/ conserva errori diagnosticati e soluzioni verificate, decisions/ ospita gli ADR, mentre conventions/ raccoglie le regole specifiche del progetto.

L’obiettivo non è creare un grande framework documentale. MEM preferisce aggiornamenti piccoli e accurati rispetto a pagine lunghe e speculative. Una memoria utile cresce in modo incrementale: una nota di troubleshooting dopo una diagnosi reale, un ADR dopo una decisione significativa, un daily log dopo una sessione di lavoro rilevante.

Activity Log persistenti

Una delle funzionalità più utili di MEM è il daily log. File come logs/YYYY-MM-DD.md registrano informazioni fattuali sul lavoro svolto durante una sessione: cosa è cambiato, quali file sono stati toccati, quali problemi sono stati individuati, cosa resta in sospeso e quali note potranno aiutare le sessioni future.

Questo è particolarmente utile con gli AI agent, perché le conversazioni contengono troppo rumore. Includono tentativi, correzioni, assunzioni temporanee e percorsi laterali che non sono utili come documentazione permanente. Un log MEM dovrebbe preservare il risultato, non l’intero transcript.

Una buona voce di log può essere breve e comunque preziosa. Per esempio, può registrare che la validazione dei token è stata rifattorizzata, che uno specifico controller e un file di configurazione sono stati modificati, che mancano ancora test di integrazione e che è stata aggiunta una nota di troubleshooting correlata. È abbastanza per consentire a un agente futuro, o a un maintainer umano, di riprendere il lavoro senza ricostruire tutto a memoria.

Sorgente MEM remota

Per impostazione predefinita, MEM viene caricato dal file locale MEM.md. Tuttavia, MEM.config.md può ora definire una sorgente remota impostando mem_source: "remote" e fornendo un mem_remote_url. In questa configurazione, il file locale MEM.md diventa un loader di bootstrap: l’agente deve recuperare il documento MEM remoto e usarlo come contesto operativo attivo.

Questo apre diversi scenari pratici. Un team può mantenere una policy MEM condivisa in una posizione centrale e lasciare che più repository la carichino. Un’organizzazione può mantenere regole comuni per qualità documentale, confini di sicurezza, comportamento degli agenti e disciplina operativa, mentre ogni progetto conserva la propria knowledge base. Un consulente o un maintainer può riutilizzare una configurazione MEM coerente su più progetti cliente senza copiare manualmente l’intero contratto operativo.

MEM definisce anche le policy di errore per il caricamento remoto:

• stop: interrompe il lavoro e segnala che il MEM remoto non può essere caricato.
• fallback_local: continua con il MEM.md locale e segnala il fallback.
• fallback_cache: continua con il file remoto in cache, se disponibile; in caso contrario si interrompe.

Il supporto per MEM remoto cambia la scala del progetto. Una memoria Markdown locale è utile per un singolo repository, ma un modello di bootstrap remoto è utile per un gruppo di progetti che devono condividere regole operative.

Nei contesti tecnici reali questo fa differenza. I team vogliono spesso un comportamento coerente tra repository: come gli agenti dovrebbero documentare il lavoro, quando servono gli ADR, come scrivere le note di troubleshooting, come gestire i segreti e quali azioni esterne richiedono conferma. Senza una sorgente condivisa, queste regole vengono copiate, biforcate e lentamente dimenticate.

Remote MEM offre a queste regole un unico posto in cui vivere, preservando al tempo stesso il contesto locale del progetto dentro ogni repository. La knowledge base locale può continuare a descrivere codice reale, architettura, attività e log. Il documento remoto può definire il contratto operativo comune.

MEM chiarisce anche le regole di precedenza: il contenuto remoto non può sovrascrivere istruzioni esplicite dell’utente o istruzioni di sistema e developer con priorità superiore. Inoltre, non deve contenere segreti. Questo limite è essenziale se la memoria remota viene usata su più progetti o team.

Operational Extensions

Un’altra funzionalità importante di MEM è l’area extensions/. MEM definisce le Operational Extensions come moduli opzionali per comportamenti specifici di un task. Possono contenere routine, checklist, comandi, chiamate API, flussi di notifica o altre azioni che non appartengono alla knowledge base generale del progetto.

Il punto di ingresso delle estensioni è extensions/EXT.md, che agisce come indice attivo delle estensioni. Ogni estensione reale vive nella propria cartella ed espone le istruzioni principali in extensions/<extension-id>/index.md. Il file template extensions/EXT.index.template.md definisce come strutturare i nuovi indici di estensione.

È una separazione utile. La memoria generale del progetto dovrebbe restare stabile e applicabile in modo ampio. Le estensioni possono essere più mirate: routine di release, checklist di deploy, gestione incidenti, flussi di pubblicazione contenuti, sincronizzazione ticket, procedure QA o workflow specifici di una certa integrazione.

Un agente legge le Operational Extensions solo quando sono rilevanti: quando l’utente richiede esplicitamente il comportamento di un’estensione, quando il task corrisponde chiaramente a un’estensione attiva o quando una pagina della KB punta a una di esse. In questo modo si evita di caricare istruzioni operative non necessarie durante lavori non correlati.

Side effect e sicurezza

MEM tratta con attenzione i side effect esterni. Un’estensione può definire azioni come richieste HTTP, notifiche, deploy, creazione di ticket o scritture su sistemi esterni. Queste azioni possono cambiare lo stato al di fuori del repository locale, quindi la specifica richiede una conferma esplicita dell’utente, a meno che allow_extension_external_side_effects: true non sia impostato in MEM.config.md.

È il default corretto. Un sistema di memoria per agenti dovrebbe rendere il lavoro più ripetibile, ma non dovrebbe trasformare silenziosamente la documentazione in automazione con impatti esterni. I default aggiornati includono anche require_confirmation_for_extension_side_effects: true, rafforzando lo stesso principio.

Alle estensioni è inoltre vietato inviare segreti, token, password, valori reali di variabili d’ambiente, log grezzi o dati personali non necessari. Se un’azione di estensione fallisce, l’agente dovrebbe segnalare l’errore ed evitare retry aggressivi, salvo richiesta esplicita dell’utente. Questi vincoli rendono il modello di estensione più credibile, perché anticipano i rischi dell’automazione operativa invece di trattarli come un dettaglio secondario.

File di configurazione

MEM.config.md è il punto in cui viene definito il comportamento specifico del progetto. I default aggiornati includono sia le impostazioni della sorgente remota sia quelle delle estensioni:

Il modello di precedenza resta esplicito. L’istruzione dell’utente per il task corrente ha la priorità più alta, seguita da MEM.config.md, quindi dai default in MEM.md e infine dai valori rilevati automaticamente da file di progetto affidabili.

Questa gerarchia mantiene MEM flessibile senza renderlo imprevedibile. Un repository può definire i propri default, un MEM remoto può fornire un layer operativo condiviso e l’utente può comunque sovrascrivere il comportamento per il task corrente quando necessario.

Casi d’uso pratici

MEM è particolarmente adatto a progetti software di lunga durata, soprattutto quando gli AI agent intervengono su coding, refactoring, troubleshooting o documentazione. Funziona bene anche per repository infrastrutturali, tool interni, progetti di sicurezza, pipeline di technical writing e qualsiasi progetto in cui la perdita di contesto abbia un costo reale.

La funzionalità di sorgente remota lo rende più adatto alle organizzazioni che mantengono più repository. Il modello di estensione lo rende più utile per progetti con routine operative ripetibili. Insieme, queste due caratteristiche spostano MEM da convenzione documentale locale a framework pratico di memoria per agenti.

Il formato resta volutamente semplice: Markdown può essere revisionato nelle pull request, cercato con strumenti standard e modificato da esseri umani senza una piattaforma dedicata. Questa trasparenza è uno dei punti di forza di MEM: la memoria non è nascosta dentro un sistema agentico proprietario e può evolvere insieme al progetto.

Limiti noti

MEM non sostituisce test, code review o giudizio umano. Offre agli AI agent un contesto di lavoro migliore, ma la qualità di quel contesto dipende dalla qualità degli aggiornamenti. Se l’agente scrive note vaghe, non ispeziona i file sorgente o lascia in giro affermazioni obsolete, la memoria diventerà inaffidabile.

La specifica affronta questo rischio con riferimenti alle sorgenti, marcatori di incertezza e linting della knowledge base. MEM chiede agli agenti di revisionare periodicamente la KB alla ricerca di affermazioni stale, contraddizioni, pagine orfane, draft irrisolti e documentazione che non corrisponde più al codice. Non è un lavoro appariscente, ma è esattamente ciò che mantiene utilizzabile una memoria di progetto nel tempo.

Conclusioni

MEM nasce da un’esigenza semplice: dare agli AI agent una memoria persistente di progetto che gli esseri umani possano leggere e mantenere. Con il supporto per MEM remoto e le Operational Extensions, diventa un layer operativo più completo per il lavoro tecnico assistito da agenti.

Il progetto resta fondato su Markdown puro, una scelta adatta a questo tipo di strumento. Mantiene la memoria visibile, versionabile e facile da correggere. Le funzionalità più recenti aggiungono scalabilità ed estendibilità senza nascondere il meccanismo dietro una piattaforma opaca.

Per i team che stanno già sperimentando gli AI agent nei workflow di sviluppo, MEM merita attenzione perché affronta uno dei problemi meno appariscenti, ma più importanti, del lavoro agentico: preservare il contesto che rende migliore il lavoro futuro.

Riferimenti

• MEM: Markdown Embedded Memory: repository GitHub ufficiale del progetto MEM.
• Markdown Guide: riferimento pratico per sintassi e formattazione Markdown.
• Architecture Decision Records: panoramica e risorse sugli ADR e sulla documentazione leggera delle decisioni.
• GitHub Docs: About READMEs: risorsa utile sulle pratiche di documentazione a livello di repository.

Print Friendly & PDF Download