Home
Blog
Aggiunta di memoria persistente al codice Claude con il plugin Lightweight memsearch

Aggiunta di memoria persistente al codice Claude con il plugin Lightweight memsearch

Engineering

February 13, 2026

Cheney Zhang

Di recente abbiamo realizzato e reso open source memsearch, una libreria di memoria a lungo termine standalone e plug-and-play che fornisce a qualsiasi agente una memoria persistente, trasparente e modificabile dall'uomo. Utilizza la stessa architettura di memoria di OpenClaw, ma senza il resto dello stack di OpenClaw. Ciò significa che è possibile inserirla in qualsiasi framework di agenti (Claude, GPT, Llama, agenti personalizzati, motori di flusso di lavoro) e aggiungere immediatamente una memoria durevole e interrogabile. (Se volete approfondire il funzionamento di memsearch, abbiamo scritto un post a parte qui).

Nella maggior parte dei flussi di lavoro degli agenti, memsearch funziona esattamente come previsto. Ma la codifica agenziale è una storia diversa. Le sessioni di codifica sono lunghe, i cambi di contesto sono continui e le informazioni che vale la pena conservare si accumulano per giorni o settimane. Questo volume e questa volatilità mettono a nudo i punti deboli dei sistemi di memoria tipici degli agenti, compreso memsearch. Negli scenari di codifica, gli schemi di recupero differiscono abbastanza da non poter semplicemente riutilizzare lo strumento esistente così com'è.

Per risolvere questo problema, abbiamo creato un plugin di memoria persistente progettato appositamente per Claude Code. Si trova sopra la CLI di memsearch e lo chiamiamo memsearch ccplugin.

GitHub Repo: https://zilliztech.github.io/memsearch/claude-plugin/ (open-source, licenza MIT)

Con il leggero ccplugin memsearch che gestisce la memoria dietro le quinte, Claude Code ottiene la capacità di ricordare ogni conversazione, ogni decisione, ogni preferenza di stile e ogni thread di più giorni: indicizzato automaticamente, completamente ricercabile e persistente in tutte le sessioni.

Per chiarezza in questo post: "ccplugin" si riferisce al livello superiore, ovvero al plugin Claude Code stesso. "memsearch" si riferisce al livello inferiore, lo strumento CLI standalone sottostante.

Perché la codifica ha bisogno di un proprio plugin e perché abbiamo costruito qualcosa di così leggero? Il motivo è da ricercare in due problemi che quasi sicuramente avrete riscontrato: La mancanza di memoria persistente di Claude Code e la goffaggine e complessità delle soluzioni esistenti come claude-mem.

Allora perché creare un plugin dedicato? Perché gli agenti di codifica si imbattono in due punti dolenti che quasi certamente avete sperimentato voi stessi:

Claude Il codice non ha memoria persistente.
Molte delle soluzioni comunitarie esistenti, come claude-mem, sonopotenti, ma pesanti, goffe o troppo complesse per il lavoro di codifica quotidiano.

Il ccplugin mira a risolvere entrambi i problemi con un livello minimo, trasparente e facile da sviluppare sopra memsearch.

Il problema di memoria del codice Claude: dimentica tutto quando una sessione finisce

Cominciamo con uno scenario in cui gli utenti di Claude Code si sono sicuramente imbattuti.

Si apre Claude Code al mattino. "Continua il refactor dell'autenticazione di ieri", scrivete. Claude risponde: "Non sono sicuro su cosa stavi lavorando ieri". Così si passano i dieci minuti successivi a copiare i log di ieri. Non è un problema enorme, ma diventa presto fastidioso perché si presenta così spesso.

Anche se Claude Code ha i suoi meccanismi di memoria, non sono affatto soddisfacenti. Il file CLAUDE.md può memorizzare le direttive e le preferenze del progetto, ma funziona meglio per regole statiche e comandi brevi, non per accumulare conoscenze a lungo termine.

Claude Code offre i comandi resume e fork, ma non sono affatto facili da usare. Per i comandi a forcella è necessario ricordare gli ID delle sessioni, digitare manualmente i comandi e gestire un albero di conversazioni ramificate. Quando si esegue /resume, si ottiene un muro di titoli di sessione. Se si ricordano solo pochi dettagli di ciò che si è fatto e che risale a più di qualche giorno fa, la fortuna è di trovare quella giusta.

Per l'accumulo di conoscenze a lungo termine e su più progetti, questo approccio è impossibile.

Per realizzare questa idea, claude-mem utilizza un sistema di memoria a tre livelli. Il primo livello cerca sommari di alto livello. Il secondo livello scava in una linea temporale per ottenere maggiori dettagli. Il terzo livello estrae le osservazioni complete per le conversazioni non elaborate. A ciò si aggiungono le etichette per la privacy, il monitoraggio dei costi e un'interfaccia di visualizzazione web.

Ecco come funziona sotto il cofano:

Livello di runtime. Un servizio Node.js Worker viene eseguito sulla porta 37777. I metadati della sessione risiedono in un database SQLite leggero. Un database vettoriale gestisce il recupero semantico preciso del contenuto della memoria.
Livello di interazione. Un'interfaccia web basata su React consente di visualizzare i ricordi acquisiti in tempo reale: riepiloghi, cronologie e record grezzi.
Livello di interfaccia. Un server MCP (Model Context Protocol) espone interfacce standardizzate per gli strumenti. Claude può chiamare search (interrogare i riepiloghi di alto livello), timeline (visualizzare le timeline dettagliate) e get_observations (recuperare i record grezzi delle interazioni) per recuperare e utilizzare direttamente le memorie.

A dire il vero, si tratta di un prodotto solido che risolve il problema della memoria di Claude Code. Ma è goffo e complesso nei modi che contano giorno per giorno.

Strato	Tecnologia
Linguaggio	TypeScript (ES2022, moduli ESNext)
Tempo di esecuzione	Node.js 18+
Database	SQLite 3 con driver bun:sqlite
Archivio vettoriale	ChromaDB (opzionale, per la ricerca semantica)
Server HTTP	Express.js 4.18
In tempo reale	Eventi inviati dal server (SSE)
Struttura UI	React + TypeScript
SDK AI	@anthropic-ai/claude-agent-sdk
Strumento di compilazione	esbuild (include TypeScript)
Gestore di processi	Bun
Test	Runner di test integrato in Node.js

Per cominciare, la configurazione è pesante. Far funzionare claude-mem significa installare Node.js, Bun e il runtime MCP, quindi creare un servizio Worker, un server Express, un'interfaccia utente React, SQLite e un archivio vettoriale. Si tratta di un sacco di parti in movimento da distribuire, mantenere e debuggare quando qualcosa si rompe.

Tutti questi componenti bruciano anche i gettoni che non avete chiesto di spendere. Le definizioni degli strumenti MCP vengono caricate in modo permanente nella finestra di contesto di Claude e ogni chiamata agli strumenti consuma token sulla richiesta e sulla risposta. Nel corso di lunghe sessioni, questo sovraccarico si accumula rapidamente e può portare i costi dei token fuori controllo.

Il richiamo della memoria è inaffidabile perché dipende interamente dalla scelta di Claude di effettuare una ricerca. Claude deve decidere da solo di chiamare strumenti come search per attivare il recupero. Se non si rende conto di aver bisogno di una memoria, il contenuto pertinente non compare mai. E ognuno dei tre livelli di memoria richiede l'invocazione esplicita di uno strumento, quindi non c'è un ripiego se Claude non pensa di cercare.

Infine, la memorizzazione dei dati è opaca, il che rende spiacevole il debugging e la migrazione. Le memorie sono divise tra SQLite per i metadati di sessione e Chroma per i dati vettoriali binari, senza un formato aperto che li colleghi. Migrare significa scrivere script di esportazione. Per vedere ciò che l'IA ricorda in realtà è necessario utilizzare l'interfaccia Web o un'interfaccia di interrogazione dedicata. Non c'è modo di guardare i dati grezzi.

Perché il plugin memsearch per Claude Code è migliore?

Volevamo un livello di memoria che fosse veramente leggero: nessun servizio aggiuntivo, nessuna architettura ingarbugliata, nessun overhead operativo. Questo è il motivo che ci ha spinto a creare il plugin memsearch per Claude Code. In fondo, si trattava di un esperimento: poteva un sistema di memoria incentrato sulla codifica essere radicalmente più semplice?

Sì, e lo abbiamo dimostrato.

L'intero ccplugin è costituito da quattro hook di shell più un processo di watch in background. Niente Node.js, niente server MCP, niente interfaccia web. Si tratta solo di script di shell che richiamano la CLI di memsearch, che riduce drasticamente la barra di configurazione e manutenzione.

Il ccplugin può essere così sottile grazie ai rigidi limiti di responsabilità. Non gestisce l'archiviazione della memoria, il recupero di vettori o l'inserimento di testo. Tutto ciò è delegato alla CLI memsearch sottostante. Il ccplugin ha un solo compito: fare da ponte tra gli eventi del ciclo di vita di Claude Code (inizio della sessione, invio della richiesta, interruzione della risposta, fine della sessione) e le corrispondenti funzioni della CLI di memsearch.

Questa struttura disaccoppiata rende il sistema flessibile al di là di Claude Code. La CLI di memsearch funziona indipendentemente da altri IDE, da altri framework di agenti o anche dalla semplice invocazione manuale. Non è vincolata a un singolo caso d'uso.

In pratica, questo design offre tre vantaggi chiave.

1. Tutte le memorie vivono in semplici file Markdown

Ogni memoria creata dal ccplugin vive in .memsearch/memory/ come file Markdown.

.memsearch/memory/
├── 2026-02-09.md
├── 2026-02-10.md
└── 2026-02-11.md

Si tratta di un file al giorno. Ogni file contiene i riassunti delle sessioni di quel giorno in testo semplice, completamente leggibile. Ecco una schermata dei file di memoria giornalieri dal progetto memsearch stesso:

Si può notare subito il formato: timestamp, ID della sessione, ID del turno e un riassunto della sessione. Non c'è nulla di nascosto.

Volete sapere cosa ricorda l'intelligenza artificiale? Aprite il file Markdown. Volete modificare una memoria? Utilizzate il vostro editor di testo. Volete migrare i vostri dati? Copiate la cartella .memsearch/memory/.

L'indice vettoriale di Milvus è una cache per accelerare la ricerca semantica. Si ricostruisce da Markdown in qualsiasi momento. Nessun database opaco, nessuna scatola nera binaria. Tutti i dati sono tracciabili e completamente ricostruibili.

2. L'iniezione automatica del contesto non comporta alcun costo aggiuntivo in termini di gettoni.

L'archiviazione trasparente è alla base di questo sistema. Il vero guadagno deriva dal modo in cui queste memorie vengono utilizzate e in ccplugin il richiamo della memoria è completamente automatico.

Ogni volta che viene inviato un prompt, l'hook di UserPromptSubmit avvia una ricerca semantica e inietta nel contesto le prime tre memorie rilevanti. Claude non decide se effettuare la ricerca. Si limita a ottenere il contesto.

Durante questo processo, Claude non vede mai le definizioni degli strumenti MCP, quindi non occupa nulla di extra nella finestra del contesto. L'hook viene eseguito a livello di CLI e inietta i risultati della ricerca in testo semplice. Nessun overhead IPC, nessun costo di token per le chiamate agli strumenti. L'ingombro della finestra di contesto che viene fornito con le definizioni degli strumenti MCP è completamente eliminato.

Per i casi in cui la top-3 automatica non è sufficiente, abbiamo creato anche tre livelli di recupero progressivo. Tutti e tre sono comandi CLI, non strumenti MCP.

L1 (automatico): Ogni prompt restituisce i primi 3 risultati della ricerca semantica con un'anteprima di chunk_hash e 200 caratteri. Questo copre la maggior parte dell'uso quotidiano.
L2 (su richiesta): Quando è necessario un contesto completo, memsearch expand <chunk_hash> restituisce l'intera sezione Markdown e i metadati.
L3 (profondo): Quando è necessaria la conversazione originale, memsearch transcript <jsonl_path> --turn <uuid> estrae il record JSONL grezzo da Claude Code.

3. I riassunti delle sessioni sono generati in background a costo quasi zero

Il recupero riguarda il modo in cui le memorie vengono utilizzate. Ma prima le memorie devono essere scritte. Come vengono creati tutti quei file Markdown?

Il ccplugin li genera attraverso una pipeline in background che viene eseguita in modo asincrono e non costa quasi nulla. Ogni volta che si interrompe una risposta di Claude, scatta l'hook Stop: analizza la trascrizione della conversazione, chiama Claude Haiku (claude -p --model haiku) per generare un riassunto e lo aggiunge al file Markdown del giorno corrente. Le chiamate all'API Haiku sono estremamente economiche, quasi trascurabili per ogni invocazione.

Da qui, il processo di sorveglianza rileva la modifica del file e indicizza automaticamente il nuovo contenuto in Milvus, in modo che sia subito disponibile per il recupero. L'intero flusso viene eseguito in background senza interrompere il lavoro e i costi rimangono controllati.

Avvio rapido del plugin memsearch con Claude Code

Innanzitutto, installatelo dal marketplace dei plugin di Claude Code:


bash
# Run in Claude Code terminal
/plugin marketplace add zilliztech/memsearch
/plugin install memsearch

In secondo luogo, riavviare Claude Code.

Il plugin inizializza automaticamente la sua configurazione.

Terzo, dopo una conversazione, controllate il file di memoria del giorno:

bash
cat .memsearch/memory/$(date +%Y-%m-%d).md

Quarto, godetevi il momento.

Al successivo avvio di Claude Code, il sistema recupera e inserisce automaticamente i ricordi pertinenti. Non sono necessari altri passaggi.

Conclusione

Torniamo alla domanda iniziale: come si fa a dare all'intelligenza artificiale una memoria persistente? claude-mem e memsearch ccplugin adottano approcci diversi, ciascuno con punti di forza differenti. Abbiamo riassunto una rapida guida alla scelta tra i due:

Categoria	memsearch	claude-mem
Architettura	4 ganci di shell + 1 processo di osservazione	Lavoratore Node.js + Express + React UI
Metodo di integrazione	Ganci nativi + CLI	Server MCP (stdio)
Richiamo	Automatico (iniezione di ganci)	Guidato da agenti (richiede l'invocazione di uno strumento)
Consumo di contesto	Zero (inietta solo il testo del risultato)	Le definizioni degli strumenti MCP persistono
Riepilogo della sessione	Una chiamata Haiku CLI asincrona	Più chiamate API + compressione dell'osservazione
Formato di archiviazione	File Markdown semplici	SQLite + incorporazioni Chroma
Migrazione dei dati	File Markdown semplici	SQLite + incorporazioni Chroma
Metodo di migrazione	Copia dei file .md	Esportazione dal database
Tempo di esecuzione	Python + Claude CLI	Node.js + Bun + runtime MCP

claude-mem offre funzioni più ricche, un'interfaccia utente raffinata e un controllo a grana più fine. Per i team che hanno bisogno di collaborazione, visualizzazione web o gestione dettagliata della memoria, è una scelta importante.

memsearch ccplugin offre un design minimale, zero overhead della finestra di contesto e una memoria completamente trasparente. Per gli ingegneri che vogliono un livello di memoria leggero senza ulteriori complessità, è la scelta migliore. Quale sia il migliore dipende dalle vostre esigenze.

Volete approfondire o essere aiutati a costruire con memsearch o Milvus?

Unitevi alla community Milvus su Slack per entrare in contatto con altri sviluppatori e condividere ciò che state costruendo.
Prenotate i nostri Milvus Office Hours per riceveredomande e risposte dal vivo e il supporto diretto del team.