Configurazione

Kore Memory si configura interamente tramite variabili d'ambiente. Non servono file di configurazione. Tutte le impostazioni hanno valori predefiniti sensati che funzionano subito per lo sviluppo locale.

Variabili d'ambiente

Variabile	Predefinito	Descrizione
KORE_DB_PATH	data/memory.db	Percorso del file database SQLite
KORE_HOST	127.0.0.1	Indirizzo di binding del server
KORE_PORT	8765	Porta del server
KORE_LOCAL_ONLY	1	Salta l'autenticazione API key per richieste localhost
KORE_API_KEY	auto-generata	Imposta manualmente la API key (vedi Autenticazione)
KORE_CORS_ORIGINS	(vuoto)	Lista di origini CORS consentite, separate da virgola
KORE_EMBED_MODEL	paraphrase-multilingual-MiniLM-L12-v2	Nome del modello sentence-transformers
KORE_MAX_EMBED_CHARS	8000	Numero massimo di caratteri inviati al modello di embedding
KORE_SIMILARITY_THRESHOLD	0.88	Soglia di similarità coseno per la compressione
KORE_LOG_LEVEL	info	Livello di logging (debug, info, warning, error)

Percorso del database

Per impostazione predefinita, Kore crea il database in data/memory.db relativo alla directory di lavoro. Sovrascrivilo per deployment personalizzati:

# Usa un percorso assoluto
KORE_DB_PATH=/var/lib/kore/production.db kore

# Database separati per ambiente
KORE_DB_PATH=./data/staging.db kore

informazioni

La directory deve esistere. Kore creerà il file .db e il suo journal WAL automaticamente, ma non creerà le directory padre.

Binding di rete

Solo locale (predefinito)

KORE_HOST=127.0.0.1 KORE_PORT=8765 kore

Il server è accessibile solo dalla macchina locale. Questa è l'impostazione predefinita più sicura.

Esporre alla rete

KORE_HOST=0.0.0.0 KORE_PORT=8765 KORE_LOCAL_ONLY=0 kore

warning

Quando si fa il binding su 0.0.0.0, imposta sempre KORE_LOCAL_ONLY=0 e assicurati che KORE_API_KEY sia impostata o auto-generata. Senza autenticazione, qualsiasi macchina sulla tua rete può leggere e scrivere ricordi.

Porta personalizzata

KORE_PORT=9000 kore

Autenticazione

Modalità locale (predefinita)

Quando KORE_LOCAL_ONLY=1 (il valore predefinito), le richieste da 127.0.0.1 e ::1 saltano completamente la validazione della API key. Questo rende lo sviluppo locale privo di attrito.

Autenticazione con API key

Per l'accesso non-localhost, Kore richiede un header X-Kore-Key:

curl -H "X-Kore-Key: your-api-key" http://your-server:8765/search?q=test

La API key viene gestita in due modi:

1. Auto-generata -- Al primo avvio, Kore genera una chiave crittograficamente casuale e la salva in data/.api_key con permessi 600 (leggibile solo dal proprietario). La chiave viene stampata in console all'avvio.

2. Override manuale -- Imposta KORE_API_KEY per usare una chiave specifica:

KORE_API_KEY=my-secret-key-here kore

suggerimento

La chiave auto-generata è consigliata per la maggior parte dei deployment. È unica per directory del database e non viene mai trasmessa sulla rete.

Funzionalità di sicurezza

Kore implementa molteplici livelli di sicurezza:

• Confronto chiavi timing-safe -- Previene attacchi temporali sulla validazione della API key
• SQL parametrizzato -- Tutte le query usano parametri, prevenendo SQL injection
• Validazione Pydantic v2 -- Tutto l'input viene validato e sanificato prima dell'elaborazione
• Rate limiting per IP e per percorso -- Previene gli abusi
• Header di sicurezza -- X-Content-Type-Options, X-Frame-Options, CSP, Referrer-Policy
• Sanificazione FTS5 -- I caratteri speciali vengono rimossi e il conteggio dei token limitato
• Nonce CSP per richiesta -- Nessun unsafe-inline nella Content Security Policy

Configurazione CORS

Per impostazione predefinita, il CORS è ristretto (nessuna richiesta cross-origin consentita). Per consentire origini specifiche:

# Singola origine
KORE_CORS_ORIGINS="https://app.example.com" kore

# Origini multiple
KORE_CORS_ORIGINS="https://app.example.com,https://admin.example.com" kore

warning

Evita di impostare il CORS a * in produzione. Specifica sempre le origini esatte.

Modelli di embedding

Il modello predefinito paraphrase-multilingual-MiniLM-L12-v2 fornisce:

• Supporto per oltre 50 lingue
• Embedding a 384 dimensioni
• Download di circa 120 MB (memorizzato in cache dopo il primo utilizzo)
• Inferenza rapida su CPU

Cambiare modello

Puoi usare qualsiasi modello dalla libreria sentence-transformers:

# Modello più grande e più accurato
KORE_EMBED_MODEL=paraphrase-multilingual-mpnet-base-v2 kore

# Modello solo inglese, più leggero
KORE_EMBED_MODEL=all-MiniLM-L6-v2 kore

warning

Cambiare il modello di embedding dopo aver salvato dei ricordi renderà gli embedding esistenti incompatibili con quelli nuovi. La qualità della ricerca ne risentirà. Se cambi modello, ri-genera gli embedding di tutti i ricordi o ricomincia con un database nuovo.

Protezione OOM

La variabile KORE_MAX_EMBED_CHARS limita la lunghezza dell'input inviato al modello di embedding. Questo previene errori out-of-memory su macchine con RAM limitata:

# Predefinito: 8000 caratteri
KORE_MAX_EMBED_CHARS=8000

# Per ambienti con memoria limitata
KORE_MAX_EMBED_CHARS=4000

Il contenuto che eccede questo limite viene troncato prima dell'embedding. Il testo completo viene comunque salvato nel database.

Soglia di compressione

La variabile KORE_SIMILARITY_THRESHOLD controlla quanto aggressivamente il motore di compressione unisce i ricordi simili:

# Predefinito: 0.88 (conservativo)
KORE_SIMILARITY_THRESHOLD=0.88

# Compressione più aggressiva
KORE_SIMILARITY_THRESHOLD=0.80

# Molto conservativo (solo quasi-duplicati)
KORE_SIMILARITY_THRESHOLD=0.95

Soglia	Comportamento
0.80	Aggressivo -- unisce ricordi vagamente simili
0.88	Predefinito -- unisce ricordi chiaramente ridondanti
0.95	Conservativo -- unisce solo quasi-duplicati esatti

Isolamento dei namespace

Kore supporta deployment multi-agent tramite l'header X-Agent-Id. Ogni agente opera nel proprio namespace isolato:

# L'agente A salva un ricordo
curl -X POST http://localhost:8765/save \
  -H "X-Agent-Id: agent-a" \
  -d '{"content": "Secret project details"}'

# L'agente B non può vedere i ricordi dell'agente A
curl "http://localhost:8765/search?q=secret" \
  -H "X-Agent-Id: agent-b"
# Restituisce: risultati vuoti

Come funziona

• Ogni ricordo viene contrassegnato con l'ID dell'agente che lo ha creato
• Ricerca, timeline, tag e relazioni sono tutti circoscritti all'agente richiedente
• L'ID agente predefinito è "default" quando non viene fornito l'header
• Non esiste un'API cross-agent -- gli agenti sono rigorosamente isolati

Casi d'uso

Scenario	Configurazione
Singolo utente, singolo agente	Ometti X-Agent-Id (usa "default")
Singolo utente, agenti multipli	Ogni agente invia il proprio X-Agent-Id
Piattaforma multi-tenant	Ogni tenant è mappato a un ID agente unico
Pipeline CI/CD	Ogni esecuzione della pipeline usa un ID agente unico

Configurazioni di esempio

Sviluppo locale

kore
# Equivalente a:
# KORE_HOST=127.0.0.1 KORE_PORT=8765 KORE_LOCAL_ONLY=1 kore

Produzione (accesso LAN)

KORE_HOST=0.0.0.0 \
KORE_PORT=8765 \
KORE_LOCAL_ONLY=0 \
KORE_DB_PATH=/var/lib/kore/production.db \
KORE_CORS_ORIGINS="https://myapp.example.com" \
KORE_API_KEY=your-strong-random-key \
kore

Docker

docker run -d \
  -p 8765:8765 \
  -v kore-data:/data \
  -e KORE_HOST=0.0.0.0 \
  -e KORE_LOCAL_ONLY=0 \
  -e KORE_DB_PATH=/data/memory.db \
  ghcr.io/auriti-web-design/kore-memory:latest

Ambiente con memoria limitata

KORE_MAX_EMBED_CHARS=4000 \
KORE_EMBED_MODEL=all-MiniLM-L6-v2 \
kore