# https://github.com/LH8PPL/claude-memory-kit Project Manual

Generated at: 2026-06-25 08:55:08 UTC

## Table of Contents

- [Overview & Three-Tier Architecture](#page-overview)
- [Memory Lifecycle: Capture, Compression, Recall](#page-lifecycle)
- [Installation & Multi-Agent Wiring (Claude Code and Kiro)](#page-install)
- [Safety, Delete-Guardrail, Health Checks & Failure Modes](#page-safety)

<a id='page-overview'></a>

## Overview & Three-Tier Architecture

### Related Pages

Related topics: [Memory Lifecycle: Capture, Compression, Recall](#page-lifecycle), [Installation & Multi-Agent Wiring (Claude Code and Kiro)](#page-install)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md)
- [packages/cli/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/README.md)
- [packages/cli/package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/package.json)
- [packages/canonicalize/package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/canonicalize/package.json)
- [plugin/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/plugin/README.md)
- [package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/package.json)
</details>

# Overview & Three-Tier Architecture

## Purpose and Scope

`claude-memory-kit` is a per-project, in-repo memory system for [Claude Code](https://docs.claude.com/en/docs/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`](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/canonicalize/package.json)). 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`](https://github.com/LH8PPL/claude-memory-kit/blob/main/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`](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md) and [`packages/cli/README.md`](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/README.md).

A simple view of the flow:

```mermaid
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`](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md).

## Distribution Surfaces

The monorepo publishes two primary artifacts and ships a third for the Claude Code plugin marketplace:

1. **npm package** — `npm 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`](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/README.md).

## See Also

- [CLI reference](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/CLI.md) — full command surface
- [MCP server reference](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/MCP.md) — tool contracts
- [Health checks](https://github.com/LH8PPL/claude-memory-kit/blob/main/HEALTH-CHECKS.md) — `cmk doctor` HC-1..HC-9
- [Security model](https://github.com/LH8PPL/claude-memory-kit/blob/main/SECURITY.md) — delete-guardrail + secret screening
- [ADR-0015 — semantic backend choice](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/adr/0015-semantic-backend-sqlite-vec-plus-local-onnx-embedder.md)

---

<a id='page-lifecycle'></a>

## Memory Lifecycle: Capture, Compression, Recall

### Related Pages

Related topics: [Overview & Three-Tier Architecture](#page-overview), [Installation & Multi-Agent Wiring (Claude Code and Kiro)](#page-install), [Safety, Delete-Guardrail, Health Checks & Failure Modes](#page-safety)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/cli/package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/package.json)
- [README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md)
- [packages/cli/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/README.md)
- [plugin/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/plugin/README.md)
- [packages/canonicalize/package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/canonicalize/package.json)
</details>

# 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](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/README.md)). Source: [packages/cli/package.json:1-50](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/package.json) 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](https://github.com/LH8PPL/claude-memory-kit/blob/main/plugin/README.md) 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](https://github.com/LH8PPL/claude-memory-kit/blob/main/plugin/README.md)). 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](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/package.json)):

| 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](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/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 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](https://github.com/LH8PPL/claude-memory-kit/blob/main/plugin/README.md); binaries registered at [packages/cli/package.json:12](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/package.json)).
- **Shell search** — `cmk 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](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md), Benchmarks).
- **MCP tools** — `cmk 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](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/README.md)).

```mermaid
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](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/canonicalize/package.json)). This is what makes citations, the trust hierarchy, and the conflict queue portable across machines, teammates, and CLI runs.

## See Also

- [docs/CLI.md](docs/CLI.md) — full command reference with examples
- [docs/MCP.md](docs/MCP.md) — MCP server surface and tool contracts
- [QUICKSTART.md](QUICKSTART.md) — installation walkthrough
- [HEALTH-CHECKS.md](HEALTH-CHECKS.md) — `cmk doctor` (HC-1..HC-9) and repair commands
- [docs/adr/0015-semantic-backend-sqlite-vec-plus-local-onnx-embedder.md](docs/adr/0015-semantic-backend-sqlite-vec-plus-local-onnx-embedder.md) — why the default embedder is `bge-base`, not the 5× heavier `bge-m3`

---

<a id='page-install'></a>

## Installation & Multi-Agent Wiring (Claude Code and Kiro)

### Related Pages

Related topics: [Overview & Three-Tier Architecture](#page-overview), [Memory Lifecycle: Capture, Compression, Recall](#page-lifecycle), [Safety, Delete-Guardrail, Health Checks & Failure Modes](#page-safety)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/cli/src/install.mjs](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/src/install.mjs)
- [packages/cli/src/install-agent.mjs](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/src/install-agent.mjs)
- [packages/cli/src/install-kiro.mjs](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/src/install-kiro.mjs)
- [packages/cli/src/kiro-cli-agent.mjs](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/src/kiro-cli-agent.mjs)
- [packages/cli/src/kiro-ide-hooks.mjs](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/src/kiro-ide-hooks.mjs)
- [packages/cli/src/kiro-hook-command.mjs](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/src/kiro-hook-command.mjs)
</details>

# 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](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md), [plugin/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/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:

```bash
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](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md), [packages/cli/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/README.md), [packages/cli/package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/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`.

```mermaid
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](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md), [packages/cli/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md), [plugin/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/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 project** — `cmk uninstall --ide claude-code` removes only the Claude Code wiring, leaving the Kiro wiring intact (and vice versa). Source: [README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md).

## See Also

- [CLI Reference](CLI.md) — full `cmk` command surface
- [MCP Tools](MCP.md) — what the registered MCP server exposes
- [Quickstart](QUICKSTART.md) — end-to-end walkthrough
- [Plugin Distribution](plugin/README.md) — the in-Claude install path
- [Architecture](Architecture.md) — how Layer 1–7 fit together
- [Benchmarks](Benchmarks.md) — measured recall quality

---

<a id='page-safety'></a>

## Safety, Delete-Guardrail, Health Checks & Failure Modes

### Related Pages

Related topics: [Overview & Three-Tier Architecture](#page-overview), [Installation & Multi-Agent Wiring (Claude Code and Kiro)](#page-install), [Memory Lifecycle: Capture, Compression, Recall](#page-lifecycle)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md)
- [packages/cli/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/README.md)
- [packages/cli/package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/package.json)
- [packages/cli/src/guard-memory.mjs](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/src/guard-memory.mjs)
- [packages/cli/bin/cmk-guard-memory.mjs](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/bin/cmk-guard-memory.mjs)
- [HEALTH-CHECKS.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/HEALTH-CHECKS.md)
- [SECURITY.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/SECURITY.md)
- [ARCHITECTURE.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/ARCHITECTURE.md)
- [docs/CLI.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/CLI.md)
- [package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/package.json)
</details>

# 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](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md) — "Stays private + bounded" and "Guards your memory from accidental deletion" sections; [SECURITY.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md) — "Delete-guardrail" section; [packages/cli/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md) — "Health checks" section; full reference in [HEALTH-CHECKS.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/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:

```bash
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](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/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](https://github.com/LH8PPL/claude-memory-kit/blob/main/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

- [Architecture Overview](https://github.com/LH8PPL/claude-memory-kit/blob/main/ARCHITECTURE.md) — the six-layer model the safety rails protect.
- [CLI Reference](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/CLI.md) — full flags for `cmk install`, `cmk doctor`, and `cmk repair`.
- [Security Policy](https://github.com/LH8PPL/claude-memory-kit/blob/main/SECURITY.md) — threat model and disclosure policy.
- [Health Checks](https://github.com/LH8PPL/claude-memory-kit/blob/main/HEALTH-CHECKS.md) — HC-1..HC-9 detail with recovery paths.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: LH8PPL/claude-memory-kit

Summary: 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
- Evidence strength: source_linked
- 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.
- Evidence: capability.host_targets | https://github.com/LH8PPL/claude-memory-kit

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/LH8PPL/claude-memory-kit

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/LH8PPL/claude-memory-kit

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- 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
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/LH8PPL/claude-memory-kit

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/LH8PPL/claude-memory-kit

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/LH8PPL/claude-memory-kit

<!-- canonical_name: LH8PPL/claude-memory-kit; human_manual_source: deepwiki_human_wiki -->