Core Memory Kit

Persistent, per-project memory — plain markdown, committed with your code, recalled by meaning.

Claude forgets everything when a session ends — so every new chat you re-explain who you are, what you're building, and how you like things done. core-memory-kit fixes that: it quietly captures your decisions, preferences, and project context, then hands them back at the start of every session. Everything is plain text inside your project, and it travels with the code — git clone brings the memory along.

> [!NOTE] > Not a developer? > If you can open a project in Claude Code, you're set — let Claude run the setup for you (see [Quickstart](#quickstart)).

How it feels

You open Claude Code on a project you haven't touched in weeks. Before you say anything, Claude already knows your stack, your conventions, and what you decided last time:

core-memory-kit: 23 fact(s) in context, 2 captured in the last 24h, 1 conflict pending

You work. It learns — automatically, no buttons. Next session, it remembers this one too.

Features

• Remembers across sessions — a frozen snapshot of your project + persona injects once at session start, so Claude leads with what it knows instead of re-deriving it from code.
• Captures automatically, prompt-free — a background pass reads each turn and saves durable facts as searchable notes. No "save" button. When you do say "remember this," the kit auto-approves its own tools and skills so the save happens with no "Allow?" prompt — nothing else is touched.
• Recalls by meaning — ask in your own words ("where do credentials go") and get the right fact even with zero keyword overlap. Fully local, zero API calls — R@5 0.941 / paraphrase 1.000 ([benchmarks](#benchmarks)).
• Learns how you work, everywhere — state a habit once ("always use uv, never pip") and a brand-new project cold-opens already knowing it.
• Learns from outcomes — memory that keeps working ranks higher — the kit watches what happens after a memory is recalled (a failing command, you correcting the agent, the same question re-asked) and adjusts each fact's utility score. Once a fact has real evidence (3+ outcome signals), search ranking blends it in: a fact that keeps failing sinks below a healthy one for the same query — automatically, no command. A fact that's floored and still failing is never silently deleted: it lands in a review queue (cmk queue prune) where you choose — convert it into a ⚠️ AVOID anti-pattern warning (kept + injected, so the mistake isn't re-derived), forget it, or vouch for it. Judgments never auto-rank, and the session-start snapshot is untouched. And the whole process is observable: cmk stats memory-health reports writes-per-search, empty-search rate, redundant writes, and snapshot pressure with week-over-week trend arrows — so you can see the memory getting healthier (or tell when it isn't).
• Stays TRUE as it ages, not just stored — facts carry a temporal shape ("ongoing state" vs "happened once" vs "planned"), facts with a shelf life expire on their own (--expires 2026-08-01 → hidden from recall, recoverably archived), and a weekly pass catches state changes: when a newer fact supersedes an older one ("cut-gate in progress" → "published to npm"), the old state's validity window closes so recall answers with the current state — history intact, and the next session opens with a one-line note of what was resolved. And history questions reach the history: asking "what did we use before X" or "how did Y change" automatically pulls in the expired/superseded facts a normal search hides — each labeled ([superseded — kept for history] / [expired] / [retracted]) so the agent never mistakes history for the present; current facts stay unlabeled, zero noise.
• Stays private + bounded — secrets are screened before every committed-tier write — not just the ones you type, but the LLM-written summaries, transcript promotions, and trust upgrades too — machine paths are abstracted to ~, and rolling compression keeps memory small as history grows (and the nightly compression is resumable: if it's interrupted at 80%, it keeps the 80% and picks up where it left off, never re-doing finished work). Because context/ is committed to git, the kit also screens personal/sensitive content automatically: a deterministic pass masks emails / phone numbers / your username before anything touches disk, and an async judge catches names, addresses, and health details in prose — so a transcript lands screened, a sensitive fact routes to a gitignored local-only note, and nothing personal reaches a committed file (kill-switch: privacy.screen: off).
• Guards against accidental deletion — a hook blocks a destructive command (rm, git reset --hard, …) the moment it targets a memory path, before it runs.
• Works across your agents — the same memory brain on Claude Code, Kiro (IDE + kiro-cli), Cursor, and Codex. A project's context/ is shared, so memory you build in one is there in the others. The automatic engine runs through your agent's own CLI (using the login you already have — no extra API key). You can even split the brain: code in one agent, run the frequent background memory work through a cheaper one (cmk install --backend kiro → keep your premium subscription for coding, run the janitor LLM on kiro-cli). cmk config show tells you which agent is doing what.
• Per-project, in your repo — context/ lives in your project and travels with git clone. Each project keeps its own memory. And when uncommitted memory piles up, Claude offers a one-tap commit — you approve, Claude runs the git command; the kit itself never touches git.

Quickstart

> [!IMPORTANT] > Prerequisite — the agent's CLI must be installed (not just its IDE). The kit's automatic features (compression, the cross-project persona/wedge, auto-extract, the temporal sweep) run an LLM through your agent's command-line tool, which is a separate install from the IDE: > > | Agent | The kit needs this CLI on your PATH | > | --- | --- | > | Claude Code | the claude CLI — required even if you use Claude inside VS Code | > | Kiro | kiro-cli — required even if you use the Kiro IDE | > | Cursor | cursor-agent (Cursor's CLI) — required in addition to the Cursor app; runs natively on Windows, macOS, and Linux (install: curl https://cursor.com/install -fsS \| bash, or on Windows irm 'https://cursor.com/install?win32=true' \| iex), using your Cursor subscription login (no API key) | > | Codex | the codex CLI (npm i -g @openai/codex) — required even if you use the Codex desktop app (it bundles the binary off-PATH), using your ChatGPT/Codex login (no API key) | > > Without the agent's CLI, capture / search / recall / the delete-guard still work (they're pure files + SQLite), but the automatic LLM steps are skipped. cmk doctor tells you if your agent's CLI is missing. > > Pick one install route below — both wire the same hooks and are complete on their own.

Route A — npm (recommended)

Install the CLI once, then run cmk install in each project — pick your agent:

npm install -g @lh8ppl/core-memory-kit
cd ~/my-project

Claude Code:

cmk install                   # scaffold context/ + wire hooks (one step)
cmk install --with-semantic   # optional: local semantic recall (~260 MB, once)
cmk doctor                    # verify, then restart Claude Code

Kiro (IDE + kiro-cli — see [docs/KIRO.md](docs/KIRO.md)):

cmk install --ide kiro                   # wire Kiro end-to-end
cmk install --ide kiro --with-semantic   # …with local semantic recall
cmk doctor                                # verify, then restart Kiro

Cursor:

cmk install --ide cursor                 # wire Cursor end-to-end
cmk install --ide cursor --with-semantic # …with local semantic recall
cmk doctor                                # verify, then restart Cursor

Codex:

cmk install --ide codex                  # wire Codex end-to-end
cmk install --ide codex --with-semantic  # …with local semantic recall
cmk doctor                                # verify, then run /hooks once inside Codex to trust the kit's hooks

cmk install is the whole entry point: it scaffolds context/, drops the memory skills, wires the lifecycle hooks, and registers the MCP server so the agent can drive memory as tools — no /plugin step needed. A project can carry both agents — run both installs; they share one context/.

> [!TIP] > Prefer not to touch the terminal? Open the project in Claude Code and say "install core-memory-kit and set it up here." Claude runs the commands; you just approve them. Restart Claude Code once afterward (/exit, then claude) so the hooks load.

Route B — Claude Code plugin

/plugin marketplace add LH8PPL/core-memory-kit   # add this repo as a plugin source (once per machine)
/plugin install core-memory-kit                  # install hooks + skills (once per machine)
cd ~/my-project
/core-memory-kit:bootstrap                        # scaffold this project's memory (once per project)

The plugin bundles the hooks + skills, so it's complete without the npm CLI. Add the CLI later only if you want cmk search / cmk doctor / cron.

Full walkthrough: [QUICKSTART.md](QUICKSTART.md). Both routes are verified on Windows / macOS / Linux in CI.

> [!NOTE] > Updating has two parts on both routes: update the machinery, then re-stamp each project (cmk install again, or /core-memory-kit:bootstrap). cmk doctor flags any project that's behind so you don't have to remember. Full steps in [QUICKSTART.md](QUICKSTART.md).

How it works

context/ is the source of truth — plain markdown, committed with your code. A regenerable SQLite + FTS5 index (plus an optional local embedder) powers search. Memory lives in three tiers:

| Tier | Location | Scope | What lives here | | --- | --- | --- | --- | | Project | /context/ | committed — travels with clone | Decisions, conventions, file purposes | | Local | /context.local/ | gitignored, per-machine | Machine paths, local tool versions | | User | ~/.core-memory-kit/ | cross-project, per-person | Persona, cross-project lessons |

Project memory follows the repo (teammates get it on clone). Your persona follows you — machine-local, never committed, so your working style never leaks to everyone who clones. Carry it between your own machines with cmk persona export / import.

The kit is built in six layers (in-repo storage → granular archive → bounded scratchpads → auto-extract hooks → search → compression). See [ARCHITECTURE.md](ARCHITECTURE.md) for the breakdown + data-flow diagram, [specs/design.md](specs/design.md) for the full design, and [specs/glossary.md](specs/glossary.md) for terminology.

CLI

You rarely type these yourself — Claude drives the same operations as tools mid-conversation through the kit's MCP server (see [docs/MCP.md](docs/MCP.md)). The most-used commands:

| Command | Purpose | | --- | --- | | cmk install [--with-semantic] [--ide claude-code\|kiro\|cursor\|codex] | Scaffold + wire hooks + register the MCP server (complete entry point) | | cmk uninstall [--ide claude-code\|kiro\|cursor\|codex] | Remove one agent's wiring — conservative, never deletes context/ | | cmk search "" [--mode keyword\|semantic\|hybrid] [--scope facts\|transcripts\|decisions] | Search memory by meaning; --scope decisions recalls how a decision evolved | | cmk remember "" | Capture a fact explicitly (deduped, secret-screened, path-abstracted) | | cmk forget | Tombstone a fact (audit trail preserved) | | cmk redact --pattern | Compliance scrub: remove a leaked secret from the fact + every archive copy + indexes, audit kept (prints the honest git-history advisory) | | cmk purge --hard --yes | Irreversible whole-fact delete — no tombstone; the compliance escalation beyond forget | | cmk lessons promote | Carry one project fact into your cross-project user tier | | cmk doctor | Run health checks; surface a repair command per failure |

There's more — cmk register-crons, cmk config, cmk persona generate/export/import, cmk repair, and the rest. Full reference: [docs/CLI.md](docs/CLI.md) or cmk --help.

Working with Kiro

Kiro (the AWS agentic IDE + kiro-cli) is a first-class target — cmk install --ide kiro wires it end-to-end for both the IDE and the terminal, and a project's context/ is shared with Claude Code. The full setup, surface table, and dual-agent notes are in [docs/KIRO.md](docs/KIRO.md).

Working with Cursor

Cursor removed its native Memories feature (2.1.x) — static rules are its only built-in persistence. cmk install --ide cursor restores the full automatic loop: recalled memory injects at session start (sessionStart → additional_context), each turn is captured at afterAgentResponse, edits are observed, the delete-guardrail screens shell commands (beforeShellExecution), and an always-applied rule (.cursor/rules/core-memory-kit.mdc) points the agent at the recall surface. All hooks drive one dispatcher (cmk cursor-hook) and are wired into .cursor/hooks.json without touching your own hooks. Restart Cursor after install so the hooks load. The full setup, surface table, backend, and dual-agent notes are in [docs/CURSOR.md](docs/CURSOR.md).

Working with Codex

Codex gets the same automatic loop via its first-class hooks system: cmk install --ide codex wires .codex/hooks.json (SessionStart recall-inject, UserPromptSubmit prompt-capture, Stop turn-capture read from the session's rollout file, PostToolUse edit-observation, PreToolUse delete-guardrail), registers the MCP server through Codex's own codex mcp add (your config.toml is never hand-edited), and drops a managed AGENTS.md block. All hooks drive one dispatcher (cmk codex-hook). One-time step: Codex hash-trusts hooks — run /hooks once inside Codex and trust the kit's entries, or the hooks stay silent. The background LLM work runs through codex exec (read-only sandbox, your existing ChatGPT/Codex login). Full setup + notes: [docs/CODEX.md](docs/CODEX.md).

Uninstalling

cmk uninstall is conservative — it removes only the kit's managed wiring for one agent and never deletes your context/ memory (your data) or anything outside the kit's markers.

Claude Code:

cmk uninstall              # remove the CLAUDE.md block + hooks

Kiro:

cmk uninstall --ide kiro   # remove the .kiro/ blocks + skills + IDE hooks + AGENTS.md + ~/.kiro CLI agent

Cursor:

cmk uninstall --ide cursor # remove the kit's hooks.json events + mcp.json entry + .mdc rule

Codex:

cmk uninstall --ide codex  # remove the kit's hooks.json events + the AGENTS.md block + codex mcp remove

On a dual-agent project, uninstall one and the other keeps working. To remove the memory data too, delete context/ (and context.local/) yourself — the kit won't do it for you.

Benchmarks

Recall quality is measured, not claimed — npm run bench:recall runs a LongMemEval-style harness through the kit's real write / index / search paths.

| Pipeline | R@5 | Paraphrase recall | API calls | | --- | --- | --- | --- | | Keyword (FTS5 one-shot) | 0.176 | 0.000 | 0 | | Agentic keyword (iterative + LLM reformulation) | 0.529 | 0.300 | 1/query | | Semantic (sqlite-vec + local bge-base, the default) | 0.941 | 1.000 | 0 |

Keyword search structurally misses natural-language questions; the emb

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: LH8PPL
• Source: LH8PPL/core-memory-kit
• License: MIT

Install and usage instructions live in the source repository linked above.