▍ Documentazione CodePalace

Guida completa all'agente di sviluppo software autonomo con memoria persistente.

1. Panoramica

CodePalace è un agente di sviluppo software autonomo con memoria persistente. Analizza il progetto, pianifica le azioni, scrive codice, esegue test e consolida le conoscenze acquisite — tutto in automatico.

Caratteristiche Principali

• Memoria Persistente — Sistema MemPalace con 10+ stanze tematiche per archiviare pattern, errori e soluzioni
• Apprendimento per Rinforzo — Reward function a 7 dimensioni che valuta ogni azione compiuta
• Dual-LLM — Un classificatore leggero per l'analisi, un modello potente per l'esecuzione
• Workflow a Fasi — analysis → planning → implementation → verification → consolidation
• Multi-Modalità — CLI, REPL interattivo, API REST, TUI terminale, TUI web
• MCP (Model Context Protocol) — Integrazione con server MCP per strumenti esterni

2. Installazione

Opzione A: Release Compilata (consigliata)

Installa il binario standalone — non richiede Python. Include il backend Rust (mempalace-rs) per prestazioni ottimali.

# Scarica ed installa automaticamente
bash install_release.sh

# Installa una versione specifica
bash install_release.sh --version 1.1.0

# Installa da archivio locale
bash install_release.sh --local

# Dopo l'installazione, ricarica la shell
source ~/.bashrc

# Verifica
codepalace version

Opzione B: Installazione Completa da Sorgente

Script completo che installa tutte le dipendenze (Python, Rust, ONNX Runtime) e compila mempalace-rs.

# Clona il repository
git clone <repo-url> codepalace
cd codepalace

# Installazione completa (Python + Rust + dipendenze)
bash install_all.sh

# Installazione senza backend Rust
SKIP_RUST=1 bash install_all.sh

# Dopo l'installazione
source ~/.bashrc
codepalace version

Opzione C: pip (sviluppatori)

# Installa da sorgente in modalità sviluppo
pip install -e .

# Oppure con dipendenze web (MemPalace web dashboard)
pip install -e ".[web]"

# Oppure con dipendenze di sviluppo
pip install -e ".[dev]"

Opzione D: Docker

# Build dell'immagine
docker build -t codepalace .

# Esegui un singolo task
docker run -it --rm \
  -e OPENROUTER_API_KEY=your-key \
  -v $(pwd)/projects:/app/projects \
  codepalace run "Crea una classe Calculator"

# Oppure con docker-compose
cp .env.example .env  # Configura le API key
docker compose up -d

Backend MemPalace (mempalace-rs)

Il backend Rust offre prestazioni fino a 10x superiori rispetto al backend Python. L'installazione compilata lo include automaticamente.

# Installa solo mempalace-rs (se hai già CodePalace)
bash install_mempalace_rs.sh

# Cambia backend in qualsiasi momento
export MEMPALACE_BACKEND=rust    # Veloce (default se disponibile)
export MEMPALACE_BACKEND=python  # Compatibile (fallback)

3. Configurazione Rapida

API Key

Almeno una chiave API è necessaria per funzionare. Imposta la variabile d'ambiente:

# OpenRouter (consigliata — accesso a tutti i modelli)
export OPENROUTER_API_KEY=sk-or-v1-...

# Oppure OpenAI diretto
export OPENAI_API_KEY=sk-...

Oppure usa il flag --api-key:

# Release compilata
codepalace run -t "Task" --api-key sk-or-v1-...

# Da sorgente
python3.11 codepalace.py run -t "Task" --api-key sk-or-v1-...

Primo Task

# Esegui il tuo primo task (release compilata)
codepalace run -t "Crea un file hello.py che stampa Hello World"

# Da sorgente
python3.11 codepalace.py run -t "Crea un file hello.py che stampa Hello World"

# Specifica la directory del progetto
codepalace run -t "Aggiungi test per Calculator" -p ./myproject

# Modalità interattiva
codepalace interactive -p ./myproject

4. Comandi

Comando	Descrizione
run	Esegue un singolo task e termina
interactive	Modalità interattiva REPL con controllo step-by-step
serve	Avvia il server API REST (HTTP POST /run)
tui	Interfaccia terminale (TUI) con Textual
webmempalace	Avvia il web server MemPalace (Flask dashboard)
self-update	Controlla e installa aggiornamenti
version	Mostra la versione corrente
help	Guida dettagliata di tutti i parametri

run — Esecuzione Singolo Task

Esegue un task specificato con --task o --task-file e termina automaticamente.

codepalace run -t "Crea una classe Calculator con add, subtract"
codepalace run --task-file task.txt -p ./myproject
codepalace run -t "Fix bug" -m anthropic/claude-3.5-sonnet --thinking high

interactive — Modalità Interattiva

REPL interattivo con comandi dedicati per esplorare il progetto, gestire la memoria e controllare il flusso.

codepalace interactive -p ./myproject

# Comandi disponibili nel REPL:
# task <desc>      Esegui un task
# chat <msg>       Chat rapida
# dir/read/tree    Esplora progetto
# git/diff/log     Operazioni git
# memory <query>  Cerca in memoria
# recall [room]    Richiama ricordi
# status/config    Info sessione
# phase [name]     Cambia fase
# auto             Toggle auto-approve
# obs              Toggle osservazioni
# help             Mostra comandi
# exit/quit/q      Esci

serve — Server API REST

Avvia un server HTTP che espone l'endpoint POST /run per eseguire task via API.

codepalace serve --host 0.0.0.0 --port 8080

# Esempio di richiesta
curl -X POST http://localhost:8080/run \
  -H "Content-Type: application/json" \
  -d '{"task": "Crea un modulo auth", "project": "./myproject", "max_steps": 50}'

# Risposta:
# {"status": "success", "steps": 12, "total_reward": 0.85, "trajectory_summary": "..."}

tui — Interfaccia Terminale

Interfaccia utente ricca nel terminale basata su Textual. Supporta anche la modalità web via browser.

# TUI nel terminale
codepalace tui -p ./myproject

# TUI nel browser (richiede textual-serve)
codepalace tui --web --host 0.0.0.0 --port 8000

# Con modello specifico
codepalace tui -m openai/gpt-4o --thinking medium

webmempalace — Dashboard MemPalace

Avvia l'interfaccia web per esplorare e gestire la memoria MemPalace.

# Richiede: pip install codepalace[web]
codepalace webmempalace
codepalace webmempalace --port 8080 --debug

5. Opzioni CLI

6. Modelli LLM

CodePalace utilizza OpenRouter come provider predefinito, con accesso a modelli di diversi provider. La configurazione Dual-LLM usa un modello principale per l'esecuzione e un modello di classificazione per l'analisi.

Modelli Principali

Modello	Caratteristiche
openai/gpt-4o	Bilanciato, alta qualità — consigliato per task complessi
openai/gpt-4o-mini	Economico, buono per task semplici
anthropic/claude-3.5-sonnet	Alta qualità, buon ragionamento
anthropic/claude-3-haiku	Economico, veloce
google/gemini-2.5-pro	Contesto ampio, buona qualità
z-ai/glm-5.1	Default, buon compromesso qualità/prezzo

Modelli di Classificazione

Usati con --classification-model per l'analisi e la classificazione dei task. Possono essere più economici del modello principale.

Modello	Note
openai/gpt-oss-120b	Default per analisi
openai/gpt-4o-mini	Alternativa economica

Esempi

# Modello principale con ragionamento esteso
codepalace run -t "Refactor architecture" -m anthropic/claude-3.5-sonnet --thinking high

# Modello principale + modello classificazione
codepalace run -t "Fix bug" -m openai/gpt-4o --classification-model openai/gpt-4o-mini

# Usare OpenAI diretto (senza OpenRouter)
codepalace run -t "Task" --base-url https://api.openai.com/v1 --api-key sk-...

7. Sistema di Memoria (MemPalace)

Il sistema MemPalace organizza la conoscenza in stanze tematiche. Ogni azione viene registrata e le lezioni apprese vengono consultate prima di ogni nuovo task per evitare errori passati.

Stanze Disponibili

Stanza	Contenuto
error_patterns	Pattern di errore e soluzioni trovate
successful_strategies	Strategie che hanno funzionato con successo
code_templates	Template di codice riutilizzabili
task_history	Cronologia dei task completati
reward_signals	Segnali di reward per l'apprendimento RL
debugging_patterns	Pattern di debug e risoluzione problemi
project_schemas	Struttura e organizzazione dei progetti
dependency_maps	Mappa delle dipendenze tra componenti
style_guides	Convenzioni di stile e formattazione
test_strategies	Strategie di testing efficaci

Operazioni nella REPL Interattiva

# Cerca nella memoria
memory Come gestire errori di connessione

# Richiama una stanza specifica
recall error_patterns

# Il Lesson Consultant consulta automaticamente la memoria
# prima di ogni task per evitare errori passati

Backend Rust vs Python

MemPalace supporta due backend: mempalace-rs (Rust, consigliato) e mempalace (Python, fallback). Il backend Rust offre prestazioni fino a 10x superiori.

Caratteristica	mempalace-rs (Rust)	mempalace (Python)
Prestazioni	Fino a 10x più veloce	Standard
Dipendenze	Nessuna (binario standalone)	chromadb, numpy, ecc.
Installazione	Incluso nella release compilata	pip install mempalace
Fallback	→ Python se non disponibile	Usato se Rust non disponibile

# Cambia backend via variabile d'ambiente
export MEMPALACE_BACKEND=rust    # Usa Rust (veloce)
export MEMPALACE_BACKEND=python  # Usa Python (compatibile)

# Oppure imposta in models.json
# "mempalace_backend": "rust"

# Installa mempalace-rs separatamente
bash install_mempalace_rs.sh

8. Docker

Avvio Rapido con docker-compose

# Configura le variabili d'ambiente
cp .env.example .env
# Modifica .env con le tue API key

# Avvia tutti i servizi
docker compose up -d

# Solo agent API
docker compose up agent

# Solo TUI web
docker compose up web

Comandi Docker

Comando	Descrizione
serve	Server API su 0.0.0.0:8080 (default)
run "task"	Esegue un singolo task
interactive	Modalità interattiva (richiede -it)
tui	TUI nel terminale
web	TUI via browser su 0.0.0.0:8000
website	Avvia il sito PHP su porta 80
shell	Shell interattiva per debug
version	Mostra la versione

Esempi Docker

# Esegui un singolo task
docker compose run --rm agent run "Crea una classe Calculator"

# Esegui con modello specifico
docker run -it --rm \
  -e OPENROUTER_API_KEY=sk-or-v1-... \
  -v $(pwd)/projects:/app/projects \
  codepalace run "Fix bug in parser" -m openai/gpt-4o

# Modalità interattiva
docker run -it --rm \
  -e OPENROUTER_API_KEY=sk-or-v1-... \
  -v $(pwd)/projects:/app/projects \
  codepalace interactive

# Shell per debug
docker compose run --rm agent shell

Variabili d'Ambiente Docker

Variabile	Descrizione	Default
OPENROUTER_API_KEY	Chiave API OpenRouter	—
OPENAI_API_KEY	Chiave API OpenAI (fallback)	—
GITHUB_PERSONAL_ACCESS_TOKEN	Token GitHub per MCP	—
BRAVE_API_KEY	Chiave API Brave Search	—
AGENT_PORT	Porta server API	8080
WEB_PORT	Porta TUI web	8000
PROJECTS_DIR	Directory progetti	/app/projects
MEMPALACE_DIR	Directory memoria MemPalace	/app/data/mempalace
MEMPALACE_BACKEND	Backend MemPalace: rust/python	rust (se disponibile)

9. File di Configurazione

models.json

Configurazione persistente di modello, temperatura, lingua e altri parametri. Si trova nella directory del progetto o in ~/.codepalace/.

{
  "model": "anthropic/claude-3.5-sonnet",
  "classification_model": "openai/gpt-4o-mini",
  "base_url": "https://openrouter.ai/api/v1",
  "temperature": 0,
  "thinking": "high",
  "language": "it",
  "context_max_tokens": 32000,
 "mempalace_backend": "rust"
}

Directory di Configurazione

CodePalace utilizza due directory distinte per separare configurazione e dati:

Directory	Contenuto
~/.codepalace/	Configurazione utente: models.json, user_config.json
~/.mempalace/	Dati MemPalace: memoria, Knowledge Graph, logs
~/.local/bin/	Binario codepalace (installazione compilata)
~/.local/share/codepalace/	Applicazione completa (installazione compilata)

Variabili d'Ambiente

Variabile	Descrizione
OPENROUTER_API_KEY	Chiave API OpenRouter (priorità alta)
OPENAI_API_KEY	Chiave API OpenAI (fallback)
CODEPALACE_DOCKER	Se impostata, configura per Docker
PROJECTS_DIR	Directory progetti (default: ./projects)
AGENT_PORT	Porta server API (per Docker)
WEB_PORT	Porta TUI web (per Docker)
MEMPALACE_BACKEND	Backend MemPalace: rust (veloce) o python (compatibile)
MEMPALACE_DIR	Directory dati MemPalace (default: ~/.mempalace)
LD_LIBRARY_PATH	Percorsi librerie aggiuntive (SQLite, ONNX Runtime)

10. Esempi d'Uso

Esecuzione Base

# Esegui un singolo task
codepalace run -t "Crea una classe Calculator con add, subtract"

# Task da file
codepalace run --task-file task.txt -p ./myproject

# Specifica progetto e modello
codepalace run -t "Fix bug in parser" \
  -p ./myproject \
  -m anthropic/claude-3.5-sonnet

Ragionamento Avanzato

# Ragionamento esteso (migliore per task complessi)
codepalace run -t "Refactor the auth module" \
  --thinking high

# Ragionamento bilanciato
codepalace run -t "Add input validation" \
  --thinking medium

# Senza ragionamento extra (più veloce, più economico)
codepalace run -t "Add a comment" \
  --thinking normal

Modalità Sicura

# Read-only: l'agente può solo leggere, non scrivere
codepalace interactive -p ./myproject --read-only

# Sandbox: comandi shell ristretti
codepalace run -t "Analyze code" --sandbox

# Disabilita git auto-commit
codepalace run -t "Fix bug" --no-git

Ottimizzazione Contesto

# Disabilita features per risparmiare token
codepalace run -t "Quick fix" \
  --no-dedup \
  --no-compression \
  --no-prompt-caching

# Limita step massimi
codepalace run -t "Simple task" --max-steps 10

# Context window più ampia per progetti grandi
codepalace run -t "Refactor" --context-max-tokens 128000

Server API

# Avvia il server
codepalace serve --host 0.0.0.0 --port 8080

# Invia un task via curl
curl -X POST http://localhost:8080/run \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Crea un modulo di autenticazione",
    "project": "./projects/myapp",
    "max_steps": 50
  }'

Debug

# Log completo (prompt e risposte LLM)
codepalace run -t "Debug this" --debug-logging

# Temperatura alta per soluzioni creative
codepalace run -t "Design a new architecture" --temperature 0.7

11. FAQ

Quali API key servono?

Almeno una tra OPENROUTER_API_KEY e OPENAI_API_KEY. OpenRouter è consigliato perché dà accesso a tutti i modelli con una sola chiave.

CodePalace è gratuito?

CodePalace è open-source e gratuito. I costi dipendono dall'uso dell'API LLM: i modelli più economici (gpt-4o-mini, claude-3-haiku) costano frazioni di centesimi per task.

Come funziona la memoria?

La memoria è organizzata in stanze tematiche (error_patterns, successful_strategies, etc.). Il Lesson Consultant consulta automaticamente le lezioni apprese prima di ogni task per evitare di ripetere errori passati. La memoria è persistente tra sessioni.

Posso usare un modello locale?

Sì, usa --base-url per puntare a un server LLM locale (es. LM Studio, Ollama):

codepalace run -t "Task" \
  --base-url http://localhost:1234/v1 \
  --model local-model-name

Come ridurre i costi?

• Usa --classification-model con un modello economico per l'analisi
• Usa --thinking normal per task semplici (nessun ragionamento extra)
• Usa modelli mini (gpt-4o-mini, claude-3-haiku) per task banali
• Limita --max-steps per evitare loop infiniti

Quali linguaggi e framework supporta?

CodePalace rileva automaticamente il linguaggio e il framework del progetto e adatta il comportamento di conseguenza. Supporta Python, JavaScript/TypeScript, PHP, Go, Rust, e molti altri.

È sicuro?

CodePalace supporta due modalità di sicurezza:

• --read-only — L'agente può solo leggere, non scrivere file
• --sandbox — L'agente può eseguire solo comandi shell approvati

In modalità interattiva, puoi approvare ogni azione prima dell'esecuzione.

← Torna alla Homepage