Add persistent memory to Claude Code

Install

You need Node 20 or newer on PATH (the package declares "node": ">=20.0.0") and a key shaped ki_sk_…. This is the exact one-liner that was run end to end against claude 2.1.220 on 2026-08-03 — copy it verbatim, including --package=, and read gotcha 1 before you shorten it.

Claude Code prints Added stdio MCP server kireo with command: npx -y --package=@kireo/mcp-server kireo-mcp to user config and writes the entry into ~/.claude.json. There is no third file to edit by hand: this CLI touches ~/.claude.json for local and user scope, and .mcp.json at the repository root for project scope.

Then confirm it actually connected. "Added" and "connected" are two different events, and only the second one means the tools exist:

Where this sits next to CLAUDE.md and auto memory

Claude Code already ships two memory surfaces, and Anthropic's documentation presents them as complementary rather than competing: CLAUDE.md is written by you and holds instructions and rules, while auto memory is written by Claude and holds learnings and patterns (code.claude.com/docs/en/memory, checked 2026-08-03). Both are on by default and cost nothing. Installing the Kireo memory MCP does not replace either.

What it adds is a third property neither file has. The same documentation states plainly: "Auto memory is machine-local. All worktrees and subdirectories within the same git repository share one auto memory directory. Files are not shared across machines or cloud environments." CLAUDE.md crosses machines the moment you commit it, but only as text you maintain by hand — the docs suggest keeping each file under 200 lines because longer files consume more context and reduce adherence, and @path imports do not help, since imported files load at launch too.

If your only problem is "auto memory does not follow me between machines", try the official autoMemoryDirectory setting first — it points the auto memory directory at any absolute path, including a synced drive, and costs you nothing. The longer version of this comparison, including where each approach genuinely wins, is in CLAUDE.md vs a memory MCP.

The eight tools 8

Read off packages/mcp-server/src/tools/index.ts on 2026-08-03, in registration order. A live tools/list against the published package returned the same eight names, character for character. Every schema is strict: an unknown field is rejected with InvalidParams, not silently dropped.

memory_savecontent required

Writes one memory. content is 1–8,000 characters; type is one of fact, decision, preference, event, goal, insight, relationship, other (default fact); optional namespace (default "default"), up to 20 entities, up to 10 tags, importance 0–1, occurred_at, and metadata capped at 2,048 bytes once serialised. Returns { id, created_at, schema_version, embedding_status } — not the full record.

memory_searchquery required

Hybrid ranked retrieval. query is 1–2,000 characters; limit defaults to 10 and caps at 50. Omitting namespace searches every namespace you own, which is usually what you want when you cannot remember which project a decision belongs to.

memory_recallno required fields

Browses a namespace instead of searching it. namespace defaults to "default", limit defaults to 20 and caps at 50, order is recency or importance, and since takes an ISO-8601 timestamp.

memory_getid required

Fetches one full record by id. The id must match ^mem_[A-Za-z0-9]+$ — the same shape memory_save handed back.

memory_updateid + at least one field

PATCH semantics: only the fields you pass change. Passing nothing but id is rejected with "Provide at least one field besides id".

memory_deleteid required

Soft delete only. A hard flag is accepted for compatibility and ignored; the memory stays recoverable for 30 days, then is purged automatically.

memory_list_namespacesno input

Returns { name, created_at } per namespace — names and creation times, no per-namespace counts.

memory_healthno input

Returns { local: { server_version, node_version, platform }, remote: { status } }. This is the fastest way to tell "the server never started" apart from "the server started and the API is unreachable".

Three Claude Code gotchas

All three are properties of the claude CLI and its scope model. None of them apply to clients that read a JSON file directly. Everything below was reproduced against claude 2.1.220 on 2026-08-03 and has not been regression-tested against other versions.

1. A bare -p after -- breaks the command

The npm package ships two binaries, kireo and kireo-mcp, so npx cannot infer an executable from the package name and needs to be told which one to run. The natural way to say that is -p @kireo/mcp-server — and that is exactly the token Claude Code's own parser grabs, after which it rejects the flags you passed it:

The same command fails with unknown option '-e' or unknown option '--scope' depending on which flag you used first. Swapping -p for npx's long form --package= makes the identical command succeed.

Dropping the flag entirely is worse than an error, because it looks like success. The CLI accepts the entry and writes it to your config; only claude mcp list reveals that it never starts:

If you would rather not think about the parser at all, claude mcp add-json skips option parsing completely, and inside JSON the short -p is perfectly fine:

2. The default scope is local, and a stale local entry hides everything else

claude mcp add --help spells it out: -s, --scope <scope> is (default: "local"). Install without a scope and claude mcp get kireo reports Scope: Local config (private to you in this project). The tools then vanish the moment you open a different repository — which reads as "the memory server broke", not "the memory server was only ever installed here".

The second half of this is nastier. Claude Code resolves same-named servers by precedence — local, then project, then user — and "the entire server entry from that source is used; fields are not merged across scopes" (code.claude.com/docs/en/mcp, checked 2026-08-03). So one forgotten local kireo entry from an earlier experiment completely shadows the correct user-scope entry you added later, including its key. If claude mcp list shows a command line you do not recognise, clear the local one with claude mcp remove kireo before you debug anything else.

3. Project scope needs approval, and ${VAR} fails quietly

--scope project writes .mcp.json at the repository root — the right choice for a team, because everyone gets the same tools from source control. It does not connect straight away, though: claude mcp list shows ⏸ Pending approval (run `claude` to approve), because Claude Code asks each person before it will run a server defined by a checked-in file (code.claude.com/docs/en/mcp, checked 2026-08-03; claude mcp reset-project-choices resets those answers). This is the file Claude Code writes, note the explicit "type": "stdio":

When it says "Failed to connect"

Configuration errors kill the process before the MCP handshake, and they are written to stderr only — which is why the host shows a bare connection error and nothing useful. The two you will actually hit:

• No key at all → [kireo-mcp] fatal: Error: Invalid Kireo configuration: KIREO_API_KEY (apiKey): Required, exit 1.
• Wrong shape (an OpenAI-style sk-… key, say) → KIREO_API_KEY must look like ki_sk_xxx.

For anything past that, read the rolling log files. They live in ~/.kireo/logs/ on all three platforms, but the writer appends a numeric suffix, so the real filenames are mcp-server.log.1, .log.2 and .log.3 — there is no plain mcp-server.log to cat. Raising KIREO_LOG_LEVEL=debug is safe over stdio: logs go to those files plus a warn-level stderr stream, and stdout is reserved for JSON-RPC, so debug logging cannot corrupt the session.

Index the repo you already have open

Claude Code runs in the terminal, so the code indexer runs in the same place — no editor UI, no extension. Point it at the repository you are already in and it uploads extracted symbols into a code-<repo> namespace, which memory_search can then reach from any MCP client, not just this one. This one runs in a plain shell rather than through claude mcp add, so the short -p from gotcha 1 is fine here:

Re-running is safe and incremental — a local .kireo/index-state.json holds a SHA-256 per file and only changed files are re-extracted, while the server deduplicates on (namespace, content_hash).

For a sense of scale, here is this site's own monorepo, measured on 2026-08-03. This covers the local half only — directory walk plus tree-sitter extraction, with no upload and no embedding: 336 source files totalling 1,371,357 bytes, from which 213 symbols were extracted (184 functions, 4 classes, 25 methods), in 486–653 ms across three runs. The derived namespace was code-lancedb_sass. Upload and embedding time is not included in that figure and was not measured.

The gap between 336 files and 213 symbols is worth understanding before you conclude something is missing. In this version the TypeScript rules match function_declaration, class_declaration and method_definition only, so export const foo = () => {} is not extracted; .vue single-file components are not indexed at all (38 of them at the time this was measured — this page is itself one, so the count has grown since; none appear in the output); and the walker skips node_modules, dist, .venv, .git and .kireo on top of your .gitignore, along with symlinks, binaries and any file over 1,000,000 bytes.

FAQ