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)

Section Related Pages

Continue reading this section for the full explanation and source context.

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.

TierLives inTravels withPurpose
Projectcontext/ inside the repogit clone (committed markdown)Project-specific facts, decisions, conventions
User / Persona~/.claude-memory-kit/The user (never committed)Cross-project lessons, personal style
SessionThe repo’s context/scratch/ + the frozen snapshot at session startAuto-generated per sessionLive 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-limited
  • cmk-compress-lazy — session-start catch-up roll, lazy-on-read
  • cmk-daily-distill — daily job
  • cmk-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 slow claude --print window could therefore time out and skip a rollup, leaving recent.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:

  1. npm packagenpm install -g @lh8ppl/claude-memory-kit followed by cmk install in the project. cmk install is the complete entry point: it scaffolds context/, drops the memory-write + memory-search skills 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.
  2. Plugin distribution/plugin marketplace add … then /plugin install claude-memory-kit, then /claude-memory-kit:bootstrap per project. The plugin provides its own hooks/hooks.json (PreToolUse for context injection, Stop for capture + auto-extract) and the memory-write / bootstrap skills. It does *not* modify .claude/settings.json and does *not* register cron. Source: plugin/README.md:7-19.
  3. 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

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

Section Related Pages

Continue reading this section for the full explanation and source context.

Section v0.3.5 fix — background compression no longer fails on slow Claude windows

Continue reading this section for the full explanation and source context.

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

  1. Automatic background pass — after every turn, the Stop hook reads the transcript and spawns cmk-capture-turn (binary: cmk-capture-turn). That binary calls cmk-capture-prompt (binary: cmk-capture-prompt), which sends a single Haiku call to extract durable facts, decisions, conventions, and tool quirks. The result lands in context/ as <type>_<slug>.md files with content-addressed IDs. Source: plugin/README.md:18-22 describes the Stop hook that triggers this.
  2. Explicit in-conversation capture — phrases like "remember this", "from now on", "we decided", "forget X" trigger the memory-write skill, exposed as /claude-memory-kit:memory-write (Source: plugin/README.md:23-24). The same surface is reachable from the shell as cmk remember "<fact>" or, for backtick/quote-heavy rich facts, cmk remember --from-file fact.json so 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):

TierBinaryTriggerPurpose
Sessioncmk-compress-sessionmid-session, run by cmk-capture-turnroll the session buffer into recent.md
Lazycmk-compress-lazysession start, fallbackcatch-up roll when no scheduler is installed
Dailycmk-daily-distillcron / launchd / Task Schedulerdistill yesterday's session logs into daily notes
Weeklycmk-weekly-curatecron / launchd / Task Schedulercurate 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 startcmk-inject-context (binary: cmk-inject-context) writes a one-shot read of SOUL.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 searchcmk search "<query>" runs keyword search by default; with the optional local embedder installed via cmk install --with-semantic, the default flips to hybrid (semantic + keyword). --scope transcripts searches the raw session record; --scope decisions searches the decision journal. Benchmarked R@5 is 0.941 with paraphrase recall 1.000, zero API calls (Source: README.md, Benchmarks).
  • MCP toolscmk install registers the kit's MCP server in .mcp.json and allow-lists mcp__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), and mk_queue_list / mk_queue_resolve for 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

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

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Claude Code surface (default)

Continue reading this section for the full explanation and source context.

Section Kiro surface (--ide kiro)

Continue reading this section for the full explanation and source context.

Section Uninstall

Continue reading this section for the full explanation and source context.

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:

RouteDistributionBest for
npm CLI (cmk install …)npm install -g @lh8ppl/claude-memory-kitUsers who want cmk search, cmk doctor, cron registration, and Kiro wiring from the terminal
Claude Code plugin/plugin install claude-memory-kitUsers 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:

  1. Scaffold context/ from the package's template/ directory (existing files are never overwritten).
  2. Drop memory-write and memory-search into .claude/skills/ (committed — they travel with git clone).
  3. Wire the five lifecycle hooks into .claude/settings.json with PATH-resolved, cross-OS bare-binary paths.
  4. Register the kit's MCP server in .mcp.json and allow-list its tools (mcp__cmk__*) in .claude/settings.json.
  5. Write a .gitattributes block that pins committed memory to LF, 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-write and memory-search skills.
  • .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:

SurfaceLocationPurpose
MCP server.kiro/settings/mcp.json (with autoApprove)IDE — Claude-in-Kiro drives memory as tools
IDE hooksemitted by kiro-ide-hooks.mjsMirror the PreToolUse / Stop lifecycle in the IDE
Steering docs.kiro/steering/Agent-level guidance injected on every prompt
Agent fileAGENTS.mdRepository-level agent instructions
Skills.kiro/skills/memory-write / memory-search for the IDE
CLI agent configemitted 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-run cmk install per project → cmk doctor.
  • Plugin: /plugin marketplace update claude-memory-kit/plugin update claude-memory-kit/reload-plugins → re-run /claude-memory-kit:bootstrap per 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.json is 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 but recent.md can lag. The v0.3.5 release notes specifically address background compression reliability when claude --print is 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 causes recent.md to fall behind.
  • Windows line-ending corruption — fix is to re-run cmk install so it can re-write the .gitattributes LF lock, then git rm --cached -r context/ and recommit.
  • Mixed surfaces in one projectcmk uninstall --ide claude-code removes only the Claude Code wiring, leaving the Kiro wiring intact (and vice versa). Source: README.md.

See Also

  • CLI Reference — full cmk command 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

Section Related Pages

Continue reading this section for the full explanation and source context.

Section What It Blocks

Continue reading this section for the full explanation and source context.

Section Why It's Intentionally Broad

Continue reading this section for the full explanation and source context.

Section Fail-Open by Design

Continue reading this section for the full explanation and source context.

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:

TierMechanismFailure Class Covered
1. Write-timeSecret screening + path abstraction + provenanceBad data reaching memory
2. Command-timecmk-guard-memory PreToolUse hookAccidental destructive deletion
3. System-timecmk doctor (HC-1..HC-9) + retry policyDrift, 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, del
  • git clean, git reset --hard
  • find … -delete
  • truncate, >-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:

SurfaceLocationPurpose
Binary entrypackages/cli/bin/cmk-guard-memory.mjsInvoked by the host agent
Logicpackages/cli/src/guard-memory.mjsPattern matching + decision
Install wiringcmk install.claude/settings.jsonRegisters the hook event

Source: packages/cli/package.jsonbin 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 --print job?
  • Index integrity — is the SQLite + FTS5 index parseable?
  • Scaffold freshness — is the per-project context/ scaffold in sync with the installed cmk version?
  • 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.mdcmk 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 --index is the recovery path if the index is damaged rather than the data itself.

See Also

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.

medium Configuration risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Capability evidence risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Maintenance risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Security or permission risk requires verification

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.

Sources 11

Count of project-level external discussion links exposed on this manual page.

Use Review before install

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.

Source: Project Pack community evidence and pitfall evidence