@lh8ppl/claude-memory-kit 0.1.1 → 0.2.0

package/src/weekly-curate.mjs

@@ -45,6 +45,9 @@ import {
   touchCooldownMarker,
 } from './cooldown.mjs';
 import { dailyDistill } from './daily-distill.mjs';
+import { autoPersona } from './auto-persona.mjs';
+import { initUserTier } from './install.mjs';
+import { autoDrainQueues } from './auto-drain.mjs';
 
 const DEFAULT_ARCHIVE_MAX_BYTES = 4096;
 const DEFAULT_RECENT_MAX_BYTES = 4096;
@@ -69,11 +72,12 @@ function buildCurateInstructions(archiveMaxBytes) {
     'Under each week heading, emit bullets that summarize the work across the days in that week. Each bullet is a single line ≤120 chars. Bullets within a week appear in chronological order.',
     '',
     'HARD RULES:',
-    '  1. Preserve every citation ID matching /#[ULP]-[A-Z0-9]{6,8}/ verbatim. Never invent new IDs.',
-    `  2. Total output ≤ ${archiveMaxBytes} bytes.`,
-    '  3. Deduplicate aggressively: if the same fact appears across multiple days, emit it ONCE. The deterministic dedup pass after your output will collapse exact-after-canonical duplicates; YOUR job is to catch the looser semantic duplicates (paraphrases, restatements).',
-    '  4. No prose between bullets — only the bulleted list per week section.',
-    '  5. Your output goes directly into archive.md. Do not address the user, do not refer to yourself.',
+    '  1. Every bullet must be grounded in the daily summaries below. Do not infer or add any fact not explicitly present in them. When the summaries show a fact was later corrected, replaced, or reversed, keep ONLY the latest version of that fact — never list the superseded one alongside it (this resolves contradictions, NOT coexisting facts on different points). If unsure, omit it.',
+    '  2. Preserve every citation ID matching /#[ULP]-[A-Z0-9]{6,8}/ verbatim. Never invent new IDs.',
+    `  3. Total output ≤ ${archiveMaxBytes} bytes.`,
+    '  4. Deduplicate aggressively: if the same fact appears across multiple days, emit it ONCE. The deterministic dedup pass after your output will collapse exact-after-canonical duplicates; YOUR job is to catch the looser semantic duplicates (paraphrases, restatements).',
+    '  5. No prose between bullets — only the bulleted list per week section.',
+    '  6. Your output goes directly into archive.md. Do not address the user, do not refer to yourself.',
     '',
     '=== BEGIN OLD DAILY SUMMARIES TO ARCHIVE ===',
   ].join('\n');
@@ -242,6 +246,7 @@ function writeCurateLogEntry({ projectRoot, date, entry }) {
  */
 export async function weeklyCurate({
   projectRoot,
+  userDir,
   backend,
   now,
   cooldownMs = DEFAULT_COOLDOWN_MS,
@@ -277,6 +282,12 @@ export async function weeklyCurate({
     };
   }
 
+  // Auto-drain the review + conflict queues (v0.2 Phase 2, D-6) — project
+  // tier always, user tier when a userDir is supplied (persona queues).
+  // Non-Haiku file IO; runs every weekly pass regardless of the cooldown.
+  const drained = { P: await autoDrainQueues({ tier: 'P', projectRoot }) };
+  if (userDir) drained.U = await autoDrainQueues({ tier: 'U', userDir });
+
   if (isCooldownActive({ projectRoot, now: ts, cooldownMs })) {
     const duration_ms = Date.now() - t0;
     writeCurateLogEntry({
@@ -297,7 +308,38 @@ export async function weeklyCurate({
         skipped_reason: 'cooldown',
       },
     });
-    return { action: 'skipped', reason: 'cooldown', duration_ms };
+    return { action: 'skipped', reason: 'cooldown', drained, duration_ms };
+  }
+
+  // Design-B auto-persona hook (Task 45). The weekly cycle is the natural
+  // trigger: once past the shared cooldown gate, synthesize cross-project
+  // doctrine from the granular fact archive and auto-promote it into the
+  // user tier. cooldownMs:0 — this Haiku call belongs to the SAME weekly
+  // cycle as the curate compress below (per §8.7.2, like the inline
+  // dailyDistill call). Skipped silently if userDir wasn't supplied (so
+  // existing project-only callers/tests are unaffected). D-14/D-15.
+  let persona;
+  if (userDir) {
+    // Ensure the user tier exists before auto-persona tries to promote into
+    // it. Without this, a user who never ran `cmk init-user-tier` has no
+    // USER.md/HABITS.md/LESSONS.md, so every promotion would silently route
+    // to `queued[]` (NOT_FOUND) and the cross-project tier would stay empty
+    // — the exact friend-handoff failure auto-persona exists to fix.
+    // initUserTier is idempotent (skips existing files).
+    try {
+      initUserTier({ userTier: userDir });
+    } catch {
+      // Best-effort: if scaffolding fails (perms, etc.), autoPersona still
+      // degrades gracefully (promotions route to queued[]); don't abort the
+      // whole curate cycle over a user-tier scaffold hiccup.
+    }
+    persona = await autoPersona({
+      projectRoot,
+      userDir,
+      backend,
+      now: ts,
+      cooldownMs: 0,
+    });
   }
 
   const files = listAllTodayFiles(projectRoot);
@@ -329,6 +371,8 @@ export async function weeklyCurate({
       action: 'skipped',
       reason: 'no-old-files',
       currentDays: current.length,
+      persona,
+      drained,
       duration_ms,
     };
   }
@@ -415,6 +459,7 @@ export async function weeklyCurate({
       now: ts,
       cooldownMs: 0,
       maxOutputBytes: recentMaxBytes,
+      skipDrain: true, // weeklyCurate already drained above; don't double-drain
     });
     if (recentResult?.outputPath) recentPath = recentResult.outputPath;
   }
@@ -449,6 +494,8 @@ export async function weeklyCurate({
     recentPath,
     bytesIn: input_bytes,
     bytesOut: output_bytes,
+    persona,
+    drained,
     duration_ms,
   };
 }

package/src/write-fact.mjs

@@ -17,8 +17,11 @@ import { join } from 'node:path';
 import { generateId } from '@lh8ppl/cmk-canonicalize';
 import { VALID_TIERS, resolveTierRoot, resolveFactDir } from './tier-paths.mjs';
 import { parse, format } from './frontmatter.mjs';
+import { reindex } from './reindex.mjs';
 import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
+import { sanitizeHomePaths } from './sanitize.mjs';
+import { checkPoisonGuard, logPoisonGuardRejection } from './poison-guard.mjs';
 
 const VALID_TYPES = new Set(['user', 'feedback', 'project', 'reference']);
 const VALID_WRITE_SOURCES = new Set([
@@ -148,7 +151,48 @@ export function writeFact(opts = {}) {
     });
   }
 
-  const id = opts.id ?? generateId(opts.tier, opts.body);
+  // Privacy (write-path fix #1): abstract absolute home-dir paths to `~` in
+  // committed/shared tiers (P/U) so a fact never ships the local username
+  // and stays portable. Local tier (L) keeps machine-specific paths verbatim
+  // — that's its purpose. The id hashes the SANITIZED body, so dedup keys on
+  // what actually lands on disk.
+  let { body, title } = opts;
+  if (opts.tier === 'P' || opts.tier === 'U') {
+    body = sanitizeHomePaths(body);
+    title = sanitizeHomePaths(title);
+  }
+
+  // Poison_Guard (write-path fix #1): fact files previously bypassed the
+  // secret/poison screen that scratchpad writes get via memoryWrite. Screen
+  // the (sanitized) body before any disk write; a rejection logs the redacted
+  // excerpt to .locks/poison-guard.log and returns a poison_guard error.
+  const guard = checkPoisonGuard(body);
+  if (guard.rejected) {
+    // Best-effort log; guard on projectRoot so a U-tier write with no
+    // project context can't turn a clean rejection into a crash.
+    if (guard.pattern_id !== 'schema' && opts.projectRoot) {
+      logPoisonGuardRejection({
+        projectRoot: opts.projectRoot,
+        ts: opts.createdAt ?? nowIso(),
+        pattern_id: guard.pattern_id,
+        source_file: `write-fact:${opts.type}_${opts.slug}`,
+        source_line: 1,
+        redacted_excerpt: guard.redacted_excerpt,
+      });
+    }
+    return errorResult({
+      category: ERROR_CATEGORIES.POISON_GUARD,
+      errors: [`Poison_Guard rejected write: pattern_id=${guard.pattern_id}`],
+      pattern_id: guard.pattern_id,
+      redacted_excerpt: guard.redacted_excerpt,
+      id: null,
+      path: null,
+    });
+  }
+
+  // Use the sanitized body/title for id, frontmatter, and the file body.
+  const factOpts = { ...opts, body, title };
+  const id = opts.id ?? generateId(opts.tier, body);
   const createdAt = opts.createdAt ?? nowIso();
   const tierRoot = resolveTierRoot(opts);
   const factDir = resolveFactDir(opts.tier, tierRoot);
@@ -198,8 +242,21 @@ export function writeFact(opts = {}) {
   }
 
   mkdirSync(factDir, { recursive: true });
-  const frontmatter = buildFrontmatterObject(opts, { id, createdAt });
-  writeFileSync(path, format({ frontmatter, body: `\n${opts.body}\n` }), 'utf8');
+  const frontmatter = buildFrontmatterObject(factOpts, { id, createdAt });
+  writeFileSync(path, format({ frontmatter, body: `\n${factOpts.body}\n` }), 'utf8');
+
+  // Keep INDEX.md consistent on every create — the index is a derived view of
+  // the fact files, so the writer owns keeping it current. Without this, a fresh
+  // `cmk remember` left INDEX.md stale until a manual `cmk reindex`, and
+  // `cmk doctor` HC-5 failed from the first capture (Task 85; lior-test-7
+  // 2026-06-03 — "users should get it working from the start"). Best-effort: the
+  // fact is already durably on disk, so an index-rebuild hiccup must not turn a
+  // successful capture into an error — the next reindex/search self-heals.
+  try {
+    reindex({ tier: opts.tier, projectRoot: opts.projectRoot, userDir: opts.userDir, warn: () => {} });
+  } catch {
+    // index rebuild is best-effort; capture already succeeded
+  }
 
   return { action: 'created', id, path };
 }

package/template/.claude/skills/memory-write/SKILL.md

@@ -1,117 +1,76 @@
 ---
 name: memory-write
-description: >
-  Saves durable facts to context/MEMORY.md or context/USER.md. Auto-triggers
-  on phrases the user uses to flag worth-remembering content: "remember this",
-  "remember that", "note this", "note that", "save this", "update memory",
-  "forget about", "let's remember", "going forward", "from now on", "i prefer",
-  "i don't like". Also triggers automatically from the auto-extract Stop hook
-  after every assistant turn when a durable fact is detected.
-  Three actions: add (append under correct section), replace (substring match
-  + swap), remove (confirm with user first). Enforces caps (MEMORY.md 2,500
-  chars, USER.md 1,375 chars) with a dedup guard so duplicate or near-duplicate
-  facts don't accumulate.
+description: Captures a durable fact to project memory by running `cmk remember`, the kit's safe write path (Poison_Guard secret/injection screening + home-path sanitization + dedup + conflict detection). Use when the user says "remember this", "note this", "save this", "from now on", "going forward", "I prefer", "I don't like", "we decided", "we agreed", or otherwise states a durable preference, decision, or environment fact worth carrying across sessions. Also covers correcting a saved fact ("update memory: X is now Y") and removing one ("forget about X"). Skip throwaway chatter and facts that only matter to the current task.
+allowed-tools: Bash(cmk remember *) Bash(cmk forget *) Read
 ---
 
-# memory-write
+# Capturing durable memory
 
-## Purpose
+Durable facts — preferences, decisions, environment state — are saved by running
+the kit's CLI. The CLI is the only safe way to write memory.
 
-Make memory writes **automatic and reliable**. Instead of the user reminding Claude to "save this to memory," the skill captures durable facts the moment they're spoken or decided, with the right structure and the right file.
+## MUST / NEVER
 
-## When this skill fires
+- **MUST** capture every durable fact by running `cmk remember` (or `cmk forget`
+  to remove). Run the command as shown; do not modify its shape.
+- **NEVER** hand-edit `context/MEMORY.md`, `context/USER.md`, or any file under
+  `context/memory/`. Direct edits bypass secret screening and home-path
+  sanitization and can leak a credential or a local path into a committed file.
+- **Silent on success.** Do not announce "saved to memory" unless the user asked.
 
-**User-explicit signals**:
+## Capture a fact (default)
 
-- "remember this" / "remember that" / "remember our X"
-- "note this" / "note that"
-- "save this" / "save that"
-- "update memory" / "add to memory"
-- "forget about X" → remove operation
-- "from now on" / "going forward" / "i prefer" / "i don't like" → preference signals
-- "we decided" / "we agreed" / "let's use X not Y" → decision signals
-
-**Auto-extract signals** (from the Stop hook):
-
-- Assistant turn contains a "Why:" or "How to apply:" line implying a durable rule
-- Assistant turn explicitly acknowledges a user correction ("you're right", "fair point", "i was wrong")
-- Assistant turn states a new decision or environment fact that wasn't in MEMORY.md before
-
-## Where to write — file routing
-
-| Content type | File | Section |
-|---|---|---|
-| Current active work / open threads | `context/MEMORY.md` | `## Active Threads` |
-| Tool versions, paths, URLs, env state | `context/MEMORY.md` | `## Environment Notes` |
-| Things the user still has to decide | `context/MEMORY.md` | `## Pending Decisions` |
-| Stable user identity, role, expertise | `context/USER.md` | `## About` |
-| Persistent preferences ("i prefer X") | `context/USER.md` | `## Preferences` |
-| How the user approaches work | `context/USER.md` | `## Working Style` |
-| Typed durable fact with rationale | `context/memory/<type>_<slug>.md` | Granular archive, with frontmatter + `**Why:**` + `**How to apply:**` |
-
-If unsure: scratchpad (MEMORY.md) is the default. If the fact has long-term reasoning, promote it to a granular file later.
-
-## How to write — the steps
-
-1. Read the target file in full (MEMORY.md or USER.md). Need current state to dedup against.
-2. **Dedup check**: scan for substring or near-paraphrase match. If the fact already exists, skip; don't append a duplicate.
-3. **Cap check**: `wc -c context/MEMORY.md` (or USER.md). If over the cap:
-   - For MEMORY.md: consolidate existing entries first (merge similar bullets, drop stale ones older than 14 days with no current reference), THEN add the new fact.
-   - For USER.md: same pattern. USER.md should rarely change — most additions go to MEMORY.md.
-4. **Write** the new fact under the appropriate section. Single bullet, concise (< 200 chars).
-5. **Confirm silently** — do not announce "saved to memory" unless the user explicitly asked. Auto-extract should be invisible.
-
-## Actions
-
-- **add** — default. Append a new bullet under the appropriate section.
-- **replace** — when the user says "update memory: X is now Y", or "we decided to switch from X to Y". Find the existing bullet by substring match and swap.
-- **remove** — when the user says "forget about X" or "we changed our mind on X". Confirm with the user FIRST before deleting. Removal is the only action that requires confirmation; add and replace are silent.
-
-## Examples
+```
+cmk remember "<the fact, one sentence>"
+```
 
-**Explicit user trigger:**
+Writes a bullet to `context/MEMORY.md`. Use it for in-flight work, decisions,
+tool versions, paths, and environment facts.
 
-> User: "remember that we're standardizing on Python 3.13"
+When the fact is not active work, pick its section:
 
-Action: add to `MEMORY.md` § Environment Notes:
 ```
-- Python 3.13 is the standard. Older 3.10 envs should be uninstalled to avoid PATH conflicts.
+cmk remember "<fact>" --section "Environment Notes"
 ```
 
-**Auto-extract trigger (silent):**
+Sections: `Active Threads` (default), `Environment Notes`, `Pending Decisions`.
 
-> Assistant turn (after a debugging session): "...so the issue was the system PATH resolving wrong. Fix uses absolute executable paths. Going forward, scheduled tasks should never rely on bare command names."
+## Capture a fact WITH rationale (preferences, working style, lasting rules)
+
+When the fact carries a reason or a how-to — a user preference, a working-style
+rule, a project constraint — capture it richly so the reasoning survives:
 
-Auto-extract recognizes "Going forward" + concrete rule → add to `MEMORY.md` § Environment Notes:
 ```
-- Scheduled tasks must use absolute executable paths (not bare command names) — system PATH can resolve to the wrong binary.
+cmk remember "<headline>" --type <type> --why "<why it holds>" --how "<how to apply it>" --title "<short title>"
 ```
 
-**Replace trigger:**
+`--type` is one of:
+
+- `feedback` — how the user wants you to work
+- `user` — who the user is (role, expertise)
+- `project` — an ongoing goal or constraint
+- `reference` — a pointer to an external resource (URL, ticket, dashboard)
 
-> User: "actually we bumped to v2.6.16 from v2.5.27"
+This writes a granular fact file with the rationale attached, not just a bullet.
 
-Action: find existing "v2.5.27" bullet in MEMORY.md, replace the version. Silent.
+## Correct a fact
 
-**Remove trigger:**
+Capture the corrected version with `cmk remember`, then remove the stale entry
+with `cmk forget` (below) if it is now wrong. Do not hand-edit the old bullet.
 
-> User: "forget about the daily-distill cron — we're going to do something different"
+## Remove a fact
 
-Action: Ask the user "Remove the daily-distill entries from MEMORY.md Active Threads? (y/n)" before deleting.
+After confirming with the user (never remove a fact they did not ask to forget):
 
-## Rules
+```
+cmk forget "<substring or citation id>" --yes --reason "<why>"
+```
 
-- Never exceed the cap. Consolidate first if needed.
-- Always check for duplicates / near-duplicates before adding.
-- Replace is preferred over add when updating existing facts (avoids accumulating contradictory bullets).
-- Removal requires user confirmation.
-- For typed durable facts with explicit `**Why:**` / `**How to apply:**` structure, write to `context/memory/<type>_<slug>.md` and add a one-line entry to INDEX.md instead of MEMORY.md.
-- **Silent by default.** Do not narrate memory writes unless the user explicitly asked. The whole point is invisible bookkeeping.
+Tombstones the fact — it keeps an audit trail and is never a silent delete.
 
-## Common mistakes to avoid
+## What NOT to capture
 
-- Don't write conversational chatter to MEMORY.md ("user said hello"). Only durable facts.
-- Don't duplicate. Always check first.
-- Don't blow the cap. Consolidate first.
-- Don't announce. Silent unless asked.
-- Don't promote everything to the granular archive — the scratchpad is the default. Granular files are for facts with explicit rationale that have long shelf life.
+- Throwaway chatter ("user said hi").
+- Facts about the current task only — those die with the task; they are not memory.
+- Anything you would not want committed to git. Poison_Guard screens secrets, but
+  do not lean on it as the first line of defense.

package/template/.gitignore.fragment

@@ -10,3 +10,9 @@ context/.index/
 
 # Run-time locks + transient state
 context/.locks/
+
+# Diagnostic NDJSON logs (observability only; carry raw turn excerpts —
+# e.g. Task 92's low_trust_discarded traces — that are NOT Poison_Guard-
+# screened, so they must never be committed). The durable memory lives in
+# the scratchpads + fact files, not these logs.
+context/sessions/*.extract.log

package/template/CLAUDE.md.template

@@ -24,19 +24,29 @@ Precedence at session start: local > project > user (most-specific wins, others
 
 Health checks (HC-1..HC-8) verify each layer is wired correctly: install integrity, hook registration, transcript capture freshness, INDEX accuracy, cron registration, semantic search backend, native Auto Memory coexistence. See [`docs/adr/`](docs/adr/) and [`specs/v0.1.0/design.md`](specs/v0.1.0/design.md) for the full contract.
 
+### Recalling memory (for Claude)
+
+The snapshot injected at session start is a **bounded hot index, not everything** — there is a deeper, queryable archive. When a question is "what did we decide / what's our X / how does the user work / what's the setup," **query your memory instead of re-deriving the answer from scratch**:
+
+- **`cmk search "<topic>"`** — find any captured fact (decisions, preferences, config, lessons) across the project + user tiers.
+- **`context/memory/<type>_<slug>.md`** — the granular fact archive with full **Why / How** rationale (`context/memory/INDEX.md` lists them).
+- **`~/.claude-memory-kit/` (`USER.md` / `HABITS.md` / `LESSONS.md`)** — how this user works across *all* their projects.
+
+Reach for these *first* — re-deriving an answer the project already recorded (by re-reading files, re-searching, or working it out again) wastes the memory that exists precisely so you don't have to. Recall from memory first, then verify against the source if needed.
+
 ### Memory write rules (for Claude)
 
-When you learn something durable about this project or the user:
+Most capture is automatic — the Stop hook extracts durable facts each turn, no action needed. To capture something **explicitly**, the **`memory-write` skill** carries the full procedure; it loads on demand when you save a fact. The invariants it enforces:
 
-1. **Working state** (current threads, today's environment, open decisions) → write to `context/MEMORY.md` (≤2,500 chars). Consolidate at the cap.
-2. **Typed durable fact** (user role / project decision / feedback / external reference) → create `context/memory/<type>_<slug>.md` with full YAML frontmatter; add a one-line entry to `context/memory/INDEX.md`.
-3. **Cross-project lesson** → user-tier `~/.claude-memory-kit/LESSONS.md` (via `cmk lessons promote`).
-4. **Never duplicate** between scratchpad and granular archive. If a working-state item becomes durable, MOVE it.
-5. **Confirm silently.** Frozen-snapshot semantics mean the write takes effect next session.
+- **Capture through `cmk remember`** — never hand-write `MEMORY.md`, `USER.md`, or files under `context/memory/`. The command routes through the kit's safe path (Poison_Guard secret screen, home-path → `~` abstraction so a committed fact never leaks your username, dedup, correct schema). Add `--why` / `--how` / `--type` to record a durable preference or decision richly — a bare bullet loses the *why*, which is the part worth keeping.
+- **Machine-specific config** (absolute paths only valid on this machine) → `context.local/machine-paths.md` (gitignored), not `cmk remember`.
+- **Cross-project lesson** (true on every project) → `cmk lessons promote <id>` moves a project fact to the user tier; never hand-edit the user-tier files (`LESSONS.md` / `HABITS.md` / `USER.md`).
+- **Confirm silently.** Don't announce captures. Frozen-snapshot semantics mean a write takes effect next session.
 
 ### Privacy
 
-Anything inside `<private>...</private>` tags in a user prompt is stripped before any disk write — never persisted in any form. Per-fact `private: true` frontmatter excludes a fact from the session-start digest.
+- Anything inside `<private>...</private>` tags in a user prompt is stripped before any disk write — never persisted in any form.
+- `cmk remember` (and auto-extract) abstract absolute home-dir paths (`C:\Users\you\…`, `/home/you/…`, `/Users/you/…`) to `~` before writing to a committed/shared tier, so a fact never ships your username and stays portable across machines. Genuinely machine-specific paths belong in `context.local/` (gitignored).
 
 ### Uninstall / remove this block
 

package/template/local/machine-paths.md.template

@@ -1,17 +1,6 @@
 <!-- Cap: 1500 chars · Last distilled: {{TODAY}} · Last health check: {{TODAY}} -->
 
-<!--
-machine-paths.md = absolute paths specific to THIS machine for THIS project.
-Local tier (gitignored — never committed). Highest priority in the 3-tier
-precedence model — overrides anything in context/ or ~/.claude-memory-kit/.
-3 fixed sections per design §2.1.
-
-Bullet+provenance format (universal — see provenance.mjs):
-  - (L-XXXXXXXX) the bullet text on one line
-    <!-- source, source_line, sha1, write, trust, at -->
-
-Auto-populated by `cmk persona generate` (Task N, design §16.16); empty is fine.
--->
+<!-- machine-paths.md = absolute tool/project paths specific to THIS machine (local tier — gitignored, highest precedence). Replace the examples; empty sections are fine. -->
 
 # Machine paths (local tier)
 

package/template/local/overrides.md.template

@@ -1,16 +1,6 @@
 <!-- Cap: 1500 chars · Last distilled: {{TODAY}} · Last health check: {{TODAY}} -->
 
-<!--
-overrides.md = machine-specific overrides of preferences declared elsewhere.
-Local tier (gitignored). Highest precedence in the 3-tier model.
-3 fixed sections per design §2.1.
-
-Bullet+provenance format (universal — see provenance.mjs):
-  - (L-XXXXXXXX) the bullet text on one line
-    <!-- source, source_line, sha1, write, trust, at -->
-
-Auto-populated by `cmk persona generate` (Task N, design §16.16); empty is fine.
--->
+<!-- overrides.md = machine-specific overrides of preferences declared elsewhere (local tier — gitignored, highest precedence). Replace the examples; empty sections are fine. -->
 
 # Machine-specific overrides (local tier)
 

package/template/project/MEMORY.md.template

@@ -1,47 +1,26 @@
 <!-- Cap: 2500 chars · Last distilled: {{TODAY}} · Last health check: {{TODAY}} -->
 
-<!--
-MEMORY.md is the working scratchpad. Cap measured by `wc -c` over the whole
-file (header + comments + bullets). Consolidation triggers at >95% (Task 12);
-stale bullets (>14d without `trust: high`) drop on consolidate. Three fixed
-sections per design §2.1.
-
-Bullet+provenance format (universal across all scratchpads):
-- (P-XXXXXXXX) the bullet text on one line
-  <!-- source: <file>, source_line: <int>, sha1: <40-hex>, write: <enum>, trust: <enum>, at: <ISO 8601> -->
-
-Each section ships with a placeholder seed bullet — replace with real project
-state. Empty sections are fine if you haven't captured anything yet.
--->
-
 # Working Memory
 
+<!-- Your project's working scratchpad. Replace the example bullets with real state; empty sections are fine. -->
+
 ## Active Threads
 
-<!--
-Current work in progress. Drop bullets when work resolves. Auto-extract
-(Task 23) writes here; manual edits welcome too.
--->
+<!-- Current work in progress. Drop bullets as work resolves. -->
 
 - (P-T6M95JXF) (example) reviewing PR #142 for the auth refactor
   <!-- source: MEMORY.md, source_line: 22, sha1: 0000000000000000000000000000000000000000, write: manual-edit, trust: medium, at: 2020-01-01T00:00:00Z -->
 
 ## Environment Notes
 
-<!--
-Tool versions, paths, URLs, env state. Update on change. Auto-extract picks
-these up from PostToolUse hook events; manual edits welcome.
--->
+<!-- Tool versions, paths, URLs, env state. -->
 
 - (P-R662a95Y) (example) Node 20.x; Python 3.13; Postgres 16 in the test environment
   <!-- source: MEMORY.md, source_line: 30, sha1: 0000000000000000000000000000000000000000, write: manual-edit, trust: medium, at: 2020-01-01T00:00:00Z -->
 
 ## Pending Decisions
 
-<!--
-Things the user still has to decide. Remove when resolved. Auto-populated by
-`cmk persona generate` (Task N, design §16.16); empty is fine.
--->
+<!-- Things still to decide. Remove when resolved. -->
 
 - (P-KU3aNBX9) (example) decide whether to deprecate /api/v1 by Q3 2026
   <!-- source: MEMORY.md, source_line: 38, sha1: 0000000000000000000000000000000000000000, write: manual-edit, trust: medium, at: 2020-01-01T00:00:00Z -->

package/template/project/SOUL.md.template

@@ -1,15 +1,6 @@
 <!-- Cap: 1800 chars · Last distilled: {{TODAY}} · Last health check: {{TODAY}} -->
 
-<!--
-SOUL.md = project persona / disposition / norms. Where USER.md = "who the user
-is", SOUL.md = "how Claude should show up". 3 fixed sections per design §2.1.
-
-Bullet+provenance format (universal — see provenance.mjs):
-  - (P-XXXXXXXX) the bullet text on one line
-    <!-- source, source_line, sha1, write, trust, at -->
-
-Auto-populated by `cmk persona generate` (Task N, design §16.16); empty is fine.
--->
+<!-- SOUL.md = how Claude should show up in this project (tone, defaults, boundaries). Replace the example bullets; empty sections are fine. -->
 
 # Project Soul
 

package/template/user/fragments/INDEX.md.template

@@ -8,7 +8,7 @@ This file is auto-maintained by `cmk reindex`. Do not hand-edit unless
 you also delete the fact file it points to (or `cmk reindex` will
 overwrite your changes).
 
-Type taxonomy per design §2.2:
+Type taxonomy:
     - user_*       facts about the user
     - feedback_*   corrections / preferences
     - project_*    decisions with rationale (rare in user tier — most

package/template/.claude/hooks/pre-tool-memory.js

@@ -1,78 +0,0 @@
-#!/usr/bin/env node
-//
-// PreToolUse hook — guarantees the frozen memory snapshot loads
-// before the first tool call of each session, without relying on
-// Claude obeying CLAUDE.md's session-startup checklist.
-//
-// Reads context/USER.md, context/SOUL.md, context/MEMORY.md,
-// context/memory/INDEX.md, and today's session log (if exists),
-// formats them as a single block, and emits the block as
-// additionalContext via the hook's output protocol.
-//
-// Fires once per session — uses a /tmp flag file to suppress subsequent
-// firings within the same session. The flag is keyed by session_id when
-// available, falling back to a per-day flag.
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-try {
-  const raw = fs.readFileSync(0, 'utf8');
-  if (!raw) process.exit(0);
-  const input = JSON.parse(raw);
-
-  // Resolve project dir.
-  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-  const ctx = path.join(projectDir, 'context');
-
-  // Per-project flag prefix. Allows multiple projects to coexist on the
-  // same machine without their session flags colliding.
-  const projectSlug = path.basename(projectDir).replace(/[^a-z0-9-]/gi, '_');
-
-  // One-per-session guard.
-  const sid = input.session_id || input.sessionId || `day-${new Date().toISOString().slice(0, 10)}`;
-  const flagPath = path.join(os.tmpdir(), `cmk-${projectSlug}-mem-injected-${sid.replace(/[^a-z0-9-]/gi, '_')}`);
-  if (fs.existsSync(flagPath)) {
-    process.exit(0);
-  }
-
-  const parts = [];
-  const safeRead = (p, label) => {
-    if (fs.existsSync(p)) {
-      const content = fs.readFileSync(p, 'utf8');
-      if (content.trim()) {
-        parts.push(`\n--- ${label} (${p.replace(projectDir, '').replace(/^[/\\]+/, '')}) ---\n${content}`);
-      }
-    }
-  };
-
-  safeRead(path.join(ctx, 'SOUL.md'), 'Project soul (persona / disposition)');
-  safeRead(path.join(ctx, 'USER.md'), 'User profile');
-  safeRead(path.join(ctx, 'MEMORY.md'), 'Working memory (scratchpad)');
-  safeRead(path.join(ctx, 'memory', 'INDEX.md'), 'Granular memory index');
-  const today = new Date().toISOString().slice(0, 10);
-  safeRead(path.join(ctx, 'sessions', `${today}.md`), `Today's session log`);
-
-  if (parts.length === 0) {
-    process.exit(0);
-  }
-
-  const block = [
-    '# Memory snapshot (auto-injected on first tool call)',
-    '',
-    'The following files form this session\'s frozen memory snapshot. Reference them when responding; mid-session edits to these files persist to disk but take effect at the NEXT session.',
-    parts.join('\n'),
-  ].join('\n');
-
-  process.stdout.write(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      additionalContext: block,
-    },
-  }));
-
-  try { fs.writeFileSync(flagPath, String(Date.now())); } catch {}
-} catch (e) {
-  process.exit(0);
-}