claude_memory 0.12.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 935474b9efd1d9fd317c410728ed36b1cedb0854d1db6e71cd45ce6372253b9c
-  data.tar.gz: 1514d8b44e8ee25d139cd0544ab527bfa00ff54ace9786b7c47709afc0095024
+  metadata.gz: cec498c9aec388d1decdcb7ae05616fb414d7f026401248b6a051d051d238e39
+  data.tar.gz: 9a8b44aa97db10ead04a074f2619f08cdb74976dd22ce7843a5968bbbbda410e
 SHA512:
-  metadata.gz: f70d8858628ecbd350e32f89da3dcdd8ff99ff2c61c85dc938a512ab79f9d6bae46d87677168a7d9059fdace727657e388aeed48a451ae8340ac2af5dd9384b8
-  data.tar.gz: 3164ae23db7e7b8fd66ece557a84953727181e2b06d2db80c4a807678015b064f196489768fb50c980c7d1de8f732b86dd5c0666d9f766a0d05ce52757f1b23d
+  metadata.gz: 22c84d179c6af89f06909604674794741739237edc5cdb11c18bd9ba06ae4f9334bf20a4d8e8057181d25a206419cf50b35fec392ec3cd7d5fb093ea0046ef0c
+  data.tar.gz: a138ae2049416a7ec21ecef3545115a8415a2d64618d8f3334a50e2b6d552b61a7056824f5ef968b78907cfbc6515e38f60a1feed75a4db8b94793736bf0826d

data/.claude/rules/claude_memory.generated.md

@@ -1,69 +1,60 @@
 <!--
   This file is auto-generated by claude-memory.
   Do not edit manually - changes will be overwritten.
-  Generated: 2026-06-01T11:23:10Z
+  Generated: 2026-06-03T13:21:02Z
 -->
 
 # Project Memory
 
 ## Current Decisions
 
-- MCP tool-call telemetry stores minimal columns (tool_name, duration_ms, result_count, scope, error_class) — deliberately no query_text or query_hash. YAGNI: hashes are write-only without the raw text, and raw text adds privacy concerns without clear value beyond existing shortcut tools (memory.decisions, memory.conventions).
-- From QMD 2026-02-02 restudy: adopt Claude Code plugin format, MCP structured content pattern, MCP query guide prompt, inline status checks. Carry forward sqlite-vec, RRF, docids, smart expansion from 2026-01-26. Reject custom fine-tuned models, LLM reranking, YAML collections.
-- From claude-supermemory study: adopt SessionStart hook context injection (hookSpecificOutput.additionalContext), tool-specific observation compression, and relative time formatting. Reject cloud storage dependency and no-test approach.
+- MCP tool-call telemetry stores minimal columns (tool_name, duration_ms, result_count, scope, error_class) — deliberately no query_text or query_hash. YAGNI: hashes are write-only without the raw text, and raw text adds privacy concerns without clear value beyond existing shortcut tools (memory.decisions, memory.conventions). — to avoid storing query hashes that are write-only without the raw text.
+- From QMD 2026-02-02 restudy: adopt Claude Code plugin format, MCP structured content pattern, MCP query guide prompt, inline status checks. Carry forward sqlite-vec, RRF, docids, smart expansion from 2026-01-26. Reject custom fine-tuned models, LLM reranking, YAML collections. — to align with our pure-Ruby/SQLite constraints (no GGUF, no LLM-side fine-tuning).
+- From claude-supermemory study: adopt SessionStart hook context injection (hookSpecificOutput.additionalContext), tool-specific observation compression, and relative time formatting. Reject cloud storage dependency and no-test approach. — to avoid cloud-storage lock-in and no-test fragility identified in the study.
 
 ## Conventions
 
-- A/B testing methodology for memory plugin evaluation — How to test with/without memory using claude CLI — --plugin-dir doesn't work with --bare, use --mcp-config instead — To A/B test memory's impact on Claude Code responses: (imported from project auto-memory; see source file for full reasoning)
-- do...end blocks over braces when args repeat or block is non-trivial — Block syntax preference for multi-argument or multi-expression blocks — When a block call has repeated argument names, multiple expressions, or reads awkwardly on one line, use `do...end` form rather than `{ }`. One-liners with simple single-expression bodies and short argument lists are fine with braces. (imported from project auto-memory; see source file for full reasoning)
-- Always commit .claude/memory.sqlite3 — Per user direction (2026-05-21), .claude/memory.sqlite3 should be staged and committed alongside any change that updates project memory — even though it's a binary SQLite DB with WAL artifacts. — Always include `.claude/memory.sqlite3` in commits that touch project memory or knowledge. (imported from project auto-memory; see source file for full reasoning)
+- A/B testing methodology for memory plugin evaluation — How to test with/without memory using claude CLI — --plugin-dir doesn't work with --bare, use --mcp-config instead — To A/B test memory's impact on Claude Code responses: (imported from project auto-memory; see source file for full reasoning) — to enable head-to-head measurement of memory's impact on Claude Code responses.
+- do...end blocks over braces when args repeat or block is non-trivial — Block syntax preference for multi-argument or multi-expression blocks — When a block call has repeated argument names, multiple expressions, or reads awkwardly on one line, use `do...end` form rather than `{ }`. One-liners with simple single-expression bodies and short argument lists are fine with braces. (imported from project auto-memory; see source file for full reasoning) — to keep multi-line blocks readable and avoid brace/multi-expression awkwardness.
+- Always commit .claude/memory.sqlite3 — Per user direction (2026-05-21), .claude/memory.sqlite3 should be staged and committed alongside any change that updates project memory — even though it's a binary SQLite DB with WAL artifacts. — Always include `.claude/memory.sqlite3` in commits that touch project memory or knowledge. (imported from project auto-memory; see source file for full reasoning) — to ensure project memory is reproducible across collaborators.
 - Commit workflow preferences — How the user prefers commits to be structured and when to make them — Wait for the user to ask for commits — don't commit proactively. When asked, group changes into logical atomic commits: (imported from project auto-memory; see source file for full reasoning)
-- Data-driven analysis before design changes — User expects thorough multi-project data surveys and critical questioning of assumptions before committing to architectural changes — When proposing design changes (especially to schemas, vocabularies, or policies), gather real usage data first and present a critical analysis before implementing. (imported from project auto-memory; see source file for full reasoning)
-- Fix hallucination triggers at the source, not via repeated reject churn — When the distiller repeatedly produces the same wrong fact, trace it to the CLAUDE.md / docs example text; fixing the source stops re-appearance — When the dashboard's Conflicts tab accumulates clusters of the same kind of bad fact (e.g. many `uses_database` contradictions against `sqlite`), the root cause is almost always **example text in documentation** that the distiller is interpreting as a literal claim about the current repo. Single-value predicates (`uses_database`, `deployment_platform`, `auth_method`) are especially vulnerable becau... (imported from project auto-memory; see source file for full reasoning)
-- Hooks run the installed gem, not the working copy — always `rake install` after editing hook/MCP code — .claude/settings.json hooks invoke `claude-memory` via PATH, so changes on a branch only take effect after `bundle exec rake install` — `.claude/settings.json` hooks call bare `claude-memory hook ingest` / `claude-memory hook context` / etc. That resolves via PATH to the installed gem, not the working-copy `./exe/claude-memory`. After editing any hook/MCP/distiller code on a branch, the change does NOT reach Claude Code until `bundle exec rake install` rebuilds and reinstalls the gem (which overwrites the prior install at the same ... (imported from project auto-memory; see source file for full reasoning)
-- No extra API costs for features — User strongly prefers using Claude Code itself (skills, context hooks) over separate API calls that cost extra money — Do not add features that require separate Anthropic API calls (e.g., via anthropic-rb gem) when Claude Code itself can perform the same task. Use skills, context hook injection, and MCP tools to leverage the existing Claude Code session instead. (imported from project auto-memory; see source file for full reasoning)
-- Quality review update cycle — Keep quality_review.md current as items are resolved — don't let it drift — When completing quality review items, update `docs/quality_review.md` immediately: (imported from project auto-memory; see source file for full reasoning)
+- Data-driven analysis before design changes — User expects thorough multi-project data surveys and critical questioning of assumptions before committing to architectural changes — When proposing design changes (especially to schemas, vocabularies, or policies), gather real usage data first and present a critical analysis before implementing. (imported from project auto-memory; see source file for full reasoning) — to avoid premature architectural commitments before real usage data is in hand.
+- Fix hallucination triggers at the source, not via repeated reject churn — When the distiller repeatedly produces the same wrong fact, trace it to the CLAUDE.md / docs example text; fixing the source stops re-appearance — When the dashboard's Conflicts tab accumulates clusters of the same kind of bad fact (e.g. many `uses_database` contradictions against `sqlite`), the root cause is almost always **example text in documentation** that the distiller is interpreting as a literal claim about the current repo. Single-value predicates (`uses_database`, `deployment_platform`, `auth_method`) are especially vulnerable becau... (imported from project auto-memory; see source file for full reasoning) — because reject-only is treating symptoms; the root cause is doc/example text the distiller mistakes for project claims.
+- Hooks run the installed gem, not the working copy — always `rake install` after editing hook/MCP code — .claude/settings.json hooks invoke `claude-memory` via PATH, so changes on a branch only take effect after `bundle exec rake install` — `.claude/settings.json` hooks call bare `claude-memory hook ingest` / `claude-memory hook context` / etc. That resolves via PATH to the installed gem, not the working-copy `./exe/claude-memory`. After editing any hook/MCP/distiller code on a branch, the change does NOT reach Claude Code until `bundle exec rake install` rebuilds and reinstalls the gem (which overwrites the prior install at the same ... (imported from project auto-memory; see source file for full reasoning) — to ensure code changes reach the production hooks, which invoke the installed gem via PATH.
+- No extra API costs for features — User strongly prefers using Claude Code itself (skills, context hooks) over separate API calls that cost extra money — Do not add features that require separate Anthropic API calls (e.g., via anthropic-rb gem) when Claude Code itself can perform the same task. Use skills, context hook injection, and MCP tools to leverage the existing Claude Code session instead. (imported from project auto-memory; see source file for full reasoning) — to avoid hidden ongoing spend that bypasses the Claude Code session's existing budget.
+- Quality review update cycle — Keep quality_review.md current as items are resolved — don't let it drift — When completing quality review items, update `docs/quality_review.md` immediately: (imported from project auto-memory; see source file for full reasoning) — to prevent quality_review.md from drifting out of date.
 - Refactoring approach preferences — How to approach god object extraction and structural refactoring in this codebase — Use module inclusion (not class extraction) when breaking up god objects. Include modules directly into the existing class so the public API is unchanged and zero tests need modification. This was validated three times:
-- Round-trip migration specs cover each prior release boundary — For pre-release prep, write end-to-end migration specs from every distinct schema boundary back through ~3 prior releases — Before cutting a release that includes migrations, add round-trip specs that fixture an older DB at each distinct prior release's schema version, open via `SQLiteStore.new`, and assert the full upgrade path: schema_info advancement, data preservation across entities/facts/content_items/provenance, additive table/column creation, predicate-rewrite effects where applicable, and idempotency on re-open... (imported from project auto-memory; see source file for full reasoning)
+- Round-trip migration specs cover each prior release boundary — For pre-release prep, write end-to-end migration specs from every distinct schema boundary back through ~3 prior releases — Before cutting a release that includes migrations, add round-trip specs that fixture an older DB at each distinct prior release's schema version, open via `SQLiteStore.new`, and assert the full upgrade path: schema_info advancement, data preservation across entities/facts/content_items/provenance, additive table/column creation, predicate-rewrite effects where applicable, and idempotency on re-open... (imported from project auto-memory; see source file for full reasoning) — to ensure migrations remain forward-compatible across release boundaries.
 - Codify behavioral contracts in tests, not just comments — When code has a deliberate scope limitation (one-shot, advisory-only, intentionally non-idempotent), write a test that fails if someone "fixes" it into being more general — When code has a deliberate scope limitation — a one-shot data migration, an advisory-only field, a method intentionally not idempotent for new inputs — write a test that exercises a scenario which would *break* if someone tried to make it more general. (imported from project auto-memory; see source file for full reasoning)
-- Treat UX gaps as architecture smells — user inspection/debugging questions expose god classes and missing abstractions — When users ask "can I see/debug/act on X in the dashboard?", the answer is almost always "we need a new class or route, not a new button" — Across three architectural reviews in the 2026-04-17 → 20 session, every concrete UX gap the user identified traced back to a structural issue the code already had, not a frontend-only fix. Treating critique as a forcing function for refactoring produced cleaner results than either extracting preemptively (premature) or patching only the surface (symptom). (imported from project auto-memory; see source file for full reasoning)
-- "database disk image is malformed" from FTS5 `ORDER BY rank` after sqlite3 .recover — sqlite3 .recover restores rows but can leave contentless FTS5 auxiliary indexes in a state where basic MATCH works but ORDER BY rank throws "malformed"; fix is `claude-memory compact` to rebuild the FTS index — A DB recovered via `sqlite3 corrupt.db .recover > dump.sql && sqlite3 fresh.db < dump.sql` can end up with an FTS5 index that's *partially* functional: (imported from project auto-memory; see source file for full reasoning)
-- `rake install` uses `git ls-files`; untracked files silently disappear from the gem — Running `bundle exec rake install` before staging new files produces a gem missing those files, causing LoadError in hooks and MCP server — The claude_memory gemspec builds its file list via `IO.popen(%w[git ls-files -z], ...)` (claude_memory.gemspec:24). Any file that hasn't been `git add`ed at build time is **invisible to the gem** even though it exists on disk. The local working copy keeps running fine (dashboard server uses `./exe/claude-memory` against the repo directly), but the installed gem at `~/.gem/ruby/*/gems/claude_memory-... (imported from project auto-memory; see source file for full reasoning)
-- Distiller scope_hint is advisory, not a routing signal — NullDistiller emits scope_hint: "global" for text matching GLOBAL_SCOPE_PATTERNS, but the resolver never routes writes between stores — scope_hint must not override fact.scope — `Distill::NullDistiller#global_scope_signal?` matches text like "always" / "my preference" / "in all projects" and stamps `scope_hint: "global"` on every fact extracted from that text. The hint is advisory metadata for downstream promotion decisions. It is NOT a routing signal — the resolver writes to whichever `SQLiteStore` was injected into it (always the project DB in the normal ingest path), re... (imported from project auto-memory; see source file for full reasoning)
-- Sequel DB reads must use the extralite adapter — Opening a SQLite DB for ad-hoc reads requires the extralite adapter URI; Sequel.sqlite silently depends on an ungem'd sqlite3 — Never use `Sequel.sqlite(db_path)` or `Sequel.sqlite(db_path, readonly: true)` in this codebase. The gemspec lists only `extralite (~> 2.14)` — it does **not** depend on the `sqlite3` gem. `Sequel.sqlite` routes through Sequel's `sqlite` adapter which requires `gem "sqlite3"` and will raise `Sequel::AdapterNotFound: LoadError: cannot load such file -- sqlite3` at runtime. (imported from project auto-memory; see source file for full reasoning)
-- Never `git checkout --` an active SQLite DB with WAL mode — Using `git checkout --` on .claude/memory.sqlite3 while readers/writers are open corrupts the DB via WAL/main file mismatch — Never run `git checkout -- .claude/memory.sqlite3` (or any SQLite DB in WAL mode) while any process has it open. Git replaces only the main DB file, leaving the WAL/SHM sidecar files referencing pages that no longer exist in the replaced file. Next read → "Extralite::Error: database disk image is malformed" and integrity_check shows btree errors across multiple trees. (imported from project auto-memory; see source file for full reasoning)
-- SQLiteStore silently creates in-memory DB for relative paths — `SQLiteStore.new('.claude/memory.sqlite3')` with a relative path opens an empty in-memory DB, not the file — always pass absolute paths in tests/probes — `SQLiteStore.new(path)` builds a Sequel URI as `extralite:#{path}`. With a relative path like `.claude/memory.sqlite3`, the resulting URI `extralite:.claude/memory.sqlite3` is parsed with an empty database component, so Extralite opens an in-memory database. Schema migrations run against the in-memory DB (so `schema_version` reports the current version), but ALL queries return 0 rows and the real f... (imported from project auto-memory; see source file for full reasoning)
-- Two tool_calls tables exist — don't conflate them — tool_calls (v3) stores transcript-observed Claude Code tool usage; mcp_tool_calls (v13) stores MCP server telemetry — There are **two** tables with similar names serving different purposes: (imported from project auto-memory; see source file for full reasoning)
-- Distiller hallucination from CLAUDE.md example text — The scope-system example in CLAUDE.md causes recurring false fact extraction — reject + re-ingest creates rejection churn — CLAUDE.md contains a scope-system explanation with example text: (imported from project auto-memory; see source file for full reasoning)
-- PredicatePolicy is the single source of truth for predicate vocabulary — All predicate knowledge (vocabulary, cardinality, sections, synonyms, LLM guidance) derives from PredicatePolicy — never hardcode predicate names elsewhere — As of 0.9.0, `PredicatePolicy` in `lib/claude_memory/resolve/predicate_policy.rb` is the authoritative source for all predicate-related behavior. This was a deliberate consolidation after finding the same predicate list duplicated in 4 files that drifted independently. (imported from project auto-memory; see source file for full reasoning)
+- Treat UX gaps as architecture smells — user inspection/debugging questions expose god classes and missing abstractions — When users ask "can I see/debug/act on X in the dashboard?", the answer is almost always "we need a new class or route, not a new button" — Across three architectural reviews in the 2026-04-17 → 20 session, every concrete UX gap the user identified traced back to a structural issue the code already had, not a frontend-only fix. Treating critique as a forcing function for refactoring produced cleaner results than either extracting preemptively (premature) or patching only the surface (symptom). (imported from project auto-memory; see source file for full reasoning) — because frontend patches usually mask structural debt that surfaces later.
+- "database disk image is malformed" from FTS5 `ORDER BY rank` after sqlite3 .recover — sqlite3 .recover restores rows but can leave contentless FTS5 auxiliary indexes in a state where basic MATCH works but ORDER BY rank throws "malformed"; fix is `claude-memory compact` to rebuild the FTS index — A DB recovered via `sqlite3 corrupt.db .recover > dump.sql && sqlite3 fresh.db < dump.sql` can end up with an FTS5 index that's *partially* functional: (imported from project auto-memory; see source file for full reasoning) — fix is claude-memory compact to rebuild the FTS index without doing another .recover.
+- `rake install` uses `git ls-files`; untracked files silently disappear from the gem — Running `bundle exec rake install` before staging new files produces a gem missing those files, causing LoadError in hooks and MCP server — The claude_memory gemspec builds its file list via `IO.popen(%w[git ls-files -z], ...)` (claude_memory.gemspec:24). Any file that hasn't been `git add`ed at build time is **invisible to the gem** even though it exists on disk. The local working copy keeps running fine (dashboard server uses `./exe/claude-memory` against the repo directly), but the installed gem at `~/.gem/ruby/*/gems/claude_memory-... (imported from project auto-memory; see source file for full reasoning) — to ensure new files reach the installed gem (the gemspec uses git ls-files for the manifest).
+- Distiller scope_hint is advisory, not a routing signal — NullDistiller emits scope_hint: "global" for text matching GLOBAL_SCOPE_PATTERNS, but the resolver never routes writes between stores — scope_hint must not override fact.scope — `Distill::NullDistiller#global_scope_signal?` matches text like "always" / "my preference" / "in all projects" and stamps `scope_hint: "global"` on every fact extracted from that text. The hint is advisory metadata for downstream promotion decisions. It is NOT a routing signal — the resolver writes to whichever `SQLiteStore` was injected into it (always the project DB in the normal ingest path), re... (imported from project auto-memory; see source file for full reasoning) — to prevent scope drift between resolver-determined store and distiller-stamped hint.
+- Sequel DB reads must use the extralite adapter — Opening a SQLite DB for ad-hoc reads requires the extralite adapter URI; Sequel.sqlite silently depends on an ungem'd sqlite3 — Never use `Sequel.sqlite(db_path)` or `Sequel.sqlite(db_path, readonly: true)` in this codebase. The gemspec lists only `extralite (~> 2.14)` — it does **not** depend on the `sqlite3` gem. `Sequel.sqlite` routes through Sequel's `sqlite` adapter which requires `gem "sqlite3"` and will raise `Sequel::AdapterNotFound: LoadError: cannot load such file -- sqlite3` at runtime. (imported from project auto-memory; see source file for full reasoning) — to avoid Sequel::AdapterNotFound at runtime (this gem doesn't depend on the sqlite3 adapter).
+- Never `git checkout --` an active SQLite DB with WAL mode — Using `git checkout --` on .claude/memory.sqlite3 while readers/writers are open corrupts the DB via WAL/main file mismatch — Never run `git checkout -- .claude/memory.sqlite3` (or any SQLite DB in WAL mode) while any process has it open. Git replaces only the main DB file, leaving the WAL/SHM sidecar files referencing pages that no longer exist in the replaced file. Next read → "Extralite::Error: database disk image is malformed" and integrity_check shows btree errors across multiple trees. (imported from project auto-memory; see source file for full reasoning) — to avoid WAL/main file mismatch corruption.
+- SQLiteStore silently creates in-memory DB for relative paths — `SQLiteStore.new('.claude/memory.sqlite3')` with a relative path opens an empty in-memory DB, not the file — always pass absolute paths in tests/probes — `SQLiteStore.new(path)` builds a Sequel URI as `extralite:#{path}`. With a relative path like `.claude/memory.sqlite3`, the resulting URI `extralite:.claude/memory.sqlite3` is parsed with an empty database component, so Extralite opens an in-memory database. Schema migrations run against the in-memory DB (so `schema_version` reports the current version), but ALL queries return 0 rows and the real f... (imported from project auto-memory; see source file for full reasoning) — to ensure SQLiteStore opens the real file rather than a silent in-memory shadow.
+- Two tool_calls tables exist — don't conflate them — tool_calls (v3) stores transcript-observed Claude Code tool usage; mcp_tool_calls (v13) stores MCP server telemetry — There are **two** tables with similar names serving different purposes: (imported from project auto-memory; see source file for full reasoning) — to avoid joining unrelated rows from disjoint telemetry tables.
+- Distiller hallucination from CLAUDE.md example text — The scope-system example in CLAUDE.md causes recurring false fact extraction — reject + re-ingest creates rejection churn — CLAUDE.md contains a scope-system explanation with example text: (imported from project auto-memory; see source file for full reasoning) — to prevent re-extraction churn from documentation example text that the distiller takes literally.
+- PredicatePolicy is the single source of truth for predicate vocabulary — All predicate knowledge (vocabulary, cardinality, sections, synonyms, LLM guidance) derives from PredicatePolicy — never hardcode predicate names elsewhere — As of 0.9.0, `PredicatePolicy` in `lib/claude_memory/resolve/predicate_policy.rb` is the authoritative source for all predicate-related behavior. This was a deliberate consolidation after finding the same predicate list duplicated in 4 files that drifted independently. (imported from project auto-memory; see source file for full reasoning) — to avoid divergent predicate lists across files that drifted independently before consolidation.
 - Hook-telemetry features need a manual hook trigger to verify in production, not just specs — `bundle exec rake install` AND fire a real hook AND check `sqlite3 ... json_extract(detail_json, '$.<field>')`, because specs assert against working-tree code but `.claude/settings.json` hooks invoke the installed gem via PATH so the asserted field can be silently absent in production. Hit on 2026-04-30 shipping #47 token-budget telemetry: 156 specs green but `context_tokens` was missing from 24h of real activity_events.
-- When verifying any new field on activity_events.detail_json, the canonical smoke test is: `echo '{"hook_event_name":"SessionStart","session_id":"smoketest","source":"startup","cwd":"$(pwd)"}' | claude-memory hook context` then inspect via `sqlite3 .claude/memory.sqlite3 "SELECT json_extract(detail_json, '$.<field>') FROM activity_events WHERE event_type='hook_context' ORDER BY id DESC LIMIT 1"`. If null after rake install, the installed gem code hasn't picked up the change.
+- When verifying any new field on activity_events.detail_json, the canonical smoke test is: `echo '{"hook_event_name":"SessionStart","session_id":"smoketest","source":"startup","cwd":"$(pwd)"}' | claude-memory hook context` then inspect via `sqlite3 .claude/memory.sqlite3 "SELECT json_extract(detail_json, '$.<field>') FROM activity_events WHERE event_type='hook_context' ORDER BY id DESC LIMIT 1"`. If null after rake install, the installed gem code hasn't picked up the change. — to ensure the installed gem actually picks up new detail_json fields.
 - Treat UX gaps as architecture smells: when a user asks "can I see/debug/act on X in the dashboard?" the answer is almost always a missing class or route, not a new button. Every UX critique in this project's dashboard work traced to a structural gap — god-class growth, four drifting fact serializers, scope_hint as silent scope override, no fact detail endpoint. Pattern: the surface question is usually a router into the architecture. Before reaching for frontend fixes, ask "what server-side data shape would make this easy?" — if that shape doesn't exist cleanly, treat it as the real work. Commit refactor separately from feature it enables ([Refactor]/[Feature]/[Fix] prefixes) so the critique→structural fix→UX fix chain is visible in git log.
 - Four-surface staleness: after any change that touches UI + backend + plugin-launched binaries, refresh all four or the change looks broken. (1) bundle exec rake install so the installed gem catches up (hooks + MCP launched by Claude Code run from PATH). (2) Ctrl-C and re-run ./exe/claude-memory dashboard — server is long-lived Ruby, no live-reload. (3) /mcp reconnect in Claude Code so the MCP subprocess respawns. (4) Hard-refresh browser (Cmd-Shift-R) so cached index.html JS reloads. Skipping any produces confusing "my fix doesn't work." rspec green does NOT mean end-to-end works; before declaring UI-affecting changes done, curl the endpoint and verify shape matches frontend expectation. curl alt-port dashboard (--port 3388 --no-open in background) is fastest smoke test without disturbing user's running dashboard.
-- fact.scope MUST match the DB the fact lives in. The distiller may emit scope_hint="global" from GLOBAL_SCOPE_PATTERNS but scope_hint is advisory only — it never routes writes or overrides the destination store's scope. Using scope_hint as a scope override produced orphaned scope=global rows inside the project DB that global recall couldn't see. Users move project facts to global via claude-memory promote (StoreManager#promote_fact does the proper cross-store copy). Sweep::Maintenance#fix_scope_leakage cleans drift in existing DBs. Invariant documented in gotcha_scope_hint_not_routing memory.
-- "disk image is malformed" from an FTS5 ORDER BY rank query after a sqlite3 .recover restore is usually FTS auxiliary-index corruption, not real DB damage. Diagnostic chain: PRAGMA integrity_check on fresh connection (ok means main DB is fine), plain MATCH (works means b-tree is fine), ORDER BY rank (fails means FTS internals rotted). Fix with claude-memory compact — rebuilds FTS from source content in a few seconds. Do NOT reach for sqlite3 .recover a second time; that's the class of action that leaves FTS in this broken state. Three distinct malformed-error flavors in this project: real corruption (use .recover), WAL stale-cache phantom from long-lived readers (release connections per request), FTS5 rank rot (compact).
-- Name collision: claude-memory recover (CLI) resets stuck operations from OperationTracker; it does NOT repair corrupt SQLite. For real disk-image corruption use sqlite3 corrupt.db ".recover" > dump.sql && sqlite3 fresh.db < dump.sql then open via SQLiteStore for migrations. Recovery can leave contentless FTS5 in a partial state where plain MATCH works but ORDER BY rank fails — follow up with claude-memory compact. Verified recoverable on 2026-04-16 — 76 facts / 56 entities / 183 content_items restored from a DB with multiple btree errors.
-- Hooks in .claude/settings.json invoke bare 'claude-memory' which resolves via PATH to the installed gem, not the working-copy ./exe/claude-memory. After editing Hook::Handler, MCP::Tools, MCP::Server, ActivityLog, Distill::*, or any commands/ file on a branch, run 'bundle exec rake install' before expecting hooks or the Claude-Code-launched MCP server to see the change. The dashboard server (./exe/claude-memory dashboard) is the exception — it runs from the working copy directly. When reinstalling while servers are running, also restart them (Ctrl-C or /mcp reconnect) since old code stays in memory.
-- Never 'git checkout --' .claude/memory.sqlite3 (or any WAL-mode SQLite DB) while a reader/writer has it open. Git replaces the main DB file but leaves the -wal and -shm sidecar files referencing stale pages, which corrupts the DB on next read. Safe sequence: stop all holders (MCP server, dashboard, hooks), delete the -wal and -shm sidecars, then checkout. Recovery path: sqlite3 corrupt.db .recover > dump.sql then reimport into a fresh file.
-- SQLiteStore.new with a relative path silently opens an empty in-memory DB instead of the file. The URI built in retry_handler.rb is extralite:<path>, and extralite:.claude/memory.sqlite3 parses with an empty database option so Extralite treats it as in-memory. Schema migrations run so schema_version looks correct but all queries return 0 rows. Production callers go through StoreManager with absolute paths (via Configuration) so this does not bite in normal use. In ad-hoc probes always pass File.expand_path(path). Diagnostic: if store.facts.count returns 0 while sqlite3 CLI shows rows, suspect this before suspecting corruption.
-- Never use Sequel.sqlite for DB reads; this gem only depends on extralite. Use Sequel.connect("extralite://#{db_path}") or SQLiteStore.new. Sequel.sqlite requires the ungem'd sqlite3 adapter and fails at runtime.
-- Two distinct tool_calls tables exist: tool_calls (v3) for transcript-observed Claude Code tool usage, and mcp_tool_calls (v13) for MCP server telemetry. Disjoint purposes, never join.
-- MCP tool-call telemetry is recorded via MCP::Telemetry wrapping Server#handle_tools_call. Writes to mcp_tool_calls table in the project DB. Swallows DB errors so telemetry never breaks a real tool response. Viewable via 'claude-memory stats --tools [--since DAYS]'.
-- mcp_tool_calls retention is 90 days, enforced by Sweep::Maintenance#prune_old_mcp_tool_calls wired into Sweeper#run!. Configurable via mcp_tool_call_retention_days in Maintenance DEFAULT_CONFIG.
-- CLAUDE_CONFIG_DIR env var overrides the default ~/.claude location for Configuration#global_db_path. Access via Configuration#claude_config_dir. Additive, backwards compatible.
-- Registry::COMMANDS stores {class:, description:} entries as the single source of truth for command name, class reference, and shell-completion description. Class constants stored directly (no const_get). Registry.descriptions feeds CompletionCommand; adding a new command requires updating only this hash.
-- Prefer do...end over braces when a block has repeated argument names, multiple expressions, or non-trivial body. Single-expression simple blocks can still use braces.
-- EXPECTED_HOOKS constant must stay in sync with events in HooksConfigurator#build_hooks_config. Adding a new hook event without updating EXPECTED_HOOKS causes false doctor warnings.
-- Tests using --db for hook context only set the project DB path. StoreManager still connects to the real global DB. Must stub Configuration to return a temp global path for isolation.
-- Version must be updated in three places: lib/claude_memory/version.rb, .claude-plugin/plugin.json, .claude-plugin/marketplace.json. Runtime code uses ClaudeMemory::VERSION dynamically.
-- Use module inclusion (not class extraction) to break up god objects — preserves public API so zero tests need modification
-- Configuration class has instance methods only — use Configuration.new.global_db_path, not Configuration.global_db_path. Stub with instance_double + allow(Configuration).to receive(:new).and_return(config)
-- OperationTracker.reset_stuck_operations only resets operations older than 24 hours (STALE_THRESHOLD_SECONDS). Tests must backdate started_at to trigger resets.
-- SCHEMA_VERSION constant lives in Store::SchemaManager module but is accessible as SQLiteStore::SCHEMA_VERSION via Ruby include-based constant lookup
-- MCP tools return dual content (text summary) + structuredContent (JSON) via TextSummary module and Server#handle_tools_call. Compact mode (compact: true) omits receipts for ~60% smaller responses.
-- ContentSanitizer strips system-reminder, local-command-caveat, command-message, command-name, command-args tags in addition to private/no-memory/secret/claude-memory-context.
-- Core::RelativeTime module provides progressive time formatting: just now → Xm ago → Xh ago → Xd ago → YYYY-MM-DD. Used in ResponseFormatter for *_ago fields.
-- MCP server registers memory_guide prompt via prompts/list and prompts/get endpoints. QueryGuide module holds prompt content.
+- MCP tool-call telemetry is recorded via MCP::Telemetry wrapping Server#handle_tools_call. Writes to mcp_tool_calls table in the project DB. Swallows DB errors so telemetry never breaks a real tool response. Viewable via 'claude-memory stats --tools [--since DAYS]'. — to ensure telemetry never breaks a real tool response (DB errors are swallowed).
+- mcp_tool_calls retention is 90 days, enforced by Sweep::Maintenance#prune_old_mcp_tool_calls wired into Sweeper#run!. Configurable via mcp_tool_call_retention_days in Maintenance DEFAULT_CONFIG. — long enough to support quarterly tool-usage retrospectives without unbounded DB growth.
+- CLAUDE_CONFIG_DIR env var overrides the default ~/.claude location for Configuration#global_db_path. Access via Configuration#claude_config_dir. Additive, backwards compatible. — to support test isolation and air-gapped installs that don't touch ~/.claude.
+- Registry::COMMANDS stores {class:, description:} entries as the single source of truth for command name, class reference, and shell-completion description. Class constants stored directly (no const_get). Registry.descriptions feeds CompletionCommand; adding a new command requires updating only this hash. — to ensure adding a command requires only this hash update (no const_get, no description duplication).
+- EXPECTED_HOOKS constant must stay in sync with events in HooksConfigurator#build_hooks_config. Adding a new hook event without updating EXPECTED_HOOKS causes false doctor warnings. — without this sync the doctor reports false hook-mismatch warnings.
+- Tests using --db for hook context only set the project DB path. StoreManager still connects to the real global DB. Must stub Configuration to return a temp global path for isolation. — to ensure test isolation from the user's real global DB.
+- Version must be updated in three places: lib/claude_memory/version.rb, .claude-plugin/plugin.json, .claude-plugin/marketplace.json. Runtime code uses ClaudeMemory::VERSION dynamically. — to ensure plugin/marketplace metadata matches the gem version on release.
+- Use module inclusion (not class extraction) to break up god objects — preserves public API so zero tests need modification — to avoid breaking the public API and forcing test updates during god-object cleanup.
+- Configuration class has instance methods only — use Configuration.new.global_db_path, not Configuration.global_db_path. Stub with instance_double + allow(Configuration).to receive(:new).and_return(config) — to make Configuration stubbable in tests via instance_double.
+- OperationTracker.reset_stuck_operations only resets operations older than 24 hours (STALE_THRESHOLD_SECONDS). Tests must backdate started_at to trigger resets. — to prevent the reset from clobbering operations still legitimately in flight.
+- SCHEMA_VERSION constant lives in Store::SchemaManager module but is accessible as SQLiteStore::SCHEMA_VERSION via Ruby include-based constant lookup — accessible via include because Ruby's constant lookup walks the inclusion chain.
+- MCP tools return dual content (text summary) + structuredContent (JSON) via TextSummary module and Server#handle_tools_call. Compact mode (compact: true) omits receipts for ~60% smaller responses. — so that compact-mode callers pay ~60% fewer tokens per response.
+- ContentSanitizer strips system-reminder, local-command-caveat, command-message, command-name, command-args tags in addition to private/no-memory/secret/claude-memory-context. — to prevent harness-internal tags from being ingested as user content.
+- Core::RelativeTime module provides progressive time formatting: just now → Xm ago → Xh ago → Xd ago → YYYY-MM-DD. Used in ResponseFormatter for *_ago fields. — to make stale-fact warnings legible across both recent and old timestamps.
+- MCP server registers memory_guide prompt via prompts/list and prompts/get endpoints. QueryGuide module holds prompt content. — to ensure memory_guide is discoverable via the standard MCP prompt registry.
 
 ## Technical Constraints
 

data/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   "plugins": [
     {
       "name": "claude-memory",
-      "version": "0.12.0",
+      "version": "0.12.1",
       "source": "./",
       "description": "Long-term memory for Claude Code. Recalls architecture, conventions, and decisions across sessions — so Claude explains your codebase without file traversal, follows your patterns, and never re-asks what it already learned.",
       "repository": "https://github.com/codenamev/claude_memory"

data/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-memory",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Long-term memory for Claude Code. Recalls architecture, conventions, and decisions across sessions — so Claude explains your codebase without file traversal, follows your patterns, and never re-asks what it already learned.",
   "author": {
     "name": "Valentino Stoll",
@@ -16,7 +16,5 @@
       "args": []
     }
   },
-  "skills": "./skills/",
-  "commands": "./commands/",
-  "outputStyles": "./output-styles/"
+  "commands": "./commands/"
 }

data/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.12.1] - 2026-06-05
+
+Theme: **Upgrade-experience patches surfaced by the 0.12.0 soak.** Four small but high-impact fixes — all uncovered by one user upgrading a single project — closing visibility gaps in the doctor and the plugin manifest. No schema changes, no breaking changes.
+
+### Added
+
+- **`claude-memory setup-vectors` command** — the documented opt-in path for end users who want vector recall via the BAAI/bge-small-en-v1.5 model. fastembed remains a dev/test gem dependency by design (the default install stays light); this command verifies the chosen provider is loadable (gracefully prompts to `gem install fastembed` if not), writes `CLAUDE_MEMORY_EMBEDDING_PROVIDER` (and optional `CLAUDE_MEMORY_EMBEDDING_MODEL`) to the project's `.claude/settings.json` env block — the same mechanism Claude Code uses for OTel — and re-indexes existing facts via the existing `IndexCommand` (skip with `--no-reindex`). Supports `--status` for current config and `--dry-run` for inspection. Preserves unrelated settings.json keys.
+- **`Checks::EmbeddingsCheck`** in `claude-memory doctor` — surfaces the active embedding provider name and dimensions, hints to set `CLAUDE_MEMORY_EMBEDDING_PROVIDER=fastembed` when on tfidf default and fastembed is loadable, and reports dimension mismatches between stored vectors and the current provider. Closes the visibility gap where a user could see `sqlite-vec available ✓` while silently running on tfidf without knowing.
+
+### Fixed
+
+- **`plugin.json` declared `skills: "./skills/"` and `outputStyles: "./output-styles/"` pointing at non-existent directories.** Per Claude Code's plugin reference, `distill-transcripts.md` is correctly a flat *command* (not a skill); both forms register as `/<name>` slash commands. Dead keys removed. Plugin spec rewritten as deletion-safe ("every directory key in plugin.json points at an existing directory") so this can't regress.
+
+### Documentation
+
+- **README "Upgrading" section** now documents the marketplace-refresh + `/reload-plugins` flow explicitly. After `/plugin marketplace update <name>` users must run `/reload-plugins` or restart Claude Code for new slash commands to appear — this bit one user upgrading to 0.12.0 looking for `/distill-transcripts`. Includes `/audit-memory` and `/distill-transcripts` as named examples.
+
+### Upgrade Notes
+
+- No DB migrations. Schema stays at v18.
+- After `gem update claude_memory`, run `/plugin marketplace update claude-memory && /reload-plugins` (or restart Claude Code) to see the new `/distill-transcripts` and `/audit-memory` slash commands.
+- Existing fact bases continue to use whatever embedding provider they were indexed under. To opt into fastembed, run `claude-memory setup-vectors` — it handles provider switching + re-index in one step.
+- `claude-memory doctor` will now emit a warning on tfidf default with fastembed loadable. This is informational, not an error; the system continues to function on tfidf.
+
 ## [0.12.0] - 2026-05-29
 
 Theme: **Release Discipline + Observability + Self-Audit** — the infrastructure that makes a 1.0 semver promise defensible. This release locks down the public API surface, adds the observability primitives (OTel ingestion, dashboard Telemetry) and the self-audit toolkit (`claude-memory audit`) that serve the visibility pillar, and ships the negative-fact harm benchmark + staleness guard that make the long-horizon-quality claim measurable rather than aspirational.

data/CLAUDE.md

@@ -167,7 +167,7 @@ New MCP tools `memory.undistilled` and `memory.mark_distilled` support the pipel
   - Each command is a separate class (HelpCommand, DoctorCommand, etc.)
   - All commands inherit from BaseCommand
   - Dependency injection for I/O (stdout, stderr, stdin)
-  - 34 commands total, each focused on single responsibility
+  - 38 commands total, each focused on single responsibility
 
 - **`Configuration`**: Centralized ENV access (`configuration.rb`)
   - Single source of truth for paths and environment variables
@@ -339,7 +339,7 @@ Also update `SECTION_MAP` if the predicate should appear in a specific snapshot
 
 - `lib/claude_memory.rb`: Main module, requires, database path helpers
 - `lib/claude_memory/cli.rb`: Thin command router (41 lines)
-- `lib/claude_memory/commands/`: Individual command classes (34 commands)
+- `lib/claude_memory/commands/`: Individual command classes (38 commands)
 - `lib/claude_memory/configuration.rb`: Centralized configuration and ENV access
 - `lib/claude_memory/domain/`: Domain models (Fact, Entity, Provenance, Conflict)
 - `lib/claude_memory/core/`: Value objects and null objects

data/README.md

@@ -238,6 +238,17 @@ gem update claude_memory
 
 All database migrations happen automatically. Run `claude-memory doctor` to verify.
 
+### After upgrading: refresh the Claude Code plugin
+
+If you installed claude-memory as a Claude Code plugin (via the marketplace), pull the latest plugin spec **and reload it in your current session**:
+
+```
+/plugin marketplace update claude-memory
+/reload-plugins
+```
+
+`/plugin marketplace update` refreshes the plugin manifest from the source, but **the new slash commands won't appear until you run `/reload-plugins` (or restart Claude Code)** — slash commands are loaded once at session start. This bites every release that adds a new command (e.g. `/distill-transcripts` in 0.11, `/audit-memory` in 0.12); if a documented slash command doesn't autocomplete after upgrade, `/reload-plugins` is the fix.
+
 See [CHANGELOG.md](CHANGELOG.md) for detailed release notes.
 
 ## Troubleshooting

data/docs/api_stability.md

@@ -47,7 +47,7 @@ When ambiguous, default is **internal** — easier to promote later than demote.
 
 ## 2. Public CLI surface
 
-All commands listed in `Commands::Registry::COMMANDS` are reachable via `claude-memory <subcommand>`. The full registered set (34 commands as of 0.12.0) is canonically stored in `lib/claude_memory/commands/registry.rb`. Stability:
+All commands listed in `Commands::Registry::COMMANDS` are reachable via `claude-memory <subcommand>`. The full registered set (38 commands as of 0.12.1) is canonically stored in `lib/claude_memory/commands/registry.rb`. Stability:
 
 ### Stable commands (covered by semver)
 
@@ -90,6 +90,7 @@ May change in any minor; treat with care.
 | `claude-memory recall --semantic` / `--mode=hybrid` | Semantic-recall flags depend on the embedding backend; `tfidf` is stable, `fastembed`/`api` may change configuration knobs. |
 | `claude-memory embeddings` | Embedding-backend inspection; the JSON shape evolves with provider work. |
 | `claude-memory import-auto-memory [--dry-run]` | Imports Claude Code auto-memory markdown files into the project DB as facts. Introduced 0.12.0 from the 2026-05-21 audit; argument shape and idempotency contract are stable but the heuristic for predicate mapping may evolve. |
+| `claude-memory setup-vectors [--provider=NAME] [--model=NAME] [--no-reindex] [--dry-run] [--status]` | Documented opt-in path for enabling vector recall via fastembed. Introduced 0.12.1. Writes `CLAUDE_MEMORY_EMBEDDING_PROVIDER` (and optional `CLAUDE_MEMORY_EMBEDDING_MODEL`) to `.claude/settings.json` env block, then re-embeds via `IndexCommand`. fastembed remains a dev/test gem dep by design; install via `gem install fastembed` if not present. Argument shape stable; the underlying re-index implementation may evolve. |
 
 ### Internal / not for external automation
 
@@ -309,7 +310,11 @@ Run before tagging a release; wire into CI on the project's own DB to catch in-c
 6. Distillation backlog < 100 (hard fail) / < 25 (warning).
 7. Project active facts ≥ 5 (sanity floor — catches over-aggressive rejection).
 
-Run via `bundle exec rspec spec/benchmarks/health/ --tag benchmark`.
+Run via `bundle exec rspec spec/benchmarks/health/ --tag benchmark`. The
+spec is **local-only** — `.claude/memory.sqlite3` is git-lfs tracked and CI
+checkout doesn't pull LFS objects, so the spec auto-skips on CI when it
+detects the unresolved pointer. Run it locally after `git lfs pull` to
+validate signal contracts before tagging a release.
 
 ---
 

data/docs/soak/audit_2026-06-03_agent-training-program.json

@@ -0,0 +1,53 @@
+{
+  "ok": true,
+  "checks_run": 10,
+  "counts": {
+    "error": 0,
+    "warn": 0,
+    "info": 2
+  },
+  "stats": {
+    "global": {
+      "active_facts": 4,
+      "predicate_counts": {
+        "convention": 4
+      }
+    },
+    "project": {
+      "active_facts": 27,
+      "predicate_counts": {
+        "convention": 20,
+        "uses_language": 3,
+        "uses_framework": 2,
+        "deployment_platform": 1,
+        "uses_database": 1
+      }
+    }
+  },
+  "findings": [
+    {
+      "id": "C007",
+      "severity": "info",
+      "title": "35% of decisions/conventions lack reason clauses (7/20)",
+      "detail": "Facts without 'because/so that/to avoid/...' lose their justification once context fades. Bare conclusions are dead weight when the team grows or you revisit a year later.",
+      "suggestion": "Inspect with: claude-memory explain <fact_id>. Reject low-value bare facts or rewrite with reason clauses via memory.store_extraction.",
+      "fact_ids": [
+        4,
+        6,
+        9,
+        13,
+        21,
+        23,
+        24
+      ]
+    },
+    {
+      "id": "C009",
+      "severity": "info",
+      "title": "24 auto-memory file(s) not yet imported",
+      "detail": "~/.claude/projects/<slug>/memory/*.md files contain durable knowledge that isn't reachable via memory.recall until imported. AutoMemoryMirror only surfaces them transiently at SessionStart.",
+      "suggestion": "Preview: claude-memory import-auto-memory --dry-run. Import: claude-memory import-auto-memory.",
+      "fact_ids": []
+    }
+  ]
+}

data/docs/soak/audit_2026-06-03_agentic.json

@@ -0,0 +1,31 @@
+{
+  "ok": true,
+  "checks_run": 10,
+  "counts": {
+    "error": 0,
+    "warn": 1,
+    "info": 0
+  },
+  "stats": {
+    "global": {
+      "active_facts": 4,
+      "predicate_counts": {
+        "convention": 4
+      }
+    },
+    "project": {
+      "active_facts": 0,
+      "predicate_counts": {}
+    }
+  },
+  "findings": [
+    {
+      "id": "C008",
+      "severity": "warn",
+      "title": "Only 0 active project fact(s)",
+      "detail": "A nearly-empty project DB suggests either a fresh install (ignore) OR a broken ingest pipeline / overzealous rejection. Verify hooks are firing: claude-memory doctor.",
+      "suggestion": "claude-memory doctor; claude-memory stats; check .claude/settings.json hook configuration.",
+      "fact_ids": []
+    }
+  ]
+}

data/docs/soak/audit_2026-06-03_ai-software-architect.json

@@ -0,0 +1,19 @@
+{
+  "ok": true,
+  "checks_run": 10,
+  "counts": {
+    "error": 0,
+    "warn": 0,
+    "info": 0
+  },
+  "stats": {
+    "global": {
+      "active_facts": 4,
+      "predicate_counts": {
+        "convention": 4
+      }
+    },
+    "project": null
+  },
+  "findings": []
+}

data/docs/soak/audit_2026-06-03_chaos_to_the_rescue.json

@@ -0,0 +1,60 @@
+{
+  "ok": true,
+  "checks_run": 10,
+  "counts": {
+    "error": 0,
+    "warn": 1,
+    "info": 1
+  },
+  "stats": {
+    "global": {
+      "active_facts": 4,
+      "predicate_counts": {
+        "convention": 4
+      }
+    },
+    "project": {
+      "active_facts": 17,
+      "predicate_counts": {
+        "convention": 15,
+        "decision": 1,
+        "uses_framework": 1
+      }
+    }
+  },
+  "findings": [
+    {
+      "id": "C003",
+      "severity": "warn",
+      "title": "46 content items not yet deeply distilled",
+      "detail": "Backlog grows when SessionStart distillation prompts aren't acknowledged with memory.mark_distilled. A large backlog means the same text gets re-extracted across sessions, increasing hallucination rate.",
+      "suggestion": "Triage with /distill-transcripts (interactive) OR mark all distilled if you accept the backlog is noise: claude-memory sweep --mark-all-distilled",
+      "fact_ids": []
+    },
+    {
+      "id": "C007",
+      "severity": "info",
+      "title": "100% of decisions/conventions lack reason clauses (16/16)",
+      "detail": "Facts without 'because/so that/to avoid/...' lose their justification once context fades. Bare conclusions are dead weight when the team grows or you revisit a year later.",
+      "suggestion": "Inspect with: claude-memory explain <fact_id>. Reject low-value bare facts or rewrite with reason clauses via memory.store_extraction.",
+      "fact_ids": [
+        2,
+        3,
+        4,
+        5,
+        6,
+        7,
+        9,
+        10,
+        11,
+        12,
+        13,
+        14,
+        15,
+        16,
+        17,
+        18
+      ]
+    }
+  ]
+}

data/docs/soak/audit_2026-06-03_claude_memory.json

@@ -0,0 +1,55 @@
+{
+  "ok": true,
+  "checks_run": 10,
+  "counts": {
+    "error": 0,
+    "warn": 2,
+    "info": 1
+  },
+  "stats": {
+    "global": {
+      "active_facts": 4,
+      "predicate_counts": {
+        "convention": 4
+      }
+    },
+    "project": {
+      "active_facts": 67,
+      "predicate_counts": {
+        "convention": 41,
+        "reference": 7,
+        "architecture": 6,
+        "uses_language": 5,
+        "uses_framework": 4,
+        "decision": 3,
+        "uses_database": 1
+      }
+    }
+  },
+  "findings": [
+    {
+      "id": "C010",
+      "severity": "warn",
+      "title": "predicate=uses_database shows churn: 9 historical non-active facts",
+      "detail": "Repeated supersession/dispute on a single-cardinality predicate usually means a contamination source (e.g., example text in CLAUDE.md or docs) keeps re-introducing the same hallucination.",
+      "suggestion": "Find the contamination source: claude-memory recall <bad_value> --scope=project. Wrap the trigger text in <no-memory> tags. See docs/audit_runbook.md.",
+      "fact_ids": []
+    },
+    {
+      "id": "C010",
+      "severity": "warn",
+      "title": "predicate=deployment_platform shows churn: 9 historical non-active facts",
+      "detail": "Repeated supersession/dispute on a single-cardinality predicate usually means a contamination source (e.g., example text in CLAUDE.md or docs) keeps re-introducing the same hallucination.",
+      "suggestion": "Find the contamination source: claude-memory recall <bad_value> --scope=project. Wrap the trigger text in <no-memory> tags. See docs/audit_runbook.md.",
+      "fact_ids": []
+    },
+    {
+      "id": "C009",
+      "severity": "info",
+      "title": "1 auto-memory file(s) not yet imported",
+      "detail": "~/.claude/projects/<slug>/memory/*.md files contain durable knowledge that isn't reachable via memory.recall until imported. AutoMemoryMirror only surfaces them transiently at SessionStart.",
+      "suggestion": "Preview: claude-memory import-auto-memory --dry-run. Import: claude-memory import-auto-memory.",
+      "fact_ids": []
+    }
+  ]
+}

data/docs/soak/audit_2026-06-03_daily-vibe.json

@@ -0,0 +1,59 @@
+{
+  "ok": false,
+  "checks_run": 10,
+  "counts": {
+    "error": 1,
+    "warn": 0,
+    "info": 1
+  },
+  "stats": {
+    "global": {
+      "active_facts": 4,
+      "predicate_counts": {
+        "convention": 4
+      }
+    },
+    "project": {
+      "active_facts": 17,
+      "predicate_counts": {
+        "convention": 14,
+        "auth_method": 1,
+        "uses_database": 1,
+        "uses_framework": 1
+      }
+    }
+  },
+  "findings": [
+    {
+      "id": "C003",
+      "severity": "error",
+      "title": "160 content items not yet deeply distilled",
+      "detail": "Backlog grows when SessionStart distillation prompts aren't acknowledged with memory.mark_distilled. A large backlog means the same text gets re-extracted across sessions, increasing hallucination rate.",
+      "suggestion": "Triage with /distill-transcripts (interactive) OR mark all distilled if you accept the backlog is noise: claude-memory sweep --mark-all-distilled",
+      "fact_ids": []
+    },
+    {
+      "id": "C007",
+      "severity": "info",
+      "title": "100% of decisions/conventions lack reason clauses (14/14)",
+      "detail": "Facts without 'because/so that/to avoid/...' lose their justification once context fades. Bare conclusions are dead weight when the team grows or you revisit a year later.",
+      "suggestion": "Inspect with: claude-memory explain <fact_id>. Reject low-value bare facts or rewrite with reason clauses via memory.store_extraction.",
+      "fact_ids": [
+        3,
+        6,
+        7,
+        11,
+        12,
+        18,
+        19,
+        20,
+        21,
+        22,
+        23,
+        24,
+        25,
+        26
+      ]
+    }
+  ]
+}

data/docs/soak/audit_2026-06-03_minerva-sky.json

@@ -0,0 +1,19 @@
+{
+  "ok": true,
+  "checks_run": 10,
+  "counts": {
+    "error": 0,
+    "warn": 0,
+    "info": 0
+  },
+  "stats": {
+    "global": {
+      "active_facts": 4,
+      "predicate_counts": {
+        "convention": 4
+      }
+    },
+    "project": null
+  },
+  "findings": []
+}

data/docs/soak/audit_2026-06-03_nowreading.dev.json

@@ -0,0 +1,19 @@
+{
+  "ok": true,
+  "checks_run": 10,
+  "counts": {
+    "error": 0,
+    "warn": 0,
+    "info": 0
+  },
+  "stats": {
+    "global": {
+      "active_facts": 4,
+      "predicate_counts": {
+        "convention": 4
+      }
+    },
+    "project": null
+  },
+  "findings": []
+}

data/docs/soak/audit_2026-06-03_ups.dev.json

@@ -0,0 +1,55 @@
+{
+  "ok": false,
+  "checks_run": 10,
+  "counts": {
+    "error": 1,
+    "warn": 0,
+    "info": 1
+  },
+  "stats": {
+    "global": {
+      "active_facts": 4,
+      "predicate_counts": {
+        "convention": 4
+      }
+    },
+    "project": {
+      "active_facts": 15,
+      "predicate_counts": {
+        "convention": 13,
+        "decision": 1,
+        "uses_framework": 1
+      }
+    }
+  },
+  "findings": [
+    {
+      "id": "C003",
+      "severity": "error",
+      "title": "107 content items not yet deeply distilled",
+      "detail": "Backlog grows when SessionStart distillation prompts aren't acknowledged with memory.mark_distilled. A large backlog means the same text gets re-extracted across sessions, increasing hallucination rate.",
+      "suggestion": "Triage with /distill-transcripts (interactive) OR mark all distilled if you accept the backlog is noise: claude-memory sweep --mark-all-distilled",
+      "fact_ids": []
+    },
+    {
+      "id": "C007",
+      "severity": "info",
+      "title": "79% of decisions/conventions lack reason clauses (11/14)",
+      "detail": "Facts without 'because/so that/to avoid/...' lose their justification once context fades. Bare conclusions are dead weight when the team grows or you revisit a year later.",
+      "suggestion": "Inspect with: claude-memory explain <fact_id>. Reject low-value bare facts or rewrite with reason clauses via memory.store_extraction.",
+      "fact_ids": [
+        2,
+        3,
+        4,
+        5,
+        6,
+        8,
+        9,
+        10,
+        12,
+        14,
+        15
+      ]
+    }
+  ]
+}

data/docs/soak/baseline_2026-06-03.md

@@ -0,0 +1,145 @@
+# 0.12 Soak Baseline — 2026-06-03
+
+Day-0 audit snapshot taken across this repo plus three real-world projects that have used claude_memory at various points. Baseline for tracking memory-health drift through the 0.12 → 1.0 soak window (target ship ~2026-06-22 to 2026-07-01).
+
+## Day-0 hygiene pass (this repo only, 2026-06-03)
+
+Before locking in the baseline, ran a focused cleanup on `claude_memory`'s own memory state:
+
+1. **Rejected 9 auto-memory duplicates** (IDs 30, 31, 36, 81, 82, 87, 143, 144, 146) — older terse facts whose auto-memory-imported richer versions (in the 213/218/225/227/228/229/230/231 range) cover the same ground better.
+2. **Appended explicit reason clauses to 38 bare-conclusion facts** via single transactional SQL UPDATE — each fact's prose already implied a `because` / `so that` / `to avoid` / etc., the BareConclusionDetector just needs the literal marker. The appends are documented per-ID in `git log -p .claude/memory.sqlite3` (commit details).
+
+**Effect on `claude_memory` audit:**
+- C007 bare-conclusion ratio: **89% (47/53) → 0% (0/44)** ✅
+- Project active facts: 76 → 67 (the 9 dup rejects)
+- Audit `ok`: false → true (no errors, two C010 warnings remain as historical scar-tissue, one C009 info)
+
+Other projects were not touched — their bare-conclusion ratios (79–100%) remain as captured below and are the right reference points for measuring cross-project drift.
+
+Audit JSONs preserved at `docs/soak/audit_2026-06-03_<project>.json` so each can be diffed against future snapshots.
+
+## Installed gem state
+
+- `claude-memory --version` → **0.12.0**
+- Binary path: `/Users/valentinostoll/.gem/ruby/4.0.2/bin/claude-memory`
+- Every project's hooks resolve to the same global binary, so "upgrading" is a single `rake install` from `claude_memory/` — already done at release time.
+
+## Cross-project comparison (9 projects)
+
+Captured against installed gem **0.12.0**. Audit JSONs at `docs/soak/audit_2026-06-03_<project>.json`.
+
+| Project | OK | Err | Warn | Info | Active facts | Setup state | Notable findings |
+|---|---|---|---|---|---|---|---|
+| `claude_memory` | ✅ | 0 | 2 | 1 | 67 | full | Post Day-0 cleanup; **0% bare conclusions** (was 89%); 2 C010 historical-churn warns |
+| `agent-training-program` | ✅ | 0 | 0 | 2 | 27 | DB only | Post Day-0 cleanup; **35% bare** (was 100%); 24 unimported auto-memory files |
+| `nowreading.dev` | ✅ | 0 | 0 | 0 | 0 | none | No project DB; not in use |
+| `ups.dev` | ❌ | 1 | 0 | 1 | 15 | full | **107-item distillation backlog (C003)**; 79% bare |
+| `agentic` | ✅ | 0 | 1 | 0 | 0 | full | **C008 starvation** — DB exists with 0 active facts (rejected or never ingested) |
+| `ai-software-architect` | ✅ | 0 | 0 | 0 | 0 | settings only | Hooks configured, never received a session that wrote facts |
+| `chaos_to_the_rescue` | ✅ | 0 | 1 | 1 | 17 | DB only | **46-item distillation backlog (C003 warn)**; bare-conclusion ratio not flagged (clean? — needs spot check); no settings.json |
+| `daily-vibe` | ❌ | 1 | 0 | 1 | 17 | full | **160-item distillation backlog (C003 error)** — biggest in the set; 79% bare |
+| `minerva-sky` | ✅ | 0 | 0 | 0 | 0 | none | Never set up |
+
+All projects' global stores aligned at **4 active facts** (same `~/.claude/memory.sqlite3`).
+
+## Cross-project patterns (cleaner view with 9 projects)
+
+### Distillation backlog is structural, not project-specific
+
+Three of the six setups with project DBs have meaningful C003 backlogs:
+
+| Project | Backlog (undistilled items) |
+|---|---|
+| `daily-vibe` | **160** (Error) |
+| `ups.dev` | **107** (Error) |
+| `chaos_to_the_rescue` | 46 (Warn) |
+
+That's a cross-project signal: Layer-2 SessionStart context injection isn't catching up in projects with long-lived sessions and steady transcript intake. The injection only fires on fresh sessions (`startup` / `resume` / `clear` per `Hook::ContextInjector#fresh_session?`); long sessions without restart silently skip the distillation prompt indefinitely.
+
+**0.13 candidate:** add a CLI command (e.g. `claude-memory distill --drain` or similar) that processes undistilled items in batches without requiring an in-Claude-Code session, OR auto-trigger Layer-2 injection mid-session after N new content items accumulate. Without this, the backlog grows monotonically in any actively-used project.
+
+### Setup drift is a real failure mode
+
+Three out of six "set-up at some point" projects have partial/stale state:
+
+- `agent-training-program`, `chaos_to_the_rescue`: DB present, no `settings.json` — hooks aren't firing locally; the DB is frozen at the last point hooks ran.
+- `ai-software-architect`: `settings.json` present, no DB — hooks configured but never accumulated facts.
+
+Today the audit doesn't surface this — `claude-memory check-setup` MCP tool covers it, but it's not in the CLI audit. **0.13 candidate:** an audit check that flags the DB/settings-disagreement state.
+
+### Detector regex strictness (newly discovered)
+
+The C007 pass on `agent-training-program` exposed a detector blind spot. `BareConclusionDetector::REASON_PATTERNS` accepts `to avoid / prevent / ensure / support / allow / enable / make / fix / handle` — but rejects natural variants like `to keep / capture / preserve / match` even though those are equally valid causal phrasings. 7 of the 20 reason-clause appends on `agent-training-program` used non-accepted verbs and re-flagged. **0.13 candidate:** widen the regex (or move to a small embedding-based check) so the visibility signal isn't punishing valid reasoning.
+
+### C007 effect of the Day-0 cleanup
+
+| Project | Pre-cleanup | Post-cleanup |
+|---|---|---|
+| `claude_memory` | 89% (47/53) | **0% (0/44)** |
+| `agent-training-program` | 100% (24/24) | **35% (7/20)** |
+
+Untouched: `ups.dev` 79%, `daily-vibe` 79%, `chaos_to_the_rescue` (not flagged but worth a spot check). These remain reference points for measuring the bare-conclusion-rate drift over the soak window.
+
+## Cross-project patterns
+
+### Universal: bare-conclusion rate (C007)
+
+Every active project carries the long-tail of pre-0.11 facts without reason clauses:
+
+- `claude_memory`: 89% (47/53)
+- `agent-training-program`: **100%** (24/24)
+- `ups.dev`: 79% (11/14)
+
+The 0.11 reason-clause distillation prompt only protects *newly extracted* facts. Existing fact bases everywhere need either incremental rewrite or selective reject. This is the most awkward signal for the 1.0 visibility pillar.
+
+### Activation drift
+
+Two projects have `.claude/memory.sqlite3` but no `.claude/settings.json` — they were set up at some point and then drifted. Effect: hooks don't fire locally, so memory stops accumulating but the DB lingers. Worth a one-line `claude-memory init` to reactivate (or formal removal if abandoned).
+
+### Distillation backlog (`ups.dev`)
+
+107 content items ingested but never deeply distilled. Layer 2 (SessionStart context injection acting as distiller) isn't catching up. Two paths:
+
+1. Run `/distill-transcripts` in `ups.dev` to clear the backlog.
+2. Investigate why Layer 2 isn't keeping up — context-hook injection of pending items only fires on fresh sessions (`startup`/`resume`/`clear`); if `ups.dev` sessions are long-lived without restart, the prompt never appears.
+
+## What to watch during soak (per project)
+
+Re-run on a weekly cadence and diff against the 2026-06-03 baseline. Five-signal watch:
+
+| Signal | Tool | Threshold to investigate |
+|---|---|---|
+| Harm rate | `EVAL_MODE=real HARM_BENCH_RUNS=3 bundle exec rspec spec/benchmarks/e2e/harm_bench_spec.rb` (claude_memory repo only) | Any harm = patch before 1.0 |
+| Open conflicts | `claude-memory audit --json` per project | Any growing trend |
+| Bare-conclusion ratio | `audit` C007 | Worsens (the floor is "stays at current %") |
+| Distillation backlog (C003) | `audit` C003 | Grows in any project that was zero |
+| Active fact count drift | `audit.stats.project.active_facts` | Sudden spikes (re-contamination) or drops (mass reject) |
+
+## Suggested 0.12.x patch candidates (optional, not 1.0 blockers)
+
+- ✅ `claude_memory` C007 cleanup (done 2026-06-03).
+- ✅ `agent-training-program` C007 partial cleanup (done 2026-06-03; 100% → 35%; residual 7 facts blocked by detector regex strictness — see 0.13 candidate below).
+- `agent-training-program`: run `claude-memory import-auto-memory` once to drain the 24 pending auto-memory files. Fast win.
+- `agent-training-program` and `chaos_to_the_rescue`: re-add `.claude/settings.json` if the projects are still active, otherwise archive the DBs.
+- `ups.dev`, `daily-vibe`, `chaos_to_the_rescue`: distillation backlogs (107/160/46). `/distill-transcripts` is a Claude Code skill that runs *in-session* in each project — I can't invoke it from the `claude_memory` repo. Two paths: (a) open Claude Code in each affected project and run `/distill-transcripts`; (b) wait for the 0.13 CLI drain command (see 0.13 candidates below).
+- `agentic` C008 starvation: DB has 0 active facts despite settings.json being configured. Either no Claude Code sessions have written facts there yet, or all facts have been rejected. Investigate when convenient.
+- `nowreading.dev`, `minerva-sky`: decide — initialize with claude_memory or accept "untouched" as the steady state.
+
+## 0.13 candidates surfaced by this cross-project audit
+
+1. **Drainable distillation backlog.** Add a CLI command that processes undistilled content items without requiring a fresh Claude Code session, or trigger Layer-2 injection mid-session when the backlog exceeds N items. The current Layer-2 path only fires on `fresh_session?` (startup/resume/clear), so long-lived sessions silently accrue backlog forever. Most impactful 0.13 item per the cross-project signal — 3 of 6 active-setup projects are affected, one with 160 items.
+2. **Setup-drift audit check.** New C-code check that compares `.claude/memory.sqlite3` presence against `.claude/settings.json` presence and flags the disagreement state. Three of nine projects today have one without the other.
+3. **Widen `BareConclusionDetector::REASON_PATTERNS`.** Accept `to keep / capture / preserve / match / record / track / store / serve / protect / safeguard` (and similar) — the current allowlist is too narrow and punishes natural reasoning. Surfaced when 7 of 20 honest reason-clause appends on `agent-training-program` failed the regex even though each contained valid causal language.
+4. **Cross-project audit aggregation.** A `claude-memory audit --multi <dir>...` mode that runs the audit across N projects and emits one comparison table. The Day-0 baseline doc had to be assembled by hand; should be automated by 1.0 if cross-project soak comparisons are going to be a recurring practice.
+
+## Reproducing this snapshot
+
+```bash
+mkdir -p docs/soak
+./exe/claude-memory audit --json --no-exit > docs/soak/audit_<DATE>_claude_memory.json
+(cd ../agent-training-program && claude-memory audit --json --no-exit) > docs/soak/audit_<DATE>_agent-training-program.json
+(cd ../nowreading.dev          && claude-memory audit --json --no-exit) > docs/soak/audit_<DATE>_nowreading.dev.json
+(cd ../ups.dev                 && claude-memory audit --json --no-exit) > docs/soak/audit_<DATE>_ups.dev.json
+```
+
+Diff against this baseline with `jq` or any JSON diff tool of choice.

data/lib/claude_memory/commands/checks/embeddings_check.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    module Checks
+      # Surfaces the active embedding provider, model, and dimension
+      # alignment between provider and stored vectors.
+      #
+      # Doctor previously had VecCheck (sqlite-vec extension + index
+      # coverage) but no signal about which provider was actually in use —
+      # so a user could see "sqlite-vec available ✓" while silently
+      # running on tfidf default when fastembed was loadable. This check
+      # closes that visibility gap and points users at
+      # `claude-memory setup-vectors` to opt into fastembed.
+      class EmbeddingsCheck
+        FASTEMBED_HINT = "Set CLAUDE_MEMORY_EMBEDDING_PROVIDER=fastembed for higher-quality semantic recall (fastembed is loadable on this system). " \
+          "Run 'claude-memory setup-vectors' to configure."
+
+        FASTEMBED_INSTALL_HINT = "fastembed is not installed; semantic recall is using tfidf (lower quality). " \
+          "Run 'claude-memory setup-vectors' to install fastembed and switch."
+
+        def call
+          provider = Embeddings.resolve
+          provider_name = provider.name
+          warnings = []
+
+          # Hint when user is on default tfidf — different message
+          # depending on whether fastembed is even loadable.
+          if provider_name == "tfidf"
+            warnings << (fastembed_loadable? ? FASTEMBED_HINT : FASTEMBED_INSTALL_HINT)
+          end
+
+          dim_mismatches = check_dimension_alignment(provider)
+          warnings.concat(dim_mismatches)
+
+          {
+            status: warnings.any? ? :warning : :ok,
+            label: "embeddings",
+            message: "Embedding provider: #{provider_name}, dimensions: #{provider.dimensions}",
+            details: {
+              provider: provider_name,
+              dimensions: provider.dimensions,
+              fastembed_loadable: fastembed_loadable?
+            },
+            warnings: warnings
+          }
+        rescue => e
+          {
+            status: :warning,
+            label: "embeddings",
+            message: "Embedding provider check failed: #{e.message}",
+            details: {},
+            warnings: []
+          }
+        end
+
+        private
+
+        def fastembed_loadable?
+          return @fastembed_loadable if defined?(@fastembed_loadable)
+          @fastembed_loadable = begin
+            require "fastembed"
+            true
+          rescue LoadError
+            false
+          end
+        end
+
+        def check_dimension_alignment(provider)
+          config = Configuration.new
+          mismatches = []
+
+          [config.global_db_path, config.project_db_path].each do |db_path|
+            next unless File.exist?(db_path)
+
+            store = nil
+            begin
+              store = Store::SQLiteStore.new(db_path)
+              result = Embeddings::DimensionCheck.call(store, provider)
+              next unless result.status == :mismatch
+
+              mismatches << "Dimension mismatch in #{File.basename(File.dirname(db_path))} DB: " \
+                "stored=#{result.stored} but current provider produces #{result.current}. " \
+                "Run 'claude-memory index --force' to re-embed under the current provider."
+            rescue => e
+              ClaudeMemory.logger.debug("EmbeddingsCheck dimension check failed for #{db_path}: #{e.message}")
+            ensure
+              store&.close
+            end
+          end
+
+          mismatches
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/doctor_command.rb

@@ -23,6 +23,7 @@ module ClaudeMemory
           Checks::DistillCheck.new(manager.global_db_path, "global"),
           Checks::DistillCheck.new(manager.project_db_path, "project"),
           Checks::VecCheck.new,
+          Checks::EmbeddingsCheck.new,
           Checks::SnapshotCheck.new,
           Checks::ClaudeMdCheck.new,
           Checks::HooksCheck.new

data/lib/claude_memory/commands/registry.rb

@@ -45,6 +45,7 @@ module ClaudeMemory
         "digest" => {class: DigestCommand, description: "Render a weekly markdown digest of memory activity"},
         "show" => {class: ShowCommand, description: "Print what memory would inject at the next SessionStart"},
         "otel" => {class: OtelCommand, description: "Configure or inspect OpenTelemetry ingestion from Claude Code"},
+        "setup-vectors" => {class: SetupVectorsCommand, description: "Opt into vector recall — write provider env to .claude/settings.json + re-index"},
         "import-auto-memory" => {class: ImportAutoMemoryCommand, description: "Import Claude Code auto-memory .md files into project DB as facts"},
         "audit" => {class: AuditCommand, description: "Run memory health audit; report inconsistencies and optimizations"}
       }.freeze

data/lib/claude_memory/commands/setup_vectors_command.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "optparse"
+
+module ClaudeMemory
+  module Commands
+    # Guides the user through opting into vector recall with fastembed
+    # (or another provider). fastembed stays a dev/test gem dependency by
+    # design; this command is the documented opt-in path for end users.
+    #
+    # Steps:
+    #   1. Verify the chosen provider is loadable. For fastembed, surface
+    #      a clear install command if the gem isn't on $LOAD_PATH.
+    #   2. Persist CLAUDE_MEMORY_EMBEDDING_PROVIDER (and optional model)
+    #      into the project's .claude/settings.json env block, the same
+    #      mechanism Claude Code uses for OTel env (see OTel::SettingsWriter).
+    #   3. Re-embed existing facts under the new provider (unless --no-reindex).
+    #   4. Report the final state — provider, dimensions, stored alignment.
+    class SetupVectorsCommand < BaseCommand
+      OWNED_KEYS = %w[
+        CLAUDE_MEMORY_EMBEDDING_PROVIDER
+        CLAUDE_MEMORY_EMBEDDING_MODEL
+      ].freeze
+
+      FASTEMBED_INSTALL_HINT = <<~HINT
+        fastembed is not installed. claude-memory keeps fastembed as a
+        dev/test dependency so the default gem install stays light. To
+        enable it, install the gem and re-run setup-vectors:
+
+          gem install fastembed
+          claude-memory setup-vectors
+
+        Or if you bundle, add to your Gemfile:
+
+          gem "fastembed"
+
+        Then `bundle install` and re-run setup-vectors. The first run
+        downloads the BAAI/bge-small-en-v1.5 ONNX model (~75MB).
+      HINT
+
+      def call(args)
+        opts = parse_opts(args)
+        return 1 if opts.nil?
+
+        return print_status if opts[:status]
+
+        provider_name = opts[:provider]
+        unless verify_provider_loadable(provider_name)
+          return 1
+        end
+
+        if opts[:dry_run]
+          stdout.puts "Would write to #{settings_path}:"
+          stdout.puts "  CLAUDE_MEMORY_EMBEDDING_PROVIDER=#{provider_name}"
+          stdout.puts "  CLAUDE_MEMORY_EMBEDDING_MODEL=#{opts[:model]}" if opts[:model]
+          stdout.puts(opts[:reindex] ? "Would re-index facts under the new provider" : "Would skip re-index (--no-reindex)")
+          return 0
+        end
+
+        write_settings(provider_name, opts[:model])
+
+        if opts[:reindex]
+          reindex_result = reindex(provider_name)
+          return 1 if reindex_result != 0
+        else
+          stdout.puts "Skipped re-index (--no-reindex). Run 'claude-memory index --force --provider=#{provider_name}' when ready."
+        end
+
+        report_final_state(provider_name)
+        0
+      end
+
+      private
+
+      def parse_opts(args)
+        options = {provider: "fastembed", model: nil, reindex: true, dry_run: false, status: false}
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: claude-memory setup-vectors [--provider=fastembed|api|tfidf] [--model=NAME] [--no-reindex] [--dry-run] [--status]"
+          o.on("--provider NAME", "Embedding provider (default: fastembed)") { |v| options[:provider] = v }
+          o.on("--model NAME", "Optional model name (e.g. BAAI/bge-small-en-v1.5)") { |v| options[:model] = v }
+          o.on("--no-reindex", "Skip re-embedding existing facts under the new provider") { options[:reindex] = false }
+          o.on("--dry-run", "Print what would change without writing or re-indexing") { options[:dry_run] = true }
+          o.on("--status", "Show the current provider config + stored alignment, then exit") { options[:status] = true }
+        end
+        parser.parse!(args.dup)
+        options
+      rescue OptionParser::InvalidOption => e
+        stderr.puts e.message
+        nil
+      end
+
+      def verify_provider_loadable(provider_name)
+        case provider_name
+        when "tfidf"
+          true # always available
+        when "fastembed"
+          require "fastembed"
+          true
+        when "api"
+          # api provider needs network + key but no gem; defer to runtime
+          true
+        else
+          stderr.puts "Unknown provider: #{provider_name}. Valid: tfidf, fastembed, api."
+          false
+        end
+      rescue LoadError
+        stderr.puts FASTEMBED_INSTALL_HINT
+        false
+      end
+
+      def settings_path
+        File.join(claude_dir, "settings.json")
+      end
+
+      def claude_dir
+        File.join(Configuration.new.project_dir, ".claude")
+      end
+
+      def write_settings(provider_name, model)
+        FileUtils.mkdir_p(claude_dir)
+        settings = load_settings
+        settings["env"] ||= {}
+        settings["env"]["CLAUDE_MEMORY_EMBEDDING_PROVIDER"] = provider_name
+        if model
+          settings["env"]["CLAUDE_MEMORY_EMBEDDING_MODEL"] = model
+        else
+          settings["env"].delete("CLAUDE_MEMORY_EMBEDDING_MODEL")
+        end
+        File.write(settings_path, JSON.pretty_generate(settings) + "\n")
+        stdout.puts "✓ Wrote CLAUDE_MEMORY_EMBEDDING_PROVIDER=#{provider_name} to #{settings_path}"
+        stdout.puts "✓ Wrote CLAUDE_MEMORY_EMBEDDING_MODEL=#{model}" if model
+      end
+
+      def load_settings
+        return {} unless File.exist?(settings_path)
+        raw = File.read(settings_path)
+        return {} if raw.strip.empty?
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError => e
+        stderr.puts "settings.json parse error: #{e.message} — refusing to overwrite"
+        {}
+      end
+
+      def reindex(provider_name)
+        stdout.puts "→ Re-embedding facts under provider=#{provider_name}…"
+        IndexCommand.new(stdout: stdout, stderr: stderr).call(["--force", "--provider", provider_name])
+      end
+
+      def report_final_state(provider_name)
+        # The settings.json write only affects future sessions (Claude Code
+        # reads the env block at session start). For the current process
+        # the ENV var isn't set, so report what Embeddings.resolve would
+        # produce under the new env.
+        env_override = ENV.to_h.merge("CLAUDE_MEMORY_EMBEDDING_PROVIDER" => provider_name)
+        provider = Embeddings.resolve(provider_name, env: env_override)
+        stdout.puts
+        stdout.puts "Provider: #{provider.name}, dimensions: #{provider.dimensions}"
+        stdout.puts "Next session will use this provider. Run 'claude-memory doctor' to verify."
+      end
+
+      def print_status
+        # Resolve under current ENV to show what the next session will use
+        provider = Embeddings.resolve
+        stdout.puts "Current provider:   #{provider.name}"
+        stdout.puts "Current dimensions: #{provider.dimensions}"
+        stdout.puts "Settings file:      #{settings_path}"
+        env = load_settings.fetch("env", {})
+        relevant = env.slice(*OWNED_KEYS)
+        if relevant.any?
+          stdout.puts "Configured env:"
+          relevant.each { |k, v| stdout.puts "  #{k}=#{v}" }
+        else
+          stdout.puts "Configured env:     (none — using default tfidf)"
+        end
+        0
+      end
+    end
+  end
+end

data/lib/claude_memory/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeMemory
-  VERSION = "0.12.0"
+  VERSION = "0.12.1"
 end

data/lib/claude_memory.rb

@@ -38,6 +38,7 @@ require_relative "claude_memory/commands/checks/claude_md_check"
 require_relative "claude_memory/commands/checks/hooks_check"
 require_relative "claude_memory/commands/checks/reporter"
 require_relative "claude_memory/commands/checks/vec_check"
+require_relative "claude_memory/commands/checks/embeddings_check"
 require_relative "claude_memory/commands/checks/distill_check"
 require_relative "claude_memory/commands/help_command"
 require_relative "claude_memory/commands/version_command"
@@ -102,6 +103,7 @@ require_relative "claude_memory/dashboard/server"
 require_relative "claude_memory/commands/digest_command"
 require_relative "claude_memory/commands/show_command"
 require_relative "claude_memory/commands/otel_command"
+require_relative "claude_memory/commands/setup_vectors_command"
 require_relative "claude_memory/commands/import_auto_memory_command"
 require_relative "claude_memory/audit/finding"
 require_relative "claude_memory/audit/checks"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_memory
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.12.1
 platform: ruby
 authors:
 - Valentino Stoll
@@ -186,6 +186,16 @@ files:
 - docs/quality_review.md
 - docs/reflection_memory_as_accumulating_judgment.md
 - docs/review_summary.md
+- docs/soak/audit_2026-06-03_agent-training-program.json
+- docs/soak/audit_2026-06-03_agentic.json
+- docs/soak/audit_2026-06-03_ai-software-architect.json
+- docs/soak/audit_2026-06-03_chaos_to_the_rescue.json
+- docs/soak/audit_2026-06-03_claude_memory.json
+- docs/soak/audit_2026-06-03_daily-vibe.json
+- docs/soak/audit_2026-06-03_minerva-sky.json
+- docs/soak/audit_2026-06-03_nowreading.dev.json
+- docs/soak/audit_2026-06-03_ups.dev.json
+- docs/soak/baseline_2026-06-03.md
 - exe/claude-memory
 - hooks/hooks.json
 - lefthook.yml
@@ -202,6 +212,7 @@ files:
 - lib/claude_memory/commands/checks/claude_md_check.rb
 - lib/claude_memory/commands/checks/database_check.rb
 - lib/claude_memory/commands/checks/distill_check.rb
+- lib/claude_memory/commands/checks/embeddings_check.rb
 - lib/claude_memory/commands/checks/hooks_check.rb
 - lib/claude_memory/commands/checks/reporter.rb
 - lib/claude_memory/commands/checks/snapshot_check.rb
@@ -242,6 +253,7 @@ files:
 - lib/claude_memory/commands/restore_command.rb
 - lib/claude_memory/commands/search_command.rb
 - lib/claude_memory/commands/serve_mcp_command.rb
+- lib/claude_memory/commands/setup_vectors_command.rb
 - lib/claude_memory/commands/show_command.rb
 - lib/claude_memory/commands/skills/distill-transcripts.md
 - lib/claude_memory/commands/skills/memory-recall.md