claude_memory 0.12.0 → 0.13.0

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/audit/checks.rb

@@ -226,6 +226,155 @@ module ClaudeMemory
         end
       end
 
+      # Scopes whose stores carry an observations table. Observation checks
+      # iterate both DBs because observations may be project- or global-scoped.
+      OBSERVATION_SCOPES = %i[project global].freeze
+
+      # Valid observation lifecycle states. Anything else means a writer or
+      # migration stamped a status the resolver/reflector never produce.
+      OBSERVATION_STATUSES = %w[active consolidated expired].freeze
+
+      def observation_stores(manager)
+        OBSERVATION_SCOPES
+          .map { |scope| [scope, manager.store_if_exists(scope.to_s)] }
+          .reject { |_, store| store.nil? }
+      end
+
+      # C011 — Orphaned observations (provenance points at a missing content item).
+      def orphaned_observations(manager)
+        observation_stores(manager).flat_map do |scope, store|
+          content_ids = store.content_items.select(:id)
+          orphans = store.observations
+            .exclude(source_content_item_id: nil)
+            .exclude(source_content_item_id: content_ids)
+            .select(:id)
+            .all
+          next [] if orphans.empty?
+
+          [Finding.new(
+            id: "C011",
+            severity: :warn,
+            title: "#{orphans.size} observation(s) in #{scope} DB reference a missing content item",
+            detail: "An observation's source_content_item_id should point at the content_items row it was distilled from. A dangling pointer means the source row was pruned or never existed, so the observation's provenance can no longer be explained.",
+            suggestion: "Inspect with memory.observations. These rows are append-only; if the provenance is unrecoverable, consolidate or expire them via the Reflector (PreCompact/SessionEnd) rather than deleting.",
+            fact_ids: orphans.map { |r| r[:id] }
+          )]
+        end
+      end
+
+      # C012 — Promotion consistency (promoted_at ⇔ promoted_fact_id, fact must exist + be active).
+      def observation_promotion_consistency(manager)
+        observation_stores(manager).flat_map do |scope, store|
+          active_fact_ids = store.facts.where(status: "active").select(:id)
+
+          missing_fact_id = store.observations
+            .exclude(promoted_at: nil)
+            .where(promoted_fact_id: nil)
+            .select(:id).all
+          dangling_fact = store.observations
+            .exclude(promoted_fact_id: nil)
+            .exclude(promoted_fact_id: store.facts.select(:id))
+            .select(:id, :promoted_fact_id).all
+          inactive_fact = store.observations
+            .exclude(promoted_fact_id: nil)
+            .exclude(promoted_fact_id: active_fact_ids)
+            .exclude(promoted_fact_id: dangling_fact.map { |r| r[:promoted_fact_id] })
+            .select(:id, :promoted_fact_id).all
+          missing_timestamp = store.observations
+            .exclude(promoted_fact_id: nil)
+            .where(promoted_at: nil)
+            .select(:id).all
+
+          obs_ids = (missing_fact_id + dangling_fact + inactive_fact + missing_timestamp).map { |r| r[:id] }.uniq
+          next [] if obs_ids.empty?
+
+          problems = []
+          problems << "#{missing_fact_id.size} promoted but missing promoted_fact_id" unless missing_fact_id.empty?
+          problems << "#{dangling_fact.size} promoted_fact_id pointing at a non-existent fact" unless dangling_fact.empty?
+          problems << "#{inactive_fact.size} promoted into a non-active fact" unless inactive_fact.empty?
+          problems << "#{missing_timestamp.size} have promoted_fact_id but no promoted_at" unless missing_timestamp.empty?
+
+          [Finding.new(
+            id: "C012",
+            severity: :error,
+            title: "#{obs_ids.size} observation(s) in #{scope} DB have inconsistent promotion state",
+            detail: "Promotion must be atomic: a promoted observation has both promoted_at set and promoted_fact_id pointing at an existing, active fact. Violations (#{problems.join("; ")}) mean mark_observation_promoted ran partially or the target fact was later rejected/superseded, leaving the observation pointing at nothing usable.",
+            suggestion: "Inspect the fact with claude-memory explain <fact_id>. If the fact was intentionally rejected, the observation should be re-opened for re-promotion via memory.promote_observation; if mark_observation_promoted half-ran, re-run promotion.",
+            fact_ids: obs_ids
+          )]
+        end
+      end
+
+      # C013 — Tombstone-chain validity (consolidated_into must point to a real,
+      # non-self row and a consolidated observation must not stay active).
+      def observation_tombstone_chain(manager)
+        observation_stores(manager).flat_map do |scope, store|
+          obs_ids = store.observations.select(:id)
+
+          dangling = store.observations
+            .exclude(consolidated_into: nil)
+            .exclude(consolidated_into: obs_ids)
+            .select(:id, :consolidated_into).all
+          self_link = store.observations
+            .exclude(consolidated_into: nil)
+            .where(Sequel[:consolidated_into] => Sequel[:id])
+            .select(:id).all
+          active_but_tombstoned = store.observations
+            .exclude(consolidated_into: nil)
+            .where(status: "active")
+            .select(:id).all
+          consolidated_without_link = store.observations
+            .where(status: "consolidated", consolidated_into: nil)
+            .select(:id).all
+
+          flagged = (dangling + self_link + active_but_tombstoned + consolidated_without_link).map { |r| r[:id] }.uniq
+          next [] if flagged.empty?
+
+          problems = []
+          problems << "#{dangling.size} consolidated_into → missing observation" unless dangling.empty?
+          problems << "#{self_link.size} consolidated_into self-link" unless self_link.empty?
+          problems << "#{active_but_tombstoned.size} active yet have a consolidated_into target" unless active_but_tombstoned.empty?
+          problems << "#{consolidated_without_link.size} status=consolidated with no consolidated_into keeper" unless consolidated_without_link.empty?
+
+          [Finding.new(
+            id: "C013",
+            severity: :error,
+            title: "#{flagged.size} observation(s) in #{scope} DB have a broken tombstone chain",
+            detail: "Tombstoning is append-only: a superseded observation gets status=consolidated and consolidated_into pointing at the surviving keeper. Violations (#{problems.join("; ")}) corrupt the lineage — recall could surface a tombstoned row, or a consolidated row could orphan its history.",
+            suggestion: "Inspect with memory.observations. Re-run the deterministic Reflector (fires on PreCompact/SessionEnd) to re-derive consolidation; a self-link or active+tombstoned row indicates a Reflector bug — file it rather than hand-editing the append-only table.",
+            fact_ids: flagged
+          )]
+        end
+      end
+
+      # C014 — Status / corroboration sanity (known status set, corroboration ≥ 1).
+      def observation_status_corroboration(manager)
+        observation_stores(manager).flat_map do |scope, store|
+          bad_status = store.observations
+            .exclude(status: OBSERVATION_STATUSES)
+            .select(:id).all
+          bad_corroboration = store.observations
+            .where { corroboration_count < 1 }
+            .select(:id).all
+
+          flagged = (bad_status + bad_corroboration).map { |r| r[:id] }.uniq
+          next [] if flagged.empty?
+
+          problems = []
+          problems << "#{bad_status.size} with status outside #{OBSERVATION_STATUSES.inspect}" unless bad_status.empty?
+          problems << "#{bad_corroboration.size} with corroboration_count < 1" unless bad_corroboration.empty?
+
+          [Finding.new(
+            id: "C014",
+            severity: :warn,
+            title: "#{flagged.size} observation(s) in #{scope} DB have invalid status/corroboration",
+            detail: "Every observation should carry a known lifecycle status (#{OBSERVATION_STATUSES.join("/")}) and at least one sighting (corroboration_count ≥ 1; a fresh insert counts as 1). Violations (#{problems.join("; ")}) break the promotion gate (which keys off corroboration) and the recall filters (which key off status).",
+            suggestion: "Inspect with memory.observations. A corroboration_count < 1 means increment_corroboration math went negative; an unknown status means a migration or external writer bypassed insert_observation. Re-derive via the Reflector if possible.",
+            fact_ids: flagged
+          )]
+        end
+      end
+
       def normalize_convention(text)
         text.to_s
           .downcase

data/lib/claude_memory/audit/runner.rb

@@ -20,6 +20,10 @@ module ClaudeMemory
         bare_conclusion_rate
         project_starvation
         auto_memory_unimported
+        orphaned_observations
+        observation_promotion_consistency
+        observation_tombstone_chain
+        observation_status_corroboration
       ].freeze
 
       Result = Data.define(:findings, :stats) do

data/lib/claude_memory/commands/census_command.rb

@@ -138,7 +138,7 @@ module ClaudeMemory
 
         predicates = db[:facts].select(:predicate, :status).group_and_count(:predicate, :status).all
           .each_with_object(Hash.new { |h, k| h[k] = Hash.new(0) }) do |row, acc|
-            acc[row[:predicate].to_s][row[:status].to_s] += row[:count].to_i
+          acc[row[:predicate].to_s][row[:status].to_s] += row[:count].to_i
         end
 
         entity_types = db[:entities].group_and_count(:type).all.each_with_object(Hash.new(0)) do |row, acc|

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