v3.1.0 — knowledge/ moved to project root

Breaking Change

knowledge/ wiki directory moved from .claude/memory/knowledge/ to project root knowledge/.

Why: Claude Code hardcodes .claude/** as sensitive file protection — compile.py (via claude -p) could not write wiki articles even with --permission-mode acceptEdits.

Migration from v3.0.x

mv .claude/memory/knowledge knowledge
# Copy updated scripts from kit:
# - .claude/memory/scripts/config.py
# - .claude/hooks/session-start.py
git add knowledge/ && git commit -m "feat(v3.1): move knowledge/ to project root"

Also in this release

• session-start.py shows "Recent updates: article-name (today)" for transparency
• compile.py Rule 6: preserve manually-written content (don't overwrite hand-authored articles)
• /knowledge-update slash command for manual wiki updates
• README badges: version + last commit date
• All CLAUDE.md path references updated

Full changelog: CHANGELOG.md

v3.0.1 — compile.py silent failure fix

[3.0.1] — 2026-04-09

Patch release: critical fix for compile.py silent failure mode discovered during rnd-hub live test of v3.0.0.

Fixed

• compile.py silent failure — v3.0.0 compile.py considered any claude -p exit 0 as a successful compile, updating the state hash for the daily log even when sub-Claude returned a text description instead of actually calling Write/Edit tools. Result: daily log was marked as "compiled" but zero wiki articles were created or modified, and the log was permanently skipped on subsequent runs (hash matched, so compile.py --all was the only recovery path). Detected during rnd-hub live test Test 10: compile.py reported "1/1 succeeded" but concepts/, connections/, knowledge/index.md, and knowledge/log.md were all unchanged.

  Three-layer fix:

  1. Mtime snapshot verification — compile_daily_log() now captures wiki state via snapshot_wiki_state() before running claude -p, then compares against post-run state. If zero files were created and zero files were modified, compile_daily_log() returns False, dumps sub-Claude stdout to .claude/state/compile-{daily-stem}-stdout.txt for debugging, and does NOT update the state hash — so the daily log stays in the queue for the next compile run.
  2. Strengthened prompt — build_compile_prompt() now opens with an explicit "CRITICAL — this is an automated pipeline, not a chat" preamble warning sub-Claude that the caller verifies success by checking wiki file mtimes. Rules 1-6 now explicitly say "use the Write tool to CREATE" / "use Edit to UPDATE" instead of just "CREATE" / "UPDATE". New Rule 11: "Every action MUST be a tool call (Write/Edit/Read/Glob/Grep). Text-only responses count as a compile failure." Added a "Final step" instructing sub-Claude to return a one-line summary only after all Write/Edit calls succeed.
  3. Added --permission-mode acceptEdits to the claude -p invocation in both compile.py and query.py. Cole's original SDK code uses permission_mode="acceptEdits" explicitly; this was lost during the SDK → CLI subprocess port in v2. Not always strictly required (control tests show claude -p sometimes accepts Write by default in headless mode), but it's correct by convention and defensive against default-mode drift in future Claude Code versions.

Changed

• compile.py output now includes Wiki touched: +{N} new files, {M} updated line on success, so you can see the pipeline working instead of just "Done. Output: X chars".

Why this matters

The v3.0.0 silent failure was invisible from compile.py output alone — it reported success, lint.py stayed green (because it only checks existing files, not whether compile produced output), and the state hash was updated. The only way to detect it was to manually ls knowledge/ before and after. Without the mtime snapshot guard, users would have assumed their pipeline was working while knowledge accumulated only in daily/ and never compiled.

Credit to rnd-hub's Test 10 protocol for catching this end-to-end — a straight happy-path sanity check would have passed without revealing the bug.

Notes for upgraders from v3.0.0

• If you already have daily logs that v3.0.0 marked as "compiled" but produced no wiki articles: delete their entries from .claude/state/compile-state.json → re-run compile.py. The new mtime guard will correctly fail (instead of silent-success) if sub-Claude still doesn't write, giving you an actionable debug dump at .claude/state/compile-{stem}-stdout.txt.
• No breaking changes to file formats, hook protocol, or CLI interface. Pure bug fix.

v3.0.0 — SessionStart injection + end-of-day auto-compile

[3.0.0] — 2026-04-09

Major upgrade: ports 3 zero-cost features from Cole Medin's claude-memory-compiler (the Karpathy-inspired original that Memory Kit v2 was derived from) that were lost in the v1 → v2 stdlib port. Also renames JOURNAL.md → BACKLOG.md (cleaner semantic separation with daily/), collapses knowledge/ from 6 → 3 subdirs, and promotes the CLAUDE_INVOKED_BY recursion guard from hidden quirk to documented feature.

All changes remain on Python stdlib + claude -p subscription. No new dependencies. Zero incremental API cost.

Added

• .claude/hooks/session-start.py — new Python hook replacing session-start.sh. Outputs JSON {"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "..."}} so Claude Code injects knowledge/index.md + recent daily/YYYY-MM-DD.md logs + top 3 recently-modified concepts into every session's initial context. Adapted from coleam00/claude-memory-compiler. Budget: 50K chars default (CMK_INJECT_BUDGET env var to tune).
• flush.py — maybe_trigger_compilation() — after 18:00 local time (CMK_COMPILE_AFTER_HOUR env), checks if today's daily/YYYY-MM-DD.md has changed since last compile via SHA-256 hash comparison. If yes, spawns compile.py as a detached background process. End-of-day auto-compile without cron. Logs to .claude/state/compile.log.
• .claude/commands/memory-compile.md — slash command wrapper around compile.py. Manual override alongside auto-trigger.
• .claude/commands/memory-lint.md — slash command wrapper around lint.py. Pass --fix for auto-backlinks.
• .claude/commands/memory-query.md — slash command wrapper around query.py. Natural-language queries with index-guided retrieval.
• CLAUDE.md sections:
  • SessionStart Injection — describes additionalContext pattern, budget, priority order
  • End-of-day Auto-Compile — describes 18:00 trigger, hash skip logic, /memory-compile manual override
  • CLAUDE_INVOKED_BY — recursion guard (critical) — documents the recursion path that prompted the guard (was hidden quirk in v2)

Changed

• JOURNAL.md → BACKLOG.md throughout the template. Renamed 3 example projects (example-webapp, example-saas, my-first-project). Updated all references in CLAUDE.md, README.md, .claude/hooks/periodic-save.sh, .claude/hooks/pre-compact.sh, .claude/skills/tour/SKILL.md, experiments/README.md, experiments/001-*/EXPERIMENT.md, context/next-session-prompt.md. Rationale: BACKLOG = task queue (future-forward), daily/ = chronological log (past-forward). Two distinct files with clear semantics. JOURNAL was ambiguous — it conflated both.
• .claude/memory/knowledge/ collapsed from 6 → 3 subdirectories. Kept: concepts/, connections/, meetings/. Removed: qa/ (empty in practice — compounding loop rarely fired manually), projects/ (duplicated root-level projects/X/BACKLOG.md), experiments/ (duplicated root-level experiments/NNN/EXPERIMENT.md). Updated config.py, compile.py, lint.py, query.py, knowledge/index.md, CLAUDE.md.
• lint.py checks: 7 → 6. Removed check_stale_experiments because it required knowledge/experiments/ which no longer exists. Remaining: broken links, orphan pages, orphan sources, missing backlinks, sparse articles, missing frontmatter.
• query.py: removed --file-back flag. It filed answers to knowledge/qa/ which no longer exists. Query remains read-only, index-guided. If you miss it, the answer is in git history.
• .claude/settings.json — SessionStart hook command updated from bash ".../session-start.sh" to python3 ".../session-start.py".

Removed

• .claude/hooks/session-start.sh — replaced by session-start.py.
• .claude/memory/knowledge/qa/ directory (and .gitkeep).
• .claude/memory/knowledge/projects/ directory (and .gitkeep).
• .claude/memory/knowledge/experiments/ directory (and .gitkeep).
• check_stale_experiments() function from lint.py.
• parse_frontmatter() helper from lint.py (became unused after stale_experiments removal).
• QA_DIR, EXPERIMENTS_WIKI_DIR, PROJECTS_WIKI_DIR constants from config.py.
• EXPERIMENTS_RAW_DIR constant from config.py (was only used by check_stale_experiments).

Migration notes for v2 → v3

Existing users with a v2 clone must:

1. Rename project files: find projects -name JOURNAL.md -exec sh -c 'mv "$0" "${0%JOURNAL.md}BACKLOG.md"' {} \; (or do it manually per project).
2. Update internal references in context/next-session-prompt.md, CLAUDE.md, and any custom rules that mention JOURNAL.md.
3. If you had content in knowledge/qa/, knowledge/projects/, or knowledge/experiments/: move articles to knowledge/concepts/ (they lose their subdir categorization but content is preserved). The v3 wiki has only 3 subdirs.
4. Update hook command in .claude/settings.json: change SessionStart command from bash .../session-start.sh to python3 .../session-start.py. Or re-copy settings.json from the updated template.
5. Replace session-start.sh with session-start.py from v3.
6. Pull updated flush.py to get maybe_trigger_compilation().
7. Optional but recommended: enable end-of-day auto-compile by leaving default CMK_COMPILE_AFTER_HOUR=18, or disable with a high value like 99.
8. query.py --file-back users: the flag is gone. Answers are no longer filed automatically. If you want this back, copy the pre-v3 version from git history.

Breaking changes summary:

• File rename: JOURNAL.md → BACKLOG.md
• Wiki structure: 6 → 3 subdirs
• Query flag: --file-back removed
• Hook command: bash → python3

Not breaking:

• MEMORY.md format unchanged
• next-session-prompt.md format unchanged (<!-- PROJECT:name --> tags still work)
• daily/ format unchanged
• compile.py CLI args unchanged
• All of v2's other hooks (session-end.sh, pre-compact.sh, periodic-save.sh, protect-tests.sh) unchanged

Fixed

• compile.py used to have an outdated prompt template that instructed the LLM to write to knowledge/{qa,projects,experiments}/ subdirs. Now strictly references concepts/ and connections/ (and implicitly meetings/ when applicable).
• pre-compact.sh counted project files by looking for JOURNAL.md. Now looks for BACKLOG.md.
• periodic-save.sh block message mentioned projects/*/JOURNAL.md. Now says projects/*/BACKLOG.md.

v2.0.1 — Post-launch polish

Post-launch polish release. Fixes issues found after v2.0.0 shipped, adds brand asset, corrects terminology leftovers.

Fixed

• README Mermaid diagram truncation — Long node labels in the architecture diagram were truncated on GitHub's rendered view. Fixed by wrapping labels with <br/> in quoted syntax. Verified via Chrome browser automation on live GitHub render. (#4a37c00)
• /tour skill obsolete content — The tour still referenced v1 architecture (3 hooks, topics/ layer). Now reflects v2: 5 hooks, knowledge/ wiki layer, new Step 5 for Memory Kit v2 Scripts. (#6da1f19)
• Terminology leftovers: topics/ → knowledge/ — Systematic audit caught 4 lingering v1 references in MEMORY.md template and CLAUDE.md. All migrated to knowledge/concepts/ naming. (#ab1b0b5)
• Missing CONTRIBUTING.md — README linked to CONTRIBUTING.md that didn't exist (broken link). Created minimal guide with PR rules and ground rules (zero dependencies, pure Markdown, Obsidian optional). (#ab1b0b5)

Added

• GitHub Social Preview banner — `.github/assets/og-banner.png` (1280×640). Dark editorial design with isometric 5-layer glass stack (BRAIN/MEMORY/RULES/JOURNAL/CONTEXT). Generated via Gemini Nano Banana Pro. Upload via repo Settings → Social preview. (#29afd04, #b9cd78e)
• Hero banner in README — Banner now renders as the first element of README via pure Markdown. Stays compliant with H3 Hybrid structure (no HTML wrappers in top zone). (#de0990b)

Upgrading from v2.0.0

No breaking changes. Pure additive + fixes.

If you already cloned v2.0.0:
```bash
git pull origin main
```

• The `/tour` skill will show the updated v2 walkthrough automatically on next invocation
• The Mermaid diagram fix only affects rendered view; no behavior change
• No migration steps needed

Full changelog

See CHANGELOG.md for complete details.

Full diff: v2.0.0...v2.0.1

v2.0.0 — Memory Kit v2: Pipeline, Knowledge Wiki, Self-Selling README

Major upgrade from v1. Full memory pipeline + structural refactor + marketing-ready README.

Highlights

New pipeline (Python stdlib only, zero pip install):

• compile.py — daily logs → knowledge wiki articles (incremental via SHA-256)
• lint.py — 7 structural health checks + --fix auto-repair
• query.py — index-guided retrieval with optional --file-back compounding loop
• flush.py — session-end background transcript extractor (Opus, 100 turns / 50KB)
• config.py — path constants

New hooks:

• session-end.sh — auto-captures conversation transcripts to daily/YYYY-MM-DD.md
• protect-tests.sh — blocks edits to existing test files (creates allowed)

Structural:

• .claude/memory/knowledge/ — 6-subdir wiki (concepts/connections/meetings/qa/projects/experiments) with index.md + log.md
• daily/ — auto-captured session logs (gitignored content)
• .claude/state/ — project-local runtime state (replaces legacy ~/.claude-starter-kit/hook_state/)

README refactor (H3 Hybrid):

• 237 → 169 lines (tighter, less filler)
• Pain-first hero + 5-layer component table
• Install CTA moved from line 77 → line 18
• GitHub admonitions, Mermaid architecture diagram, FAQ collapsibles
• New positioning: "The OS layer for Claude Code. Not just memory — the entire context management lifecycle."

CLAUDE.md fixes:

• Added @README.md import so README loads automatically at session start (Claude Code does NOT auto-load README otherwise)
• topics/ terminology replaced with knowledge/ throughout
• Periodic save default: 15 → 50 exchanges

Migration notes (v1 → v2)

• Existing users: the session counter at ~/.claude-starter-kit/hook_state/session_count is no longer read. Counter resets to 1. Non-critical (cosmetic).
• MEMORY.md, JOURNAL.md, and next-session-prompt.md formats are unchanged — your existing content continues to work.
• After pulling v2: run chmod +x .claude/hooks/session-end.sh .claude/hooks/protect-tests.sh if the executable bit didn't survive.

Dependencies

• Python 3.9+ (stdlib only — no pip install)
• Claude Code CLI (existing)
• Claude Pro/Max subscription or API credits (existing)
• Obsidian is NOT required — the wiki works in any Markdown editor. Obsidian is only for the optional visual graph view.

See CHANGELOG.md for the full changelog.