@lh8ppl/claude-memory-kit 0.2.1 → 0.2.3

package/src/weekly-curate.mjs

@@ -339,6 +339,11 @@ export async function weeklyCurate({
       backend,
       now: ts,
       cooldownMs: 0,
+      // Task 111 (F-2): the weekly janitor sweeps the whole-project `facts`
+      // corpus (heavier than a session summary) and runs as a cron/lazy child
+      // with no 60s hook ceiling — give the classifier headroom so a large
+      // corpus doesn't time out. (Corpus is byte-capped at PERSONA_CORPUS_BYTES.)
+      timeoutMs: 120_000,
     });
   }
 

package/src/write-fact.mjs

@@ -248,7 +248,7 @@ export function writeFact(opts = {}) {
   // 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
+  // `cmk doctor` HC-5 failed from the first capture (Task 85; live-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.
@@ -258,5 +258,29 @@ export function writeFact(opts = {}) {
     // index rebuild is best-effort; capture already succeeded
   }
 
+  // Default create-audit (Task 123.A / D-103). writeFact is the single boundary
+  // every fact create flows through, so it owns the operational audit entry —
+  // the prior "caller's responsibility" design left 3 of 4 create paths
+  // (auto-extract, explicit-remember, graduation) silently unaudited (cut-gate7:
+  // 6 creates → 0 audit lines). Callers that emit a richer-semantic audit for
+  // the same write (merge-facts → `merged`/CURATED_MERGE) pass `audit:false` to
+  // avoid a redundant `created` entry. Best-effort: a successful capture must
+  // not be turned into an error by an audit-log hiccup.
+  if (opts.audit !== false) {
+    try {
+      appendAuditEntry(tierRoot, {
+        ts: createdAt,
+        action: 'created',
+        tier: opts.tier,
+        id,
+        reasonCode: REASON_CODES.FACT_CREATED,
+        paths: { after: path },
+        extra: { writeSource: factOpts.writeSource, trust: factOpts.trust },
+      });
+    } catch {
+      // audit append is best-effort; the fact is already durably on disk
+    }
+  }
+
   return { action: 'created', id, path };
 }

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

@@ -1,33 +1,55 @@
 ---
 name: memory-write
-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
+description: Captures a durable fact to project memory through the kit's safe write path (Poison_Guard secret/injection screening + home-path sanitization + dedup + conflict detection) — preferring the cmk MCP tools (mk_remember / mk_forget / mk_trust) when connected, falling back to the cmk CLI. 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"), removing one ("forget about X"), and adjusting how much a saved fact is trusted ("trust this", "that's important — keep it", "that's not important / I'm not sure about that / low priority"). Skip throwaway chatter and facts that only matter to the current task.
+allowed-tools: mcp__cmk__mk_remember mcp__cmk__mk_forget mcp__cmk__mk_trust Bash(cmk remember *) Bash(cmk forget *) Bash(cmk trust *) Read
 ---
 
 # Capturing durable memory
 
-Durable facts — preferences, decisions, environment state — are saved by running
-the kit's CLI. The CLI is the only safe way to write memory.
+Durable facts — preferences, decisions, environment state — are saved through the
+kit's safe write path (Poison_Guard secret screening + home-path sanitization +
+dedup + conflict detection).
 
-## MUST / NEVER
-
-- **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.
+- **NEVER hand-edit** `context/MEMORY.md`, `context/USER.md`, or any file under
+  `context/memory/`. Direct edits bypass screening 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.
 
-## Capture a fact (default)
+There are two equivalent surfaces onto the same safe path. **Prefer the MCP tools
+when the `cmk` server is connected** — params are structured data, so backtick /
+`$()` / quote-heavy rationale can't be mangled by a shell, and there's no
+per-command approval prompt.
+
+## Preferred: the cmk MCP tools (when connected)
+
+- **Capture** → call `mk_remember` with `text`. For a preference, working-style
+  rule, or constraint, also pass `why`, `how`, `title`, and `type` — this writes a
+  rich Why/How fact file, not just a bullet.
+- **Remove** → call `mk_forget` with the fact `id`. Two-step: the first call
+  previews what would be removed and returns a `confirm_token`; call again with
+  that token to tombstone (audit trail preserved). Confirm with the user first.
+- **Adjust trust** → call `mk_trust` with the fact `id` and a `level` of `low`,
+  `medium`, or `high`. Use when the user signals how much a saved fact matters:
+  "trust this" / "that's important — keep it" → `high`; "that's not important / I'm
+  not sure / low priority" → `low`. Trust drives what gets injected first and what
+  ages out, so this is the user steering their own memory without editing files.
+
+`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)
+
+## Fallback: the cmk CLI (when the MCP server isn't connected)
+
+Capture a bullet:
 
 ```
 cmk remember "<the fact, one sentence>"
 ```
 
-Writes a bullet to `context/MEMORY.md`. Use it for in-flight work, decisions,
-tool versions, paths, and environment facts.
-
-When the fact is not active work, pick its section:
+Pick a section for facts that are not active work:
 
 ```
 cmk remember "<fact>" --section "Environment Notes"
@@ -35,32 +57,21 @@ cmk remember "<fact>" --section "Environment Notes"
 
 Sections: `Active Threads` (default), `Environment Notes`, `Pending Decisions`.
 
-## 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:
+Capture WITH rationale (preference, working-style rule, project constraint):
 
 ```
 cmk remember "<headline>" --type <type> --why "<why it holds>" --how "<how to apply it>" --title "<short title>"
 ```
 
-`--type` is one of:
+For backtick / quote-heavy rationale, pass it off-shell as a JSON object so the
+shell can't corrupt it (the D-81 fix):
 
-- `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)
-
-This writes a granular fact file with the rationale attached, not just a bullet.
-
-## Correct a fact
-
-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.
-
-## Remove a fact
+```
+cmk remember --from-file fact.json
+```
 
-After confirming with the user (never remove a fact they did not ask to forget):
+Remove a fact (after confirming with the user — never remove one they did not ask
+to forget):
 
 ```
 cmk forget "<substring or citation id>" --yes --reason "<why>"
@@ -68,6 +79,12 @@ cmk forget "<substring or citation id>" --yes --reason "<why>"
 
 Tombstones the fact — it keeps an audit trail and is never a silent delete.
 
+Adjust how much a saved fact is trusted (`<id>` comes from `cmk search`):
+
+```
+cmk trust <id> <low|medium|high>
+```
+
 ## What NOT to capture
 
 - Throwaway chatter ("user said hi").

package/template/.gitignore.fragment

@@ -12,7 +12,13 @@ context/.index/
 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.
+# e.g. discarded-low-trust traces — that are NOT secret-screened, so they
+# must never be committed). The durable memory lives in the scratchpads +
+# fact files, not these logs.
 context/sessions/*.extract.log
+
+# Transcript-extraction temp buffer. capture-turn writes
+# context/transcripts/.extract-<ts>.tmp as the turn buffer for the detached
+# auto-extract child, which consumes + deletes it. Gitignored so a crash-orphaned
+# partial (raw, un-screened turn content) never travels with `git clone`.
+context/transcripts/.extract-*.tmp

package/template/CLAUDE.md.template

@@ -2,7 +2,7 @@
 
 This project uses **claude-memory-kit** for per-project, in-repo memory that survives session boundaries. Memory lives in `context/` (committed) and `context.local/` (gitignored). Cross-project memory lives at `~/.claude-memory-kit/` (or `$MEMORY_KIT_USER_DIR`).
 
-> v0.1.0 is under active development. This block is the runtime contract. Specific mechanisms (auto-extract, memory-write skill, MCP search) come online incrementally — `cmk doctor` will tell you which layers are active in the current install. Full architecture: <https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/journey/v0.1.0-build-log.md>
+> This block is the runtime contract for the kit. `cmk doctor` reports which layers are active in your install. Docs: <https://github.com/LH8PPL/claude-memory-kit>
 
 ### Where memory lives
 
@@ -22,7 +22,7 @@ Precedence at session start: local > project > user (most-specific wins, others
 
 ### Health checks (when `cmk doctor` is live)
 
-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.
+The `cmk doctor` health checks verify each layer is wired correctly: install integrity, hook registration, transcript capture freshness, INDEX accuracy, cron registration, semantic search backend, native Auto Memory coexistence, and stale locks. Full design + decision records: <https://github.com/LH8PPL/claude-memory-kit>.
 
 ### Recalling memory (for Claude)
 

package/template/docs/journey/journey-log.md.template

@@ -23,7 +23,7 @@ How to update it:
 
 For inspiration:
   See claude-memory-kit's own journey log as a worked example:
-  https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/journey/v0.1.0-build-log.md
+  https://github.com/LH8PPL/claude-memory-kit/tree/main/docs/journey
 
 This template uses HTML comments (like this one) to coach the
 user through each section. The comments are stripped from