MCP Server

Kore Memory includes a built-in Model Context Protocol (MCP) server that exposes 14 tools for AI assistants. This lets Claude, Cursor, and other MCP-compatible clients save, search, and manage memories directly during conversations.

Installation

The MCP server requires the mcp extra:

pip install kore-memory[semantic,mcp]

Starting the MCP Server

kore-mcp

This starts the MCP server using stdio transport, which is what Claude Desktop and Cursor expect.

info

The MCP server communicates via stdin/stdout using the MCP protocol. It connects to a running Kore Memory REST API server internally. Make sure kore is running before starting kore-mcp, or use the MCP server standalone (it can start its own embedded server).

MCP Tools

The server exposes 14 tools that MCP clients can call:

#	Tool	Description
1	memory_save	Save a memory with auto-importance scoring
2	memory_search	Semantic or FTS5 search with pagination
3	memory_delete	Delete a memory by ID
4	memory_update	Update content, category, or importance
5	memory_save_batch	Batch save up to 100 memories
6	memory_add_tags	Add tags to a memory
7	memory_search_by_tag	Find all memories with a specific tag
8	memory_add_relation	Create a relation between two memories
9	memory_timeline	Retrieve chronological history for a subject
10	memory_decay_run	Run the Ebbinghaus decay pass
11	memory_compress	Merge similar memories
12	memory_cleanup	Remove expired (TTL) memories
13	memory_import	Import memories from JSON
14	memory_export	Export all memories as JSON

Tool Details

memory_save

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

• content (required): 3--4000 characters
• category (optional): defaults to general
• importance (optional): 1 for auto-score, 2--5 for explicit
• ttl_hours (optional): auto-expire after N hours

memory_search

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

Returns memories ranked by effective score (similarity x decay x importance).

memory_save_batch

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

Saves up to 100 memories in a single call.

memory_timeline

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

Returns chronological history for the given subject.

memory_decay_run

No parameters. Recalculates decay scores and removes fully decayed memories.

memory_compress

No parameters. Merges memories with cosine similarity above the configured threshold.

Client Configuration

Claude Desktop

Add the following to your Claude Desktop configuration file:

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

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

After saving, restart Claude Desktop. You should see "kore-memory" in the MCP tools list.

tip

If kore-mcp is not in your system PATH, use the full path to the executable. Find it with which kore-mcp (macOS/Linux) or where kore-mcp (Windows).

Claude Desktop with Custom Environment

If you need to pass environment variables (e.g., custom port or database path):

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

Cursor

Add to your Cursor MCP configuration (.cursor/mcp.json in your project or global settings):

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

Claude Code

Add to your Claude Code MCP settings (.claude/settings.json or project-level .mcp.json):

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

Using with uvx (No Install)

If you prefer not to install Kore globally, you can use uvx to run it directly:

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

This downloads and runs the latest version automatically.

Usage Patterns

Once configured, you can interact with Kore Memory naturally in your AI conversations:

Saving Context

"Remember that this project uses React 19 with TypeScript and deploys to Cloudflare Pages."

The AI client calls memory_save with the content and auto-scored importance.

Recalling Information

"What do you know about the deployment setup for this project?"

The AI client calls memory_search with a relevant query and includes the results in its response.

Building Knowledge Over Time

"Tag that last memory with 'infrastructure' and 'cloudflare'."

The AI client calls memory_add_tags to organize the memory.

Maintenance

"Run memory maintenance to clean up old memories."

The AI client calls memory_decay_run, memory_compress, and memory_cleanup in sequence.

Agent Namespace

The MCP server uses a default agent ID for all operations. To use a custom agent namespace, configure it via the KORE_MCP_AGENT_ID environment variable:

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

This ensures memories saved from Claude Desktop are isolated from memories saved by other agents.

Troubleshooting

MCP server not showing up in Claude Desktop

1. Verify kore-mcp is installed: which kore-mcp
2. Check the config file path is correct for your OS
3. Restart Claude Desktop completely (not just the conversation)
4. Check Claude Desktop logs for connection errors

Tools not working

1. Ensure the Kore Memory server is running: curl http://localhost:8765/health
2. Check that the semantic extra is installed if using semantic search
3. Verify there are no port conflicts on 8765

Permission errors

If you see authentication errors, ensure KORE_LOCAL_ONLY=1 (the default) or provide the correct API key via environment variables.