# Core Memory Kit > Persistent per-project memory for Claude Code, Kiro, Cursor & Codex - plain markdown committed with your code, captured prompt-free, auto-injected at session start, recalled by meaning (local semantic search, zero API). Cross-project persona, cited recall, searchable session history. - **Type:** MCP server - **Install:** `agentstack add mcp-lh8ppl-core-memory-kit` - **Verified:** Pending review - **Seller:** [LH8PPL](https://agentstack.voostack.com/s/lh8ppl) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [LH8PPL](https://github.com/LH8PPL) - **Source:** https://github.com/LH8PPL/core-memory-kit ## Install ```sh agentstack add mcp-lh8ppl-core-memory-kit ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About 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](https://kiro.dev)** (IDE + `kiro-cli`), **[Cursor](https://cursor.com)**, and **[Codex](https://developers.openai.com/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: ```bash npm install -g @lh8ppl/core-memory-kit cd ~/my-project ``` **Claude Code:** ```bash 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)): ```bash 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:** ```bash 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:** ```bash 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 ```text /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](https://kiro.dev) (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](https://cursor.com) 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](https://developers.openai.com/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:** ```bash cmk uninstall # remove the CLAUDE.md block + hooks ``` **Kiro:** ```bash cmk uninstall --ide kiro # remove the .kiro/ blocks + skills + IDE hooks + AGENTS.md + ~/.kiro CLI agent ``` **Cursor:** ```bash cmk uninstall --ide cursor # remove the kit's hooks.json events + mcp.json entry + .mdc rule ``` **Codex:** ```bash 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](https://github.com/LH8PPL) - **Source:** [LH8PPL/core-memory-kit](https://github.com/LH8PPL/core-memory-kit) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-lh8ppl-core-memory-kit - Seller: https://agentstack.voostack.com/s/lh8ppl - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.