AgentMemory: Memoria Persistente per i Tuoi Agenti AI di Coding

AgentMemory è un motore di memoria persistente progettato per gli agenti di coding AI, capace di eliminare la necessità di rispiegare architetture e preferenze a ogni nuova sessione. Costruito sul motore iii, si integra con strumenti come Claude Code, GitHub Copilot CLI e Cursor, riducendo il consumo di token fino al 92%.

Installazione e Avvio Rapido

AgentMemory può essere installato globalmente tramite npm o eseguito direttamente con npx. Il sistema richiede il motore iii-engine, un runtime leggero per l'esecuzione di funzioni e la gestione dello stato degli agenti AI.

shellCopia
# Installazione globale
npm install -g @agentmemory/agentmemory

# Avvia il server di memoria sulla porta :3111
agentmemory

# In un altro terminale, carica dati di esempio per testare il richiamo (recall)
agentmemory demo

# Collega l'agente specifico (es. Claude Code)
agentmemory connect claude-code

# Installa le "skills" native per istruire l'agante su quando usare la memoria
npx skills add rohitg00/agentmemory -y

Compatibilità con gli Agenti AI

AgentMemory è agnostico rispetto alla piattaforma e funziona con qualsiasi client che supporti il protocollo MCP (Model Context Protocol — uno standard aperto per connettere modelli AI a sorgenti dati esterne) o le API REST.

Perché AgentMemory è necessario

Ogni volta che termini una sessione di chat con un assistente AI, l'agente "dimentica" tutto. Nella sessione successiva, sprechi i primi minuti a rispiegare lo stack tecnologico, le scelte architetturali (es. "uso jose invece di jsonwebtoken per compatibilità con Edge") e i bug già risolti. I file di memoria integrati (come CLAUDE.md) hanno limiti di circa 200 righe e diventano presto obsoleti.

AgentMemory risolve questo problema catturando silenziosamente le azioni dell'agente, comprimendole in memorie strutturate e iniettando il contesto pertinente solo quando serve, basandosi sulla pertinenza semantica.

Benchmark e Performance

L'efficacia di un sistema di memoria si misura nell'accuratezza del recupero (retrieval) e nel risparmio di risorse.

Nel benchmark LongMemEval-S (presentato a ICLR 2025), AgentMemory ha ottenuto risultati d'eccellenza:

• R@5 (Recupero top 5): 95,2%
• R@10: 98,6%
• MRR (Mean Reciprocal Rank): 88,2%

Come Funziona: La Pipeline della Memoria

AgentMemory non si limita a salvare testo. Segue un processo di consolidamento ispirato al cervello umano, dividendo la memoria in quattro livelli: operativa (short-term), episodica (riassunti di sessione), semantica (fatti e pattern) e procedurale (workflow).

Il sistema utilizza una Ricerca Ibrida che combina tre segnali:

1. BM25: Ricerca per parole chiave (keyword matching).
2. Vector: Somiglianza semantica tramite calcolo vettoriale.
3. Graph: Attraversamento del grafo della conoscenza per trovare entità correlate.

Configurazione e Provider LLM

Per impostazione predefinita, AgentMemory non effettua chiamate LLM esterne. Per abilitare la compressione intelligente e i riassunti, è necessario configurare un provider tramite il file ~/.agentmemory/.env.

Copia
# Esempio configurazione per Ollama (Locale)
OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen2.5-coder:7b

# Esempio per Embedding locali (Gratuiti)
EMBEDDING_PROVIDER=local

Provider Supportati

• Anthropic: Claude 3.5 Sonnet (Qualità massima).
• Gemini: gemini-embedding-001 (Ottimo compromesso gratuito).
• OpenRouter: Accesso a DeepSeek e altri modelli economici.
• Voyage AI: Modelli ottimizzati specificamente per il codice.

Strumenti e Toolkit MCP

AgentMemory espone ben 53 strumenti tramite MCP, permettendo all'agente non solo di leggere e scrivere memorie, ma di gestire cicli di vita complessi.

• memory_smart_search: Ricerca semantica avanzata.
• memory_save: Salva un'intuizione o una decisione specifica.
• memory_relations: Interroga il grafo delle relazioni tra i concetti.
• memory_governance_delete: Eliminazione sicura con audit trail (tracciamento delle modifiche).
• memory_lease: Gestione dei blocchi per evitare conflitti in configurazioni multi-agente.

Visualizzatore Real-Time e Console iii

AgentMemory include una dashboard web accessibile localmente per monitorare cosa l'agente sta imparando.

• Viewer (:3113): Una vista "lato utente" per esplorare le sessioni, i riassunti e visualizzare il grafo della conoscenza.
• Console iii (:3114): Una vista "lato tecnico" per il debug. Permette di vedere ogni traccia OpenTelemetry, ispezionare il database Key-Value e testare le funzioni manualmente.