@lh8ppl/claude-memory-kit 0.2.2 → 0.2.4

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

@@ -16,3 +16,9 @@ context/.locks/
 # 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/support/cron-jobs/nightly-memsearch-index.md

@@ -1,17 +0,0 @@
----
-name: Nightly MemSearch Index
-time: '02:00'
-days: daily
-active: 'true'
-description: 'Re-indexes context/ markdown files for vector search'
-timeout: 10m
-job_type: shell_command
-command: 'bash scripts/memsearch-index-with-flush.sh context/memory context/sessions context/transcripts'
-working_directory: '${CLAUDE_PROJECT_DIR}'
-# Requires Layer 5 installed (memsearch on PATH + a reachable Milvus backend).
-# On Windows: Docker Desktop running with Milvus container — see context/SETUP.md.
-# If memsearch isn't installed or backend isn't reachable, the task will fail;
-# HC-7 (backend reachability) will flag it on the next session start.
----
-
-Updates the memsearch vector index with any new content from `context/memory/`, `context/sessions/`, and `context/transcripts/`. Idempotent: only re-embeds chunks whose hash changed since the last run.

package/template/support/milvus-deploy/README.md

@@ -1,57 +0,0 @@
-# Milvus deployment (Windows + optional)
-
-This compose stack runs Milvus v2.6.16 plus its required dependencies (etcd, MinIO) as three local containers. It's used by **Layer 5** (memsearch vector search) of the memory system.
-
-## When you need this
-
-- **Windows**: required. `milvus-lite` (the default embedded vector store memsearch ships) has no Windows wheels on PyPI. Use this Docker stack instead.
-- **Linux / macOS**: optional. memsearch auto-installs milvus-lite and uses it at `~/.memsearch/milvus.db`. Skip this directory entirely unless you specifically want a remote Milvus.
-
-## Bring it up
-
-```bash
-cd milvus-deploy
-docker compose up -d
-```
-
-Wait ~30-60 seconds for all three containers to report `(healthy)`:
-
-```bash
-docker compose ps
-```
-
-You should see `milvus-etcd`, `milvus-minio`, `milvus-standalone` all `Up (healthy)`.
-
-## Configure memsearch to use it
-
-```bash
-memsearch config set milvus.uri "http://localhost:19530"
-```
-
-## Bring it down
-
-```bash
-docker compose down
-```
-
-Volumes persist in `./volumes/` — re-running `up -d` reuses the same data.
-
-## Why a multi-container stack and not just `milvus-standalone`?
-
-Milvus standalone needs etcd (metadata store) and MinIO (object storage for segments and index data). On Linux/macOS, `milvus-lite` bundles all of that into one Python wheel; on Windows there's no equivalent wheel, so the three services run as separate containers.
-
-The single-container `docker run milvusdb/milvus:latest standalone` pattern referenced in some older docs is no longer supported — `latest` is `v3.0-beta` whose entrypoint doesn't accept `standalone` as a command. Use this compose file with the pinned versions instead.
-
-## Known quirk: memsearch index without flush
-
-memsearch v0.4.x doesn't call `flush()` after `MilvusStore.upsert()`. On Milvus v2.6+ (Woodpecker WAL), this means `memsearch index` reports success but the data isn't searchable until a flush forces the growing segment to seal.
-
-Use `scripts/memsearch-index-with-flush.sh` instead of raw `memsearch index` until upstream ships a fix. Tracked as [memsearch issue #534](https://github.com/zilliztech/memsearch/issues/534).
-
-## Pinned versions
-
-| Image | Version | Why pinned |
-|---|---|---|
-| `milvusdb/milvus` | `v2.6.16` | Latest stable v2.6 line. `latest` tag is v3.0-beta and crashes. |
-| `quay.io/coreos/etcd` | `v3.5.25` | Compatible with milvus v2.6. |
-| `minio/minio` | `RELEASE.2024-12-18T13-15-44Z` | Recent stable RELEASE tag. |

package/template/support/milvus-deploy/docker-compose.yml

@@ -1,66 +0,0 @@
-version: '3.5'
-
-services:
-  etcd:
-    container_name: milvus-etcd
-    image: quay.io/coreos/etcd:v3.5.25
-    environment:
-      - ETCD_AUTO_COMPACTION_MODE=revision
-      - ETCD_AUTO_COMPACTION_RETENTION=1000
-      - ETCD_QUOTA_BACKEND_BYTES=4294967296
-      - ETCD_SNAPSHOT_COUNT=50000
-    volumes:
-      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/etcd:/etcd
-    command: etcd -advertise-client-urls=http://etcd:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
-    healthcheck:
-      test: ["CMD", "etcdctl", "endpoint", "health"]
-      interval: 30s
-      timeout: 20s
-      retries: 3
-
-  minio:
-    container_name: milvus-minio
-    image: minio/minio:RELEASE.2024-12-18T13-15-44Z
-    environment:
-      MINIO_ACCESS_KEY: minioadmin
-      MINIO_SECRET_KEY: minioadmin
-    ports:
-      - "9001:9001"
-      - "9000:9000"
-    volumes:
-      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/minio:/minio_data
-    command: minio server /minio_data --console-address ":9001"
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
-      interval: 30s
-      timeout: 20s
-      retries: 3
-
-  standalone:
-    container_name: milvus-standalone
-    image: milvusdb/milvus:v2.6.16
-    command: ["milvus", "run", "standalone"]
-    security_opt:
-    - seccomp:unconfined
-    environment:
-      ETCD_ENDPOINTS: etcd:2379
-      MINIO_ADDRESS: minio:9000
-      MQ_TYPE: woodpecker
-    volumes:
-      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/milvus:/var/lib/milvus
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"]
-      interval: 30s
-      start_period: 90s
-      timeout: 20s
-      retries: 3
-    ports:
-      - "19530:19530"
-      - "9091:9091"
-    depends_on:
-      - "etcd"
-      - "minio"
-
-networks:
-  default:
-    name: milvus

package/template/support/scripts/memsearch-index-with-flush.sh

@@ -1,59 +0,0 @@
-#!/usr/bin/env bash
-#
-# Wraps `memsearch index` to also force a Milvus flush afterward.
-#
-# Why: Milvus v2.6+ uses the Woodpecker WAL backend, which (unlike v2.5's
-# Pulsar) does not auto-flush growing segments on a short timer. As a result,
-# `memsearch index` reports "Indexed N chunks" successfully but
-# `get_collection_stats` returns 0 rows and search returns no results until
-# a manual flush forces the growing segment to seal.
-#
-# This wrapper runs the index, then issues a flush via pymilvus.
-#
-# Usage:
-#   bash scripts/memsearch-index-with-flush.sh context/memory context/sessions context/transcripts
-#
-# Reads MILVUS_URI from env (falls back to the memsearch config value, then localhost).
-# Reads MILVUS_COLLECTION from env (falls back to memsearch config, then "memsearch_chunks").
-
-# Task Scheduler / launchd / unattended cron contexts don't always inherit
-# the user's PATH. Set it up explicitly for the common locations.
-case ":$PATH:" in
-    *":/usr/bin:"*) ;;
-    *) export PATH="/usr/bin:/usr/local/bin:/opt/homebrew/bin:/c/Program Files/Git/usr/bin:$PATH" ;;
-esac
-
-# On Windows, also add the Python Scripts dir where `memsearch.exe` lands.
-if [ -d "/c/Users/$USERNAME/AppData/Local/Programs/Python" ]; then
-    for d in /c/Users/$USERNAME/AppData/Local/Programs/Python/Python*/Scripts \
-             /c/Users/$USERNAME/AppData/Local/Programs/Python/Python*; do
-        [ -d "$d" ] && export PATH="$d:$PATH"
-    done
-fi
-
-set -euo pipefail
-
-# Step 1 — index. Pass through all args.
-memsearch index "$@"
-
-# Step 2 — flush.
-MILVUS_URI="${MILVUS_URI:-$(memsearch config get milvus.uri 2>/dev/null | tail -n1 | tr -d '\r')}"
-MILVUS_COLLECTION="${MILVUS_COLLECTION:-$(memsearch config get milvus.collection 2>/dev/null | tail -n1 | tr -d '\r')}"
-MILVUS_URI="${MILVUS_URI:-http://localhost:19530}"
-MILVUS_COLLECTION="${MILVUS_COLLECTION:-memsearch_chunks}"
-
-# Flush only if we're using a remote Milvus (milvus-lite auto-flushes).
-case "$MILVUS_URI" in
-    http://*|https://*|tcp://*)
-        python -c "
-from pymilvus import MilvusClient
-client = MilvusClient(uri='${MILVUS_URI}')
-client.flush('${MILVUS_COLLECTION}')
-stats = client.get_collection_stats('${MILVUS_COLLECTION}')
-print(f'Flushed. Collection {stats!r}')
-"
-        ;;
-    *)
-        echo "Local milvus-lite detected (${MILVUS_URI}); skipping flush (auto-flush)."
-        ;;
-esac