Server MCP

Kore Memory include un server Model Context Protocol (MCP) integrato che espone 14 tool per gli assistenti AI. Questo permette a Claude, Cursor e altri client compatibili MCP di salvare, cercare e gestire i ricordi direttamente durante le conversazioni.

Installazione

Il server MCP richiede l'extra mcp:

pip install kore-memory[semantic,mcp]

Avvio del server MCP

kore-mcp

Questo avvia il server MCP utilizzando il trasporto stdio, che è ciò che Claude Desktop e Cursor si aspettano.

informazioni

Il server MCP comunica tramite stdin/stdout usando il protocollo MCP. Si connette internamente a un server REST API Kore Memory in esecuzione. Assicurati che kore sia in esecuzione prima di avviare kore-mcp, oppure usa il server MCP in modalità standalone (può avviare il proprio server integrato).

Tool MCP

Il server espone 14 tool che i client MCP possono invocare:

#	Tool	Descrizione
1	memory_save	Salva un ricordo con punteggio di importanza automatico
2	memory_search	Ricerca semantica o FTS5 con paginazione
3	memory_delete	Elimina un ricordo per ID
4	memory_update	Aggiorna contenuto, categoria o importanza
5	memory_save_batch	Salvataggio batch di fino a 100 ricordi
6	memory_add_tags	Aggiunge tag a un ricordo
7	memory_search_by_tag	Trova tutti i ricordi con un tag specifico
8	memory_add_relation	Crea una relazione tra due ricordi
9	memory_timeline	Recupera la cronologia di un argomento
10	memory_decay_run	Esegue il passaggio di decay di Ebbinghaus
11	memory_compress	Unisce i ricordi simili
12	memory_cleanup	Rimuove i ricordi scaduti (TTL)
13	memory_import	Importa i ricordi da JSON
14	memory_export	Esporta tutti i ricordi come JSON

Dettagli dei tool

memory_save

{
  "content": "User prefers dark mode",
  "category": "preference",
  "importance": 1,
  "ttl_hours": null
}

• content (obbligatorio): 3--4000 caratteri
• category (opzionale): predefinito general
• importance (opzionale): 1 per punteggio automatico, 2--5 per esplicito
• ttl_hours (opzionale): scadenza automatica dopo N ore

memory_search

{
  "query": "user preferences",
  "limit": 5,
  "semantic": true
}

Restituisce i ricordi ordinati per punteggio effettivo (similarity x decay x importance).

memory_save_batch

{
  "memories": [
    {"content": "First memory", "category": "general"},
    {"content": "Second memory", "category": "decision", "importance": 5}
  ]
}

Salva fino a 100 ricordi in una singola chiamata.

memory_timeline

{
  "subject": "project alpha",
  "limit": 20
}

Restituisce la cronologia dell'argomento specificato.

memory_decay_run

Nessun parametro. Ricalcola i punteggi di decay e rimuove i ricordi completamente decaduti.

memory_compress

Nessun parametro. Unisce i ricordi con similarità coseno superiore alla soglia configurata.

Configurazione dei client

Claude Desktop

Aggiungi quanto segue al file di configurazione di Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kore-memory": {
      "command": "kore-mcp",
      "args": []
    }
  }
}

Dopo aver salvato, riavvia Claude Desktop. Dovresti vedere "kore-memory" nell'elenco dei tool MCP.

suggerimento

Se kore-mcp non si trova nel PATH di sistema, usa il percorso completo dell'eseguibile. Trovalo con which kore-mcp (macOS/Linux) o where kore-mcp (Windows).

Claude Desktop con ambiente personalizzato

Se hai bisogno di passare variabili d'ambiente (es. porta personalizzata o percorso del database):

{
  "mcpServers": {
    "kore-memory": {
      "command": "kore-mcp",
      "args": [],
      "env": {
        "KORE_PORT": "9000",
        "KORE_DB_PATH": "/path/to/custom.db"
      }
    }
  }
}

Cursor

Aggiungi alla configurazione MCP di Cursor (.cursor/mcp.json nel progetto o nelle impostazioni globali):

{
  "mcpServers": {
    "kore-memory": {
      "command": "kore-mcp",
      "args": []
    }
  }
}

Claude Code

Aggiungi alle impostazioni MCP di Claude Code (.claude/settings.json o .mcp.json a livello di progetto):

{
  "mcpServers": {
    "kore-memory": {
      "command": "kore-mcp",
      "args": []
    }
  }
}

Utilizzo con uvx (senza installazione)

Se preferisci non installare Kore globalmente, puoi usare uvx per eseguirlo direttamente:

{
  "mcpServers": {
    "kore-memory": {
      "command": "uvx",
      "args": ["--from", "kore-memory[semantic,mcp]", "kore-mcp"]
    }
  }
}

Questo scarica e esegue automaticamente l'ultima versione.

Pattern di utilizzo

Una volta configurato, puoi interagire con Kore Memory in modo naturale nelle conversazioni con l'AI:

Salvare il contesto

"Ricorda che questo progetto usa React 19 con TypeScript e fa il deploy su Cloudflare Pages."

Il client AI chiama memory_save con il contenuto e il punteggio di importanza calcolato automaticamente.

Recuperare informazioni

"Cosa sai riguardo alla configurazione del deploy di questo progetto?"

Il client AI chiama memory_search con una query pertinente e include i risultati nella risposta.

Costruire conoscenza nel tempo

"Tagga l'ultimo ricordo con 'infrastructure' e 'cloudflare'."

Il client AI chiama memory_add_tags per organizzare il ricordo.

Manutenzione

"Esegui la manutenzione della memoria per pulire i ricordi vecchi."

Il client AI chiama memory_decay_run, memory_compress e memory_cleanup in sequenza.

Namespace dell'agente

Il server MCP utilizza un ID agente predefinito per tutte le operazioni. Per usare un namespace agente personalizzato, configuralo tramite la variabile d'ambiente KORE_MCP_AGENT_ID:

{
  "mcpServers": {
    "kore-memory": {
      "command": "kore-mcp",
      "args": [],
      "env": {
        "KORE_MCP_AGENT_ID": "claude-desktop"
      }
    }
  }
}

Questo garantisce che i ricordi salvati da Claude Desktop siano isolati da quelli salvati da altri agenti.

Risoluzione dei problemi

Il server MCP non appare in Claude Desktop

1. Verifica che kore-mcp sia installato: which kore-mcp
2. Controlla che il percorso del file di configurazione sia corretto per il tuo sistema operativo
3. Riavvia completamente Claude Desktop (non solo la conversazione)
4. Controlla i log di Claude Desktop per errori di connessione

I tool non funzionano

1. Assicurati che il server Kore Memory sia in esecuzione: curl http://localhost:8765/health
2. Verifica che l'extra semantic sia installato se usi la ricerca semantica
3. Controlla che non ci siano conflitti di porta sulla 8765

Errori di permesso

Se riscontri errori di autenticazione, assicurati che KORE_LOCAL_ONLY=1 (il valore predefinito) oppure fornisci la API key corretta tramite variabili d'ambiente.