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.
shell# 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.
| Agente | Tipo di Integrazione | Configurazione |
|---|---|---|
| Claude Code | Plugin nativo + 12 hook + MCP | ~/.claude.json |
| Cursor / Windsurf | Server MCP | Impostazioni MCP nell'IDE |
| GitHub Copilot CLI | MCP + Plugin hook | ~/.copilot/mcp-config.json |
| Cline / Roo Code | Server MCP | Settings UI -> MCP Servers |
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.
Mostra dati
| Voce | Mln Token |
|---|---|
| Contesto Completo | 19,5 |
| Riassunto LLM | 0,65 |
| AgentMemory | 0,17 |
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:
- BM25: Ricerca per parole chiave (keyword matching).
- Vector: Somiglianza semantica tramite calcolo vettoriale.
- 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.
# 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=localProvider 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.
