@kireo/mcp-server
This server provides long-term memory and context management for MCP-compatible AI tools, letting agents save, search, recall, update, and organize memories across namespaces, plus archive/load conversation context and index local code.
Memory management:
memory_savestores facts, decisions, preferences, events, goals, insights, relationships, or other items;memory_getfetches by id;memory_updatepatches fields;memory_deletesoft-deletes with a 30-day recovery window.Search & recall:
memory_searchperforms hybrid semantic + keyword search with filters (namespace, type, tags, entities, date range, score threshold);memory_recallreplays recent or important memories chronologically or by importance with pagination.Organization:
memory_list_namespacesenumerates the user's namespaces with counts; memories can be bucketed into logical namespaces (e.g., per project).Context handoff:
context_saveuploads a conversation summary/handoff,context_loadretrieves it, andcontext_archivemanages archived context.Project awareness:
project_infoexposes project details;kireo indexextracts functions/classes/methods from a local codebase into acode-<repo>namespace searchable viamemory_search.Health & diagnostics:
memory_healthprobes local server version and remote API status.Privacy controls: telemetry can be disabled via
KIREO_TELEMETRY=0; only explicitly supplied content is uploaded.
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., "@@kireo/mcp-server save a memory: deployment branch is main, not master"
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.
@kireo/mcp-server
Long-term memory for any MCP-compatible AI tool (Claude Code, Cursor, Windsurf, Cline, Zed, Continue …).
What is Kireo memory MCP?
Kireo memory MCP is a Model Context Protocol server that gives Claude Code, Cursor, Cline, Windsurf and any other MCP client long-term memory. Save a decision once; recall it in any later session, on any machine. Hybrid semantic + keyword search over LanceDB, 12 MCP tools, plus local code indexing. Free beta — an API key is all you need.
How do I install Kireo memory MCP?
One line for Claude Code, one JSON block everywhere else. Both need a free key from
https://app.kireo.app/app/api-keys (ki_sk_…).
# Claude Code — add --scope user to get it in every project
claude mcp add kireo --scope user --env KIREO_API_KEY=ki_sk_xxx -- npx -y --package=@kireo/mcp-server kireo-mcpEvery other client takes the same server entry; only the file it goes in differs:
{
"mcpServers": {
"kireo": {
"command": "npx",
"args": ["-y", "--package=@kireo/mcp-server", "kireo-mcp"],
"env": { "KIREO_API_KEY": "ki_sk_xxx" }
}
}
}Client | Where that block goes |
Claude Code |
|
Cursor |
|
Cline | MCP Servers → Configure MCP Servers ( |
Claude Desktop |
|
Windsurf |
|
Zed / Continue / any MCP host | Whatever that host calls its MCP server list — same three fields |
Restart the client afterwards. Node.js ≥ 20 must be on PATH for npx.
Which tools does it expose?
Twelve, over MCP stdio: memory_save, memory_search, memory_recall, memory_get,
memory_update, memory_delete, memory_list_namespaces, memory_health, context_save,
context_load, project_info, and context_archive. Every client sees the same set. Call memory_health first to confirm the key works.
Does it bloat my prompt?
No — memory is pulled, not pushed. Nothing is injected into the system prompt. The agent calls
memory_search only when it decides prior context is worth retrieving, and gets back a bounded
ranked set (default 10 hits, hard cap 50), so tokens are spent per-query rather than per-turn.
How is it different from a CLAUDE.md / .cursorrules file?
A rules file is static text re-read in full every session and shared by nothing. Kireo memory MCP is queried on demand, is written by the agent as work happens, is searchable semantically, and is shared across projects, sessions and machines through namespaces.
Can it index my codebase?
Yes. npx -y -p @kireo/mcp-server kireo index ./ --repo my-app extracts functions/classes/methods
into a code-<repo> namespace that memory_search can reach. Indexing is incremental — re-runs
only send changed files, and the server dedupes identical symbols, so retrying is safe.
Is my code uploaded?
The compact command uploads the conversation summary you ask it to archive. context_save
uploads a handoff; memory_save uploads supplied content; kireo index uploads extracted code
symbols. These actions send their content to your Kireo account. Set KIREO_TELEMETRY=0 to also drop the X-Device-Id header.
What does it cost?
Free beta. Sign up at https://app.kireo.app, create a key, done — no card.
Related MCP server: Synapse Memory
Conversation compression (0.3.0)
The Kireo plugin adds /kireo:compact in Claude Code and $kireo-compact in Codex:
it summarizes the visible conversation, writes <directory-name>.md, and uploads
it to your Kireo account with offline retry and versioned file metadata.
Install the plugin.
The MCP now also provides project_info, context_save, context_load, and
context_archive, alongside the eight general memory tools below.
Quickstart
Get an API key at https://app.kireo.app/app/api-keys (
ki_sk_…).Add this MCP server to your host. Claude Code — run:
claude mcp add kireo --scope user --env KIREO_API_KEY=ki_sk_xxx -- npx -y --package=@kireo/mcp-server kireo-mcpTwo details in that line are load-bearing, both verified against claude 2.1.220 and npm 11 on 2026-08-03:
--package=@kireo/mcp-server kireo-mcp, not@kireo/mcp-server. This package ships two binaries (kireo,kireo-mcp), neither named after the package, sonpx -y @kireo/mcp-servercannot pick one and fails withcould not determine executable to run.--package=, not the short-p. A bare-pafter--gets swallowed by theclaude mcp addoption parser, which then rejects its own flag:claude mcp add kireo --env … -- npx -y -p @kireo/mcp-server kireo-mcperrors withunknown option '--env'. The long form parses cleanly.
Drop --scope user if you only want it in the current project. Alternatively, check a project-scoped .mcp.json into your repo root with the same shape (inside JSON args the short -p is fine — it goes straight to npx and never reaches the claude parser):
// .mcp.json (project root)
{
"mcpServers": {
"kireo": {
"command": "npx",
"args": ["-y", "--package=@kireo/mcp-server", "kireo-mcp"],
"env": { "KIREO_API_KEY": "ki_sk_xxx" }
}
}
}Restart the host. You now have 12 tools available to the AI:
Tool | Purpose |
| Persist a long-term memory |
| Hybrid semantic + keyword search |
| Replay recent/important memories |
| Fetch by id |
| Patch fields |
| Soft/hard delete |
| Enumerate namespaces |
| Probe service |
Configuration
Sources are merged in order: CLI args > env > ~/.kireo/config.json.
ENV / CLI | Default | Description |
| required | Bearer token ( |
|
| Override for self-host. |
|
| Per-request timeout in ms, max |
|
| 5xx/429 retries (alias: |
|
| Exponential backoff base. |
|
| Set to |
|
|
|
| none | HTTP(S) proxy. |
|
| Locale for error hints. |
Logs land in ~/.kireo/logs/ on all platforms (macOS, Linux, Windows).
Indexing local code
Index a repository's symbols (functions / classes / methods) into a
code-<repo> namespace so the AI can recall them via memory_search:
export KIREO_API_KEY=ki_sk_xxx
npx -y -p @kireo/mcp-server kireo index ./ --repo my-appIndexing is incremental — only changed files are re-sent on subsequent runs.
Flag | Default | Description |
| directory basename | Repo name → |
|
| Symbols per upload batch ( |
|
| Per-request timeout (max |
| — | Same as the config table above; CLI flags override env. |
Run kireo --help for the full usage text. --help and --version never touch
the network or the filesystem and don't require an API key. If a batch upload
times out, re-running the same command is safe: the server dedupes identical
symbols, so retries won't create duplicates.
Host setup
Privacy
Set KIREO_TELEMETRY=0 to drop the X-Device-Id header. We never read your code; only the explicit content you pass to memory_save reaches the API.
Troubleshooting
AUTH_INVALID_KEY→ rotate your key at https://app.kireo.app/app/api-keys.QUOTA_EXCEEDED→ upgrade or wait for next billing cycle.Tools missing in your host → run
npx @modelcontextprotocol/inspector node $(npm root -g)/@kireo/mcp-server/bin/kireo-mcp.cjsto verify locally.
License
MIT
Available Tools
12 toolscontext_archiveA
Save and upload a semantically compressed conversation as .md. When to use: after /kireo:compact has summarized the requested conversation rounds, and the user has asked to upload them. The host model does the compression; this tool redacts, writes the Markdown file, splits it losslessly and uploads it to the memory API. Always pass the conversation directory as cwd. Directory archives use their own namespace (different worktrees and same-named directories stay separate) and never change relay project keys. dry_run:true previews without side effects; otherwise invocation saves AND uploads. A failed or incomplete upload stays queued locally. Run compact again to retry. Returns the project, filename, local_path, namespace, snapshot_id, stored, deduped, outbox_pending, memory_ids and dashboard_url. Never call a queued archive uploaded.
Inputs: cwd (required), host (required), summary (required), session_id (required), +1 more.
context_loadA
Load previously saved context for the current project and render it.
When to use: at the start of work on a project — especially on a machine or in a tool where you have not worked on it before.
The first line reports the project identity and the code index freshness. Relay both to the user; never assume the code index is current.
Returns rendered text, grouped constraints → open threads → decisions → gotchas → key files → preferences.
A repo with a .kireo/disabled file, or the KIREO_DISABLED env var,
disables this tool entirely — it returns immediately and does nothing: no
outbox flush, no request, no CONTEXT.md.
Inputs: cwd, outbox_dir, token_budget, audit_log_path.
context_saveA
Persist distilled session context for the current project.
When to use: ONCE per /kireo:save, after you have distilled the session. Always call project_info first and show the user the resolved project.
Each entry needs non-empty evidence — a concrete basis from THIS session
(a file path, a command you ran, something the user said). If you cannot
cite one, do not write the entry.
Do NOT store things re-derivable from the repo in 60 seconds — that is the code index’s job. Store decisions, constraints, gotchas, open threads, a small map of key files, and stated preferences.
Privacy: content, evidence, and files are pattern-redacted for known
credential shapes, but that is NOT a privacy guarantee — it cannot catch
business secrets ("customer A’s contract is worth $X") that got paraphrased
into evidence/files from things the session read (.env, docker logs, a
pasted SQL result). The first run is therefore FORCED into a preview by the
tool itself: until a .first-run-acknowledged marker exists next to the
outbox directory, every call returns the exact (post-redaction) text and
writes/uploads nothing, no matter what dry_run says. Show that text to
the user, and only after they confirm there is nothing business-sensitive
call again with an explicit dry_run: false — that call performs the real
save and records the acknowledgement. From then on dry_run is an ordinary
optional preview flag (omitted = real save). A repo with a .kireo/disabled
file, or the KIREO_DISABLED env var, disables this tool entirely — it
returns immediately and does nothing.
Returns: { stored, deduped, failed, outbox_pending, namespace, dashboard_url }
Inputs: host (required), entries (required), session_id (required), cwd, +5 more.
memory_deleteA
Delete a memory. Defaults to a soft delete (30-day recovery window).
When to use:
The user explicitly asks to forget something ("forget that I said …").
A memory is clearly wrong AND not worth correcting.
GDPR / privacy removal request.
When NOT to use:
The memory is just outdated — prefer memory_update.
You're unsure — ask the user first.
Note: deletes are always soft — the API has no immediate hard delete. Soft-deleted memories are purged permanently after the 30-day window.
Inputs: id (required), hard.
memory_getA
Fetch a single memory by id.
When to use:
You already have a memory id from a previous memory_search / memory_recall / memory_save call.
The user references "that memory you saved" and you stored the id.
When NOT to use:
You only have a vague query — use memory_search or memory_recall instead.
Inputs: id (required).
memory_healthA
Probe the Kireo service and report local + remote health.
When to use:
User reports "memory tools aren't working".
You hit unexplained errors and need to confirm the API is reachable.
First-time setup verification.
Returns: { local: { server_version, node_version, platform }, remote: { status } }.
Inputs: no named parameters.
memory_list_namespacesA
List all namespaces the current user has, with per-namespace counts.
When to use:
Before deciding which namespace to save to, when the user has multiple projects.
To answer "what projects do I have memories for?".
For diagnostics.
Returns: array of { name, created_at }.
Inputs: no named parameters.
memory_recallA
Replay recent or important memories from a namespace, without a query.
When to use:
At the start of a new chat — to load recent context.
The user says "what have we been working on" / "remind me".
You want a chronological feed rather than a search match.
When NOT to use:
The user has a specific question → use memory_search.
You already have the id → use memory_get.
Inputs: limit, order, since, cursor, +1 more.
memory_saveA
Persist a long-term memory for the current user.
When to use:
The user states a preference, decision, fact, plan, or goal that should outlive this chat.
You learn a stable property of the user, their project, or their tooling.
The user explicitly says "remember", "记住", "save this".
When NOT to use:
Ephemeral chat turns ("ok", "thanks").
Sensitive secrets (API keys, passwords) — refuse and warn the user.
Information you can re-derive from the codebase on demand.
Returns: { id, created_at, schema_version, embedding_status } — use memory_get for the full record.
Inputs: content (required), tags, type, entities, +4 more.
memory_searchA
Hybrid semantic + keyword search over the user's memories.
When to use:
The user asks "do you remember…" or "what did I say about X".
Before answering project-specific questions, search for stored preferences and decisions.
You need to ground your answer in user-supplied facts.
When NOT to use:
You already have the memory id → use memory_get.
You just want the most recent items in a namespace → use memory_recall.
Returns: ranked list of MemoryRecord with a raw RRF relevance score (typically 0.01–0.04).
Inputs: query (required), tags, type, limit, +5 more.
memory_updateA
Patch an existing memory. Only the fields you provide are changed.
When to use:
The user corrects a previously stored fact ("actually, I use Tailwind v4 not v3").
You need to add tags / entities to an existing memory.
The user lowers/raises priority of a memory.
When NOT to use:
The memory is wrong AND no longer relevant → use memory_delete.
You don't have the id yet → search first.
Inputs: id (required), tags, type, content, +5 more.
project_infoA
Resolve the stable identity of the current project and the namespaces its memories live in.
When to use: before every context_save and context_load, and any time the user asks which project or bucket their memories are going to.
ALWAYS call this before context_save or context_load, and ALWAYS show the
user the returned key and source — a misidentified project is the one
failure the user can catch instantly, and cannot catch at all if hidden.
If warn is non-null the identity is NOT stable across machines; relay it verbatim.
Returns: { key, source, display_name, warn, ctx_namespace, code_namespace, home_namespace }
Inputs: cwd.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct operation: memory_get/search/recall are clearly separated by id, query, or chronological feed; memory_save/update/delete cover lifecycle edits; context_save/load/archive handle project session context. Even the potentially overlapping memory and context tools are differentiated by their descriptions and usage guidance.
Memory tools consistently use memory_<verb> (memory_save, memory_search, memory_delete), and context tools use context_<verb>. The only deviation is project_info, which breaks the verb-first pattern, and memory_list_namespaces which mixes noun phrasing, but overall the convention is predictable and readable.
12 tools is well-scoped for a memory and context persistence server. Each tool earns its place: CRUD for memories, search/recall/health/namespace utilities, and context save/load/archive. No redundant tools or excessive surface area.
The tool surface covers the full memory lifecycle: create, read, update, delete, search, recall, and namespace management. Context persistence is complete with save, load, and archive. Project identity resolution and health probing fill the operational gaps, leaving no obvious dead ends.
Maintenance
Related MCP Connectors
An MCP memory server. One memory your agents share — across models, devices and apps.
Hosted memory for AI agents over MCP. One memory shared by all your agents.
Persistent personal memory for AI assistants — save, search, and recall across every MCP client.
Persistent memory for AI agents to retain, retrieve, and recall conversation context through MCP.
Related MCP Servers
- AlicenseAqualityCmaintenanceA production-grade long-term memory MCP server that enables AI agents to persist and recall memories across sessions with importance weighting, confidence calibration, and efficient context window management.918 PyPI1MIT
- AlicenseNot gradedqualityCmaintenanceA lightweight MCP server that provides long-term memory for LLMs by storing and retrieving important facts, decisions, and preferences through smart semantic search and automatic organization.12MIT
- AlicenseAqualityBmaintenanceA long-term memory MCP server for AI agents that stores memories (facts, decisions, etc.) in a single SQLite database with hybrid search and full edit history, ensuring consistency across sessions.43MIT
- AlicenseAqualityDmaintenanceMCP server for persistent, semantic memory across AI sessions; store context, decisions, and learnings and recall them with natural language search.238 npmMIT