LH8PPL/core-memory-kit

<p align="center" <picture <source media="(prefers-color-scheme: dark)" srcset="docs/public/assets/wordmark-dark.svg" <img src="docs/public/assets/wordmark.svg" alt="core-memory-kit" width="340" </picture </p

<p align="center" <strongPersistent, per-project memory — plain markdown, committed with your code, recalled by meaning.</strong </p

<p align="center" <a href="https://www.npmjs.com/package/@lh8ppl/core-memory-kit"<img src="https://img.shields.io/npm/v/@lh8ppl/core-memory-kit?label=npm&color=blue" alt="npm"</a <a href="LICENSE"<img src="https://img.shields.io/badge/license-MIT-yellow" alt="License: MIT"</a <img src="https://img.shields.io/badge/Node.js-bundled%20%C2%B7%20none%20required-brightgreen" alt="Node.js bundled, none required" <a href="https://github.com/LH8PPL/core-memory-kit/actions/workflows/ci.yml"<img src="https://github.com/LH8PPL/core-memory-kit/actions/workflows/ci.yml/badge.svg" alt="CI"</a </p

<p align="center" <img src="https://img.shields.io/badge/Windows-supported-0078D6?logo=windows&logoColor=white" alt="Windows supported" <img src="https://img.shields.io/badge/macOS-supported-000000?logo=apple&logoColor=white" alt="macOS supported" <img src="https://img.shields.io/badge/Linux-supported-FCC624?logo=linux&logoColor=black" alt="Linux supported" </p

<p align="center" <img src="https://img.shields.io/badge/ClaudeCode-supported-6E56CF" alt="Claude Code supported" <img src="https://img.shields.io/badge/Kiro-supported-6E56CF" alt="Kiro supported" <img src="https://img.shields.io/badge/Cursor-supported-6E56CF" alt="Cursor supported" <img src="https://img.shields.io/badge/Codex-supported-6E56CF" alt="Codex supported" </p

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?<br 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 of your project + persona injects once at session start, so Claude leads with what it knows instead of re-deriving it from code.
• Tells live knowledge from finished work — the injected snapshot labels its in-flight sections (Active Threads, Pending Decisions) as work-state-as-last-captured, so an agent resuming your project won't re-run a task that already shipped. Durable facts keep their full authority.
• Starts with a memory, not from zero — cmk import-sessions bootstraps the memory from your existing Claude Code history: past sessions are summarized into dated memory ("as if captured live"), screened for secrets/PII before anything lands in a committed file, and searchable immediately. cmk install detects existing history and offers it (one question, default-skip). Resumable — a killed run keeps its progress, and a re-run imports only new sessions.
• 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.
• Keeps capturing even when the extractor fails — if the background pass times out or errors, capture doesn't silently drop the turn: a deterministic no-LLM fallback keeps your durable statements, routed through the normal review queue and tagged with its own provenance so a heuristic capture is never mistaken for a real one. Memory degrades to partial, never to nothing.
• Fills in the days it missed, from your git history — if a session crashed, a hook misfired, or you spent the day in another tool and only committed, that day had work but no memory of it. Measured on this repo, that was 37% of working days. The kit now notices those gaps and rebuilds a short log of what you did from that day's commits — automatically, on the nightly pass, no command to remember. A reconstruction is marked as one rather than passed off as a captured session, and a real session log is never overwritten. cmk backfill --dry-run shows the gaps if you want to look first.

• Survives a long session, not just a clean exit — when the agent compacts its context mid-session (the marathon case), the kit rolls the session buffer right then. Until now the roll had only two triggers, and neither fires during a session: a clean window-close (which a long session often never gets) and the next session's start (too late to help this one). Nothing was ever lost — the buffer is on disk from the first turn — but it could sit unconsolidated for days. The compaction handler gates in milliseconds and hands the work to a background pass, so your compaction never waits on memory.
• 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). And a hit isn't a dead end: cmk expand returns the neighborhood around it (the rest of its section in the source file) — the recall ladder's middle rung between a search hit and a raw-transcript drill.
• 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.
• Rescues memory an older version stranded — upgrading isn't only forward-looking. If a past version left an orphaned context/ folder in a subdirectory (a real bug, fixed in v0.6.2 — automatic capture forked a second, unread copy when the agent ran from a subfolder), the next cmk install finds it and brings those facts back into your project's memory with their original ids and dates intact, skipping anything already there and never resurrecting something you forgot. The old folder is left untouched with a delete command printed for your shell — deleting memory is always your call, never the kit's.
• 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.
• Shows you around — cmk tour (or /tour in conversation) walks you through YOUR memory: what's been captured, where it lives, how to get it back — real counts and your own fact titles, never invented examples.

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)