Doramagic Project Pack · Human Manual
claude-memory-kit
Persistent per-project memory for Claude Code — plain markdown committed with your code, captured automatically every turn, recalled by meaning (local semantic search, zero API). Cross-project persona, cited recall, and a searchable session record down to raw transcripts.
Overview & Three-Tier Architecture
Related topics: Memory Lifecycle: Capture, Compression, Recall, Installation & Multi-Agent Wiring (Claude Code and Kiro)
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Memory Lifecycle: Capture, Compression, Recall, Installation & Multi-Agent Wiring (Claude Code and Kiro)
Overview & Three-Tier Architecture
Purpose and Scope
claude-memory-kit is a per-project, in-repo memory system for Claude Code. It addresses the model’s per-session amnesia by persisting *intent* — conventions, decisions, tool quirks, and user style — as plain markdown that travels with the repository, plus a machine-local *persona* tier that travels with the user. The system is delivered as a monorepo with a published CLI package (@lh8ppl/claude-memory-kit, currently 0.4.0) and a small canonicalization helper package (@lh8ppl/cmk-canonicalize, 0.1.0) that guarantees byte-identical text canonicalization across Node and Python runtimes (packages/canonicalize/package.json:9-13). Source: packages/canonicalize/package.json:9-13.
The kit’s headline guarantee is that memory lives *with the code* — context/ is committed, the persona tier is local — and that recall works "by meaning" rather than by exact keyword, with a measured R@5 of 0.941 on a LongMemEval-style benchmark using a local ONNX embedder and sqlite-vec (README.md).
The Three Tiers
The architecture organises memory into three scopes. The split is described in the project documentation: project memory follows the repo (every teammate gets it on git clone), while persona follows the user and is machine-local so working style never leaks to a fresh clone. The third tier is the session — the live scratchpad and frozen snapshot that bookend each conversation.
| Tier | Lives in | Travels with | Purpose |
|---|---|---|---|
| Project | context/ inside the repo | git clone (committed markdown) | Project-specific facts, decisions, conventions |
| User / Persona | ~/.claude-memory-kit/ | The user (never committed) | Cross-project lessons, personal style |
| Session | The repo’s context/scratch/ + the frozen snapshot at session start | Auto-generated per session | Live buffer, auto-extracted facts, daily/weekly rollup targets |
Source: README.md and packages/cli/README.md.
A simple view of the flow:
flowchart LR Turn[Assistant turn] -->|auto-extract| Buf[Session buffer] Buf -->|Haiku rollup| Daily[Daily distill] Daily -->|Haiku rollup| Weekly[Weekly curate] Buf -->|lazy-on-read| Proj[Project context/] User[User statement] -->|promote| Persona[~/.claude-memory-kit/] Proj -->|frozen snapshot| Inject[Session-start inject] Persona --> Inject Inject --> Claude[Claude Code]
Per-turn auto-extract writes durable facts into the project tier; a user statement like *"always use uv, never pip"* is promoted into the persona tier the same turn, so a brand-new project cold-opens already knowing the user’s style. Source: packages/cli/README.md:7-21.
Background Lifecycle and Compression
Memory is kept bounded by a layered compression pipeline: session → daily → weekly, with a lazy-on-read fallback so the system self-heals even when no scheduler is installed. The CLI ships dedicated entry points for each stage, declared as separate binaries in packages/cli/package.json:
cmk-compress-session— in-session rollup, time-limitedcmk-compress-lazy— session-start catch-up roll, lazy-on-readcmk-daily-distill— daily jobcmk-weekly-curate— weekly job
Source: packages/cli/package.json:11-21.
v0.3.5 fix (community context): the lifecycle compression jobs that run with no time limit (daily distill, weekly curate, the session-start catch-up roll) were previously using the same 50-second budget as the in-session compressor and retrying too quickly. A slowclaude --printwindow could therefore time out and skip a rollup, leavingrecent.md/ the archive stale. v0.3.5 gives the no-time-limit jobs a fitting budget and gentler retry so background memory compression no longer fails needlessly.
When cron is unavailable, compression degrades gracefully to lazy-on-read at session start, so memory stays bounded without any scheduler. Source: README.md:FAQ.
Distribution Surfaces
The monorepo publishes two primary artifacts and ships a third for the Claude Code plugin marketplace:
- npm package —
npm install -g @lh8ppl/claude-memory-kitfollowed bycmk installin the project.cmk installis the complete entry point: it scaffoldscontext/, drops thememory-write+memory-searchskills into.claude/skills/, writes 5 lifecycle hooks (PATH-resolved, cross-OS) into.claude/settings.json, registers the MCP server in.mcp.json, and allow-lists its tools. Source:packages/cli/README.md:29-50. - Plugin distribution —
/plugin marketplace add …then/plugin install claude-memory-kit, then/claude-memory-kit:bootstrapper project. The plugin provides its ownhooks/hooks.json(PreToolUse for context injection, Stop for capture + auto-extract) and thememory-write/bootstrapskills. It does *not* modify.claude/settings.jsonand does *not* register cron. Source:plugin/README.md:7-19. - MCP server — registered on
cmk install, allows Claude to drive capture, recall, trust adjustment, forgetting, and queue resolution as tools (mk_remember,mk_search,mk_get,mk_timeline,mk_cite,mk_trust,mk_forget,mk_queue_list,mk_queue_resolve) without per-call prompts. Source:packages/cli/README.md.
See Also
- CLI reference — full command surface
- MCP server reference — tool contracts
- Health checks —
cmk doctorHC-1..HC-9 - Security model — delete-guardrail + secret screening
- ADR-0015 — semantic backend choice
Source: https://github.com/LH8PPL/claude-memory-kit / Human Manual
Memory Lifecycle: Capture, Compression, Recall
Related topics: Overview & Three-Tier Architecture, Installation & Multi-Agent Wiring (Claude Code and Kiro), Safety, Delete-Guardrail, Health Checks & Failure Modes
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Overview & Three-Tier Architecture, Installation & Multi-Agent Wiring (Claude Code and Kiro), Safety, Delete-Guardrail, Health Checks & Failure Modes
Memory Lifecycle: Capture, Compression, Recall
Overview
claude-memory-kit runs a three-stage memory lifecycle — Capture, Compression, Recall — implemented as a set of small, composable CLIs wired into Claude Code and (optionally) Kiro. Each stage owns a narrow responsibility: capture writes durable facts, compression keeps the store bounded as history grows, and recall surfaces those facts to the agent at the right moment. The lifecycle is bounded by design: there is no central daemon; every stage is a short-lived process spawned by a hook, a skill, or a cron entry, so nothing accumulates in memory and a crash in one stage cannot wedge a session.
The lifecycle also coexists with Anthropic's native auto-memory and can import its bullets through cmk import-anthropic-memory (Source: packages/cli/README.md). Source: packages/cli/package.json:1-50 declares every lifecycle binary that cmk install PATH-resolves and wires into .claude/settings.json.
Capture
Capture has two entry points that share the same safe write path (deduplication, secret screening, machine-path abstraction, provenance stamping).
- Automatic background pass — after every turn, the Stop hook reads the transcript and spawns
cmk-capture-turn(binary:cmk-capture-turn). That binary callscmk-capture-prompt(binary:cmk-capture-prompt), which sends a single Haiku call to extract durable facts, decisions, conventions, and tool quirks. The result lands incontext/as<type>_<slug>.mdfiles with content-addressed IDs. Source: plugin/README.md:18-22 describes the Stop hook that triggers this. - Explicit in-conversation capture — phrases like "remember this", "from now on", "we decided", "forget X" trigger the
memory-writeskill, exposed as/claude-memory-kit:memory-write(Source: plugin/README.md:23-24). The same surface is reachable from the shell ascmk remember "<fact>"or, for backtick/quote-heavy rich facts,cmk remember --from-file fact.jsonso the content never touches the shell (Source: README.md).
A fact whose pattern is "how *I* work" is promoted to the user tier (~/.claude-memory-kit/) on the same turn, so a brand-new project cold-opens already knowing the user's working style (Source: packages/cli/README.md).
A PreToolUse hook (cmk-guard-memory) blocks destructive commands (rm, Remove-Item, del, git clean, git reset --hard, find … -delete, truncate, >-truncate) aimed at a memory path before they run — on Claude Code's Bash/PowerShell and Kiro's execute_bash. It is intentionally fail-open and broad: a false block is recoverable, a false allow is the data loss it prevents (Source: README.md).
Compression
Compression is tiered, with each tier rolling older material up into denser summaries. Every binary is registered in packages/cli/package.json as a standalone executable (Source: packages/cli/package.json:8-19):
| Tier | Binary | Trigger | Purpose |
|---|---|---|---|
| Session | cmk-compress-session | mid-session, run by cmk-capture-turn | roll the session buffer into recent.md |
| Lazy | cmk-compress-lazy | session start, fallback | catch-up roll when no scheduler is installed |
| Daily | cmk-daily-distill | cron / launchd / Task Scheduler | distill yesterday's session logs into daily notes |
| Weekly | cmk-weekly-curate | cron / launchd / Task Scheduler | curate weekly notes into long-term facts |
Manual triggers exist for the same paths: cmk roll --scope now|today|recent re-runs any of them on demand (Source: packages/cli/README.md).
v0.3.5 fix — background compression no longer fails on slow Claude windows
The lifecycle compression jobs that run with no time limit (daily distill, weekly curate, the session-start catch-up roll) were previously sharing the in-session compressor's 50-second budget and retrying too quickly. A slow claude --print window could therefore time out and leave recent.md and the archive stale. v0.3.5 separates the budgets so the background jobs run with a longer timeout and a more forgiving retry policy, and recent.md plus the archive now stay fresh even when Claude is slow (Source: community context, v0.3.5 release notes).
This makes the lazy-on-read fallback meaningful: even if cron is unavailable, the session-start catch-up roll now has the time it needs to actually finish (Source: README.md, FAQ).
Recall
Recall has three surfaces that read from the same store, so a fact written by any capture path is reachable from any of them:
- Frozen snapshot at session start —
cmk-inject-context(binary:cmk-inject-context) writes a one-shot read ofSOUL.md+USER.md+MEMORY.md+INDEX.md+ today's session log into the conversation, so Claude leads with what it already knows (Source: plugin/README.md:16-17; binaries registered at packages/cli/package.json:12). - Shell search —
cmk search "<query>"runs keyword search by default; with the optional local embedder installed viacmk install --with-semantic, the default flips to hybrid (semantic + keyword).--scope transcriptssearches the raw session record;--scope decisionssearches the decision journal. Benchmarked R@5 is 0.941 with paraphrase recall 1.000, zero API calls (Source: README.md, Benchmarks). - MCP tools —
cmk installregisters the kit's MCP server in.mcp.jsonand allow-listsmcp__cmk__*in.claude/settings.json, so Claude drives the full surface in-conversation:mk_remember(capture, including rich Why/How),mk_search/mk_get/mk_timeline/mk_cite(read),mk_trust(adjust trust),mk_lessons_promote(promote a fact across projects),mk_forget(preview-then-delete), andmk_queue_list/mk_queue_resolvefor the conflict queue (Source: packages/cli/README.md).
flowchart LR
A[Turn ends] --> B[Stop hook]
B --> C[cmk-capture-turn]
C --> D[cmk-capture-prompt<br/>Haiku extract]
D --> E[context/ facts]
E --> F[cmk-compress-session]
F --> G[recent.md]
G --> H[cmk-daily-distill<br/>cron or lazy]
H --> I[cmk-weekly-curate]
E --> J[Session start<br/>cmk-inject-context]
J --> K[Frozen snapshot]
E --> L[cmk search<br/>or MCP mk_*]
L --> M[Recall to Claude]Every fact is identified by a content-addressed ID generated through the cross-language cmk-canonicalize package, which keeps Node and Python implementations byte-identical (Source: packages/canonicalize/package.json:2-5). This is what makes citations, the trust hierarchy, and the conflict queue portable across machines, teammates, and CLI runs.
See Also
- docs/CLI.md — full command reference with examples
- docs/MCP.md — MCP server surface and tool contracts
- QUICKSTART.md — installation walkthrough
- HEALTH-CHECKS.md —
cmk doctor(HC-1..HC-9) and repair commands - docs/adr/0015-semantic-backend-sqlite-vec-plus-local-onnx-embedder.md — why the default embedder is
bge-base, not the 5× heavierbge-m3
Source: https://github.com/LH8PPL/claude-memory-kit / Human Manual
Installation & Multi-Agent Wiring (Claude Code and Kiro)
Related topics: Overview & Three-Tier Architecture, Memory Lifecycle: Capture, Compression, Recall, Safety, Delete-Guardrail, Health Checks & Failure Modes
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Overview & Three-Tier Architecture, Memory Lifecycle: Capture, Compression, Recall, Safety, Delete-Guardrail, Health Checks & Failure Modes
Installation & Multi-Agent Wiring (Claude Code and Kiro)
Overview
The Installation & Multi-Agent Wiring subsystem is the complete entry point for adopting claude-memory-kit. It does far more than copy files: it scaffolds the per-project memory tree (context/), drops the memory-write and memory-search skills, wires the five lifecycle hooks into the agent's configuration, registers the MCP server with the right allow-list, pins a .gitattributes block so memory survives cross-platform clones with intact line endings, and — depending on the target agent — materializes the agent-specific surface. The core memory engine (store, search, compression, auto-extract) is identical across agents; only the per-agent wiring differs. Source: README.md.
Two install routes exist, and the user is expected to pick one for a given machine:
| Route | Distribution | Best for |
|---|---|---|
npm CLI (cmk install …) | npm install -g @lh8ppl/claude-memory-kit | Users who want cmk search, cmk doctor, cron registration, and Kiro wiring from the terminal |
| Claude Code plugin | /plugin install claude-memory-kit | Users who prefer an in-Claude install with no terminal interaction |
Source: README.md, plugin/README.md.
The `cmk install` Pipeline (npm CLI Route)
The flagship command is cmk install (implemented in install.mjs), which orchestrates a single, idempotent workflow:
- Scaffold
context/from the package'stemplate/directory (existing files are never overwritten). - Drop
memory-writeandmemory-searchinto.claude/skills/(committed — they travel withgit clone). - Wire the five lifecycle hooks into
.claude/settings.jsonwith PATH-resolved, cross-OS bare-binary paths. - Register the kit's MCP server in
.mcp.jsonand allow-list its tools (mcp__cmk__*) in.claude/settings.json. - Write a
.gitattributesblock that pins committed memory toLF, so a Windows clone cannot mangle line endings and break the index.
A typical invocation:
cmk install # baseline scaffold + hooks + MCP
cmk install --with-semantic # one-time ~260 MB embedder download; search defaults to hybrid
cmk install --ide kiro # target Kiro instead of Claude Code (see next section)
cmk install --no-hooks # scaffold-only — useful when hooks will be wired by another tool
Source: README.md, packages/cli/README.md, packages/cli/package.json.
The same source describes the related lifecycle binaries published as bin: cmk-inject-context, cmk-capture-turn, cmk-compress-session, cmk-daily-distill, cmk-weekly-curate, cmk-compress-lazy, cmk-guard-memory, cmk-capture-prompt, cmk-observe-edit. These are the targets the hooks shell out to. Source: packages/cli/package.json.
Agent Adapters: Claude Code vs Kiro
Wiring is split by adapter so the same memory core can target different hosts. install-agent.mjs defines the shared adapter contract; install.mjs selects which adapter to dispatch to based on --ide.
flowchart LR
User["User runs<br/>cmk install [--ide kiro]"] --> Dispatch["install.mjs<br/>(dispatcher)"]
Dispatch -->|default| CC["install-agent.mjs<br/>Claude Code adapter"]
Dispatch -->|--ide kiro| KI["install-kiro.mjs<br/>Kiro adapter"]
CC --> CCSurf[".claude/settings.json<br/>.claude/skills/<br/>.mcp.json<br/>.gitattributes"]
KI --> KiroIDE["kiro-ide-hooks.mjs<br/>.kiro/settings/mcp.json"]
KI --> KiroCLI["kiro-cli-agent.mjs<br/>kiro-hook-command.mjs"]
KiroCLI --> KiroSurfs[".kiro/steering/<br/>AGENTS.md<br/>agent config"]Claude Code surface (default)
When --ide is omitted, the adapter writes the Claude Code surface:
.claude/settings.json— PreToolUse + Stop hooks (PATH-resolved), MCP tool allow-list..claude/skills/—memory-writeandmemory-searchskills..mcp.json— registers@lh8ppl/claude-memory-kit's MCP server.context/— the per-project memory tree (committed, git-portable)..gitattributes— LF lock for committed memory files.
Source: README.md.
Kiro surface (`--ide kiro`)
When --ide kiro is passed, install-kiro.mjs switches dispatch and the wiring targets both the Kiro IDE and kiro-cli:
| Surface | Location | Purpose |
|---|---|---|
| MCP server | .kiro/settings/mcp.json (with autoApprove) | IDE — Claude-in-Kiro drives memory as tools |
| IDE hooks | emitted by kiro-ide-hooks.mjs | Mirror the PreToolUse / Stop lifecycle in the IDE |
| Steering docs | .kiro/steering/ | Agent-level guidance injected on every prompt |
| Agent file | AGENTS.md | Repository-level agent instructions |
| Skills | .kiro/skills/ | memory-write / memory-search for the IDE |
| CLI agent config | emitted by kiro-cli-agent.mjs (with shared hook command logic in kiro-hook-command.mjs) | Wires kiro-cli so terminal sessions also capture and recall |
Source: README.md, packages/cli/README.md.
The same README notes that cmk install --with-semantic --ide kiro is the canonical one-liner for Kiro, and cmk doctor (run after install) verifies both surfaces, after which the IDE must be restarted so the hooks load.
Uninstall, Update, and Common Failure Modes
Uninstall
cmk uninstall [--ide claude-code|kiro] is conservative: it removes only the managed wiring for the targeted agent (.claude/settings.json blocks, .mcp.json registration, Kiro steering/skills, etc.) and never deletes context/. Use --ide kiro to remove the Kiro surface without disturbing the Claude Code surface, which is the right behavior when both are present in the same project. Source: README.md.
Update
Updates have two parts on both routes: refresh the global machinery, then re-stamp each project's scaffold.
- npm:
npm update -g @lh8ppl/claude-memory-kit→ re-runcmk installper project →cmk doctor. - Plugin:
/plugin marketplace update claude-memory-kit→/plugin update claude-memory-kit→/reload-plugins→ re-run/claude-memory-kit:bootstrapper project →cmk doctor.
The plugin path is parallel to the npm one: the marketplace refresh supplies new hooks/skills, but a project's context/ scaffold is per-project, so the bootstrap is repeated per project (mirrors re-running cmk install). Source: README.md, plugin/README.md.
Common failure modes
- Hooks don't fire after install — the agent must be restarted once so the new
settings.jsonis loaded. This is the most common gotcha for both Claude Code and Kiro. - Memory never gets compressed — cron is opt-in. Without
cmk register-crons, compression falls back to lazy-on-read at session start; memory stays bounded butrecent.mdcan lag. The v0.3.5 release notes specifically address background compression reliability whenclaude --printis slow: the lifecycle jobs (daily distill, weekly curate, session-start catch-up) now use a budget appropriate for unbounded work and retry with backoff, so a slow compression window no longer causesrecent.mdto fall behind. - Windows line-ending corruption — fix is to re-run
cmk installso it can re-write the.gitattributesLF lock, thengit rm --cached -r context/and recommit. - Mixed surfaces in one project —
cmk uninstall --ide claude-coderemoves only the Claude Code wiring, leaving the Kiro wiring intact (and vice versa). Source: README.md.
See Also
- CLI Reference — full
cmkcommand surface - MCP Tools — what the registered MCP server exposes
- Quickstart — end-to-end walkthrough
- Plugin Distribution — the in-Claude install path
- Architecture — how Layer 1–7 fit together
- Benchmarks — measured recall quality
Source: https://github.com/LH8PPL/claude-memory-kit / Human Manual
Safety, Delete-Guardrail, Health Checks & Failure Modes
Related topics: Overview & Three-Tier Architecture, Installation & Multi-Agent Wiring (Claude Code and Kiro), Memory Lifecycle: Capture, Compression, Recall
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Overview & Three-Tier Architecture, Installation & Multi-Agent Wiring (Claude Code and Kiro), Memory Lifecycle: Capture, Compression, Recall
Safety, Delete-Guardrail, Health Checks & Failure Modes
claude-memory-kit is designed around the principle that memory is durable infrastructure: once a fact lands in context/, it must not silently disappear. To honor that, the kit layers three independent safety rails on top of every write, every command, and every scheduled task: the delete-guardrail hook, the nine health checks, and a documented set of failure-mode recovery paths. This page maps those rails, how they interact, and where they can still fail.
The Three-Tier Safety Model
The kit treats safety as a property of the whole system, not a single check. Each tier covers a different failure class:
| Tier | Mechanism | Failure Class Covered |
|---|---|---|
| 1. Write-time | Secret screening + path abstraction + provenance | Bad data reaching memory |
| 2. Command-time | cmk-guard-memory PreToolUse hook | Accidental destructive deletion |
| 3. System-time | cmk doctor (HC-1..HC-9) + retry policy | Drift, staleness, broken installs |
Source: README.md — "Stays private + bounded" and "Guards your memory from accidental deletion" sections; SECURITY.md for the threat model.
The Delete-Guardrail (`cmk-guard-memory`)
The most distinctive safety rail is the delete-guardrail, wired by cmk install as a PreToolUse hook. It inspects every shell command the agent is about to run and blocks it before execution when the command is destructive *and* aimed at a known memory path.
What It Blocks
The hook covers both supported agents — Claude Code (Bash / PowerShell tool calls) and Kiro (execute_bash) — and watches for these destructive verbs:
rm,Remove-Item,delgit clean,git reset --hardfind … -deletetruncate,>-truncate (shell redirection that truncates)
Memory paths under protection include context/, the persona tier at ~/.claude-memory-kit/, MEMORY.md, and DECISIONS.md. Source: README.md — "Delete-guardrail" section; packages/cli/README.md — "Guards your memory from an accidental delete".
Why It's Intentionally Broad
A false block is recoverable (rephrase the command); a false allow is the data loss the guard exists to prevent. The hook is therefore biased toward over-blocking rather than under-blocking. This is documented explicitly in the README's security note.
Fail-Open by Design
If the guard itself crashes — for example, because the Node runtime can't be resolved — the hook returns without blocking rather than wedging the agent session. A broken guard simply stops guarding; it never turns into an unreachable agent. Source: README.md — "fail-open (a broken guard never wedges your session; it just stops guarding)".
Implementation Surfaces
The hook is implemented as a binary entry point (cmk-guard-memory) that the kit resolves and PATH-registers during install:
| Surface | Location | Purpose |
|---|---|---|
| Binary entry | packages/cli/bin/cmk-guard-memory.mjs | Invoked by the host agent |
| Logic | packages/cli/src/guard-memory.mjs | Pattern matching + decision |
| Install wiring | cmk install → .claude/settings.json | Registers the hook event |
Source: packages/cli/package.json — bin map includes cmk-guard-memory.
Health Checks (HC-1..HC-9)
cmk doctor is the kit's self-diagnostic. It runs nine checks, each reported as PASS / FAIL / SKIP, and each FAIL ships with a concrete repair command so the user never has to guess the next step. Source: README.md — "Health checks" section; full reference in HEALTH-CHECKS.md.
Why Nine, Not One
A single "is it working" check would hide which layer is broken. The nine checks span:
- Hook registration — are the lifecycle hooks present in
.claude/settings.json? - Lock files — are stale lock files left from a crashed
claude --printjob? - Index integrity — is the SQLite + FTS5 index parseable?
- Scaffold freshness — is the per-project
context/scaffold in sync with the installedcmkversion? - Scaffold version drift — HC-9 flags a project whose scaffold is behind the installed kit.
Source: README.md — "including HC-9, which flags a project whose scaffold is behind your installed cmk (re-run cmk install there)".
Repair Workflow
cmk doctor outputs repair commands that flow into cmk repair, which is idempotent:
cmk doctor # run all checks
cmk repair --hooks # re-wire hooks (idempotent)
cmk repair --locks # clear stale locks
cmk repair --index # rebuild the SQLite index
cmk repair --all # run all repair passes
Source: packages/cli/README.md — cmk repair --hooks / --locks / --index / --all.
Known Failure Modes & Recovery
The kit documents, and the v0.3.5 release fixed, several real failure modes worth understanding:
Compression Budget Mismatch (fixed in v0.3.5)
Lifecycle compression jobs (daily distill, weekly curate, session-start catch-up) were sharing the 50-second budget used by the in-session compressor, and were retrying too quickly. A slow claude --print window could time out, causing recent.md and the archive to go stale. The fix gives the no-time-limit jobs an appropriately longer budget and a saner retry interval. Source: community context for v0.3.5 release notes.
npm 12 Silent Script Block (forward-looking)
npm 12 (July 2026) skips dependency install scripts by default, which silently blocks better-sqlite3's native build. cmk install detects this and offers to fix it inline; users who want to pre-empt can install with --allow-scripts=better-sqlite3. Source: README.md — npm 12 note.
No Cron / Scheduler
If the user cannot run cron, launchd, or Task Scheduler, compression falls back to lazy-on-read at session start — memory stays bounded without any scheduler. Cron just makes it proactive. Source: README.md — FAQ: "What if I can't run cron / a scheduler?".
Guardrail Bypass Scenarios
The delete-guardrail is intentionally broad but not omniscient. It does not block:
- Edits that *truncate-then-rewrite* (e.g.,
cat > MEMORY.md) unless the write itself is destructive redirection. Users who need edit-time protection should commit frequently. - Delete operations outside the protected path list. Path coverage is intentionally limited to avoid surprising the user;
cmk repair --indexis the recovery path if the index is damaged rather than the data itself.
See Also
- Architecture Overview — the six-layer model the safety rails protect.
- CLI Reference — full flags for
cmk install,cmk doctor, andcmk repair. - Security Policy — threat model and disclosure policy.
- Health Checks — HC-1..HC-9 detail with recovery paths.
Source: https://github.com/LH8PPL/claude-memory-kit / Human Manual
Doramagic Pitfall Log
Source-linked risks stay visible on the manual page so the preview does not read like a recommendation.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
Doramagic Pitfall Log
Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.
1. Configuration risk: Configuration risk requires verification
- Severity: medium
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.host_targets | https://github.com/LH8PPL/claude-memory-kit
2. Capability evidence risk: Capability evidence risk requires verification
- Severity: medium
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.assumptions | https://github.com/LH8PPL/claude-memory-kit
3. Maintenance risk: Maintenance risk requires verification
- Severity: medium
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | https://github.com/LH8PPL/claude-memory-kit
4. Security or permission risk: Security or permission risk requires verification
- Severity: medium
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: downstream_validation.risk_items | https://github.com/LH8PPL/claude-memory-kit
5. Security or permission risk: Security or permission risk requires verification
- Severity: medium
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: risks.scoring_risks | https://github.com/LH8PPL/claude-memory-kit
6. Maintenance risk: Maintenance risk requires verification
- Severity: low
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | https://github.com/LH8PPL/claude-memory-kit
7. Maintenance risk: Maintenance risk requires verification
- Severity: low
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | https://github.com/LH8PPL/claude-memory-kit
Source: Doramagic discovery, validation, and Project Pack records
Community Discussion Evidence
These external discussion links are review inputs, not standalone proof that the project is production-ready.
Count of project-level external discussion links exposed on this manual page.
Open the linked issues or discussions before treating the pack as ready for your environment.
Community Discussion Evidence
Doramagic exposes project-level community discussion separately from official documentation. Review these links before using claude-memory-kit with real data or production workflows.
- v0.3.5 - github / github_release
- v0.3.4 - github / github_release
- v0.3.3 - github / github_release
- v0.3.2 - github / github_release
- v0.3.1 - github / github_release
- v0.3.0 - github / github_release
- v0.2.4 - github / github_release
- v0.2.3 - github / github_release
- v0.2.2 - github / github_release
- v0.2.1 - github / github_release
- Configuration risk requires verification - GitHub / issue
Source: Project Pack community evidence and pitfall evidence