Skip to main content
Glama
Kaede Recall MCP

Kaede Recall MCP

Kaede Recall MCP

The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.

A Model Context Protocol server that turns a vector database into a typed long-term memory for coding agents.

Overview

One collection, one write path, four tools. Every memory is a typed node, not an opaque document, and every mutation goes through the same store.

Architecture

  • Typed nodes. Each point carries kind (fact, preference, profile, decision, problem, procedure, trace, doc), text, summary, scope, optional project, status, hash, entities, edges and backlinks.

  • Four tools. memory-recall, memory-write, memory-update and memory-delete. There is no second, untyped document API.

  • Deterministic ids. The point id is a uuid5 of the content hash, scope and project, so a retry or a replay lands on the same key.

  • Write path. Dedupe by hash, auto-supersede a near-identical fact at 0.92 only when scope, project and the entity set match, and link relations in the same call.

  • Read path. One embedding per query. A global vector search, an entity slot, and an exact lane for paths, known file names and hex digests (real similarity plus a bounded +0.08). Slot 1 needs a raw score of 0.33; slot 2 can displace it at a 0.12 margin. An optional graph hop follows payload edges and drops superseded or deprecated nodes.

  • Embeddings. A local daemon exposes POST /embed and POST /invalidate on 127.0.0.1:7451. MCP clients ask it for vectors instead of loading their own model, and the daemon owns the entity registry and the recall cache.

  • Maintenance. bootstrap dedupe and bootstrap compact consolidate historical duplicates offline from the stored vectors; a weekly timer takes a snapshot and compacts.

Integrating with an agent? See AGENT_INTEGRATION.md for a copy-paste guide, the MCP config for each client and the recommended system prompt.

Related MCP server: enhx-memory

Components

Tools

Four tools, one collection, one write path. Every write goes through the same typed memory store, so there is no second, untyped copy of the same memory.

  1. memory-write

    • Store one durable memory. Dedupes by content hash, links relations and supersedes an older fact in the same call.

    • Input: kind, text, summary, scope, project, tags, entities, links, supersedes_id, source.

    • Returns: Stored <kind>, id=<uuid>, or Already stored, id=<uuid>.

  2. memory-recall

    • Search long-term memory with a hard character budget. One dense search, an entity slot, exact-path/hash matching and an optional graph hop.

    • Input: query, kinds, scope, project, limit, max_chars, walk_depth, include_superseded, ids.

    • Returns: numbered hits with [kind score], a trigger line, the id, and the body of the first one or two slots.

  3. memory-update

    • Edit a memory in place. text recomputes the hash, re-extracts the entities and re-embeds summary + first 1200 chars. Tags and entities alone rewrite the payload without a model call.

    • Input: point_id, text, summary, tags, entities.

    • This tool is disabled when KAEDE_READ_ONLY is enabled.

  4. memory-delete

    • Delete by exact point_id or by semantic query, with dry_run to preview the matches.

    • Input: point_id, query, limit, score_threshold, dry_run.

    • This tool is disabled when KAEDE_READ_ONLY is enabled.

To audit historical duplicates, python -m kaede_recall_mcp.memory_os.bootstrap dedupe --dry-run lists active pairs that share an entity with similarity >= 0.90; without --dry-run the older point of each pair is superseded by the newer one.

Payload fields written by the server

Field

Meaning

kind

fact, preference, profile, decision, problem, procedure, trace, doc.

text

The memory body.

summary

One-line trigger, also the head of the embedding input.

scope

global or project:<id>.

project

Optional project id, stored only when set.

status

active or superseded.

hash

SHA-256 of the normalized kind + text. Dedupe key and id source.

entities

Structural aliases used by the entity slot.

edges

Outgoing relations {rel, to}.

backlinks

Incoming relations {rel, from}.

created_at

ISO 8601 UTC timestamp of the first write.

updated_at

ISO 8601 UTC timestamp of the last write.

Environment Variables

Configuration is done via environment variables. The only command-line argument is --transport, used to select the transport protocol.

NOTE

You cannot provide bothKAEDE_BACKEND_URL and KAEDE_BACKEND_PATH at the same time.

Name

Description

Default Value

KAEDE_BACKEND_URL

URL of the vector backend

None

KAEDE_BACKEND_API_KEY

API key for the vector backend

None

COLLECTION_NAME

Name of the default collection to use.

None

KAEDE_BACKEND_PATH

Path to the local vector database (alternative to KAEDE_BACKEND_URL)

None

EMBEDDING_PROVIDER

Embedding provider to use (currently only "fastembed" is supported)

fastembed

EMBEDDING_MODEL

Name of the embedding model to use

sentence-transformers/all-MiniLM-L6-v2

MEMORY_OS_EMBED_URL

Memory OS daemon used for embeddings and invalidation

http://127.0.0.1:7451

MEMORY_OS_EMBED_REMOTE

Ask the daemon before loading a local model (false forces local)

true

KAEDE_SEARCH_LIMIT

Maximum number of results to return from search

10

KAEDE_READ_ONLY

Enable read-only mode (disables mutation tools)

false

KAEDE_DEDUPE

Skip a write when the same content and metadata already exist

true

KAEDE_RETRIES

Attempts for a call that fails on a transient connection error

3

FastMCP Environment Variables

Since kaede-recall-mcp is based on FastMCP, it also supports all the FastMCP environment variables. The most important ones are listed below:

Environment Variable

Description

Default Value

FASTMCP_LOG_LEVEL

Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

INFO

FASTMCP_SERVER_DEBUG

Enable debug mode

false

FASTMCP_SERVER_HOST

Host address to bind the server to

127.0.0.1

FASTMCP_SERVER_PORT

Port to run the server on

8000

FASTMCP_SERVER_ON_DUPLICATE_RESOURCES

Behavior for duplicate resources (warn, error, replace, ignore)

warn

FASTMCP_SERVER_ON_DUPLICATE_TOOLS

Behavior for duplicate tools (warn, error, replace, ignore)

warn

FASTMCP_SERVER_ON_DUPLICATE_PROMPTS

Behavior for duplicate prompts (warn, error, replace, ignore)

warn

FASTMCP_SERVER_DEPENDENCIES

List of dependencies to install in the server environment

[]

NOTE

Server-specific settings use theFASTMCP_SERVER_ prefix. This may change in future versions.

Installation

From source

The package is distributed from this repository, not from PyPI.

git clone https://github.com/MapleProjects/kaede-recall-mcp
cd kaede-recall-mcp
uv pip install -e .
KAEDE_BACKEND_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
kaede-recall-mcp

Transport Protocols

The server supports different transport protocols that can be specified using the --transport flag:

KAEDE_BACKEND_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
kaede-recall-mcp --transport sse

Supported transport protocols:

  • stdio (default): Standard input/output transport, might only be used by local MCP clients

  • sse: Server-Sent Events transport, perfect for remote clients

  • streamable-http: Streamable HTTP transport, perfect for remote clients, more recent than SSE

The default transport is stdio if not specified.

When SSE transport is used, the server will listen on the specified port and wait for incoming connections. The default port is 8000, however it can be changed using the FASTMCP_SERVER_PORT environment variable.

KAEDE_BACKEND_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_SERVER_PORT=1234 \
kaede-recall-mcp --transport sse

Podman runs rootless and needs no daemon. The same Dockerfile works.

# Build the image
podman build -t kaede-recall-mcp .

# Run the container
podman run --rm -p 8000:8000 \
  -e FASTMCP_SERVER_HOST="0.0.0.0" \
  -e KAEDE_BACKEND_URL="http://your-vector-server:6333" \
  -e KAEDE_BACKEND_API_KEY="your-api-key" \
  -e COLLECTION_NAME="kaede-memory" \
  kaede-recall-mcp
TIP

FASTMCP_SERVER_HOST="0.0.0.0" makes the server listen on all network interfaces, which is required inside a container.

Docker works too. Replace podman with docker in the commands above.

Manual configuration of Claude Desktop

To use this server with the Claude Desktop app, add the following configuration to the "mcpServers" section of your claude_desktop_config.json:

{
  "kaede-recall": {
    "command": "/path/to/kaede-recall-mcp/.venv/bin/kaede-recall-mcp",
    "env": {
      "KAEDE_BACKEND_URL": "https://localhost:6333",
      "KAEDE_BACKEND_API_KEY": "your_api_key",
      "COLLECTION_NAME": "kaede-memory",
      "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
    }
  }
}

For local backend mode:

{
  "kaede-recall": {
    "command": "/path/to/kaede-recall-mcp/.venv/bin/kaede-recall-mcp",
    "env": {
      "KAEDE_BACKEND_PATH": "/path/to/backend/database",
      "COLLECTION_NAME": "kaede-memory",
      "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
    }
  }
}

This MCP server will automatically create a collection with the specified name if it doesn't exist.

By default, the server will use the sentence-transformers/all-MiniLM-L6-v2 embedding model to encode memories. For the time being, only FastEmbed models are supported.

Support for other tools

This MCP server can be used with any MCP-compatible client. For example, you can use it with Cursor and VS Code, which provide built-in support for the Model Context Protocol.

Using with Cursor/Windsurf

You can configure this MCP server to work as a code search tool for Cursor or Windsurf by customizing the tool descriptions:

KAEDE_BACKEND_URL="http://localhost:6333" \
COLLECTION_NAME="code-snippets" \
TOOL_STORE_DESCRIPTION="Store reusable code snippets for later retrieval. \
The 'information' parameter should contain a natural language description of what the code does, \
while the actual code should be included in the 'metadata' parameter as a 'code' property. \
The value of 'metadata' is a Python dictionary with strings as keys. \
Use this whenever you generate some code snippet." \
TOOL_FIND_DESCRIPTION="Search for relevant code snippets based on natural language descriptions. \
The 'query' parameter should describe what you're looking for, \
and the tool will return the most relevant code snippets. \
Use this when you need to find existing code snippets for reuse or reference." \
kaede-recall-mcp --transport sse # Enable SSE transport

In Cursor/Windsurf, you can then configure the MCP server in your settings by pointing to this running server using SSE transport protocol. The description on how to add an MCP server to Cursor can be found in the Cursor documentation. If you are running Cursor/Windsurf locally, you can use the following URL:

http://localhost:8000/sse
TIP

We suggest SSE transport as a preferred way to connect Cursor/Windsurf to the MCP server, as it can support remote connections. That makes it easy to share the server with your team or use it in a cloud environment.

This configuration transforms the MCP server into a specialized code search tool that can:

  1. Store code snippets, documentation, and implementation details

  2. Retrieve relevant code examples based on semantic search

  3. Help developers find specific implementations or usage patterns

You can populate the database by storing natural language descriptions of code snippets (in the information parameter) along with the actual code (in the metadata.code property), and then search for them using natural language queries that describe what you're looking for.

NOTE

The tool descriptions provided above are examples and may need to be customized for your specific use case. Consider adjusting the descriptions to better match your team's workflow and the specific types of code snippets you want to store and retrieve.

If you have successfully installed the kaede-recall-mcp, but still can't get it to work with Cursor, please consider creating the Cursor rules so the MCP tools are always used when the agent produces a new code snippet. You can restrict the rules to only work for certain file types, to avoid using the MCP server for the documentation or other types of content.

Using with Claude Code

You can enhance Claude Code's capabilities by connecting it to this MCP server, enabling semantic search over your existing codebase.

Setting up kaede-recall-mcp

  1. Add the MCP server to Claude Code:

    # Add kaede-recall for code search
    claude mcp add kaede-recall \
    -e KAEDE_BACKEND_URL="http://localhost:6333" \
    -e COLLECTION_NAME="kaede-memory" \
    -e EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
    -- /path/to/kaede-recall-mcp/.venv/bin/kaede-recall-mcp
  2. Verify the server was added:

    claude mcp list

Using Semantic Code Search in Claude Code

Tool descriptions, specified in TOOL_STORE_DESCRIPTION and TOOL_FIND_DESCRIPTION, guide Claude Code on how to use the MCP server. The ones provided above are examples and may need to be customized for your specific use case. However, Claude Code should be already able to:

  1. Use the memory-write tool to store code snippets with descriptions.

  2. Use the memory-recall tool to search for relevant code snippets using natural language.

Run MCP server in Development Mode

The MCP server can be run in development mode using the mcp dev command. This will start the server and open the MCP inspector in your browser.

COLLECTION_NAME=mcp-dev fastmcp dev src/kaede_recall_mcp/server.py

Using with VS Code

Add this to your User Settings (JSON) or to .vscode/mcp.json:

{
  "servers": {
    "kaede-recall": {
      "command": "/path/to/kaede-recall-mcp/.venv/bin/kaede-recall-mcp",
      "env": {
        "KAEDE_BACKEND_URL": "http://localhost:6333",
        "COLLECTION_NAME": "kaede-memory",
        "EMBEDDING_MODEL": "jinaai/jina-embeddings-v2-base-es"
      }
    }
  }
}

Contributing

If you have suggestions for how kaede-recall-mcp could be improved, or want to report a bug, open an issue! We'd love all and any contributions.

Testing kaede-recall-mcp locally

The MCP inspector is a developer tool for testing and debugging MCP servers. It runs both a client UI (default port 5173) and an MCP proxy server (default port 3000). Open the client UI in your browser to use the inspector.

KAEDE_BACKEND_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/kaede_recall_mcp/server.py

Once started, open your browser to http://localhost:5173 to access the inspector interface.

License

This MCP server is licensed under the Apache License 2.0. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the Apache License 2.0. For more details, please see the LICENSE file in the project repository.

Privacy and support

Available Tools

4 tools
memory-deleteA

Delete a memory by exact id or by semantic match, with a dry-run preview. The only way to remove a node.

Inputs: limit, query, dry_run, point_id, +1 more.

memory-recallB

Search long-term memory (facts, decisions, problems, procedures) with a hard size budget.

Inputs: ids, kinds, limit, query, +5 more.

memory-updateA

Edit a stored memory in place: text, summary, tags or entities. Re-embeds when the trigger or the body changes.

Inputs: point_id (required), tags, text, summary, +1 more.

memory-writeA

Store one durable memory. Dedupes, links and supersedes in one call.

Inputs: kind (required), text (required), tags, links, +6 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool maps to a distinct lifecycle action on a single resource: memory-write stores, memory-recall searches, memory-update edits in place, memory-delete removes. The write/update boundary is the only potential source of confusion, but the descriptions clearly separate storing a new memory from editing an existing one.

    Naming Consistency5/5

    All four names follow a strict memory-<verb> kebab-case pattern with action-oriented verbs (write, recall, update, delete). Fully predictable and readable.

    Tool Count5/5

    Four tools cover the full memory lifecycle (create, read/search, update, delete) with no filler. The surface is tightly scoped to the server's single purpose.

    Completeness4/5

    Core CRUD lifecycle is fully covered, including a dry-run preview on delete. Minor gaps: no explicit get-by-id or list/browse operation, and no tools for inspecting tags, entities, or links outside of recall results.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      A persistent, project-scoped memory layer for AI coding agents, providing 39 tools for capturing, searching, deduplicating, relating, and maintaining memory records across long-running coding sessions.
      0
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables coding agents to store, recall, and manage persistent memory across sessions through MCP tools, with reviewable handoffs and SQLite-backed local storage.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides AI coding agents with a persistent memory layer to save, recall, update, and track memories across sessions and repositories using hybrid semantic search.
      5
      MIT