▍ Documentazione MemPalace

Guida completa al sistema di memoria persistente di CodePalace — installazione, architettura, comandi CLI e utilizzo avanzato.

1. Panoramica

MemPalace è il sistema di memoria persistente che alimenta CodePalace. Ispirato al "Metodo dei Loci" (il palazzo della memoria), organizza la conoscenza in stanze tematiche all'interno di ali (wings) per progetto.

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 (mempalace-rs) per prestazioni native
• Protocollo MCP per la comunicazione tra agente e memoria
• Ricerca semantica per trovare ricordi rilevanti
• Consolidamento automatico delle esperienze in insight di alto livello
• Lesson Consultant che consulta la memoria prima di ogni task

2. Installazione

Prerequisiti

• Python 3.11+ — versione minima richiesta
• pip — package manager Python
• Git — per il controllo versione integrato

Installazione Base

# Installa CodePalace (include MemPalace)
pip install codepalace

# Verifica l'installazione
codepalace version

Installazione da Sorgente

# Clona il repository
git clone https://github.com/diegotruccolo/codepalace.git
cd codepalace

# Installa in modalità sviluppo
pip install -e .

# Verifica
codepalace version

Dipendenze Opzionali

CodePalace supporta gruppi di dipendenze opzionali per funzionalità specifiche:

# Per il web server (Flask + Stripe + i18n)
pip install codepalace[web]

# Per lo sviluppo (pytest, ruff, mypy, pyinstaller)
pip install codepalace[dev]

# Per entrambi
pip install codepalace[web,dev]

Backend Rust — mempalace-rs

Il sistema di memoria utilizza mempalace-rs, un backend nativo in Rust accessibile via protocollo MCP/stdio.

# Se mempalace-rs è compilato da sorgente
cd mempalace-rs
cargo build --release

# Il binario deve essere nel PATH
# Verifica:
mempalace-rs --help

Configurazione dell'Ambiente

Per utilizzare CodePalace con un provider LLM, configura la chiave API:

# Variabile d'ambiente per OpenRouter
export OPENROUTER_API_KEY="sk-or-v1-..."

# Oppure usa il flag --api-key
codepalace run -t "task" --api-key "sk-or-v1-..."

3. Architettura della Memoria

Struttura del Palace

La memoria è organizzata gerarchicamente:

~/.mempalace/                   # Palace root
├── wing_codepalace/            # Ala principale
│   ├── error_patterns/        # Stanza: pattern di errore
│   ├── successful_strategies/ # Stanza: strategie di successo
│   ├── task_history/          # Stanza: cronologia task
│   ├── conversations/         # Stanza: conversazioni
│   ├── ...                    # Altre stanze
├── wing_/            # 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_codepalace — Memoria globale dell'agente (errori comuni, template, insight)
• wing_<project> — Memoria specifica per progetto (convenzioni, struttura, task)

Protocollo MCP/stdio

La comunicazione tra CodePalace (Python) e mempalace-rs (Rust) avviene tramite il protocollo MCP (Model Context Protocol) su stdin/stdout:

# Avvio del server MCP
mempalace-rs mcp-server

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

Flusso dei Dati

1. L'agente avvia mempalace-rs mcp-server come subprocess
2. Handshake MCP (initialize → initialized)
3. Le operazioni di memoria (store, recall, search) vengono inviate come request JSON-RPC
4. mempalace-rs persiste i dati su disco e risponde con i risultati
5. Il Lesson Consultant consulta la memoria prima di ogni task
6. Le esperienze vengono salvate alla fine di ogni task (consolidation phase)

4. 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).

Consolidamento Automatico

Il sistema BackgroundConsolidator 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.

5. Operazioni di Memoria

Operazioni Primarie

Operazioni Avanzate

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)

6. Command-Line Interface

CodePalace offre diversi comandi per interagire con il sistema:

Comandi Principali

codepalace
codepalace -p /path/to/project

codepalace run -t "Crea una classe Calculator" -p ./myproject

codepalace interactive -p ./myproject

codepalace serve --host 0.0.0.0 --port 8080

codepalace webmempalace --port 5000
codepalace webmempalace --debug

codepalace self-update
codepalace self-update --check-only

Opzioni Globali

Opzioni per run

Modalità Web TUI

Per eseguire la TUI nel browser tramite textual-serve:

# Installa textual-serve
pip install textual-serve

# Avvia la TUI via browser
codepalace --web --port 8000

# Apri http://localhost:8000 nel browser

7. Web Dashboard

MemPalace include una dashboard web per esplorare e gestire la memoria in modo visuale.

Avvio del Server Web

# Avvia il server Flask
codepalace webmempalace --port 5000

# Oppure con debug
codepalace webmempalace --debug --host localhost

# Apri http://localhost:5000 nel browser

Funzionalità della Dashboard

• Vista Stanze — Esplora tutte le stanze con conteggio elementi
• Ricerca Semantica — Cerca ricordi per rilevanza
• Filtri per Ala — Filtra la memoria per progetto/wing
• Statistiche — Panoramica dell'utilizzo della memoria
• Knowledge Graph — Visualizzazione delle relazioni tra entità

Variabili d'Ambiente per il Web Server

# Database Flask
DATABASE_PATH=website/data/mempalace.db

# Stripe (per piani a pagamento)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Licenza
LICENSE_SECRET_KEY=your-hmac-secret

8. Apprendimento per Rinforzo

MemPalace integra un sistema di apprendimento per rinforzo (RL) che valuta ogni azione e aggiorna i segnali di reward nelle stanze della memoria.

Reward Function — 6 Dimensioni

Lesson Consultant

Prima di ogni task, il Lesson Consultant consulta la memoria MemPalace:

1. Cerca nella stanza error_patterns per errori simili a quelli potenziali
2. Cerca in successful_strategies per approcci che hanno funzionato
3. Consulta style_guides e project_schemas per il contesto del progetto
4. Recupera user_preferences per personalizzare l'interazione
5. Inietta i risultati nel contesto del LLM per guidare l'azione

Ciclo di Apprendimento

1. CONSULTA: Prima del task → recall(error_patterns, successful_strategies, ...)
2. AGISCI: Esegue il task con le lezioni nel contesto
3. VALUTA: Reward function calcola il punteggio dell'azione
4. SALVA: Salva l'esperienza nella stanza appropriata
5. CONSOLIDA: BackgroundConsolidator estrae insight di alto livello

9. API REST

MemPalace espone API REST tramite Flask per l'accesso programmatico alla memoria.

Endpoint della Memoria

GET    /api/memories                    # Lista ricordi (filtri: wing, room, limit, offset)
GET    /api/memories/<id>               # Dettaglio di un ricordo per ID
POST   /api/memories/search              # Ricerca semantica per testo
DELETE /api/memories/<id>               # Elimina un ricordo per ID
POST   /api/memories/bulk-delete         # Elimina multipla per lista ID
DELETE /api/memories                     # Elimina con filtri (wing, room)
GET    /api/memories/stats               # Statistiche della memoria
GET    /api/memories/wings               # Lista delle ali (wings)
GET    /api/memories/rooms               # Lista delle stanze disponibili

Endpoint del Knowledge Graph

GET    /api/memories/kg/query            # Interroga il Knowledge Graph
POST   /api/memories/kg/add              # Aggiungi entità o tripla al KG
GET    /api/memories/kg/stats            # Statistiche del Knowledge Graph
GET    /api/memories/kg/timeline/<entity> # Timeline di un'entità

Esempio: Lista Ricordi

curl http://localhost:5000/api/memories?room=error_patterns&limit=10

Esempio: Ricerca Semantica

curl -X POST http://localhost:5000/api/memories/search  -H "Content-Type: application/json"  -d '{
    "query": "database connection timeout",
    "limit": 5
 }'

Esempio: Query Knowledge Graph

curl http://localhost:5000/api/memories/kg/query?entity=FastAPI

Autenticazione

Gli endpoint protetti richiedono un header Authorization: Bearer <token> (JWT).

10. Esempi Pratici

Esempio 1: Primo Avvio

# Installa e configura
pip install codepalace
export OPENROUTER_API_KEY="sk-or-v1-..."

# Lancia nella directory del tuo progetto
cd my-project
codepalace

# Alla prima esecuzione, MemPalace crea ~/.mempalace/
# e inizializza le stanze vuote

Esempio 2: Esecuzione di un Task Singolo

# Crea un file con il task
echo "Aggiungi validazione input alla funzione process_data()" > task.txt

# Esegui
codepalace run --task-file task.txt -p ./my-project

# MemPalace consulta error_patterns e successful_strategies
# prima di iniziare, per evitare errori comuni

Esempio 3: Sessione Interattiva

# Avvia la modalità REPL
codepalace interactive -p ./my-project

# Le conversazioni vengono salvate nella stanza 'conversations'
# e sono disponibili nelle sessioni successive
# La memoria cresce ad ogni interazione

Esempio 4: Dashboard Web

# Avvia il server web per la memoria
codepalace webmempalace --port 5000

# Apri http://localhost:5000
# Esplora le stanze, cerca nei ricordi
# Controlla le statistiche della memoria

Esempio 5: Integrazione Programmatica

# Python API
from mempalace_interface import get_backend

backend = get_backend()
palace_path = backend.init_config()

# Salva un'esperienza
backend.store(
    palace_path=palace_path,
    room="error_patterns",
    key="json_parse_error",
    text="JSON parsing failed: always use try/except for json.loads()",
    metadata={"severity": "medium", "source": "codepalace"}
)

#Consulta la memoria
results = backend.query(
    palace_path=palace_path,
    room="error_patterns",
    query_text="json parsing"
)
print(results)

11. FAQ

Dove viene salvata la memoria?

La memoria è salvata in ~/.mempalace/. Ogni ala ha la sua directory con le stanze. I metadata 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 BackgroundConsolidator 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?

La memoria è efficiente: utilizza un backend Rust (mempalace-rs) con storage su disco SQLite. Il consumo tipico è di pochi MB per centinaia di ricordi. Il consolidamento automatico previene la crescita illimitata.

Posso cancellare la memoria?

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

mempalace-rs è obbligatorio?

No, CodePalace funziona anche senza mempalace-rs, ma con funzionalità di memoria ridotte (modalità fallback). Per prestazioni ottimali, si consiglia di installare mempalace-rs.

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.

Posso usare CodePalace senza memoria?

Sì, ma l'agente non potrà imparare dalle esperienze passate. La memoria è ciò che rende CodePalace autonomo e capace di migliorare nel tempo.