@lh8ppl/claude-memory-kit 0.1.0

package/template/support/scripts/register-crons.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""
+register-crons.py — reads cron/jobs/*.md and registers the active jobs with
+the host scheduler (Task Scheduler on Windows, crontab on Unix).
+
+Idempotent: re-running re-registers any missing tasks without disturbing existing ones.
+
+Usage:
+  python scripts/register-crons.py [--dry-run] [--unregister NAME]
+
+The task name prefix defaults to the project directory's basename
+(slugified). Override with the env var CMK_TASK_PREFIX, e.g.:
+
+  CMK_TASK_PREFIX=ytslide- python scripts/register-crons.py
+
+Job file format (YAML frontmatter):
+  ---
+  name: Daily Memory Distillation
+  time: '23:00'
+  days: daily | mon | tue | wed | thu | fri | sat | sun
+  active: 'true'
+  job_type: timestamp_refresh | shell_command | claude_prompt
+  command: 'bash scripts/run-daily-distill.sh'
+  working_directory: '${CLAUDE_PROJECT_DIR}'
+  ---
+  [task body / prompt]
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import platform
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    print("ERROR: pyyaml not installed. Run: python -m pip install pyyaml", file=sys.stderr)
+    sys.exit(1)
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+JOBS_DIR = REPO_ROOT / "cron" / "jobs"
+
+
+def _default_prefix() -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", REPO_ROOT.name.lower()).strip("-")
+    return f"{slug}-" if slug else "cmk-"
+
+
+TASK_NAME_PREFIX = os.environ.get("CMK_TASK_PREFIX", _default_prefix())
+
+DAY_MAP = {"daily": "DAILY", "mon": "MON", "tue": "TUE", "wed": "WED",
+           "thu": "THU", "fri": "FRI", "sat": "SAT", "sun": "SUN"}
+
+
+def slugify(name: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+
+
+def parse_job_file(path: Path) -> dict | None:
+    text = path.read_text(encoding="utf-8")
+    m = re.match(r"^---\s*\n(.*?)\n---\s*\n(.*)$", text, re.DOTALL)
+    if not m:
+        print(f"WARN: {path.name} has no YAML frontmatter, skipping")
+        return None
+    front = yaml.safe_load(m.group(1)) or {}
+    front["__body__"] = m.group(2).strip()
+    front["__source__"] = path.name
+    return front
+
+
+def _windows_bash_path() -> str | None:
+    """Find Git Bash on Windows. Task Scheduler runs `cmd /c` with System32
+    high on PATH, so a bare `bash` command resolves to Windows' WSL bash
+    launcher (which fails if no WSL distro is configured)."""
+    candidates = [
+        Path(r"C:\Program Files\Git\usr\bin\bash.exe"),
+        Path(r"C:\Program Files\Git\bin\bash.exe"),
+        Path(r"C:\Program Files (x86)\Git\usr\bin\bash.exe"),
+    ]
+    for p in candidates:
+        if p.exists():
+            return str(p)
+    return None
+
+
+def build_task_command(job: dict) -> str | None:
+    jt = job.get("job_type")
+    wd = job.get("working_directory", "").replace("${CLAUDE_PROJECT_DIR}", str(REPO_ROOT))
+    if jt == "shell_command":
+        cmd = job.get("command", "")
+        if not cmd:
+            return None
+        if platform.system() == "Windows":
+            if cmd.startswith("bash "):
+                gitbash = _windows_bash_path()
+                if gitbash:
+                    cmd = f'"{gitbash}" {cmd[5:]}'
+            if wd:
+                return f'cmd /c "cd /d \"{wd}\" && {cmd}"'
+            return f'cmd /c "{cmd}"'
+        if wd:
+            return f'sh -c "cd \"{wd}\" && {cmd}"'
+        return cmd
+    if jt == "timestamp_refresh":
+        helper = REPO_ROOT / "scripts" / "refresh-distill-timestamp.py"
+        py = "python" if platform.system() == "Windows" else "python3"
+        return f'{py} "{helper}"'
+    if jt == "claude_prompt":
+        msg = f"Job {job.get('name')!r} is registered but its body needs Claude CLI to run."
+        if platform.system() == "Windows":
+            return f'cmd /c "echo {msg}"'
+        return f'sh -c "echo {msg}"'
+    return None
+
+
+def register_windows(job: dict, dry_run: bool) -> tuple[bool, str]:
+    name = TASK_NAME_PREFIX + slugify(job["name"])
+    time = job.get("time", "")
+    days = job.get("days", "daily")
+    cmd = build_task_command(job)
+    if not cmd:
+        return False, "no command for this job_type"
+
+    if days == "daily":
+        schedule = ["/sc", "daily"]
+    elif days in DAY_MAP:
+        schedule = ["/sc", "weekly", "/d", DAY_MAP[days]]
+    else:
+        return False, f"unknown days value: {days!r}"
+
+    args = [
+        "schtasks", "/create", "/tn", name,
+        "/tr", cmd,
+        "/st", time,
+        *schedule,
+        "/f",
+    ]
+    if dry_run:
+        return True, "DRY-RUN: " + " ".join(args)
+    result = subprocess.run(args, capture_output=True, text=True, check=False)
+    if result.returncode != 0:
+        return False, f"schtasks failed: {result.stderr.strip() or result.stdout.strip()}"
+    return True, f"registered as {name}"
+
+
+def register_unix(job: dict, dry_run: bool) -> tuple[bool, str]:
+    name = TASK_NAME_PREFIX + slugify(job["name"])
+    time = job.get("time", "")
+    days = job.get("days", "daily")
+    cmd = build_task_command(job)
+    if not cmd:
+        return False, "no command for this job_type"
+
+    if not re.match(r"^\d{2}:\d{2}$", time):
+        return False, f"bad time format: {time!r}"
+    hh, mm = time.split(":")
+
+    if days == "daily":
+        day_field = "*"
+    elif days in DAY_MAP:
+        day_field = {"mon": "1", "tue": "2", "wed": "3", "thu": "4",
+                     "fri": "5", "sat": "6", "sun": "0"}[days]
+    else:
+        return False, f"unknown days value: {days!r}"
+
+    cron_line = f"{mm} {hh} * * {day_field} {cmd}  # {name}"
+    if dry_run:
+        return True, "DRY-RUN: would append to crontab: " + cron_line
+
+    existing = subprocess.run(["crontab", "-l"], capture_output=True, text=True).stdout
+    if name in existing:
+        return True, f"{name} already in crontab"
+    new = existing.rstrip() + "\n" + cron_line + "\n"
+    proc = subprocess.run(["crontab", "-"], input=new, text=True, capture_output=True)
+    if proc.returncode != 0:
+        return False, f"crontab failed: {proc.stderr.strip()}"
+    return True, f"appended {name}"
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--dry-run", action="store_true", help="Print what would happen without changing anything")
+    p.add_argument("--unregister", help="Remove a task by name (with or without prefix)")
+    args = p.parse_args()
+
+    if args.unregister:
+        name = args.unregister if args.unregister.startswith(TASK_NAME_PREFIX) else TASK_NAME_PREFIX + slugify(args.unregister)
+        if platform.system() == "Windows":
+            r = subprocess.run(["schtasks", "/delete", "/tn", name, "/f"], capture_output=True, text=True)
+            print(r.stdout or r.stderr)
+            return r.returncode
+        existing = subprocess.run(["crontab", "-l"], capture_output=True, text=True).stdout
+        new = "\n".join(line for line in existing.splitlines() if name not in line) + "\n"
+        subprocess.run(["crontab", "-"], input=new, text=True)
+        print(f"Removed lines matching {name}")
+        return 0
+
+    jobs = sorted(JOBS_DIR.glob("*.md"))
+    if not jobs:
+        print(f"No job files found in {JOBS_DIR}")
+        return 0
+
+    print(f"Found {len(jobs)} job file(s) in {JOBS_DIR}")
+    print(f"Platform: {platform.system()}; using {'schtasks' if platform.system() == 'Windows' else 'crontab'}")
+    print(f"Task name prefix: {TASK_NAME_PREFIX}")
+    print()
+
+    n_ok = 0
+    n_skip = 0
+    n_fail = 0
+    for path in jobs:
+        job = parse_job_file(path)
+        if not job:
+            continue
+        name = job.get("name", "(unnamed)")
+        active = str(job.get("active", "")).lower() == "true"
+        if not active:
+            print(f"SKIP   {name} (active: false)")
+            n_skip += 1
+            continue
+        if platform.system() == "Windows":
+            ok, msg = register_windows(job, args.dry_run)
+        else:
+            ok, msg = register_unix(job, args.dry_run)
+        marker = "OK" if ok else "FAIL"
+        print(f"{marker:6s} {name}: {msg}")
+        if ok:
+            n_ok += 1
+        else:
+            n_fail += 1
+
+    print()
+    print(f"Done. registered: {n_ok}, skipped: {n_skip}, failed: {n_fail}")
+    return 0 if n_fail == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/template/support/scripts/run-daily-distill.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# Daily memory distill — invokes Claude headlessly with a prompt that reads
+# today's session log and extracts durable facts into context/MEMORY.md.
+#
+# Wired by cron/jobs/daily-memory-distill.md → schtasks/cron at 23:00 daily.
+# Logs to context/sessions/{today}.md under a "## Automated distill" heading
+# so the work is traceable.
+
+# When run from Task Scheduler / cron / launchd, PATH may not include the
+# directories where bash builtins or Claude CLI live. Set up explicitly.
+case ":$PATH:" in
+    *":/usr/bin:"*) ;;
+    *) export PATH="/usr/bin:/usr/local/bin:/opt/homebrew/bin:/c/Program Files/Git/usr/bin:$PATH" ;;
+esac
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+TODAY=$(date +%Y-%m-%d)
+SESSION_LOG="context/sessions/${TODAY}.md"
+
+if [ ! -f "$SESSION_LOG" ]; then
+    echo "[$(date -Iseconds)] daily-distill: no session log at $SESSION_LOG; nothing to distill" >&2
+    # Still refresh the timestamp so HC-3 stays green.
+    python "${REPO_ROOT}/scripts/refresh-distill-timestamp.py" || true
+    exit 0
+fi
+
+PROMPT=$(cat <<EOF
+You are running as a scheduled background task at $(date -Iseconds) for this project. No human is watching. Be concise and idempotent.
+
+GOAL: distill durable facts from today's session log into the bounded scratchpad.
+
+STEPS:
+1. Read \`${SESSION_LOG}\`. This is today's session log with deliverables, decisions, and open threads.
+2. Read \`context/MEMORY.md\` to see what's already captured (active threads, environment notes, pending decisions).
+3. Read \`context/memory/INDEX.md\` to see what's already in the granular archive.
+4. For each meaningful item in the session log:
+   - If it's transient working state (current discussion, today's iteration) → if not already in MEMORY.md "Active Threads", add a one-line bullet there.
+   - If it's a durable typed fact (user preference learned, project decision made, feedback rule, external reference) → create or update a granular file at \`context/memory/<type>_<slug>.md\` with frontmatter + Why + How to apply. Add a one-line entry to INDEX.md. Don't duplicate in MEMORY.md.
+   - If it's an environment change (new tool installed, path discovered) → MEMORY.md "Environment Notes".
+   - If it's a decision the user still needs to make → MEMORY.md "Pending Decisions".
+5. Before writing MEMORY.md, run \`wc -c context/MEMORY.md\`. If over 2500 chars, FIRST consolidate by merging similar bullets and dropping stale ones (anything older than 14 days that has no current relevance). Then add the new content.
+6. Update the \`<!-- Last distilled: YYYY-MM-DD -->\` line at the top of MEMORY.md to ${TODAY}.
+7. Append a one-line entry to \`${SESSION_LOG}\` under a new "## Automated distill" heading describing what changed.
+
+CONSTRAINTS:
+- Use the Read, Edit, and Bash tools only. Do NOT use Write to overwrite MEMORY.md — use Edit so the metadata comment is preserved.
+- Do NOT create new files outside context/memory/ or modify anything outside context/.
+- Do NOT commit, push, or run git operations.
+- If the session log has nothing distillable, still update the timestamp on MEMORY.md so HC-3 stays green, and append a "## Automated distill" note saying "nothing new to distill."
+- Keep total output under 3 paragraphs.
+EOF
+)
+
+echo "$PROMPT" | claude --print \
+    --add-dir "$REPO_ROOT" \
+    --allowed-tools "Read" "Edit" "Bash(wc *)" "Bash(date *)" \
+    --output-format text \
+    2>&1 | tee -a "${REPO_ROOT}/context/sessions/${TODAY}.distill.log"
+
+EXIT=${PIPESTATUS[0]}
+echo "[$(date -Iseconds)] daily-distill: exit=$EXIT" >&2
+exit "$EXIT"

package/template/support/scripts/run-weekly-curate.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+#
+# Weekly memory curator — invokes Claude headlessly with a prompt that
+# prunes, merges, and consolidates entries in context/MEMORY.md.
+#
+# Wired by cron/jobs/weekly-memory-curator.md → schtasks/cron at Sun 09:00.
+
+case ":$PATH:" in
+    *":/usr/bin:"*) ;;
+    *) export PATH="/usr/bin:/usr/local/bin:/opt/homebrew/bin:/c/Program Files/Git/usr/bin:$PATH" ;;
+esac
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+TODAY=$(date +%Y-%m-%d)
+SESSION_LOG="context/sessions/${TODAY}.md"
+
+PROMPT=$(cat <<EOF
+You are running as a scheduled weekly background task at $(date -Iseconds) for this project. No human is watching. Be conservative — if unsure whether something should be kept, KEEP IT.
+
+GOAL: prune, merge, and consolidate \`context/MEMORY.md\` so it stays informative and well under the 2500-char cap.
+
+STEPS:
+1. Read \`context/MEMORY.md\` end to end.
+2. Read \`context/memory/INDEX.md\` and at least the most recent 3 session logs (\`ls -t context/sessions/ | head -3\`) for context on what's currently relevant.
+3. For each entry in MEMORY.md "Active Threads":
+   - Is it still being worked on? Check session logs. If resolved → REMOVE.
+   - Are there duplicates? → MERGE into one.
+4. For each "Environment Note":
+   - Is it still accurate? Drop only if clearly stale.
+5. For each "Pending Decision":
+   - Has it been resolved (look for matching deliverables in recent session logs)? → REMOVE.
+   - Has new context arrived? → UPDATE the bullet to reflect current state.
+6. After curating, run \`wc -c context/MEMORY.md\` and report the new size.
+7. Update the \`<!-- Last health check: YYYY-MM-DD -->\` line to ${TODAY}.
+8. If today doesn't have a session log yet, create \`${SESSION_LOG}\` with a "## Session — automated curation" heading. Append a summary of what was changed (e.g., "Removed 2 resolved threads, merged 3 environment-notes duplicates, new size 1840/2500 chars.").
+
+CONSTRAINTS:
+- Use Read, Edit, and Bash(wc *), Bash(ls *), Bash(date *) only.
+- NEVER add new content during curation — this is a cleanup pass, not a writing pass. If you find something missing, NOTE it in the session log but don't add to MEMORY.md.
+- Do NOT touch granular archive files in context/memory/<type>_*.md unless they're obviously orphaned (no INDEX entry AND no references in MEMORY.md AND no recent session log mention).
+- Do NOT commit, push, or run git operations.
+- Keep total output under 5 lines: summary of changes only.
+EOF
+)
+
+echo "$PROMPT" | claude --print \
+    --add-dir "$REPO_ROOT" \
+    --allowed-tools "Read" "Edit" "Bash(wc *)" "Bash(ls *)" "Bash(date *)" \
+    --output-format text \
+    2>&1 | tee -a "${REPO_ROOT}/context/sessions/${TODAY}.curate.log"
+
+EXIT=${PIPESTATUS[0]}
+echo "[$(date -Iseconds)] weekly-curate: exit=$EXIT" >&2
+exit "$EXIT"

package/template/user/HABITS.md.template

@@ -0,0 +1,18 @@
+<!-- Cap: 1800 chars · Last distilled: {{TODAY}} · Last health check: {{TODAY}} -->
+
+# Habits (cross-project working style)
+
+## Iteration Cadence
+
+- (U-CEKUY3H4) commits incrementally as work progresses; not in one big push at the end
+  <!-- source: HABITS.md, source_line: 7, sha1: 0000000000000000000000000000000000000000, write: manual-edit, trust: medium, at: 2020-01-01T00:00:00Z -->
+
+## Destructive Operations
+
+- (U-GXB2C4JZ) always confirms before git push, git reset --hard, or other irreversible operations
+  <!-- source: HABITS.md, source_line: 12, sha1: 0000000000000000000000000000000000000000, write: manual-edit, trust: medium, at: 2020-01-01T00:00:00Z -->
+
+## Communication Style
+
+- (U-aUMQHVCV) reads the diff before the commit message; trusts code over claims
+  <!-- source: HABITS.md, source_line: 17, sha1: 0000000000000000000000000000000000000000, write: manual-edit, trust: medium, at: 2020-01-01T00:00:00Z -->

package/template/user/LESSONS.md.template

@@ -0,0 +1,18 @@
+<!-- Cap: 1800 chars · Last distilled: {{TODAY}} · Last health check: {{TODAY}} -->
+
+# Lessons (cross-project)
+
+## Tooling Lessons
+
+- (U-RDBNQSL7) fix the code, not the test
+  <!-- source: LESSONS.md, source_line: 7, sha1: 0000000000000000000000000000000000000000, write: manual-edit, trust: medium, at: 2020-01-01T00:00:00Z -->
+
+## Process Lessons
+
+- (U-APHTKHMQ) correlation is not causation; measured profiling beats educated guessing
+  <!-- source: LESSONS.md, source_line: 12, sha1: 0000000000000000000000000000000000000000, write: manual-edit, trust: medium, at: 2020-01-01T00:00:00Z -->
+
+## Anti-patterns
+
+- (U-U5RM2FXH) premature abstraction outlives the requirement that motivated it
+  <!-- source: LESSONS.md, source_line: 17, sha1: 0000000000000000000000000000000000000000, write: manual-edit, trust: medium, at: 2020-01-01T00:00:00Z -->

package/template/user/USER.md.template

@@ -0,0 +1,18 @@
+<!-- Cap: 1375 chars · Last distilled: {{TODAY}} · Last health check: {{TODAY}} -->
+
+# User Profile
+
+## About
+
+- (U-PRNQKRaC) engineer comfortable with TDD and incremental code review
+  <!-- source: USER.md, source_line: 7, sha1: 0000000000000000000000000000000000000000, write: manual-edit, trust: medium, at: 2020-01-01T00:00:00Z -->
+
+## Preferences
+
+- (U-K3Z73EAQ) prefers terse responses; no preamble before the answer
+  <!-- source: USER.md, source_line: 12, sha1: 0000000000000000000000000000000000000000, write: manual-edit, trust: medium, at: 2020-01-01T00:00:00Z -->
+
+## Working Style
+
+- (U-PUYHL2BL) one PR per parent task; squash-merge into main
+  <!-- source: USER.md, source_line: 17, sha1: 0000000000000000000000000000000000000000, write: manual-edit, trust: medium, at: 2020-01-01T00:00:00Z -->

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

@@ -0,0 +1,23 @@
+<!--
+File: ~/.claude-memory-kit/fragments/INDEX.md  (or $MEMORY_KIT_USER_DIR/fragments/INDEX.md).
+Purpose: pointer index for the user-tier granular archive.
+Format: one line per non-tombstoned fact file:
+    - ({id}) [type] [title](filename.md) — <hook>
+
+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:
+    - user_*       facts about the user
+    - feedback_*   corrections / preferences
+    - project_*    decisions with rationale (rare in user tier — most
+                   are project-specific)
+    - reference_*  pointers to external systems
+-->
+
+# User-tier granular memory — INDEX
+
+## Files
+
+<!-- Auto-generated by `cmk reindex`. No entries yet on a fresh install. -->