Riferimento API

Kore Memory espone un'API REST su http://localhost:8765 per impostazione predefinita. Tutti gli endpoint accettano e restituiscono JSON. La documentazione interattiva dell'API è disponibile su /docs.

Header	Obbligatorio	Descrizione
`Content-Type`	Sì (POST/PUT)	Deve essere `application/json`
`X-Agent-Id`	Opzionale	Identificatore del namespace dell'agente. Predefinito: `"default"`.
`X-Kore-Key`	Condizionale	API key. Obbligatoria per richieste non-localhost quando `KORE_LOCAL_ONLY=0`.

Endpoint principali

Salvare un ricordo

POST /save

Salva un singolo ricordo con punteggio di importanza automatico opzionale.

Corpo della richiesta:

Campo	Tipo	Obbligatorio	Descrizione
`content`	string	Sì	Testo del ricordo, 3--4000 caratteri
`category`	string	No	Uno tra: `general`, `project`, `trading`, `finance`, `person`, `preference`, `task`, `decision`. Predefinito: `general`
`importance`	integer	No	`1` = punteggio automatico, `2`--`5` = esplicito. Predefinito: `1`
`ttl_hours`	integer o null	No	Scadenza automatica dopo N ore (1--8760). Predefinito: `null` (mai)

Esempio:

curl -X POST http://localhost:8765/save \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-agent" \
  -d '{
    "content": "User prefers concise responses in Italian",
    "category": "preference",
    "importance": 4
  }'

Risposta (201):

{
  "id": 42,
  "content": "User prefers concise responses in Italian",
  "category": "preference",
  "importance": 4,
  "decay_score": 1.0,
  "created_at": "2025-01-15T10:30:00Z"
}

Salvataggio batch

POST /save/batch

Salva fino a 100 ricordi in una singola richiesta.

Corpo della richiesta:

Campo	Tipo	Obbligatorio	Descrizione
`memories`	array	Sì	Array di oggetti memory (stesso schema del salvataggio singolo)

Esempio:

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}
    ]
  }'

Risposta (201):

{
  "saved": 2,
  "memories": [
    {"id": 43, "importance": 3, "decay_score": 1.0},
    {"id": 44, "importance": 5, "decay_score": 1.0}
  ]
}

Cercare i ricordi

GET /search

Cerca i ricordi usando la ricerca full-text FTS5 o la similarità semantica.

Parametri di query:

Parametro	Tipo	Predefinito	Descrizione
`q`	string	(obbligatorio)	Query di ricerca
`limit`	integer	10	Risultati massimi (1--100)
`offset`	integer	0	Offset per la paginazione
`category`	string	(tutti)	Filtra per categoria
`semantic`	boolean	false	Usa la ricerca semantica invece di FTS5

Esempio:

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

Risposta (200):

{
  "results": [
    {
      "id": 42,
      "content": "User prefers concise responses in Italian",
      "category": "preference",
      "importance": 4,
      "decay_score": 0.92,
      "effective_score": 0.87,
      "created_at": "2025-01-15T10:30:00Z",
      "tags": ["language", "preference"]
    }
  ],
  "total": 1,
  "limit": 5,
  "offset": 0
}

informazioni

I risultati sono ordinati per effective_score = similarity * decay * importance. Questo garantisce che i ricordi rilevanti, recenti e importanti appaiano sempre per primi.

Timeline

GET /timeline

Recupera la cronologia di un argomento.

Parametri di query:

Parametro	Tipo	Predefinito	Descrizione
`subject`	string	(obbligatorio)	Argomento da interrogare
`limit`	integer	20	Risultati massimi
`offset`	integer	0	Offset per la paginazione

Esempio:

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

Risposta (200):

{
  "results": [
    {
      "id": 10,
      "content": "Project alpha kickoff meeting scheduled",
      "category": "task",
      "importance": 3,
      "decay_score": 0.85,
      "created_at": "2025-01-10T09:00:00Z"
    },
    {
      "id": 25,
      "content": "Project alpha: decided on React + FastAPI stack",
      "category": "decision",
      "importance": 5,
      "created_at": "2025-01-12T14:00:00Z"
    }
  ],
  "total": 2
}

Aggiornare un ricordo

PUT /memories/{id}

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

Parametri del percorso:

Parametro	Tipo	Descrizione
`id`	integer	ID del ricordo

Corpo della richiesta (tutti i campi opzionali):

Campo	Tipo	Descrizione
`content`	string	Nuovo contenuto (3--4000 caratteri)
`category`	string	Nuova categoria
`importance`	integer	Nuova importanza (1--5)

Esempio:

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

Risposta (200):

{
  "id": 42,
  "content": "User prefers dark mode (confirmed)",
  "importance": 5,
  "updated_at": "2025-01-16T08:00:00Z"
}

Eliminare un ricordo

DELETE /memories/{id}

Elimina definitivamente un ricordo.

Esempio:

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

Risposta (200):

{"deleted": true, "id": 42}

Endpoint dei tag

Aggiungere tag

POST /memories/{id}/tags

Corpo della richiesta:

{"tags": ["react", "frontend", "v19"]}

Risposta (200):

{"id": 42, "tags": ["react", "frontend", "v19"]}

Elencare i tag

GET /memories/{id}/tags

Risposta (200):

{"id": 42, "tags": ["react", "frontend", "v19"]}

Rimuovere tag

DELETE /memories/{id}/tags

Corpo della richiesta:

{"tags": ["v19"]}

Risposta (200):

{"id": 42, "tags": ["react", "frontend"]}

Cercare per tag

GET /tags/{tag}/memories

Esempio:

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

Risposta (200):

{
  "tag": "react",
  "results": [
    {
      "id": 42,
      "content": "React 19 supports server components",
      "category": "project",
      "importance": 3,
      "decay_score": 0.95
    }
  ],
  "total": 1
}

Endpoint delle relazioni

Creare una relazione

POST /memories/{id}/relations

Crea un collegamento bidirezionale tra due ricordi.

Corpo della richiesta:

Campo	Tipo	Obbligatorio	Descrizione
`target_id`	integer	Sì	ID del ricordo di destinazione
`relation`	string	Sì	Tipo di relazione (es. `depends_on`, `related_to`, `contradicts`, `supersedes`)

Esempio:

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

Risposta (201):

{
  "source_id": 42,
  "target_id": 58,
  "relation": "depends_on",
  "created_at": "2025-01-16T09:00:00Z"
}

Elencare le relazioni

GET /memories/{id}/relations

Restituisce tutte le relazioni bidirezionali di un ricordo.

Risposta (200):

{
  "id": 42,
  "relations": [
    {"target_id": 58, "relation": "depends_on", "created_at": "2025-01-16T09:00:00Z"},
    {"target_id": 12, "relation": "related_to", "created_at": "2025-01-15T11:00:00Z"}
  ]
}

Endpoint di manutenzione

Eseguire il passaggio di decay

POST /decay/run

Ricalcola i punteggi di decay per tutti i ricordi utilizzando la formula di Ebbinghaus. Rimuove i ricordi completamente decaduti.

Risposta (200):

{
  "processed": 150,
  "decayed": 12,
  "removed": 3
}

Comprimere i ricordi

POST /compress

Unisce i ricordi con similarità coseno superiore alla soglia configurata (predefinita: 0.88).

Risposta (200):

{
  "compressed": 5,
  "merged_pairs": [
    {"kept": 42, "merged": 43},
    {"kept": 55, "merged": 56}
  ]
}

informazioni

La compressione richiede l'extra semantic. Mantiene il ricordo con importanza maggiore e unisce il contenuto di quello con importanza minore.

Pulizia dei ricordi scaduti

POST /cleanup

Rimuove i ricordi che hanno superato il loro TTL.

Risposta (200):

{"removed": 7}

Metriche Prometheus

GET /metrics

Restituisce metriche in formato Prometheus per il monitoraggio.

Risposta (200):

# HELP kore_memories_total Total number of active memories
# TYPE kore_memories_total gauge
kore_memories_total 150
# HELP kore_searches_total Total search requests
# TYPE kore_searches_total counter
kore_searches_total 1234

Endpoint di archivio e backup

Archiviare un ricordo

POST /memories/{id}/archive

Eliminazione temporanea di un ricordo. Viene nascosto dalla ricerca ma può essere ripristinato.

Risposta (200):

{"id": 42, "archived": true}

Ripristinare un ricordo

POST /memories/{id}/restore

Ripristina un ricordo precedentemente archiviato.

Risposta (200):

{"id": 42, "restored": true}

Elencare i ricordi archiviati

GET /archive

Risposta (200):

{
  "results": [
    {"id": 42, "content": "...", "archived_at": "2025-01-16T10:00:00Z"}
  ],
  "total": 1
}

Esportare i ricordi

GET /export

Esporta tutti i ricordi attivi come array JSON.

Risposta (200):

{
  "memories": [
    {
      "id": 42,
      "content": "User prefers dark mode",
      "category": "preference",
      "importance": 4,
      "decay_score": 0.92,
      "tags": ["ui"],
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "exported_at": "2025-01-16T12:00:00Z",
  "total": 1
}

Importare i ricordi

POST /import

Importa i ricordi da un'esportazione precedente.

Corpo della richiesta: L'oggetto JSON restituito da /export.

Risposta (200):

{"imported": 42}

Endpoint di utilità

Verifica dello stato

GET /health

Risposta (200):

{
  "status": "healthy",
  "version": "1.0.0",
  "capabilities": {
    "semantic_search": true,
    "fts5": true,
    "mcp": true
  }
}

Dashboard web

GET /dashboard

Restituisce la dashboard web integrata. Nessun passaggio di build o npm necessario. Include schede per panoramica, ricordi, tag, relazioni, timeline, manutenzione e backup.

Documentazione API interattiva

GET /docs

Restituisce la documentazione interattiva Swagger/OpenAPI.

Codici di stato

Codice	Significato
200	Successo
201	Creato (salvataggio, salvataggio batch, creazione relazione)
400	Richiesta non valida (JSON malformato, campi obbligatori mancanti)
401	Non autorizzato (API key mancante)
403	Vietato (API key non valida)
404	Non trovato (l'ID del ricordo non esiste)
422	Errore di validazione (contenuto troppo corto, categoria non valida, ecc.)
429	Limite di richieste superato
500	Errore interno del server

Limiti di frequenza

Kore applica rate limiting per IP e per percorso. I limiti predefiniti sono generosi per deployment a singolo utente. Quando si supera il limite, la risposta include:

Retry-After: 5
X-RateLimit-Remaining: 0

Header​

Endpoint principali​

Salvare un ricordo​

Salvataggio batch​

Cercare i ricordi​

Timeline​

Aggiornare un ricordo​

Eliminare un ricordo​

Endpoint dei tag​

Aggiungere tag​

Elencare i tag​

Rimuovere tag​

Cercare per tag​

Endpoint delle relazioni​

Creare una relazione​

Elencare le relazioni​

Endpoint di manutenzione​

Eseguire il passaggio di decay​

Comprimere i ricordi​

Pulizia dei ricordi scaduti​

Metriche Prometheus​

Endpoint di archivio e backup​

Archiviare un ricordo​

Ripristinare un ricordo​

Elencare i ricordi archiviati​

Esportare i ricordi​

Importare i ricordi​

Endpoint di utilità​

Verifica dello stato​

Dashboard web​

Documentazione API interattiva​

Codici di stato​

Limiti di frequenza​

Header

Endpoint principali

Salvare un ricordo

Salvataggio batch

Cercare i ricordi

Timeline

Aggiornare un ricordo

Eliminare un ricordo

Endpoint dei tag

Aggiungere tag

Elencare i tag

Rimuovere tag

Cercare per tag

Endpoint delle relazioni

Creare una relazione

Elencare le relazioni

Endpoint di manutenzione

Eseguire il passaggio di decay

Comprimere i ricordi

Pulizia dei ricordi scaduti

Metriche Prometheus

Endpoint di archivio e backup

Archiviare un ricordo

Ripristinare un ricordo

Elencare i ricordi archiviati

Esportare i ricordi

Importare i ricordi

Endpoint di utilità

Verifica dello stato

Dashboard web

Documentazione API interattiva

Codici di stato

Limiti di frequenza