agentmemory

Cos'è agentmemory?

agentmemory è un “livello di memoria” locale per agenti di coding AI che cattura l’attività di sessione di un agente e fornisce un recall rapido per i passaggi successivi. Funziona sulla tua macchina come un singolo processo Node e memorizza lo stato su disco in formato JSON, senza database esterni.

Il sistema cattura le chiamate agli strumenti e i prompt tramite hook di auto-capture, consolida le osservazioni grezze in memorie semantiche e fornisce il recupero attraverso una pipeline ibrida (BM25 + vettoriale + grafo di conoscenza) con reranking on-device.

Funzionalità principali

• Runtime locale con stato JSON su disco (zero database esterni): Funziona come un unico processo Node e persiste i dati su disco in formato JSON; non richiede Redis, Kafka, Postgres, Qdrant o Neo4j.
• Hook di auto-capture per l’attività dell’agente: PreToolUse, PostToolUse、SessionStart, Stop e altri eventi alimentano la pipeline di memoria senza codice aggiuntivo una volta installato.
• Recupero ibrido con reranking on-device: Il recall a tre flussi combina segnali BM25, vettoriali e del grafo di conoscenza e riordina i risultati on-device (descritto come “P50 sotto 20ms su un laptop” sulla pagina).
• Comportamento di consolidamento e retention automatici: Sweep orari consolidano le osservazioni grezze in memorie semantiche, uniscono duplicati, rimuovono righe obsolete tramite scoring di retention e generano righe di audit in batch quando gli elementi vengono eliminati.
• MCP server con superficie di strumenti definita: Espone strumenti MCP come memory_save, memory_recall, memory_smart_search, memory_sessions, governance, audit e export, insieme a un twin REST per ogni strumento MCP sotto /agentmemory/*.
• Riproduzione di sessioni tramite importazione JSONL: Reidrata una sessione da un transcript JSONL di Claude Code, 包括 osservazioni, usi degli strumenti e timeline, nel datastore.
• Compressione e query del grafo di conoscenza: Estrae entità e relazioni durante la compressione; supporta query grafiche tramite /agentmemory/graph e visualizzazione nel viewer.
• Sincronizzazione federata tra nodi (HTTPS autenticato): Push/pull di memorie tra nodi agentmemory con autenticazione bearer-token; la pagina nota esplicitamente “nessuna sincronizzazione silenziosa”.
• Viewer locale e output di osservabilità: Fornisce un viewer dello stream di osservazioni live (porta 3113) e log/tracce tramite un “OTEL observability worker” (esportazione OTLP per backend di tracing come Jaeger/Honeycomb/Tempo menzionati sulla pagina).

Come usare agentmemory

1. Installa una volta: Esegui npm install -g @agentmemory/agentmemory per aggiungere agentmemory al tuo PATH.
2. Avvia il server: Lancia agentmemory (il server gira su :3111, il viewer su :3113).
3. Verifica localmente: Apri http://localhost:3113 per vedere lo stream di osservazioni live e le dashboard.
4. Connetti un agente tramite MCP: Configura il tuo agente per usare la configurazione JSON MCP di agentmemory (il sito afferma “un JSON MCP si adatta quasi a tutto”).
5. Importa facoltativamente sessioni passate: Usa la funzionalità di importazione JSONL delle sessioni fornita per riprodurre esecuzioni precedenti dell’agente nel datastore.

Casi d'uso

• Costruisci continuità tra più sessioni di coding: Cattura prompt e usi degli strumenti di ogni sessione per consentire alle azioni dell’agente successive di recuperare rapidamente osservazioni rilevanti del passato.
• Supporta l’auditing “perché l’agente ha fatto questo?”: Usa l’emissione di audit descritta per le cancellazioni e l’output di osservabilità/tracing per ispezionare cosa è avvenuto durante le operazioni di memoria e la gestione delle sessioni.
• Migliora la qualità del recupero per query miste: Usa la ricerca ibrida (BM25 + vettoriale + grafo di conoscenza) con reranking on-device quando le query sono in parte lessicali, in parte semantiche o dipendono da relazioni estratte.
• Trasforma i transcript in memoria riutilizzabile: Importa transcript JSONL di Claude Code per reidratare una timeline completa di sessione—utile quando hai run passati da queryare later.
• Coordina tra più macchine con agenti: Imposta la sincronizzazione peer-to-peer tra nodi agentmemory usando HTTPS autenticato per lo scambio push/pull di memorie.

FAQ

• agentmemory richiede un database esterno (come Postgres o Qdrant)? No. La pagina indica “ZERO EXTERNAL DATABASES” e descrive il sistema come un singolo processo con lo stato salvato su disco in formato JSON.

• Come accedo agli strumenti per salvare e richiamare la memoria? agentmemory espone un server MCP con tool come memory_save e memory_recall. La pagina menziona anche endpoint REST per ogni tool sotto /agentmemory/*.

• Dove posso vedere cosa sta catturando il server? Un viewer si avvia automaticamente sulla porta 3113, mostrando lo stream di osservazioni live, l’esploratore di sessioni, il browser della memoria, la visualizzazione del knowledge graph e una dashboard di salute.

• Posso importare trascrizioni di coding esistenti? Sì. La pagina descrive un workflow di importazione JSONL per sessioni che acquisisce una trascrizione Claude Code JSONL e reidrata osservazioni, usi di tool e timeline.

• agentmemory supporta lo spostamento dei dati di memoria tra macchine? La pagina descrive una sincronizzazione peer-to-peer su HTTPS autenticato con token bearer (e nessuna sincronizzazione silenziosa).

Alternative

• Database vettoriali generici + layer personalizzato per memoria agente: Puoi memorizzare embedding e implementare il retrieval, ma devi gestire tu stesso orchestrazione, consolidamento, hook e gestione di sessioni/timeline — diversamente da quanto descritto per agentmemory con auto-capture + interfaccia MCP/REST.
• Tool locali per knowledge base di cronologia codice (sistemi note/grafi): I tool che indicizzano documenti e offrono viste di search/grafi possono aiutare con il recall, ma potrebbero non catturare direttamente le chiamate ai tool degli agenti e gli eventi di sessione tramite la pipeline di hook descritta qui.
• Framework RAG senza auto-capture specifico per agenti: Molti stack RAG forniscono retrieval e assemblaggio di contesto al momento della generazione, ma potrebbero richiedere un’integrazione bespoke più complessa per catturare eventi SessionStart/Stop e tool-use in un modello di memoria retrievable.
• Setup di agent telemetry/observability-only: I tool di tracing possono aiutare a ispezionare il comportamento, ma tipicamente non forniscono il consolidamento della memoria, gli endpoint di retrieval e il workflow di importazione replay descritti per agentmemory.