Skip to main content
Glama

@kireo/mcp-server

Long-term memory for any MCP-compatible AI tool (Claude Code, Cursor, Windsurf, Cline, Zed, Continue …).

npm version

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-mcp

Every 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

.mcp.json in the project root (or use the claude mcp add line above)

Cursor

~/.cursor/mcp.json, or <workspace>/.cursor/mcp.json for one repo

Cline

MCP Servers → Configure MCP Servers (cline_mcp_settings.json)

Claude Desktop

claude_desktop_config.json (Settings → Developer → Edit Config)

Windsurf

~/.codeium/windsurf/mcp_config.json

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

  1. Get an API key at https://app.kireo.app/app/api-keys (ki_sk_…).

  2. 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-mcp

Two 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, so npx -y @kireo/mcp-server cannot pick one and fails with could not determine executable to run.

  • --package=, not the short -p. A bare -p after -- gets swallowed by the claude mcp add option parser, which then rejects its own flag: claude mcp add kireo --env … -- npx -y -p @kireo/mcp-server kireo-mcp errors with unknown 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" }
    }
  }
}
  1. Restart the host. You now have 12 tools available to the AI:

Tool

Purpose

memory_save

Persist a long-term memory

memory_search

Hybrid semantic + keyword search

memory_recall

Replay recent/important memories

memory_get

Fetch by id

memory_update

Patch fields

memory_delete

Soft/hard delete

memory_list_namespaces

Enumerate namespaces

memory_health

Probe service

Configuration

Sources are merged in order: CLI args > env > ~/.kireo/config.json.

ENV / CLI

Default

Description

KIREO_API_KEY / --api-key

required

Bearer token (ki_sk_…).

KIREO_API_URL / --api-url

https://api.kireo.app

Override for self-host.

KIREO_REQUEST_TIMEOUT_MS / --timeout

60000

Per-request timeout in ms, max 300000 (env alias: KIREO_TIMEOUT_MS).

KIREO_RETRY_MAX_ATTEMPTS

3

5xx/429 retries (alias: KIREO_RETRY_MAX).

KIREO_RETRY_BASE_MS

200

Exponential backoff base.

KIREO_TELEMETRY

1

Set to 0 to disable device-id header.

KIREO_LOG_LEVEL

info

debug / info / warn / error / silent.

KIREO_PROXY_URL

none

HTTP(S) proxy.

KIREO_ACCEPT_LANGUAGE

en

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-app

Indexing is incremental — only changed files are re-sent on subsequent runs.

Flag

Default

Description

--repo <name>

directory basename

Repo name → code-<name> namespace.

--batch-size <n>

100

Symbols per upload batch (1..100). Lower it if a batch times out.

--timeout <ms>

60000

Per-request timeout (max 300000).

--api-key / --api-url / --namespace / --log-level / --no-telemetry

—

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.cjs to verify locally.

License

MIT

Available Tools

12 tools
context_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_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

    A4.4/5.0

    Scored across 12 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      A 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.
      9
      18 PyPI
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A 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.
      12
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      43
      MIT