Guida all'uso

Questa guida copre tutte le operazioni principali di Kore Memory: salvataggio dei ricordi, ricerca, gestione di tag e relazioni, operazioni batch, query timeline e esportazione/importazione dei dati.

Avvio del server

# Predefinito: localhost:8765
kore

# Porta personalizzata
KORE_PORT=9000 kore

# Con logging dettagliato
KORE_LOG_LEVEL=debug kore

La dashboard web è immediatamente disponibile su http://localhost:8765/dashboard.

Salvataggio dei ricordi

Salvataggio base

Salva un ricordo con punteggio di importanza automatico:

from kore_memory import KoreClient

with KoreClient("http://localhost:8765", agent_id="my-agent") as kore:
    result = kore.save("User prefers dark mode for all interfaces")
    print(result.id, result.importance)  # es. 42, 3

Tramite curl:

curl -X POST http://localhost:8765/save \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-agent" \
  -d '{"content": "User prefers dark mode for all interfaces"}'

Con categoria e importanza

Sovrascrivere il punteggio automatico specificando l'importanza esplicitamente:

kore.save(
    "Never deploy on Fridays - production incident in Q3",
    category="decision",
    importance=5
)

curl -X POST http://localhost:8765/save \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-agent" \
  -d '{
    "content": "Never deploy on Fridays - production incident in Q3",
    "category": "decision",
    "importance": 5
  }'

suggerimento

Imposta importance a 1 (o omettilo) per lasciare che Kore calcoli il punteggio automaticamente. I valori 2--5 sono trattati come override espliciti. I ricordi critici (importanza 5) hanno un'emivita di decay di 365 giorni.

Con TTL (scadenza automatica)

I ricordi possono scadere automaticamente dopo un numero di ore impostato:

kore.save(
    "Deploy scheduled for Friday at 14:00 UTC",
    category="task",
    ttl_hours=48
)

Dopo 48 ore, questo ricordo viene automaticamente rimosso durante il ciclo di pulizia successivo.

informazioni

L'intervallo TTL va da 1 a 8760 ore (da 1 ora a 1 anno). Imposta ttl_hours a null o omettilo per ricordi che non scadono mai.

Ricerca dei ricordi

Ricerca full-text (FTS5)

Sempre disponibile, anche senza l'extra semantic:

results = kore.search("dark mode", limit=5)
for memory in results:
    print(f"[{memory.decay_score:.2f}] {memory.content}")

curl "http://localhost:8765/search?q=dark+mode&limit=5" \
  -H "X-Agent-Id: my-agent"

Ricerca semantica

Richiede l'extra semantic. Trova ricordi concettualmente simili attraverso le lingue:

# Troverà "User prefers dark mode" anche con formulazioni diverse
results = kore.search("interface color preferences", limit=5, semantic=True)

curl "http://localhost:8765/search?q=interface+color+preferences&limit=5&semantic=true" \
  -H "X-Agent-Id: my-agent"

informazioni

La ricerca semantica utilizza la similarità coseno tra gli embedding. I risultati sono ordinati per punteggio effettivo: similarity * decay * importance. Questo significa che i ricordi recenti, importanti e rilevanti si posizionano sempre in cima.

Filtraggio per categoria

curl "http://localhost:8765/search?q=deploy&category=decision&limit=10" \
  -H "X-Agent-Id: my-agent"

Paginazione

curl "http://localhost:8765/search?q=project&limit=10&offset=20" \
  -H "X-Agent-Id: my-agent"

API Timeline

Recupera la cronologia di un argomento:

timeline = kore.timeline(subject="project alpha")
for entry in timeline:
    print(f"{entry.created_at}: {entry.content}")

curl "http://localhost:8765/timeline?subject=project+alpha" \
  -H "X-Agent-Id: my-agent"

L'API Timeline restituisce i ricordi ordinati per data di creazione, offrendo una visione narrativa di come la conoscenza su un argomento si è evoluta nel tempo.

Tag

I tag permettono di organizzare e incrociare i ricordi oltre le categorie.

Aggiungere tag

kore.add_tags(memory_id=42, tags=["ui", "preference", "dark-theme"])

curl -X POST http://localhost:8765/memories/42/tags \
  -H "Content-Type: application/json" \
  -d '{"tags": ["ui", "preference", "dark-theme"]}'

Elencare i tag di un ricordo

tags = kore.get_tags(memory_id=42)
print(tags)  # ["ui", "preference", "dark-theme"]

curl http://localhost:8765/memories/42/tags

Cercare per tag

Trova tutti i ricordi con un tag specifico:

results = kore.search_by_tag("dark-theme")

curl "http://localhost:8765/tags/dark-theme/memories" \
  -H "X-Agent-Id: my-agent"

Rimuovere tag

curl -X DELETE http://localhost:8765/memories/42/tags \
  -H "Content-Type: application/json" \
  -d '{"tags": ["dark-theme"]}'

Relazioni

Le relazioni creano collegamenti bidirezionali tra i ricordi, formando un grafo della conoscenza.

Creare una relazione

kore.add_relation(source_id=42, target_id=58, relation="depends_on")

curl -X POST http://localhost:8765/memories/42/relations \
  -H "Content-Type: application/json" \
  -d '{"target_id": 58, "relation": "depends_on"}'

Elencare le relazioni

relations = kore.get_relations(memory_id=42)
for rel in relations:
    print(f"{rel.relation}: memory #{rel.target_id}")

curl http://localhost:8765/memories/42/relations

Le relazioni sono bidirezionali -- interrogando da entrambi i lati si ottiene la connessione.

Operazioni batch

Salva fino a 100 ricordi in una singola richiesta:

memories = [
    {"content": "React 19 supports server components", "category": "project"},
    {"content": "Always use parameterized queries", "category": "decision", "importance": 5},
    {"content": "Team standup at 09:30 CET", "category": "task", "ttl_hours": 168},
]
results = kore.save_batch(memories)
print(f"Salvati {len(results)} ricordi")

curl -X POST http://localhost:8765/save/batch \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-agent" \
  -d '{"memories": [
    {"content": "React 19 supports server components", "category": "project"},
    {"content": "Always use parameterized queries", "category": "decision", "importance": 5}
  ]}'

suggerimento

I salvataggi batch sono significativamente più veloci dei salvataggi singoli perché condividono un'unica transazione di database e un batch di embedding.

Aggiornamento dei ricordi

Aggiorna il contenuto, la categoria o l'importanza di un ricordo esistente:

kore.update(memory_id=42, content="User prefers dark mode (confirmed)", importance=4)

curl -X PUT http://localhost:8765/memories/42 \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers dark mode (confirmed)", "importance": 4}'

Eliminazione dei ricordi

Eliminazione definitiva

kore.delete(memory_id=42)

curl -X DELETE http://localhost:8765/memories/42

Eliminazione temporanea (Archivio)

L'archiviazione preserva il ricordo ma lo nasconde dai risultati di ricerca:

curl -X POST http://localhost:8765/memories/42/archive

Ripristinare un ricordo archiviato:

curl -X POST http://localhost:8765/memories/42/restore

Elencare tutti i ricordi archiviati:

curl http://localhost:8765/archive

Esportazione e importazione

Esportare tutti i ricordi

backup = kore.export_memories()
# Restituisce JSON con tutti i ricordi attivi

curl http://localhost:8765/export > backup.json

Importare da backup

kore.import_memories(backup)

curl -X POST http://localhost:8765/import \
  -H "Content-Type: application/json" \
  -d @backup.json

warning

L'importazione non sovrascrive i ricordi esistenti. Contenuti duplicati possono generare voci simili. Esegui la compressione dopo l'importazione per unire i quasi-duplicati.

Operazioni di manutenzione

Eseguire il passaggio di decay

Ricalcola i punteggi di decay per tutti i ricordi e rimuove quelli completamente decaduti:

kore.decay_run()

curl -X POST http://localhost:8765/decay/run

Comprimere i ricordi simili

Unisce i ricordi con similarità coseno superiore a 0.88 (configurabile tramite KORE_SIMILARITY_THRESHOLD):

kore.compress()

curl -X POST http://localhost:8765/compress

Pulizia dei ricordi scaduti

Rimuovi i ricordi che hanno superato il loro TTL:

curl -X POST http://localhost:8765/cleanup

suggerimento

Esegui la manutenzione periodicamente -- ad esempio tramite un cron job o il tool MCP memory_decay_run. La dashboard web dispone anche di pulsanti one-click per tutte le operazioni di manutenzione.

Utilizzo asincrono in Python

Per applicazioni asincrone (FastAPI, aiohttp, ecc.):

from kore_memory import AsyncKoreClient

async with AsyncKoreClient("http://localhost:8765", agent_id="my-agent") as kore:
    result = await kore.save("Async memory example")
    results = await kore.search("async", limit=5)
    await kore.add_tags(result.id, ["async", "example"])
    await kore.decay_run()

Gestione degli errori

Il Python SDK lancia eccezioni tipizzate:

from kore_memory import KoreClient, KoreValidationError, KoreNotFoundError

with KoreClient("http://localhost:8765") as kore:
    try:
        kore.save("")  # Troppo corto
    except KoreValidationError as e:
        print(f"Validazione fallita: {e}")

    try:
        kore.delete(99999)
    except KoreNotFoundError:
        print("Ricordo non trovato")

Gerarchia delle eccezioni:

Eccezione	Codice HTTP	Quando
KoreValidationError	422	Input non valido (troppo corto, categoria errata, ecc.)
KoreNotFoundError	404	L'ID del ricordo non esiste
KoreAuthError	401 / 403	API key non valida o mancante
KoreRateLimitError	429	Troppe richieste
KoreServerError	500	Errore interno del server

Tutte le eccezioni ereditano da KoreError.