@lh8ppl/claude-memory-kit 0.1.0 → 0.1.2

package/template/support/cron-jobs/daily-memory-distill.md

@@ -1,15 +1,15 @@
----
-name: Daily Memory Distillation
-time: '23:00'
-days: daily
-active: 'true'
-description: 'Distills durable facts from today''s session log into MEMORY.md and updates Last-distilled timestamp'
-timeout: 10m
-job_type: shell_command
-command: 'bash scripts/run-daily-distill.sh'
-working_directory: '${CLAUDE_PROJECT_DIR}'
----
-
-Invokes Claude headlessly to extract durable facts from `context/sessions/{today}.md` into `context/MEMORY.md`. Promotes typed facts to `context/memory/<type>_*.md` granular files. Enforces the 2,500-char MEMORY.md cap by consolidating older entries if needed. Updates the `Last distilled` timestamp so HC-3 stays green.
-
-See `scripts/run-daily-distill.sh` for the exact prompt and tool allowlist.
+---
+name: Daily Memory Distillation
+time: '23:00'
+days: daily
+active: 'true'
+description: 'Distills durable facts from today''s session log into MEMORY.md and updates Last-distilled timestamp'
+timeout: 10m
+job_type: shell_command
+command: 'bash scripts/run-daily-distill.sh'
+working_directory: '${CLAUDE_PROJECT_DIR}'
+---
+
+Invokes Claude headlessly to extract durable facts from `context/sessions/{today}.md` into `context/MEMORY.md`. Promotes typed facts to `context/memory/<type>_*.md` granular files. Enforces the 2,500-char MEMORY.md cap by consolidating older entries if needed. Updates the `Last distilled` timestamp so HC-3 stays green.
+
+See `scripts/run-daily-distill.sh` for the exact prompt and tool allowlist.

package/template/support/cron-jobs/nightly-memsearch-index.md

@@ -1,17 +1,17 @@
----
-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.
+---
+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/cron-jobs/weekly-memory-curator.md

@@ -1,15 +1,15 @@
----
-name: Weekly Memory Curator
-time: '09:00'
-days: sun
-active: 'true'
-description: 'Prunes, merges, and consolidates entries in MEMORY.md; updates Last-health-check timestamp'
-timeout: 15m
-job_type: shell_command
-command: 'bash scripts/run-weekly-curate.sh'
-working_directory: '${CLAUDE_PROJECT_DIR}'
----
-
-Conservative cleanup pass on `context/MEMORY.md`. Removes resolved Active Threads, merges duplicate bullets, drops clearly stale entries — but never ADDS content (that's the daily-distill's job). Logs results to today's session log under a "## Session — automated curation" heading.
-
-See `scripts/run-weekly-curate.sh` for the exact prompt and tool allowlist.
+---
+name: Weekly Memory Curator
+time: '09:00'
+days: sun
+active: 'true'
+description: 'Prunes, merges, and consolidates entries in MEMORY.md; updates Last-health-check timestamp'
+timeout: 15m
+job_type: shell_command
+command: 'bash scripts/run-weekly-curate.sh'
+working_directory: '${CLAUDE_PROJECT_DIR}'
+---
+
+Conservative cleanup pass on `context/MEMORY.md`. Removes resolved Active Threads, merges duplicate bullets, drops clearly stale entries — but never ADDS content (that's the daily-distill's job). Logs results to today's session log under a "## Session — automated curation" heading.
+
+See `scripts/run-weekly-curate.sh` for the exact prompt and tool allowlist.

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

@@ -1,57 +1,57 @@
-# 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. |
+# 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 +1,66 @@
-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
+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/auto-extract-memory.sh

@@ -1,102 +1,102 @@
-#!/usr/bin/env bash
-#
-# Auto-extract: invoked by the Stop hook in the background after every
-# assistant turn. Reads the turn from a temp file, runs Claude headlessly
-# with a focused fact-extraction prompt, and lets Claude write any
-# durable facts to MEMORY.md / USER.md / granular archive via the
-# memory-write skill.
-#
-# This is the "make it automatic" piece: instead of the user having to
-# say "remember this", the system harvests memory-worthy content from
-# every turn on its own.
-#
-# Args:
-#   $1 — path to a temp file containing the assistant turn's text
-#
-# Detached from the parent hook — runs in background, fire-and-forget.
-# Errors are swallowed (logged to context/sessions/{today}.extract.log).
-
-# Detached process contexts don't always inherit Git Bash's PATH on
-# Windows. Set it up explicitly. On Linux/macOS this is a no-op since
-# /usr/bin is already present.
-case ":$PATH:" in
-    *":/usr/bin:"*) ;;
-    *) export PATH="/usr/bin:/c/Program Files/Git/usr/bin:$PATH" ;;
-esac
-
-set -u
-
-TURN_FILE="${1:-}"
-[ -z "$TURN_FILE" ] && exit 0
-[ ! -f "$TURN_FILE" ] && exit 0
-
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-cd "$REPO_ROOT"
-
-TODAY=$(date +%Y-%m-%d)
-LOG="${REPO_ROOT}/context/sessions/${TODAY}.extract.log"
-
-TURN_TEXT=$(cat "$TURN_FILE")
-
-trap "rm -f \"$TURN_FILE\"" EXIT
-
-# Skip very short turns — nothing to extract.
-TURN_LEN=${#TURN_TEXT}
-if [ "$TURN_LEN" -lt 100 ]; then
-    echo "[$(date -Iseconds)] skip: turn too short ($TURN_LEN chars)" >> "$LOG"
-    exit 0
-fi
-
-PROMPT=$(cat <<EOF
-You are running as a silent background auto-extract task for this project. No one is watching this output. Be CONSERVATIVE — only capture what is clearly durable. Most turns will have nothing to save. That is the correct outcome.
-
-GOAL: look at the assistant turn below and decide whether the user (in the conversation that produced it) said anything that should be saved to memory. If yes, write it to context/MEMORY.md, context/USER.md, or context/memory/<type>_<slug>.md using the memory-write skill.
-
-EXTRACT and SAVE only when one of these is clearly present:
-- User explicitly asked to remember ("remember this", "note that", "save this", "from now on", "going forward", "i prefer")
-- User made a concrete decision worth carrying forward ("we're using X not Y", "let's go with X")
-- User corrected the assistant ("actually it's X not Y", "you got that wrong, X is the right answer")
-- Assistant acknowledged a NEW environment fact not already in MEMORY.md / USER.md (new tool version, new path, new config)
-- Assistant identified a durable rule with "Why:" / "How to apply:" structure
-
-DO NOT save:
-- Conversational chatter, hello/goodbye
-- One-off task execution narration ("ran the script, got output X")
-- Information already in MEMORY.md / USER.md / context/memory/ (check INDEX.md)
-- Anything you would summarize as "we discussed X" without a concrete decision
-
-STEPS:
-1. Read context/MEMORY.md, context/USER.md, and context/memory/INDEX.md to know current state.
-2. Read the turn content (passed as the user message of this conversation).
-3. If anything durable is present, use the memory-write skill rules:
-   - Choose the right file (scratchpad vs USER.md vs granular archive)
-   - Dedup-check against existing content
-   - Cap-check (consolidate first if over)
-   - Write a single bullet, concise (<200 chars)
-4. If nothing durable: exit silently. Do not write.
-5. Output ONE line of plain text: either "saved: <one-line summary of what>" or "skip: nothing durable" — for the log.
-
-CONSTRAINTS:
-- Use Read, Edit, and Bash(wc *) only.
-- Do NOT create new files outside context/memory/.
-- Do NOT commit, push, or run git operations.
-- Do NOT print anything except the one-line outcome.
-
-=== TURN CONTENT ===
-${TURN_TEXT}
-=== END TURN ===
-EOF
-)
-
-mkdir -p "$(dirname "$LOG")"
-echo "[$(date -Iseconds)] auto-extract fired on turn len=$TURN_LEN" >> "$LOG"
-
-OUTPUT=$(echo "$PROMPT" | claude --print \
-    --add-dir "$REPO_ROOT" \
-    --allowed-tools "Read" "Edit" "Bash(wc *)" \
-    --output-format text \
-    2>&1)
-EXIT=$?
-
-echo "[$(date -Iseconds)] auto-extract exit=$EXIT output: $OUTPUT" >> "$LOG"
-exit 0
+#!/usr/bin/env bash
+#
+# Auto-extract: invoked by the Stop hook in the background after every
+# assistant turn. Reads the turn from a temp file, runs Claude headlessly
+# with a focused fact-extraction prompt, and lets Claude write any
+# durable facts to MEMORY.md / USER.md / granular archive via the
+# memory-write skill.
+#
+# This is the "make it automatic" piece: instead of the user having to
+# say "remember this", the system harvests memory-worthy content from
+# every turn on its own.
+#
+# Args:
+#   $1 — path to a temp file containing the assistant turn's text
+#
+# Detached from the parent hook — runs in background, fire-and-forget.
+# Errors are swallowed (logged to context/sessions/{today}.extract.log).
+
+# Detached process contexts don't always inherit Git Bash's PATH on
+# Windows. Set it up explicitly. On Linux/macOS this is a no-op since
+# /usr/bin is already present.
+case ":$PATH:" in
+    *":/usr/bin:"*) ;;
+    *) export PATH="/usr/bin:/c/Program Files/Git/usr/bin:$PATH" ;;
+esac
+
+set -u
+
+TURN_FILE="${1:-}"
+[ -z "$TURN_FILE" ] && exit 0
+[ ! -f "$TURN_FILE" ] && exit 0
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+TODAY=$(date +%Y-%m-%d)
+LOG="${REPO_ROOT}/context/sessions/${TODAY}.extract.log"
+
+TURN_TEXT=$(cat "$TURN_FILE")
+
+trap "rm -f \"$TURN_FILE\"" EXIT
+
+# Skip very short turns — nothing to extract.
+TURN_LEN=${#TURN_TEXT}
+if [ "$TURN_LEN" -lt 100 ]; then
+    echo "[$(date -Iseconds)] skip: turn too short ($TURN_LEN chars)" >> "$LOG"
+    exit 0
+fi
+
+PROMPT=$(cat <<EOF
+You are running as a silent background auto-extract task for this project. No one is watching this output. Be CONSERVATIVE — only capture what is clearly durable. Most turns will have nothing to save. That is the correct outcome.
+
+GOAL: look at the assistant turn below and decide whether the user (in the conversation that produced it) said anything that should be saved to memory. If yes, write it to context/MEMORY.md, context/USER.md, or context/memory/<type>_<slug>.md using the memory-write skill.
+
+EXTRACT and SAVE only when one of these is clearly present:
+- User explicitly asked to remember ("remember this", "note that", "save this", "from now on", "going forward", "i prefer")
+- User made a concrete decision worth carrying forward ("we're using X not Y", "let's go with X")
+- User corrected the assistant ("actually it's X not Y", "you got that wrong, X is the right answer")
+- Assistant acknowledged a NEW environment fact not already in MEMORY.md / USER.md (new tool version, new path, new config)
+- Assistant identified a durable rule with "Why:" / "How to apply:" structure
+
+DO NOT save:
+- Conversational chatter, hello/goodbye
+- One-off task execution narration ("ran the script, got output X")
+- Information already in MEMORY.md / USER.md / context/memory/ (check INDEX.md)
+- Anything you would summarize as "we discussed X" without a concrete decision
+
+STEPS:
+1. Read context/MEMORY.md, context/USER.md, and context/memory/INDEX.md to know current state.
+2. Read the turn content (passed as the user message of this conversation).
+3. If anything durable is present, use the memory-write skill rules:
+   - Choose the right file (scratchpad vs USER.md vs granular archive)
+   - Dedup-check against existing content
+   - Cap-check (consolidate first if over)
+   - Write a single bullet, concise (<200 chars)
+4. If nothing durable: exit silently. Do not write.
+5. Output ONE line of plain text: either "saved: <one-line summary of what>" or "skip: nothing durable" — for the log.
+
+CONSTRAINTS:
+- Use Read, Edit, and Bash(wc *) only.
+- Do NOT create new files outside context/memory/.
+- Do NOT commit, push, or run git operations.
+- Do NOT print anything except the one-line outcome.
+
+=== TURN CONTENT ===
+${TURN_TEXT}
+=== END TURN ===
+EOF
+)
+
+mkdir -p "$(dirname "$LOG")"
+echo "[$(date -Iseconds)] auto-extract fired on turn len=$TURN_LEN" >> "$LOG"
+
+OUTPUT=$(echo "$PROMPT" | claude --print \
+    --add-dir "$REPO_ROOT" \
+    --allowed-tools "Read" "Edit" "Bash(wc *)" \
+    --output-format text \
+    2>&1)
+EXIT=$?
+
+echo "[$(date -Iseconds)] auto-extract exit=$EXIT output: $OUTPUT" >> "$LOG"
+exit 0