Come Memora Fornisce agli Assistenti Claude Code una Memoria a Lungo Termine e un Grafo della Conoscenza

Chiunque abbia provato ad assegnare compiti lunghi ad agenti come Claude Code o Codex CLI conosce questa sensazione. Ieri hai passato mezza giornata a rintracciare un bug di autorizzazione non ovvio, hai discusso i vincoli architetturali e hai delineato un piano di refactoring. Oggi apri una nuova sessione e il modello ti suggerisce esattamente quella soluzione che hai rifiutato ieri.

I normali file di memoria testuale come MEMORY.md diventano ingestibili in un paio di settimane. Il contesto si intasa di duplicati, fatti contraddittori e piani obsoleti. Il progetto Memora risolve questo attraverso il Model Context Protocol (MCP), trasformando note sparse degli agenti in un grafo della conoscenza strutturato.

Cosa c'è sotto il cofano e perché è importante

Memora funziona come server MCP Python, memorizzando i dati in un database SQLite locale o cloud storage (Cloudflare D1, S3, R2). La chiave qui non è solo salvare stringhe, ma come il sistema elabora nuovi fatti.

Quando un agente completa un'attività e vuole salvare il contesto, chiama il comando di assorbimento dati (absorb). Un modello linguistico integrato confronta il nuovo fatto con i record esistenti e lo classifica: duplicato, aggiornamento, contraddizione, connessione o conoscenza fondamentalmente nuova.

Se le informazioni aggiornano una voce precedente, Memora costruisce una catena di versioni. Il vecchio record non viene eliminato senza traccia—viene contrassegnato come obsoleto, preservando la cronologia delle modifiche. Durante le ricerche normali, l'agente vede solo lo snapshot corrente, ma può recuperare la retrospettiva completa se necessario.

Cosa distingue questo progetto in pratica

Il repository riunisce diverse soluzioni ingegneristiche che la memoria RAG standard per gli agenti è gravemente carente.

1. Deduplicazione Intelligente e Riepiloghi Tematici

Invece di fornire al modello decine di frammenti di testo simili, lo strumento consolida i fatti per argomento. Il metodo memory_digest(topic) raccoglie tutti i ricordi rilevanti, i TODO aperti, i bug scoperti e le loro connessioni in una singola chiamata.

I duplicati vengono tracciati automaticamente:

# Поиск похожих записей через векторную близость и LLM-анализ
memory_find_duplicates(min_similarity=0.7, max_similarity=0.95, limit=10, use_llm=True)

# Объединение записей с нужной стратегией
memory_merge(source_id=123, target_id=456, merge_strategy="append")

Quando confronta, l'LLM fornisce un verdetto chiaro: duplicato, pensiero simile o cose diverse—integrando la valutazione con ragionamento e una raccomandazione.

2. Documenti Strutturati e Frammenti Atomici

Spesso un agente ha bisogno di ricordare non una breve frase, ma un intero rapporto di ricerca o una decisione architetturale (ADR). Se salvi markdown come un singolo blocco, la ricerca semantica granulare al suo interno avrà prestazioni scarse.

Memora analizza markdown in un albero di frammenti:

• le tabelle diventano affermazioni separate;
• gli elenchi numerati diventano elementi del piano;
• gli elenchi di riferimento diventano riferimenti;
• le sezioni sui rischi vengono analizzate come rischi.

Ogni frammento è disponibile per la ricerca vettoriale in modo indipendente, e il documento originale può essere recuperato completamente in qualsiasi momento. I frammenti sono protetti da cancellazione accidentale o fusione tramite controlli di sistema.

3. Grafo Interattivo e Pannello Web

Accanto al server MCP, si avvia un'interfaccia web locale sulla porta 8765. Puoi visualizzare il grafo della conoscenza, filtrare le connessioni per tag, tracciare le timeline delle azioni e chattare con il database attraverso una chat RAG integrata.

La chat dell'interfaccia web supporta le chiamate di funzione. Puoi chiedere al modello direttamente dal browser: "Elimina nota #42" o "Aggiorna requisiti nel task #10", e farà modifiche al database.

Configurazione e Insidie degli Embedding

Installa il pacchetto tramite pip:

pip install memora-mcp

Per embedding locali senza chiamare API esterne, l'opzione [local] è utile:

pip install "memora-mcp[local]"

La connessione a Claude Code è configurata nel file .mcp.json alla radice del progetto:

{
  "mcpServers": {
    "memora": {
      "command": "memora-server",
      "args": [],
      "env": {
        "MEMORA_DB_PATH": "~/.local/share/memora/memories.db",
        "MEMORA_ALLOW_ANY_TAG": "1",
        "MEMORA_GRAPH_PORT": "8765",
        "MEMORA_EMBEDDING_STRICT": "1"
      }
    }
  }
}

Gli autori del progetto avvertono onestamente di un errore di configurazione comune. Memora può separare il provider per LLM (es. OpenRouter) e il provider per le rappresentazioni vettoriali (es. Cloudflare Workers AI o OpenAI).

Se usi OpenRouter per il ragionamento, ricorda: non ha un endpoint per embeddings. Se commetti un errore nella configurazione e non imposti il flag MEMORA_EMBEDDING_STRICT=1, il server torna silenziosamente alla ricerca keyword TF-IDF primitiva. Il database continuerà a rispondere, ma la qualità della ricerca vettoriale calerà in modo impercettibile. La modalità strict genererà immediatamente un errore se l'endpoint di vettorizzazione non è disponibile.

Per gli utenti di Neovim, c'è un bel bonus sotto forma di integrazione con Telescope: il plugin memora.lua ti permette di cercare nella memoria con un hotkey direttamente mentre modifichi il codice.

A Chi È Destinato Questo Progetto

Memora è adatto a chi usa attivamente Claude Code, Codex CLI o agenti personalizzati basati su MCP per progetti di lunga durata. Affronta il principale punto dolente dello sviluppo agentico—la perdita di contesto tra i riavvii delle sessioni.

Se hai bisogno di una base di conoscenza che non si ingombri di duplicati e che visualizzi chiaramente le connessioni tra task e decisioni architetturali, provare lo strumento ha sicuro senso. Il codice sorgente è disponibile sotto licenza MIT nel repository agentic-box/memora.