Kaede Recall MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Kaede Recall MCP recall why we picked Postgres for billing"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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, optionalproject,status,hash,entities,edgesandbacklinks.Four tools.
memory-recall,memory-write,memory-updateandmemory-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 /embedandPOST /invalidateon127.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 dedupeandbootstrap compactconsolidate 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.
memory-writeStore 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>, orAlready stored, id=<uuid>.
memory-recallSearch 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, theid, and the body of the first one or two slots.
memory-updateEdit a memory in place.
textrecomputes the hash, re-extracts the entities and re-embedssummary + 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_ONLYis enabled.
memory-deleteDelete by exact
point_idor by semanticquery, withdry_runto preview the matches.Input:
point_id,query,limit,score_threshold,dry_run.This tool is disabled when
KAEDE_READ_ONLYis 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 |
|
|
| The memory body. |
| One-line trigger, also the head of the embedding input. |
|
|
| Optional project id, stored only when set. |
|
|
| SHA-256 of the normalized |
| Structural aliases used by the entity slot. |
| Outgoing relations |
| Incoming relations |
| ISO 8601 UTC timestamp of the first write. |
| 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.
You cannot provide bothKAEDE_BACKEND_URL and KAEDE_BACKEND_PATH at the same time.
Name | Description | Default Value |
| URL of the vector backend | None |
| API key for the vector backend | None |
| Name of the default collection to use. | None |
| Path to the local vector database (alternative to | None |
| Embedding provider to use (currently only "fastembed" is supported) |
|
| Name of the embedding model to use |
|
| Memory OS daemon used for embeddings and invalidation |
|
| Ask the daemon before loading a local model ( |
|
| Maximum number of results to return from search |
|
| Enable read-only mode (disables mutation tools) |
|
| Skip a write when the same content and metadata already exist |
|
| Attempts for a call that fails on a transient connection error |
|
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 |
| Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
|
| Enable debug mode |
|
| Host address to bind the server to |
|
| Port to run the server on |
|
| Behavior for duplicate resources (warn, error, replace, ignore) |
|
| Behavior for duplicate tools (warn, error, replace, ignore) |
|
| Behavior for duplicate prompts (warn, error, replace, ignore) |
|
| List of dependencies to install in the server environment |
|
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-mcpTransport 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 sseSupported transport protocols:
stdio(default): Standard input/output transport, might only be used by local MCP clientssse: Server-Sent Events transport, perfect for remote clientsstreamable-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 sseUsing Podman (recommended)
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-mcpFASTMCP_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 transportIn 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/sseWe 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:
Store code snippets, documentation, and implementation details
Retrieve relevant code examples based on semantic search
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.
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
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-mcpVerify 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:
Use the
memory-writetool to store code snippets with descriptions.Use the
memory-recalltool 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.pyUsing 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.pyOnce 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 toolsmemory-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
Scored across 4 tools
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.
All four names follow a strict memory-<verb> kebab-case pattern with action-oriented verbs (write, recall, update, delete). Fully predictable and readable.
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.
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
Related MCP Connectors
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Memory for AI agent teams across tools, sessions, repositories, and teammates.
Persistent memory for AI agents: add, search, update, and delete long-term memories.
Persistent memory for AI agents: save, search and connect context across tools and sessions.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI agents to store and recall persistent long-term memories across sessions using LanceDB, with semantic search, automatic linking, conflict detection, and maintenance tools.726 npmMIT
- AlicenseNot gradedqualityAmaintenanceA 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.0MIT
- AlicenseNot gradedqualityDmaintenanceEnables coding agents to store, recall, and manage persistent memory across sessions through MCP tools, with reviewable handoffs and SQLite-backed local storage.1MIT
- AlicenseNot gradedqualityBmaintenanceProvides AI coding agents with a persistent memory layer to save, recall, update, and track memories across sessions and repositories using hybrid semantic search.5MIT