v2.0.0 — Never explore twice#29
Merged
Merged
Conversation
Stamp the version at the START of the release branch (lesson from v1.5.0: artifacts must never self-report a stale version). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ctions + bump helper Prevents a repeat of the v1.5.0 botch: - new version-guard job fails in seconds if the tag != [workspace.package] version; build/release/publish all need it (no more 13-min build + partial publish before the mismatch surfaces) - smoke-test now asserts the built binary self-reports the tag version - bump actions/checkout, upload-artifact, download-artifact, setup-node -> v5 (Node-24 ready; forced June 16 2026) - scripts/bump-version.sh codifies the one-step workspace bump so the stamp can't be forgotten Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…s, drop caveat Re-checked both hosts' current official MCP docs (June 2026): Cursor needs mcpServers + type:"stdio" + command + args; Gemini CLI needs mcpServers + command + args (transport inferred, no type). bridge.rs already writes exactly these shapes — the v1.5 'inferred / not verified' caveat in INSTALL.md + CHANGELOG was overly cautious and contradicted the code comments. Caveat removed. (A full live-install MCP handshake still wasn't run here — no Cursor/ Gemini installed in this env — but the config format is now doc-confirmed.) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…, toml_edit config writes S4.1 — analytics/doctor active counts exclude superseded rows - analytics.rs CorpusHealth.active/by_scope/by_kind: add superseded_by IS NULL - analytics.rs UsefulnessTrend sum_usefulness/avg_ratio: add superseded_by IS NULL - doctor.rs check_user_brain_opens active count: add superseded_by IS NULL - Test: superseded_memory_excluded_from_active_count asserts active=1 after marking m2 S4.2 — toml_edit comment-preservation on config writes - Workspace: add toml_edit = "0.22" dependency - main.rs: add set_toml_edit_path() surgical writer (preserves comments + unknown keys) - config set, tune --apply, brain_tune_revert: switch to set_toml_edit_path - set_toml_path moved to #[cfg(test)] (still used by existing pure unit tests) - Test: set_toml_edit_path_preserves_comments_and_unknown_keys S4.3 — sidecar atomic writes (temp + rename) - dropped_capsule.rs save(): atomic_write_json() helper (tmp+rename) - proactive_state.rs save(): inline tmp+rename pattern - Tests: save_is_atomic_no_tmp_leftover in both files S4.4 — superseded filters in reindex / peek-undo / list asymmetry - reindex.rs: total count and candidate queries add superseded_by IS NULL - project.rs peek_last_memory / undo_last_memory: add superseded_by IS NULL - project.rs list_memories_from_conn: add invalidated_at IS NULL AND superseded_by IS NULL (symmetric with list_user_memories — decision documented in code comment) - Updated test invalidated_memory_is_excluded_from_broker_retrieval to check DB directly for persistence instead of via list_memories (now active-only) - Test: reindex_one_conn_skips_superseded_rows All gates pass: cargo fmt, clippy lean, clippy --features embeddings, cargo test (0 failures) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ection, doctor probe S1.1 — Ollama first-class provider: - Add `provider = "ollama"` to normalize_distiller_provider(); ollama reuses the OpenAI-compatible request path with default base URL http://localhost:11434/v1 (override via OLLAMA_BASE_URL env var). - API key optional for ollama; an empty key is valid. - make_provider_for_resolved() and run_distiller_for_transcript() now handle the "ollama" arm via the same OpenAiProvider path. - harvest_setup wizard gains `ollama` as a provider option (no key required, informational skip message). S1.2 — One [cheap_model] config section: - Add CheapModelSection to kimetsu-core config.rs: same shape as DistillerSection, provider set extended with "ollama". - Add optional `cheap_model: Option<CheapModelSection>` to ProjectConfig; `#[serde(default)]` keeps all existing project.toml files loading cleanly. - Add ProjectConfig::cheap_model() resolver: [cheap_model] wins if present and enabled, else falls back to [learning.distiller] (back-compat alias). - Route resolve_distiller_with() through the new resolver via a shared resolve_from_cheap_model() helper; distiller back-compat maintained. - CheapModelSection::OLLAMA_DEFAULT_BASE_URL constant for the default endpoint. - Tests: (a) [learning.distiller] back-compat, (b) [cheap_model] precedence, (c) ollama default base URL and round-trip, (d) absent/disabled → None. S1.3 — Doctor check + LOCAL-MODELS.md: - Add check_cheap_model() to kimetsu doctor: Skip when unconfigured (not a failure), Pass for cloud providers, and for ollama probe the endpoint via TCP connect (2s timeout) — Warn if unreachable, never Fail (informational). - Add docs/LOCAL-MODELS.md: fully-local config guide (local embedder + local reranker + ollama cheap model = zero external calls), recommended models (qwen2.5:3b, llama3.2:3b), both wizard and manual toml setup paths, back-compat note, TODO for ask-latency benchmark (Flagship 3). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…onfig + doctor/docs) into release/v2.0.0
…eSection config seam
Introduces the RetrievalBackend abstraction as a minimal, zero-behavior-change
seam between candidate generation and the broker. The broker (scoring, floors,
rerank, compression) is entirely backend-agnostic; only the memory candidate
step is delegated to the backend.
- `crates/kimetsu-brain/src/backend.rs` (new): `pub(crate) trait RetrievalBackend`
with a single method `memory_candidates(conn, query, query_embedding,
half_life_days) -> KimetsuResult<Vec<Candidate>>`; `FlatBackend` impl
delegates to the existing `context::memory_candidates_flat` (identical SQL
+ ANN calls); `backend_for(str)` selection point with TODO seams for
"graph-lite" and "graph" (both resolve to FlatBackend for S5.1).
- `context.rs`: `Candidate` and `QueryEmbedding` made `pub(crate)`;
`memory_candidates_flat` added as a `pub(crate)` shim;
`retrieve_context_with_embedder_and_backend` added (broker body extracted
from `retrieve_context_with_embedder`, which now delegates with FlatBackend);
all existing call sites unchanged — zero behavior difference.
- `project.rs`: all four BrainSession retrieval methods (`retrieve_context_with_request`,
`retrieve_proactive`, `retrieve_context_lexical`, `retrieve_context_with_injected_embedder`)
call `retrieve_context_with_embedder_and_backend` with `backend_for(config.storage.backend)`.
- `config.rs` (kimetsu-core): `StorageSection { backend: String }` added with
`#[serde(default)]`; default `"flat"`; `ProjectConfig::default_for_project`
and backward-compat tests updated; new round-trip tests for S5.1.
Gate results: fmt clean, clippy -D warnings clean (both with and without
--features embeddings), cargo test --workspace: 0 failures across all suites.
Benchmark: the kbench retrieval-quality bench requires Harbor/Docker and cannot
run in this environment. The full test suite (retrieval tests, context tests,
ANN recall guards) is the regression gate per spec and stays green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ojection (schema v4)
- Add `memory_edges` table via schema v4 migration (src_id, dst_id, edge_type, created_at;
PK on the triple; indexes on both src and dst for BFS traversal).
- Bump KIMETSU_SCHEMA_VERSION 3→4 in kimetsu-core; add migrate_v3_to_v4 to schema.rs and
the migration runner in migrate.rs.
- `reset_projection` now DELETEs from memory_edges so rebuild_in_place repopulates it
from the event log (rebuild-safe).
- `apply_memory_superseded` inserts a `supersedes` edge (survivor→member) after stamping
superseded_by; `insert_memory_edge` is the canonical public(crate) write path for all
future edge types (refines/dead_end_of/decision_touches/lesson_from reserved for F1).
- Implement `GraphLiteBackend`: flat candidate set ∪ 1–2-hop iterative BFS over
memory_edges in both directions; bounded by MAX_HOPS=2 and MAX_FAN_OUT=20.
Graph-reached candidates have raw_relevance=0.0 and ProvenanceRef.source="graph"
so the broker scores/floors them normally — no blindly-injected capsules.
- Wire backend_for("graph-lite") to GraphLiteBackend; "graph" remains FlatBackend stub.
- Expose freshness_pub/scope_weight_pub/excerpt_pub from context.rs for backend use.
- Four S5.2 correctness-bar tests in backend::tests: no-edges→flat-parity,
supersedes-edge survives rebuild, 1-hop surfaces graph-only memory, graph-lite resolves.
- Update schema tests (v3→v4 now the fresh-init target), two migration-version tests in
consolidate.rs and user_brain.rs updated from hardcoded 3 to KIMETSU_SCHEMA_VERSION.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…schema v4) into release/v2.0.0
Story 1.3: work.episode event + work_episodes projection table (v4→v5 migration); auto-capture at SessionEnd with cheap-model distillation and rule-based fallback when no model is configured; rebuild-safe via reset_projection + rebuild_in_place. Story 1.4: render_resume_context() for Pass B SessionStart injection; kimetsu resume CLI command prints the live episode; friendly empty state. Checkpoint: kimetsu checkpoint [note] for manual mid-session saves. Story 1.7 (light): lesson_from edges inserted via insert_memory_edge for any memory_ids in the episode payload; left minimal, rest deferred. Gates: cargo fmt --all clean; clippy -D warnings (lean + embeddings); cargo test --workspace 382 passed, 0 failed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…bution
Story 1.1: digest builder (`kimetsu-brain/src/digest.rs`)
- Assemble inputs: top-usefulness memories (use_count >= 0, ordered by
usefulness ratio then recency), repo_manifests summary, recent
work_episodes task titles ("current focus").
- Rule-based assembler with ~1 600-char (≈400-token) budget cap.
- Cache at `.kimetsu/digest.md` keyed by a DefaultHasher content hash of
the inputs; atomic temp+rename write. `--refresh` flag forces rebuild.
- `cheap_model()` hook point present in config (degrades gracefully — the
rule-based path runs when no cheap model is configured).
Story 1.2: staleness detection (`is_stale`) — cheap hash comparison,
no model call; detached rebuild path left for the caller.
Story 1.5: new `kimetsu brain session-start-hook` CLI subcommand
- Combines digest (1.1) + `episode::render_resume_context` (Pass A 1.4).
- Gated by `[broker] warm_start = true` (new field, default on).
- Emits Claude Code `additionalContext` JSON (`hookEventName: "SessionStart"`).
- Silent when both halves are empty (no content, no live episode).
- Wired into `bridge.rs` for Claude Code (confirmed to support SessionStart
additionalContext injection). Codex, Cursor, GeminiCli, Pi, OpenClaw:
NOT wired — left with a comment pending live verification of their
SessionStart additionalContext schema support.
- Claude Code SessionStart group now has TWO hooks: `warm` + `session-start-hook`.
Story 1.6: ROI attribution (`record_warmstart_served`) — `digest_served` /
`resume_served` events written to the brain's event log with `approx_tokens`
field. Best-effort (errors ignored, never blocks startup). Size gate:
D7 test asserts assembled digest ≤ 1 603 chars (≈400 tokens).
Config: `[broker] warm_start` toggle added to `BrokerSection` (default true,
`#[serde(default = "default_true")]` keeps all existing project.toml files
loading cleanly).
New CLI:
`kimetsu brain session-start-hook [--workspace <path>]`
`kimetsu brain digest [--refresh] [--workspace <path>]`
Tests: 8 new digest tests (D1–D8), 1 updated bridge test
(claude_hooks_include_sessionstart_warm now also asserts session-start-hook
wiring), 1 updated config test (warm_start defaults to true).
Gate results: cargo fmt, clippy (lean + embeddings), 964 tests / 0 failures.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… SessionStart hook, schema v5) into release/v2.0.0
…+ command fast-path
3.1 — `kimetsu brain ask "<question>"`:
- New BrainCommand::Ask subcommand with --json and --helpful flags
- Grounded-only: returns "Nothing in project memory answers that." when
retrieval is empty/floored — never hallucinates
- DP-B: resolve_ask_provider prefers local/ollama (zero frontier tokens,
offline); falls back to distiller credentials when no local model
- DP-C: verbatim top-capsule dump when no model configured — never fails
- --helpful <handles>: records memory.cited events for each memory handle,
wiring the helpful-mark into the self-tuning ROI loop
3.2 — `kimetsu_brain_answer` MCP tool (mcp_server.rs):
- New MCP tool: grounded brief synthesis for mid-task host-agent queries
- Reuses the shared composer from kimetsu-chat::ask exactly
- mark_helpful:true records citations for all returned memories
- Stable JSON schema: answer, citations[], grounded, model_used, verbatim
- Read-only: never in is_privileged_write_tool list
3.4 — Command fast-path:
- is_command_query() detects "how do I …" / "how to …" / "what command …"
- reorder_for_command_fastpath() surfaces command-kind capsules first in
both the context block and the verbatim output
- Unit-tested for detection and reordering
Shared composer in kimetsu-chat/src/ask.rs:
- compose_answer(workspace, question) → AskAnswer (shared by 3.1 + 3.2)
- record_helpful_mark() wires helpful answers to record_mcp_citation
- kimetsu-cli/src/ask.rs is a thin re-export facade
Gates passed:
- cargo fmt --all
- cargo clippy --workspace --all-targets -- -D warnings
- cargo clippy --workspace --all-targets --features embeddings -- -D warnings
- cargo test --workspace: 975 passed, 0 failed
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…tive pre-fetch toggle (3.5) Answer-grade injection (3.3): - New `[broker] answer_grade_min_score` knob (default 0.92, rare threshold). - When the top capsule's broker score clears the threshold, the render path prefixes it with "Verified answer from project memory:" so the model can act in one turn without re-verifying. - STRICTLY ADDITIVE: only changes the rendered prefix of an already-top capsule; ranking, floors, and selection are never touched. - Regret guard: if the same memory_id appears in the recent dropped-capsule sidecar (floors rejected it in a prior retrieval within the 2h window), the prefix is suppressed — prevents overconfident labelling of capsules with inconsistent floor scores. Proactive pre-fetch (3.5): - New `[broker] proactive_prefetch` toggle (default `false`, OPT-IN). - When ON: the PreToolUse hook augments the retrieval query with `tool_input.file_path` (if present) so file-relevant memories surface before the agent reads or edits a file, not only after failures. - When OFF (default): PreToolUse behaviour is identical to before — zero behaviour change for all existing users. Default-on graduation waits for regret data (Epic S2). - Gate relaxed for non-Bash PreToolUse tools when pre-fetch is ON; PostTool remains Bash-only (file tools produce no failure output). Config: both fields use `#[serde(default)]` so all pre-F3 project.toml files load unchanged. New tests: round-trip, conservative-default, and missing-field assertions added to `kimetsu-core::config`. Gates: cargo fmt --all ✓, clippy -D warnings (lean + embeddings) ✓, cargo test --workspace: 978 passed, 0 failed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…mand fast-path + answer-grade injection + opt-in pre-fetch) into release/v2.0.0
- **2.1 Trigger**: `find_synthesis_candidates` detects memories cited ≥ 3× across distinct runs (CITATION_THRESHOLD) or members of a tight semantic cluster (≥ 3, cosine 0.75–0.92 band). Pure SQL / counter — zero model cost. - **2.2 Drafting**: `run_skill_synthesis` in `skill_synth.rs` calls `config.cheap_model()` for a grounded SKILL.md draft per candidate. When no model is configured, degrades gracefully to a report listing candidates without drafting — no hard-fail. - **2.3 Review + install**: `kimetsu brain skills [--review]` lists proposals; `--accept <id>` installs via `SkillRegistry::install_as_kimetsu` and writes `.kimetsu-skill-provenance.json` with source memory ids. `--reject <id>` marks rejected. NEVER auto-installs. - **2.4 Staleness**: `kimetsu brain skills --status` reports STALE when any source memory in an accepted proposal's provenance is superseded or invalidated. - **2.5 Tests**: 8 unit tests + 1 integration round-trip test (cited ≥ 3 → candidate → insert proposal → install → provenance JSON verified → accepted status confirmed → staleness check runs clean). Schema bumped v5 → v6: adds `skill_proposals` table + index. All gates pass: fmt, clippy (plain + --features embeddings), tests (530+ passed, 0 failed). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…/install + staleness, schema v6) into release/v2.0.0
S2.1 Re-tune triggers (tune.rs + CLI): - Corpus milestone (≥50 memories added since last tune) and drift signal (regret rate ≥10% over 24 h) computed cheaply without running a sweep. - `TuneHistoryEntry.memory_count_at_tune` records corpus size per tune. - `compute_retune_trigger()` pure function; exposed via `--status`/`--triggers`. - Stop hook emits a one-liner proposal when either trigger is active. - PROPOSE ONLY — no auto-apply. S2.2 Model re-selection advisor (tune.rs + CLI --models): - `compute_model_advisor()` reports current embedder, reindex cost in tokens, candidate models with download sizes (MiB). - `kimetsu brain tune --models` prints advisor; `--status --models` combines. - Full grid run reuses existing sweep machinery; advisor itself needs no models. - RECOMMEND ONLY — never auto-switches; download+reindex cost stated explicitly. S2.3 Regret-driven floor penalty (tune.rs): - `compute_objective_with_regret(mean_mrr, mean_tokens, cost_weight, regret_rate)` adds `− REGRET_PENALTY_WEIGHT * regret_rate` term (weight = 0.5). - Calibration: 100% regret rate shifts objective by −0.5 (≈ 0.5-rank MRR drop); realistic < 10% rates contribute < 0.05 — signal without overwhelming MRR. - `count_regret_events()` helper queries `retrieval.regret` events in a window. - Sweep uses regret-penalised objective; history entry records memory count. S2.4 ROI v2 (roi.rs + CLI): - (a) Per-memory ROI: `per_memory_roi()` + `kimetsu brain roi --top N` lists memories ranked by citation-weighted estimated token savings. - (b) Output-token accounting: `estimate_output_tokens()` at ratio 0.25 of input tokens (audited limitation: ratio-based, no per-session output data). `RoiReport.estimated_output_tokens` field added. - (c) New event attribution: `digest_served` and `resume_served` events now contribute to the ROI ledger (800 and 500 tokens saved per event respectively, conservative lower-bounds). `RoiReport` gains `digest_served_events`, `resume_served_events`, `warmstart_saved_tokens` fields. Warm-start savings are included in `estimated_saved_tokens`. What was EXTENDED (not rebuilt): - tune.rs: extended TuneHistoryEntry, added new pub functions alongside existing. - roi.rs: extended RoiReport struct, roi_report() now fills new fields; existing per-kind savings table and estimate_savings() untouched. - main.rs: extended brain_tune()/brain_roi()/brain_stop_hook(); sweep reuses all existing evaluate_cases() closure, select_winner(), train_holdout_split(). Gates: cargo fmt --all ✓ · clippy -D warnings ✓ · clippy --features embeddings ✓ Tests: 1011 passed, 0 failed (full workspace). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…regret-penalty objective + ROI v2) into release/v2.0.0
Implements S3.1 (export/import), S3.2 (directory protocol), and S3.3
(doctor/dry-run). Sync = EVENT-LOG REPLICATION, not SQLite file copying.
Only durable memory-lifecycle kinds are replicated; telemetry and
work.episode are excluded at the export allowlist level.
Key decisions:
- Allowlist: memory.{accepted,proposed,rejected,invalidated,cited,superseded}
- Cursor: SQLite rowid (monotonic, per-table); stored in sync-cursors.json
- Idempotency: event_id (ULID) presence check before apply; INSERT OR IGNORE
- Directory layout: <dir>/<machine_id>/<cursor>.jsonl; atomic temp+rename
- Redaction: same payload redaction as the projector at export time
- Config: [sync] dir + machine_id in project.toml, #[serde(default)]
- 7 new sync tests; 0 failures across 1021 workspace tests
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…directory protocol) into release/v2.0.0
….4 cross-backend benchmark
S5.3 — PetgraphBackend (Tier-2, remote-only):
- Add `graph = ["dep:petgraph"]` feature to kimetsu-brain. Default stays empty;
petgraph is an optional dep that NEVER compiles in lean/CLI builds.
- kimetsu-remote/Cargo.toml: depend on kimetsu-brain with `features = ["graph"]`
so the workspace feature-unification compiles the petgraph code when remote is
included — without changing any crate's `default = []`.
- PetgraphBackend (cfg(feature = "graph")): loads all memory_edges into an
in-memory petgraph::Graph at construction; BFS expansion (petgraph_expand)
replaces graph-lite's per-hop SQLite queries with pure in-memory traversal.
Candidate set is a strict superset of flat (no recall loss).
- Graph algorithm helpers exposed for future remote endpoints:
* node_centrality: in/out degree per memory (importance ranking hints)
* shortest_path: BFS A* between two memory ids (explainability)
* community_hints: Kosaraju SCCs as community proxy (consolidation hints)
- DeferredPetgraphBackend: lazy wrapper that constructs the graph on first
memory_candidates call, safe behind Mutex<Option<…>>.
- backend_for("graph"): returns DeferredPetgraphBackend when graph feature is
on; falls back to GraphLiteBackend (not flat) on lean builds — so config
files with backend="graph" still get graph expansion on lean builds.
S5.4 — Cross-backend benchmark harness (backend_bench.rs):
- run_cross_backend_bench: seeds a synthetic FTS corpus, runs 10 query cases
across flat / graph-lite / petgraph (when feature on), returns BackendBenchResult
per backend with recall@5, recall@10, mean_candidates, latency µs.
- format_results_markdown: renders results as a markdown table for reporting.
- V25_DECISION_CRITERION: documented spike result + criterion for whether
Kùzu/Cozo is justified at v2.5. VERDICT: NOT justified — petgraph-in-remote
is sufficient at 100k-memory scale. Revisit at v3.0 if corpus > 500k memories
or embedding eval shows > 5 pp recall lift from petgraph-specific algorithms.
- Full numbers (embedding + ANN path) require --features embeddings + real
brain.db + EvalFixture; harness is structured to accept them without API changes.
Gates passed (Windows/PowerShell):
- cargo clippy --workspace --all-targets -- -D warnings: CLEAN
- cargo clippy --workspace --all-targets --features embeddings -- -D warnings: CLEAN
- cargo test --workspace: 1022 passed, 0 failed
- cargo test -p kimetsu-brain (lean, no graph): 432 passed, 0 failed
- cargo build -p kimetsu-cli --no-default-features: petgraph ABSENT from tree
(lean-build-purity proof: `cargo tree` returns nothing for petgraph)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ackend benchmark harness) into release/v2.0.0
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…onfiguration README: - New 'At a glance' block opening with a measured-metrics table (cost/win, retrieval quality, scale, footprint) + a configurable-surface table - 'Why Kimetsu' reframed for the v2.0 flagships (warm-start/resume, ask, skill synthesis, self-tuning, per-memory ROI) - Quickstart + 'What's in the box' gain the v2.0 commands/surfaces - Retrieval metric corrected to the canonical 100-memory/210-case dataset: default recall@4 0.949 / MRR 0.914 @ ~138ms, best 0.975 / 0.933 (re-measured on v2.0 with kimetsu brain bench --dataset bench/dataset-100.json) HOW-KIMETSU-WORKS: - Config reference (#10) documents v2.0 keys: [cheap_model], [storage] backend, [broker] warm_start/answer_grade_min_score/proactive_prefetch, [sync] - Off-switch note covers the new toggles + the honest rule-based-digest caveat - Retrieval grid (#7b) re-confirmed on v2.0; bge-small/off row refreshed Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
v2.0.0 — Never explore twice
The biggest token sink for a coding agent is re-exploration — re-deriving what the brain (or the repo) already knows. v2.0 attacks it from three flagship directions and adds a pluggable storage tier, an optional local-model layer, continuous self-tuning, and server-less sync.
Backward-compatible: existing
project.tomlandbrain.dbfiles upgrade in place (schema v3 → v6, automatic on open). Default retrieval behavior is unchanged ([storage] backend = flat).Flagships
work_episode(schema v5) captures your working state at SessionEnd — task, dead-ends, open threads, hypothesis — scoped per-repo.kimetsu resume/kimetsu checkpoint. Plus a project digest, injected together via a newsession-start-hook([broker] warm_start, wired for Claude Code).kimetsu brain ask "…"composes a grounded, cited answer from memory via a local model — zero frontier tokens, works offline, refuses rather than hallucinating. Newkimetsu_brain_answerMCP tool for mid-task synthesis; command fast-path; answer-grade injection ([broker] answer_grade_min_score, render-time only, regret-guarded); opt-in pre-fetch.Supporting cast
[cheap_model]config resolved by digest / resume / skill-draft /ask/ distiller / consolidation. Back-compatible with[learning.distiller]; degrades gracefully when absent.docs/LOCAL-MODELS.md.RetrievalBackendtrait with[storage] backend = flat | graph-lite | graph; the broker stays backend-agnostic. Graph-lite adds typed-edge 1–2 hop expansion (memory_edges, schema v4) as a strict superset of flat. Petgraph Tier-2 is remote-only and feature-gated (never compiled in local lean/embeddings builds).roi --top, output-token accounting, warm-start savings attribution.sync export/import+ a server-less[sync] dirdirectory protocol. Telemetry, raw queries, and local-only episodes are excluded by allowlist; redaction respected.version-guard(fails in seconds on a tag/version mismatch + asserts the binary self-reports the tag) that closes the gap behind the v1.5.0 botch, plusscripts/bump-version.sh.Metrics (re-measured on v2.0)
kimetsu brain bench --dataset bench/dataset-100.json(100 memories / 210 cases), jina-v2-base-code:Cost: $0.19/win vs $2.47/win (~13×) on the recorded 16-task Terminal-Bench slice. Retrieval quality is deterministic and unchanged from v1.5 — the default combo matches the published figure exactly.
How it was built
10 epics, each on its own story branch → gated (
fmt+ clippy lean and--features embeddings-D warnings+ fullcargo test --workspace) → merged--no-ff→ re-verified on the integrated tree after every merge. Final: test exit 0 (~1022 tests), lean build confirmed petgraph-free, binary reports2.0.0.Honest limitations (also in the CHANGELOG)
[cheap_model]distillation hook-point exists but doesn't yet call the model (ask/resume/skill-draft do use it).Review
🤖 Generated with Claude Code