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).

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 · snapshot 4812 B

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

Features

• Remembers across sessions — a frozen snapshot injects at session start, so Claude leads with what it knows.
• Captures automatically — a background pass saves durable facts from each turn. No save button, no prompt.
• Recalls by meaning — ask in your own words; no keyword overlap needed. Fully local, zero API calls.
• Learns how you work — state a habit once, and every new project cold-opens knowing it.
• Learns from outcomes — facts that keep failing sink in ranking; you decide whether to keep or prune.
• Links related facts — cmk autolink proposes up to 3 related: edges per fact; opt-in write-time linking does it as you capture.
• Stays true as it ages — facts expire, supersede, and keep their history labelled rather than lost.
• Stays private — secrets, personal data and machine paths are screened before every committed write.
• Guards your memory — destructive commands aimed at a memory path are blocked before they run.
• Tells you when it is broken — a real failure surfaces on your next prompt, naming the fix.
• Fixes itself, with your say-so — cmk doctor --repair offers each fix [y/N]; deletes stay yours to run.
• Lets you SEE your memory — cmk view opens a read-only browser view: search, graph, health, decisions. Updates live as you capture.
• Works across your agents — Claude Code, Kiro, Cursor and Codex share one project memory.
• Per-project, in your repo — context/ lives in your project and travels with git clone.

Full feature detail → — what each one actually does, and why it works that way.

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):

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

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	<repo>/context/	committed — travels with clone	Decisions, conventions, file purposes
Local	<repo>/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 for the breakdown + data-flow diagram, specs/design.md for the full design, and specs/glossary.md for terminology.

Browse it in Obsidian

Your memory is plain markdown, so Obsidian opens context/memory/ as a vault — search, backlinks, and a graph view of your facts, no export step. Browsing is free and safe; keep writing through the kit (cmk remember / your agent) so secret-screening, path-abstraction, and the audit trail stay intact. Walkthrough: docs/OBSIDIAN.md.

The four memory types, in kit terms

If you know the standard agent-memory taxonomy (working / semantic / episodic / procedural), the kit implements all four:

Memory type	What it holds	Where the kit keeps it
Working	the current session's live state	MEMORY.md scratchpad + sessions/now.md (bounded, cap-managed)
Semantic	durable facts — decisions, preferences, config	the fact archive context/memory/ + USER.md (typed, with Why/How)
Episodic	what happened, when	the rolling session window (today-* → recent → archive) + verbatim transcripts
Procedural	how to work — habits, lessons, judgment	HABITS.md / LESSONS.md + judgment records + the scaffolded skills

And the taxonomy's classic pitfalls each have a built-in answer: re-asking (over-trimmed working memory) → load-caps with graduation, not truncation; contradictory retrieval (facts and events in one undifferentiated store) → facts and session logs are separate stores, and non-current facts come back labeled ([superseded] / [expired]); corrupted semantic memory (no write-time validation) → every write passes dedup + the conflict queue + the Poison_Guard screen; procedural memory that never improves (storing replays, not lessons) → the distill chain keeps lessons, and the learn-loop scores what keeps working.

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). 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/