release: v0.9.0 — auto-harvested memories

[RodCor]

Summary

v0.9.0 — the Kimetsu hooks now drive memory generation, not just retrieval ("the other way" the brain was missing), plus a credentialed end-of-session distiller, Codex parity, and a round of non-destructive install hardening.

This branch is stacked on the v0.8.4 work (#14) and folds in the global distiller / OpenAI provider (#16), so this PR is the full v0.8.4 + v0.9.0 delta against main.

What's in this branch

🧠 Auto-harvested memories (in-agent, no credentials)

The hooks now generate memories. When a command that failed earlier in the session later succeeds (PostToolUse), or a non-trivial session ends having recorded nothing (Stop), Kimetsu emits a throttled [kimetsu-harvest] cue telling the agent to dispatch a new background kimetsu-memory-harvester subagent (installed at .claude/agents/ for Claude Code and .codex/agents/ for Codex, pinned to a cheap model). The subagent distills 0–3 generalizable lessons and records them through the confidence-gated kimetsu_brain_record path — no separate API key, billed in-agent at the cheap model's rate, non-blocking. Disable with [learning] auto_harvest = false.

🔑 Credentialed SessionEnd distiller (opt-in)

A second, deterministic harvest path alongside the in-agent harvester. kimetsu plugin install claude-code / ... codex now runs an interactive wizard (on a TTY; skip with --no-setup, force with --setup-harvest) configuring a cheap distiller model — Anthropic (claude-haiku-4-5), OpenAI (gpt-5.4-mini), or a compatible endpoint via ANTHROPIC_BASE_URL / OPENAI_BASE_URL. The key + base URL go to a gitignored .env; the selection lands in [learning.distiller] in project.toml. A SessionEnd hook (Claude Code) runs kimetsu brain session-end-hook; when credentialed it reads the transcript with that model and records via propose_or_merge_memory. When the distiller is enabled it owns end-of-session — the Stop harvest cue is suppressed, while the mid-session PostToolUse resolved-failure cue stays. AnthropicProvider gained an optional base URL (LiteLLM); a new OpenAI Responses-API provider was added.

🤖 Codex parity

• kimetsu plugin install codex writes .codex/config.toml, .codex/hooks.json, the kimetsu-bridge skill, and a .codex/agents/kimetsu-memory-harvester.toml custom agent — the Codex equivalent of the Claude harvester subagent (Codex's standalone TOML agent format). So the in-agent auto-harvest flow works on Codex too.
• Codex hooks are merged, not replaced. UserPromptSubmit → kimetsu brain context-hook, Stop → kimetsu brain stop-hook --distill-on-stop, plus proactive Bash-wrapping PreToolUse/PostToolUse hooks. Existing user hooks on the same events are preserved alongside Kimetsu's; re-install is idempotent.
• Distiller via the Stop hook. Current Codex releases expose Stop but not SessionEnd, so the credentialed distiller runs from Codex's Stop hook via --distill-on-stop (Claude Code uses the dedicated SessionEnd event).
• Wizard supports Codex. Selecting the codex harness configures the OpenAI provider (default gpt-5.4-mini) or a compatible endpoint via OPENAI_BASE_URL; the key lands in the gitignored .env and the selection in [learning.distiller].
• New OpenAI Responses-API provider (OpenAiProvider, crates/kimetsu-agent/src/openai.rs) powers the OpenAI/Codex distiller path.

🌍 Global distiller in ~/.kimetsu/

With --scope global the wizard configures the distiller once in ~/.kimetsu/ (config + .env). That global distiller then runs in every project and records into the user brain (~/.kimetsu/brain.db, available everywhere), with a per-project distiller taking precedence when one is configured.

📄 CLAUDE.md merge (append, never replace)

kimetsu plugin install now merges its guidance into an existing CLAUDE.md — workspace .claude/CLAUDE.md or global ~/.claude/CLAUDE.md — inside <!-- kimetsu:begin -->/<!-- kimetsu:end --> markers: write-if-missing / append-if-absent / replace-the-marked-region-in-place / repair-a-corrupt-half-block / BOM-tolerant. The user's content is never overwritten. --force no longer overwrites CLAUDE.md (the whole install is idempotent and non-destructive; the flag is retained only for compatibility).

🔧 Non-destructive install hardening (v0.8.4, bundled)

• Hook merge. plugin install merges its hooks into existing Claude settings.json / Codex hooks.json instead of replacing them — hooks you already have, even on the same events (UserPromptSubmit, PreToolUse, …), are preserved with Kimetsu's group added alongside. Idempotent (no duplicate groups).
• --scope workspace|global. Install the Kimetsu surface into the workspace (default) or the user's home (~/.claude/ + ~/.claude.json, ~/.codex/) for every session. Also exposed as the scope arg on the kimetsu_plugin_install MCP tool.
• BOM-tolerant reads. Strips a leading UTF-8 BOM before parsing an existing settings.json / hooks.json / config.toml / .mcp.json (older Windows editors no longer break the install).
• Polish. --scope global on the workspace-only kimetsu target warns instead of silently no-op'ing; --workspace is canonicalized leniently so a global install doesn't fail on a missing path.

🐛 Stop hook fix

The Stop hook counted kimetsu_brain_record calls from a non-existent inline transcript array; Claude Code actually passes a transcript_path to a JSONL file. It now streams the JSONL line-by-line (multi-MB transcripts never load fully into memory), keeps the inline array as a fallback, and counts both the bare and MCP-namespaced (mcp__kimetsu__kimetsu_brain_record) tool names — so the "lessons recorded" banner and the end-of-session cue actually fire.

🧹 Cleaner help & tool menus

Stripped internal version-history prefixes (v0.x:, MP-…:) from --help text and the MCP tool/argument descriptions so menus read as plain present-tense descriptions (code comments unchanged).

Test Plan

• cargo test --workspace — all green (333 tests). New coverage includes:
  • failure→resolution + harvest-throttle proactive state; count_brain_record_calls bare + namespaced shapes; [learning] / [learning.distiller] config back-compat; harvester subagent install.
  • Codex: write_codex_hooks idempotent merge + Stop --distill-on-stop + proactive PostToolUse; .codex/agents/kimetsu-memory-harvester.toml install; wizard accepts the codex harness → OpenAI (wizard_accepts_codex_harness, wizard_accepts_openai_custom_model); OpenAiProvider Responses-URL / base-URL resolution.
  • resolve_distiller precedence (workspace > global) under an env-locked temp user brain; distill_and_record GlobalUser routing; string-aware lesson extraction.
  • the full merge_claude_md matrix (fresh / preserve / idempotent / in-place upgrade / begin-without-end repair / BOM) + install_preserves_existing_user_claude_md.
• cargo fmt --all --check clean; cargo build --workspace warning-clean after the 0.9.0 bump.
• Real-binary smoke (Windows): PostToolUse failure→success emits the [kimetsu-harvest] cue; Stop reads a JSONL transcript and reports recorded lessons (verified with the namespaced tool name) vs cues a harvest when none; plugin install into a workspace with a pre-existing CLAUDE.md preserves the user content and is idempotent (exactly one marker block after a re-install).

Merge notes

Bundles #14 (v0.8.4) and #16 (global distiller / OpenAI provider). Merge this and close #14, or merge #14 first — the overlap reconciles automatically.