▍ Documentazione MemPalace

Guida completa a MemPalace — il sistema di memoria persistente ad alte prestazioni per agenti AI, scritto in Rust.

Indice

1. Panoramica
2. Architettura della Memoria
3. Stanze (Rooms)
4. Operazioni di Memoria
5. Command-Line Interface
6. Protocollo MCP
7. Compressione AAAK
8. Esempi Pratici
9. FAQ

1. Panoramica

MemPalace è un sistema di memoria persistente ad alte prestazioni per agenti AI, costruito in Rust. Ispirato al "Metodo dei Loci" (il palazzo della memoria), organizza la conoscenza in stanze tematiche all'interno di ali (wings) per progetto, con ricerca semantica vettoriale, knowledge graph temporale e compressione AAAK.

Perché una memoria persistente?

Gli agenti AI tradizionali partono da zero ad ogni sessione. MemPalace risolve questo problema memorizzando:

Errori passati e le relative soluzioni — per non ripeterli
Strategie di successo — per replicarle in contesti simili
Preferenze dell'utente — per personalizzare l'interazione
Conversazioni — per mantenere il contesto tra sessioni
Insight consolidati — conoscenza estratta dalle esperienze passate

Caratteristiche Principali

15+ stanze tematiche per organizzare la conoscenza per tipo
Backend Rust nativo per prestazioni elevate (~1800 ops/sec compressione)
Protocollo MCP per la comunicazione con qualsiasi client AI
Ricerca semantica vettoriale per trovare ricordi rilevanti
Knowledge Graph temporale con triple soggetto-predicato-oggetto
Compressione AAAK v3.2 — ~30x riduzione token con density adattiva
4-Layer Memory Stack (L0-L3) per contesto gerarchico
20+ strumenti MCP per integrazione completa con agenti AI

2. Architettura della Memoria

Memory Stack (L0-L3)

MemPalace organizza il contesto gerarchicamente in 4 layer:

Layer	Nome	Contenuto	Token
`L0`	IDENTITY	Core persona e identità	~100
`L1`	ESSENTIAL	Eventi recenti con bias di recency	~500-800
`L2`	ON-DEMAND	Contesto cercato per similarità	variabile
`L3`	SEARCH	Ricerca semantica raw	variabile

Struttura del Palace

La memoria è organizzata gerarchicamente:

~/.mempalace/                   # Palace root
├── wing_default/               # Ala principale (globale)
│   ├── error_patterns/         # Stanza: pattern di errore
│   ├── successful_strategies/ # Stanza: strategie di successo
│   ├── task_history/          # Stanza: cronologia task
│   ├── conversations/         # Stanza: conversazioni
│   ├── ...                    # Altre stanze
├── wing_<project>/             # Ala per progetto specifico
│   ├── style_guides/          # Convenzioni del progetto
│   ├── project_schemas/       # Struttura del progetto
│   └── ...                    # Stanze specifiche
└── metadata.db                # Database metadata (SQLite)

Ali (Wings)

Le ali separano la memoria per contesto:

wing_default — Memoria globale (errori comuni, template, insight)
wing_<project> — Memoria specifica per progetto (convenzioni, struttura, task)

Protocollo MCP/stdio

mempalace-rs comunica tramite il protocollo MCP (Model Context Protocol) su stdin/stdout, esponendo 20+ strumenti per l'integrazione con qualsiasi client AI compatibile:

# Avvio del server MCP
mempalace-rs mcp-server

# Il processo resta in ascolto su stdin
# e risponde su stdout in formato JSON-RPC

Integrazione con Client AI

mempalace-rs si integra facilmente con i principali client AI tramite MCP:

Claude Code — claude add mcp "mempalace-rs" --command "cargo" --args "run,--,mcp-server"
Cursor — Settings → Features → MCP → Add New Server
Windsurf — Trascina il file mempalace-rs.skill nella sidebar

3. Stanze (Rooms)

Ogni stanza memorizza un tipo specifico di conoscenza. Le stanze hanno scope global (condivise tra progetti), project (specifiche per progetto) o user (specifiche per utente).

Stanza	Scope	Descrizione
`error_patterns`	project	Pattern di errore ricorrenti e relative soluzioni
`successful_strategies`	project	Sequenze di azioni che hanno portato al successo
`task_history`	project	Cronologia dei task completati e falliti
`debugging_patterns`	project	Casi di debug risolti: sintomo → diagnosi → fix
`project_schemas`	project	Strutture di progetto per linguaggio/framework
`conversations`	user	Cronologia delle conversazioni con l'utente
`user_preferences`	user	Preferenze dell'utente (stile, formati, scelte)
`reward_signals`	user	Segnali di reward/punishment per l'apprendimento RL
`projects`	user	Progetti noti: percorso, linguaggio, framework, attività recenti
`consolidated_insights`	user	Insight di alto livello estratti dalle esperienze
`learned_facts`	user	Fatti e informazioni appresi dalle conversazioni
`code_templates`	global	Template di codice riutilizzabili
`dependency_maps`	global	Mappatura di quali librerie usare per quali task
`style_guides`	global	Convenzioni di codifica per ogni progetto
`test_strategies`	project	Strategie di testing efficaci per tipi di progetto

Consolidamento Automatico

Il sistema estrae automaticamente insight dalle stanze raw e li trasferisce nelle stanze di consolidamento:

error_patterns + successful_strategies → consolidated_insights
conversations → user_preferences + learned_facts

Questo processo avviene in background e riduce la quantità di dati da consultare ad ogni task, mantenendo solo la conoscenza essenziale.

4. Operazioni di Memoria

Operazioni Primarie

Operazione	Descrizione	Esempio
`store(room, key, text, metadata)`	Salva un elemento in una stanza	`store("error_patterns", "import_error", "ImportError: No module", {...})`
`recall(room, query, n_results)`	Richiama elementi da una stanza (con ricerca semantica opzionale)	`recall("error_patterns", query_text="database connection")`
`query(room, query_text, n_results)`	Ricerca semantica in una stanza con scoring di rilevanza	`query("error_patterns", "retry backoff strategy")`
`search_memory(query)`	Cerca in tutte le stanze contemporaneamente	`search_memory("database timeout")`
`delete(room, key)`	Elimina un elemento specifico da una stanza	`delete("error_patterns", "import_error")`

Operazioni Avanzate

Operazione	Descrizione
`recall_recent_conversations(n)`	Richiama le ultime N conversazioni, ordinate dalla più recente
`recall_recent_conversations_as_messages(n)`	Restituisce le conversazioni come lista di dict (formato LLM)
`store_conversation(role, text)`	Salva una conversazione nel buffer (persistita da `flush_conversations_buffer()`)
`flush_conversations_buffer()`	Persiste il buffer delle conversazioni su disco
`list_projects()`	Elenca i progetti noti per l'utente corrente
`register_project(path, language, framework)`	Registra un progetto nella stanza `projects` e nel KG
`add_concept(subject, object, predicate)`	Aggiunge una relazione al Knowledge Graph
`query_kg(entity)`	Interroga il Knowledge Graph per relazioni e fatti
`get_rooms(wing)`	Elenca le stanze disponibili in un'ala
`get_stats()`	Statistiche sulla memoria (stanze, elementi, dimensioni)

Scoring di Rilevanza

La funzione query() utilizza uno scoring composito a 3 dimensioni:

Similarità semantica (peso 0.5) — quanto il query è simile al contenuto
Recency (peso 0.2) — quanto è recente il ricordo
Success score (peso 0.3) — quanto è stata utile questa informazione in passato

# Esempio di output query
[successful_strategies/test] SUCCESS Strategia: Leggere sempre i file prima di modificarli
[successful_strategies] (score: 0.80 = sim:0.70 + rec:0.85 + succ:0.75)

Filtraggio per Soglia

È possibile filtrare i risultati per rilevanza minima:

# Solo risultati con score >= 0.5
recall("error_patterns", query_text="database", min_relevance=0.5)

# Solo risultati molto rilevanti (score >= 0.9)
query("error_patterns", "test", min_relevance=0.99)

5. Command-Line Interface

mempalace-rs offre diversi comandi per interagire con il sistema di memoria:

Comandi Principali

🔧 Init

Onboarding guidato con rilevamento automatico delle stanze.

mempalace-rs init /path/to/project

⛏️ Mine

Ingestisce progetti o conversazioni nella memoria.

mempalace-rs mine /path/to/project \
  --mode project --wing MyProject

🔍 Search

Ricerca semantica sui dati memorizzati.

mempalace-rs search "async patterns"
mempalace-rs search "async" --wing MyProject

🌅 Wakeup

Ottieni il contesto L0+L1 (~600-900 token) per l'agente.

mempalace-rs wakeup

📦 Compress

Comprime i drawer con AAAK v3.2 (~30x riduzione).

mempalace-rs compress

✂️ Prune

Deduplicazione semantica con clustering e merging.

mempalace-rs prune --threshold 0.8

🔌 MCP Server

Avvia il server MCP su stdio per l'integrazione AI.

mempalace-rs mcp-server

📋 Instructions

Genera system prompts per l'onboarding degli agenti.

mempalace-rs instructions

🩹 Repair

Ripristina e re-indicizza lo storage vettoriale.

mempalace-rs repair

✂️ Split

Divide mega-file in file per-sessione.

mempalace-rs split /path/to/dir

Opzioni Globali

Flag	Descrizione	Default
`--wing`	Ala (wing) su cui operare	wing_default
`--room`	Stanza specifica	tutte
`--results`	Numero di risultati per la ricerca	10
`--limit`	Limite per l'ingestione (mine)	nessuno
`--dry-run`	Simula l'operazione senza scrivere	—
`--no-gitignore`	Ignora .gitignore durante il mine	—

6. Protocollo MCP

mempalace-rs espone 20+ strumenti tramite il protocollo MCP (Model Context Protocol) su stdio, permettendo l'integrazione con qualsiasi client AI compatibile.

Palace Overview

Strumento	Descrizione
`mempalace_status`	Stato del palace: drawers, wings, rooms, protocollo
`mempalace_list_wings`	Elenca tutte le ali con conteggio
`mempalace_list_rooms`	Elenca le stanze in un'ala
`mempalace_get_taxonomy`	Albero completo wing → room → count
`mempalace_graph_stats`	Statistiche del Knowledge Graph

Search & Retrieval

Strumento	Descrizione
`mempalace_search`	Ricerca semantica con filtri wing/room
`mempalace_check_duplicate`	Controllo similarità per deduplicazione
`mempalace_prune`	Potatura semantica e merging della memoria

Graph Navigation

Strumento	Descrizione
`mempalace_traverse_graph`	Attraversamento BFS da una stanza di partenza
`mempalace_find_tunnels`	Trova stanze ponte (bridge rooms)

Content Management

Strumento	Descrizione
`mempalace_add_drawer`	Aggiunge contenuto verbatim a una stanza
`mempalace_delete_drawer`	Rimuove un drawer per ID
`mempalace_get_aaak_spec`	Restituisce la specifica AAAK corrente

Knowledge Graph

Strumento	Descrizione
`mempalace_kg_add`	Aggiunge una tripla (soggetto, predicato, oggetto)
`mempalace_kg_query`	Interroga relazioni e fatti di un'entità
`mempalace_kg_invalidate`	Marca una tripla come non più valida
`mempalace_kg_timeline`	Timeline cronologica di un'entità
`mempalace_kg_stats`	Statistiche del Knowledge Graph

Agent Diary

Strumento	Descrizione
`mempalace_diary_write`	Scrive un'entrata nel diario dell'agente
`mempalace_diary_read`	Legge le ultime N entrate del diario

7. Compressione AAAK

MemPalace utilizza il dialetto AAAK v3.2 per comprimere i ricordi con un rapporto di ~30x, riducendo il consumo di token nel contesto LLM.

Formato AAAK

WING|ROOM|DATE|SOURCE
0:ENTITIES|TOPICS|"QUOTE"|EMOTIONS|FLAGS

Caratteristiche

Density adattiva — il livello di dettaglio si adatta all'importanza del contenuto
Importance scoring — ogni elemento ha un punteggio di rilevanza
Delta encoding — solo le differenze rispetto allo stato precedente
Codici entità — riferimenti compatti a entità e relazioni
Codici emozione — rappresentazione compatta del sentimento

Prestazioni

Metrica	Valore
Throughput compressione	~1808 ops/sec
Latenza compressione	~553 µs
Rilevamento entità	~267K ops/sec
Conteggio token	~3.8M ops/sec
Rapporto compressione	~30x

8. Esempi Pratici

Esempio 1: Primo Avvio

# Inizializza il palace per un progetto
mempalace-rs init /percorso/del/progetto

# Il wizard rileverà automaticamente le stanze
# e configurerà il palace

# Ottieni il contesto essenziale
mempalace-rs wakeup

Esempio 2: Ingestione di un Progetto

# Ingestisci un progetto nella memoria
mempalace-rs mine /percorso/del/progetto \
  --mode project \
  --wing MyProject

# Ingestisci una conversazione
mempalace-rs mine /percorso/chat_log.md \
  --mode conversation \
  --wing MyProject

Esempio 3: Ricerca Semantica

# Cerca in tutto il palace
mempalace-rs search "async patterns in Rust"

# Cerca in una stanza specifica
mempalace-rs search "database connection" \
  --wing MyProject \
  --room error_patterns \
  --results 5

Esempio 4: Integrazione MCP con un Agente AI

# Avvia il server MCP
mempalace-rs mcp-server

# L'agente può ora usare tutti gli strumenti MCP:
# mempalace_search, mempalace_kg_add, mempalace_wakeup, ...

# Per Claude Code:
claude add mcp "mempalace-rs" \
  --command "cargo" \
  --args "run,--,mcp-server" \
  --cwd "$(pwd)"

Esempio 5: Wakeup Context

# Ottieni il contesto essenziale per l'agente
# (L0: identità + L1: eventi recenti)
mempalace-rs wakeup

# Output: ~600-900 token di contesto concentrato
# Include: identità, eventi recenti, insight consolidati

Esempio 6: Manutenzione della Memoria

# Comprime i drawer per ridurre il contesto
mempalace-rs compress

# Rimuovi duplicati semantici
mempalace-rs prune --threshold 0.8

# Ripristina lo storage vettoriale
mempalace-rs repair

9. FAQ

Dove viene salvata la memoria?

La memoria è salvata in ~/.mempalace/. Ogni ala ha la sua directory con le stanze. I metadata e il Knowledge Graph sono in un database SQLite.

Posso condividere la memoria tra progetti?

Sì, le stanze con scope global (come code_templates, dependency_maps, style_guides) sono condivise tra tutti i progetti. Le stanze con scope project sono specifiche per progetto. Le stanze con scope user (come consolidated_insights, user_preferences) sono specifiche per utente ma condivise tra progetti.

Come funziona il consolidamento?

Il consolidamento analizza periodicamente le stanze raw (error_patterns, successful_strategies, conversations) ed estrae insight di alto livello che salva nelle stanze di consolidamento (consolidated_insights, user_preferences, learned_facts). Questo riduce il rumore e mantiene solo la conoscenza essenziale.

Quanta memoria consuma?

MemPalace è efficiente: il backend Rust utilizza storage su disco SQLite con indicizzazione vettoriale embedded. Il consumo tipico è di pochi MB per centinaia di ricordi, con un baseline di ~50 MB di RAM. La compressione AAAK previene la crescita illimitata del contesto.

Posso cancellare la memoria?

Sì, puoi eliminare singoli elementi con l'operazione delete via MCP, oppure resettare tutta la memoria eliminando ~/.mempalace/.

Funziona offline?

Sì, MemPalace è completamente offline-first. Lo storage vettoriale è embedded e zero-network. Non richiede connessione internet per funzionare, né chiavi API.

Come funziona la ricerca semantica?

La ricerca semantica utilizza embedding vettoriali per trovare ricordi rilevanti anche quando il query non corrisponde esattamente al testo memorizzato. Lo scoring combina similarità semantica, recency e success score.

Quali client AI sono supportati?

mempalace-rs supporta qualsiasi client compatibile con il protocollo MCP. Le integrazioni testate includono: Claude Code, Cursor, Windsurf e qualsiasi client che supporti MCP su stdio.

Come contribuire?

Il progetto è open source su GitHub. Consulta il file CONTRIBUTING.md per le linee guida.

← Torna alla Homepage