claude_memory 0.11.0 → 0.12.1

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

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Audit
+    # Individual audit checks. Each method takes a Store::StoreManager and
+    # returns an Array<Finding>. Checks must be read-only — write
+    # operations belong in dedicated commands the user opts into.
+    #
+    # Adding a new check:
+    #   1. Define a method here with an explicit C### id assignment.
+    #   2. Append the method name to Runner::CHECK_METHODS.
+    #   3. Document it in docs/audit_runbook.md.
+    module Checks
+      module_function
+
+      # C001 — Open conflicts in either DB.
+      def open_conflicts(manager)
+        findings = []
+        {project: manager.store_if_exists("project"), global: manager.store_if_exists("global")}.each do |scope, store|
+          next unless store
+          conflicts = store.open_conflicts
+          next if conflicts.empty?
+          findings << Finding.new(
+            id: "C001",
+            severity: :error,
+            title: "#{conflicts.size} open conflict(s) in #{scope} DB",
+            detail: "Open conflicts indicate unresolved single-cardinality disputes. Each will keep re-firing until the losing fact is rejected.",
+            suggestion: "claude-memory conflicts && claude-memory reject <fact_id>",
+            fact_ids: conflicts.flat_map { |c| [c[:fact_a_id], c[:fact_b_id]] }.uniq
+          )
+        end
+        findings
+      end
+
+      # C002 — Single-cardinality predicates with > 1 active fact.
+      SINGLE_CARDINALITY_PREDICATES = %w[uses_database deployment_platform auth_method].freeze
+
+      def single_cardinality_multiplicity(manager)
+        store = manager.store_if_exists("project")
+        return [] unless store
+
+        SINGLE_CARDINALITY_PREDICATES.flat_map do |predicate|
+          rows = store.facts.where(status: "active", predicate: predicate).all
+          next [] if rows.size <= 1
+          [Finding.new(
+            id: "C002",
+            severity: :error,
+            title: "predicate=#{predicate} has #{rows.size} active facts (single-cardinality)",
+            detail: "Single-cardinality predicates must have at most one active value. Multiple actives mean resolver dropped a supersession or distillation produced contradictory claims.",
+            suggestion: "Inspect with: claude-memory explain <fact_id>. Reject the wrong ones: claude-memory reject <fact_id>",
+            fact_ids: rows.map { |r| r[:id] }
+          )]
+        end
+      end
+
+      # C003 — Distillation backlog (warn ≥ 25, error ≥ 100).
+      def distillation_backlog(manager)
+        store = manager.store_if_exists("project")
+        return [] unless store
+        distilled_ids = store.ingestion_metrics.select(:content_item_id).distinct
+        pending = store.content_items.exclude(id: distilled_ids).count
+        return [] if pending < 25
+
+        severity = (pending >= 100) ? :error : :warn
+        [Finding.new(
+          id: "C003",
+          severity: severity,
+          title: "#{pending} 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: []
+        )]
+      end
+
+      # C004 — memory.decisions leaking non-decision predicates.
+      def shortcut_decision_leak(manager)
+        results = Shortcuts.decisions(manager, limit: 50)
+        leaked = results.map { |r| r[:fact][:predicate] }.uniq - ["decision"]
+        return [] if leaked.empty?
+
+        [Finding.new(
+          id: "C004",
+          severity: :error,
+          title: "memory.decisions returns non-decision predicates: #{leaked.inspect}",
+          detail: "memory.decisions should return only `decision`-predicate facts. Predicate leakage suggests the shortcut implementation has regressed back to text-search filtering (pre-2026-05-21 audit).",
+          suggestion: "Inspect lib/claude_memory/shortcuts.rb — SHORTCUTS[:decisions][:predicates] should equal ['decision']. Run `bundle exec rspec spec/claude_memory/shortcuts_spec.rb`.",
+          fact_ids: results.select { |r| leaked.include?(r[:fact][:predicate]) }.map { |r| r[:fact][:id] }
+        )]
+      end
+
+      # C005 — memory.conventions returns no project facts despite project conventions existing.
+      def shortcut_convention_scope(manager)
+        project_store = manager.store_if_exists("project")
+        return [] unless project_store
+        project_count = project_store.facts.where(status: "active", predicate: "convention").count
+        return [] if project_count.zero?
+
+        results = Shortcuts.conventions(manager, limit: 50)
+        project_returned = results.count { |r| r[:source] == "project" }
+        return [] if project_returned > 0
+
+        [Finding.new(
+          id: "C005",
+          severity: :warn,
+          title: "memory.conventions returned 0 project facts despite #{project_count} project conventions existing",
+          detail: "Pre-2026-05-21 audit, memory.conventions was hardcoded to scope=global. If you're seeing 0 project facts in a project with conventions, the shortcut has regressed.",
+          suggestion: "Check Shortcuts.collect_facts in lib/claude_memory/shortcuts.rb. Re-run `bundle exec rspec spec/claude_memory/shortcuts_spec.rb`.",
+          fact_ids: []
+        )]
+      end
+
+      # C006 — Duplicate global convention candidates (near-identical text).
+      def duplicate_global_conventions(manager)
+        store = manager.store_if_exists("global")
+        return [] unless store
+        rows = store.facts.where(status: "active", predicate: "convention").select(:id, :object_literal).all
+        return [] if rows.size < 2
+
+        # Group by normalized object text (lowercased, stripped of leading
+        # "uses"/"prefers"/punctuation). Pairs with the same normalized
+        # key are likely near-duplicates.
+        groups = rows.group_by { |r| normalize_convention(r[:object_literal]) }
+        dupe_groups = groups.select { |_, list| list.size > 1 }
+        return [] if dupe_groups.empty?
+
+        [Finding.new(
+          id: "C006",
+          severity: :info,
+          title: "#{dupe_groups.size} near-duplicate global convention group(s)",
+          detail: "Multiple global conventions normalize to the same phrasing. Pick the cleanest and reject the rest to keep memory.conventions output tight.",
+          suggestion: "Review with: claude-memory recall <concept> --scope=global. Reject duplicates: claude-memory reject <fact_id>",
+          fact_ids: dupe_groups.values.flatten.map { |r| r[:id] }
+        )]
+      end
+
+      # C007 — Bare-conclusion decisions/conventions (no reason clause).
+      def bare_conclusion_rate(manager)
+        store = manager.store_if_exists("project")
+        return [] unless store
+        detector = Distill::BareConclusionDetector.new
+        rows = store.facts.where(status: "active", predicate: %w[decision convention]).select(:id, :predicate, :object_literal).all
+        bare = rows.select { |r| detector.bare_conclusion?(predicate: r[:predicate], object_literal: r[:object_literal]) }
+        return [] if bare.empty?
+
+        ratio = bare.size.to_f / rows.size
+        return [] if ratio < 0.3
+
+        [Finding.new(
+          id: "C007",
+          severity: :info,
+          title: "#{(ratio * 100).round}% of decisions/conventions lack reason clauses (#{bare.size}/#{rows.size})",
+          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: bare.map { |r| r[:id] }
+        )]
+      end
+
+      # C008 — Project DB starvation (< 5 active facts may indicate broken ingest).
+      def project_starvation(manager)
+        store = manager.store_if_exists("project")
+        return [] unless store
+        count = store.facts.where(status: "active").count
+        return [] if count >= 5
+
+        [Finding.new(
+          id: "C008",
+          severity: :warn,
+          title: "Only #{count} 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: []
+        )]
+      end
+
+      # C009 — Auto-memory drift (markdown files newer than project DB facts).
+      def auto_memory_unimported(manager)
+        config = Configuration.new
+        dir = Hook::AutoMemoryMirror.default_dir(config.project_dir, config.claude_config_dir)
+        return [] unless Dir.exist?(dir)
+
+        md_files = Dir.glob(File.join(dir, "*.md")).reject { |f| File.basename(f) == "MEMORY.md" }
+        return [] if md_files.empty?
+
+        store = manager.store_if_exists("project")
+        return [] unless store
+
+        # Look for auto_memory_import content items as evidence of prior
+        # import. Count files that would be new on the next import.
+        imported_count = store.content_items.where(source: "auto_memory_import").count
+        net_new = md_files.size - imported_count
+        return [] if net_new <= 0
+
+        [Finding.new(
+          id: "C009",
+          severity: :info,
+          title: "#{net_new} 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: []
+        )]
+      end
+
+      # C010 — Recurring single-cardinality churn (history shows the same
+      # predicate has accumulated many superseded/disputed facts — sign of
+      # a persistent contamination source).
+      CHURN_THRESHOLD = 5
+
+      def single_cardinality_churn(manager)
+        store = manager.store_if_exists("project")
+        return [] unless store
+
+        SINGLE_CARDINALITY_PREDICATES.flat_map do |predicate|
+          non_active = store.facts
+            .where(predicate: predicate, status: %w[superseded disputed rejected])
+            .count
+          next [] if non_active < CHURN_THRESHOLD
+
+          [Finding.new(
+            id: "C010",
+            severity: :warn,
+            title: "predicate=#{predicate} shows churn: #{non_active} 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: []
+          )]
+        end
+      end
+
+      def normalize_convention(text)
+        text.to_s
+          .downcase
+          .gsub(/\b(?:uses|prefers|always|never)\b/, "")
+          .gsub(/[[:punct:]]/, "")
+          .gsub(/\s+/, " ")
+          .strip
+      end
+    end
+  end
+end

data/lib/claude_memory/audit/finding.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Audit
+    # A single audit finding. Immutable value object emitted by checks
+    # (see Audit::Checks) and aggregated by Audit::Runner.
+    #
+    # Severity levels:
+    #   - :error — a contract violation; CI/automation should fail
+    #   - :warn  — likely problem requiring attention but not blocking
+    #   - :info  — observation; suggests an optimization or cleanup
+    #
+    # Each finding embeds the suggested remediation command(s) as plain
+    # strings so the audit output is directly actionable. The skill
+    # `/audit-memory` reads these and offers to run them for the user.
+    Finding = Data.define(:id, :severity, :title, :detail, :suggestion, :fact_ids) do
+      def error? = severity == :error
+      def warn? = severity == :warn
+      def info? = severity == :info
+
+      def to_h
+        {
+          id: id,
+          severity: severity,
+          title: title,
+          detail: detail,
+          suggestion: suggestion,
+          fact_ids: fact_ids
+        }
+      end
+    end
+  end
+end

data/lib/claude_memory/audit/runner.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Audit
+    # Orchestrates the audit: opens a StoreManager, runs every check in
+    # CHECK_METHODS, collects findings, computes an exit code.
+    #
+    # The runner itself is read-only. Suggestions in each Finding name
+    # the commands a user (or skill) would run to remediate; the audit
+    # never writes.
+    class Runner
+      CHECK_METHODS = %i[
+        open_conflicts
+        single_cardinality_multiplicity
+        single_cardinality_churn
+        distillation_backlog
+        shortcut_decision_leak
+        shortcut_convention_scope
+        duplicate_global_conventions
+        bare_conclusion_rate
+        project_starvation
+        auto_memory_unimported
+      ].freeze
+
+      Result = Data.define(:findings, :stats) do
+        def errors = findings.select(&:error?)
+        def warnings = findings.select(&:warn?)
+        def info = findings.select(&:info?)
+        def ok? = errors.empty?
+        def exit_code = ok? ? 0 : 1
+      end
+
+      def initialize(manager: nil)
+        @manager = manager || Store::StoreManager.new
+      end
+
+      def run
+        findings = CHECK_METHODS.flat_map { |method| Checks.public_send(method, @manager) }
+        Result.new(findings: findings, stats: collect_stats)
+      end
+
+      private
+
+      def collect_stats
+        global = @manager.store_if_exists("global")
+        project = @manager.store_if_exists("project")
+        {
+          checks_run: CHECK_METHODS.size,
+          global: store_stats(global),
+          project: store_stats(project)
+        }
+      end
+
+      def store_stats(store)
+        return nil unless store
+        {
+          active_facts: store.facts.where(status: "active").count,
+          predicate_counts: predicate_distribution(store)
+        }
+      end
+
+      def predicate_distribution(store)
+        store.facts
+          .where(status: "active")
+          .group_and_count(:predicate)
+          .all
+          .map { |row| [row[:predicate], row[:count]] }
+          .sort_by { |_, c| -c }
+          .to_h
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/audit_command.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+
+module ClaudeMemory
+  module Commands
+    # Runs the memory health audit and prints findings. Exits non-zero
+    # when error-severity findings are present (unless --no-exit is
+    # given). JSON output is the stable surface — humans should not
+    # script against the text output.
+    class AuditCommand < BaseCommand
+      SEVERITY_RANK = {info: 0, warn: 1, error: 2}.freeze
+
+      def call(args)
+        opts = parse_opts(args)
+        return 1 if opts.nil?
+
+        manager = Store::StoreManager.new
+        result = Audit::Runner.new(manager: manager).run
+        filtered = filter_by_severity(result.findings, opts[:severity])
+
+        if opts[:json]
+          stdout.puts JSON.pretty_generate(payload(result, filtered))
+        else
+          render_text(result, filtered)
+        end
+
+        manager.close
+        opts[:no_exit] ? 0 : result.exit_code
+      end
+
+      def filter_by_severity(findings, threshold)
+        return findings if threshold.nil?
+        floor = SEVERITY_RANK.fetch(threshold) { return findings }
+        findings.select { |f| SEVERITY_RANK[f.severity] >= floor }
+      end
+
+      private
+
+      def parse_opts(args)
+        options = {json: false, no_exit: false, severity: nil}
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: claude-memory audit [--json] [--no-exit] [--severity=error|warn|info]"
+          o.on("--json", "Emit JSON instead of text") { options[:json] = true }
+          o.on("--no-exit", "Always exit 0 even on error-severity findings") { options[:no_exit] = true }
+          o.on("--severity LEVEL", "Only show findings at or above LEVEL (error|warn|info)") { |v| options[:severity] = v.to_sym }
+        end
+        parser.parse!(args.dup)
+        options
+      rescue OptionParser::InvalidOption => e
+        stderr.puts e.message
+        nil
+      end
+
+      def payload(result, filtered)
+        {
+          ok: result.ok?,
+          checks_run: result.stats[:checks_run],
+          counts: {
+            error: result.errors.size,
+            warn: result.warnings.size,
+            info: result.info.size
+          },
+          stats: result.stats.except(:checks_run),
+          findings: filtered.map(&:to_h)
+        }
+      end
+
+      def render_text(result, filtered)
+        stdout.puts "Memory health audit — #{Time.now.utc.iso8601}"
+        stdout.puts("=" * 60)
+        render_stats(result.stats)
+        stdout.puts ""
+        render_summary(result)
+        stdout.puts ""
+        render_findings(filtered)
+        stdout.puts ""
+        stdout.puts(result.ok? ? "OK" : "FAIL")
+      end
+
+      def render_stats(stats)
+        %i[global project].each do |scope|
+          s = stats[scope]
+          next unless s
+          preds = s[:predicate_counts].map { |k, v| "#{k}=#{v}" }.join(", ")
+          stdout.puts "#{scope.to_s.capitalize.ljust(7)} #{s[:active_facts]} active facts  #{preds}"
+        end
+      end
+
+      def render_summary(result)
+        stdout.puts "Checks run: #{result.stats[:checks_run]}"
+        stdout.puts "Errors: #{result.errors.size}   Warnings: #{result.warnings.size}   Info: #{result.info.size}"
+      end
+
+      def render_findings(findings)
+        if findings.empty?
+          stdout.puts "No findings."
+          return
+        end
+
+        findings.each do |f|
+          marker = case f.severity
+          when :error then "[ERROR]"
+          when :warn then "[WARN]"
+          when :info then "[INFO]"
+          end
+          stdout.puts "#{marker} #{f.id}  #{f.title}"
+          stdout.puts "  #{f.detail}"
+          stdout.puts "  → #{f.suggestion}"
+          stdout.puts "  fact_ids: #{f.fact_ids.first(20).inspect}#{"  (+#{f.fact_ids.size - 20} more)" if f.fact_ids.size > 20}" if f.fact_ids.any?
+          stdout.puts ""
+        end
+      end
+    end
+  end
+end