claude_memory 0.10.0 → 0.12.0

data/docs/GETTING_STARTED.md

@@ -593,8 +593,10 @@ Now that you're up and running:
 | `claude-memory changes` | Recent updates |
 | `claude-memory conflicts` | Show contradictions |
 | `claude-memory dashboard` | Open the local web UI (0.10.0+) |
-| `claude-memory digest --since 7` | Markdown report of the last 7 days (0.10.0+) |
+| `claude-memory digest --since 7` | Markdown report of the last 7 days (0.10.0+; gains Context cost + Quality sections in 0.11.0) |
+| `claude-memory show [--pending] [--source]` | Print what memory would inject at next SessionStart (0.11.0+) |
 | `claude-memory stats --stale` | List facts not recalled recently (0.10.0+) |
+| `claude-memory stats --tokens [--since DAYS]` | SessionStart context-token budget histogram (0.11.0+) |
 | `claude-memory stats --tools` | MCP tool-call telemetry (0.9.0+) |
 | `claude-memory census` | Privacy-safe predicate audit across projects (0.10.0+) |
 | `claude-memory dedupe-conflicts --dry-run` | Preview historical conflict-row dedup (0.10.0+) |

data/docs/api_stability.md

@@ -0,0 +1,341 @@
+# API Stability
+
+> Authoritative reference for what ClaudeMemory promises to keep stable
+> across releases. If a surface is listed here as **stable**, breaking
+> it without a deprecation cycle is a bug. If it's listed as **internal**
+> or simply not listed, no compatibility is implied.
+
+**Last updated:** 2026-05-01 (initial publication for 0.12.0). **Applies to:** `claude_memory` ≥ 0.12.0.
+
+This doc is the contract `claude-memory` semver depends on. The 1.0.0 release will lock the **stable** surfaces below; subsequent minor releases (`1.x`) may grow the stable set but won't shrink it without a deprecation cycle. Earlier 0.x releases also followed semver in spirit, but the absence of this doc made it un-arbitrable. From 0.12 onward, this is the single source of truth.
+
+---
+
+## 1. Versioning policy
+
+ClaudeMemory follows [SemVer 2.0](https://semver.org):
+
+- **MAJOR** (`1.0.0`, `2.0.0`): breaking changes to **stable** surfaces below.
+- **MINOR** (`0.X.0`, `1.X.0`): new features and additions; existing **stable** surfaces remain compatible.
+- **PATCH** (`0.X.Y`): bug fixes only; no new features and no behavior changes to **stable** surfaces.
+
+### Deprecation cycle
+
+When we want to break or rename a **stable** surface in a future major:
+
+1. Pick a `removed_in` version (typically `(N+1).0.0`).
+2. Wire a runtime warning via `ClaudeMemory::Deprecations.warn(name:, replacement:, removed_in:)`. Continue accepting the old form.
+3. Document in CHANGELOG under "Deprecated".
+4. Keep the old surface working for **at least one minor cycle**.
+5. Remove no earlier than the `removed_in` version.
+
+Suppress deprecation noise in CI/tests with `CLAUDE_MEMORY_NO_DEPRECATIONS=1`.
+
+### Stability tiers
+
+Throughout this doc each surface carries one tier:
+
+| Tier | Meaning |
+|---|---|
+| **stable** | Covered by semver. Breaking change requires deprecation cycle. |
+| **experimental** | May change in any minor without deprecation. Use at your own risk. |
+| **internal** | No guarantees. May change in any patch. Don't rely on it from external code. |
+
+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:
+
+### Stable commands (covered by semver)
+
+These commands and their **documented** flags are stable. Adding new commands or new flags is non-breaking; renaming or removing requires a deprecation cycle.
+
+| Command | Notes |
+|---|---|
+| `claude-memory init` | Project + global initialization. |
+| `claude-memory uninstall` | Removes `.claude/settings.json` hooks and rules. |
+| `claude-memory doctor` | Health check. New checks may be added; the JSON-summary mode is also stable. |
+| `claude-memory dashboard [--port N] [--no-open]` | Local web UI. The dashboard's **JSON HTTP API is internal** — see §7. |
+| `claude-memory recall <query>` | Fact retrieval. |
+| `claude-memory promote <fact_id>` | Promote project → global. |
+| `claude-memory reject <id_or_docid>` | Reject + close associated conflicts. |
+| `claude-memory restore --predicate NAME` | Recover supersession from obsolete single-value classifications. |
+| `claude-memory explain <fact_id>` | Provenance receipts. |
+| `claude-memory recover` | Database recovery. |
+| `claude-memory compact` | VACUUM + FTS rebuild. |
+| `claude-memory export` | Dump facts to JSON. |
+| `claude-memory ingest` / `sweep` / `publish` | Pipeline entrypoints. Hook commands stable as listed in §4. |
+| `claude-memory hook <ingest\|sweep\|publish\|context\|nudge>` | Hook entrypoints; stdin JSON contract in §4. |
+| `claude-memory serve-mcp` | MCP server. Argument schemas in §3. |
+| `claude-memory stats [--scope SCOPE] [--tools] [--tokens] [--stale] [--since DAYS] [--stale-days N]` | Statistics. |
+| `claude-memory show [--source SOURCE] [--pending]` | Print would-be-injected context (0.11.0+). |
+| `claude-memory digest [--since DAYS] [--output FILE]` | Markdown rollup (0.10.0+). |
+| `claude-memory census [--root DIR]` | Cross-project predicate audit (0.10.0+). |
+| `claude-memory conflicts` / `changes` | Inspection. |
+| `claude-memory db:init` | Initialize a single DB at a path. |
+| `claude-memory completion <bash\|zsh\|fish>` | Shell completions. |
+| `claude-memory version` / `help` | Inspection. |
+
+### Experimental commands
+
+May change in any minor; treat with care.
+
+| Command | Notes |
+|---|---|
+| `claude-memory dedupe-conflicts [--dry-run] [--apply]` | One-shot historical cleanup. The output format (preview rows, count summary) may change. |
+| `claude-memory reclassify-references [--dry-run] [--apply]` | Same shape; introduced 0.10.0. |
+| `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. |
+
+### Internal / not for external automation
+
+- `claude-memory index --vec` (rebuild operation) — semantics may shift with the embeddings overhaul.
+- `claude-memory git-lfs` — installation helper; output shape not guaranteed.
+- `claude-memory install-skill <name>` — skill plumbing.
+
+### Exit codes (stable)
+
+`Hook::ExitCodes`:
+
+| Code | Meaning |
+|---|---|
+| `0` | Success or graceful degradation. |
+| `1` | Non-blocking warning (shown to user; session continues). |
+| `2` | Blocking error (fed to Claude for processing). |
+
+Renaming or repurposing a code is a major-version change.
+
+---
+
+## 3. Public MCP tool surface
+
+All 23 tools registered via `MCP::ToolDefinitions.all`. Argument schemas, return shapes (both `content` and `structuredContent`), and tool-annotation hints (`readOnlyHint`, `idempotentHint`, `destructiveHint`) are **stable** for the listed tools.
+
+### Stable MCP tools
+
+| Tool | Group | Stability notes |
+|---|---|---|
+| `memory.recall` | Query | Argument schema + return shape stable. New optional fields may be added. |
+| `memory.recall_index` | Query | Stable. |
+| `memory.recall_details` | Query | Stable. |
+| `memory.recall_semantic` | Query | Stable since 0.9.0. |
+| `memory.search_concepts` | Query | Stable. |
+| `memory.explain` | Provenance | Stable. |
+| `memory.fact_graph` | Provenance | Stable. |
+| `memory.decisions` | Shortcut | Stable. |
+| `memory.conventions` | Shortcut | Stable. |
+| `memory.architecture` | Shortcut | Stable. |
+| `memory.facts_by_tool` | Context | Stable. |
+| `memory.facts_by_context` | Context | Stable. |
+| `memory.promote` | Management | Stable. |
+| `memory.reject_fact` | Management | Stable since 0.10.0. |
+| `memory.store_extraction` | Management | Argument schema (`facts`, `entities`, `decisions`) stable. |
+| `memory.undistilled` | Distillation | Stable since 0.10.0. |
+| `memory.mark_distilled` | Distillation | Stable since 0.10.0. |
+| `memory.status` | Monitoring | Stable. |
+| `memory.stats` | Monitoring | Stable. |
+| `memory.changes` | Monitoring | Stable. |
+| `memory.conflicts` | Monitoring | Stable. |
+| `memory.activity` | Monitoring | Stable since 0.10.0. |
+| `memory.sweep_now` | Maintenance | Stable. |
+| `memory.check_setup` | Discovery | Stable. |
+| `memory.list_projects` | Discovery | Stable since 0.10.0. |
+
+### Stability of tool responses
+
+Both response shapes are stable:
+
+- **Text content**: a human-readable summary in `content[0].text`. Content text format may evolve, but always remains valid Markdown.
+- **Structured content**: machine-parseable JSON in `structuredContent`. Top-level keys for each tool are stable; new keys may be added.
+- **Compact mode** (`compact: true` argument where supported): the compact representation is stable but explicitly omits receipts. Decision is documented per-tool.
+
+### What is NOT promised about MCP tools
+
+- Tool descriptions (the prose strings in `tool_definitions.rb`) may be tuned for prompt quality.
+- Tool annotations (`readOnlyHint` etc.) may flip if a tool's behavior changes — annotation flips count as a deprecation event.
+- Server-internal pagination cursors are opaque to clients.
+
+---
+
+## 4. Public hook contract
+
+ClaudeMemory ships hooks for **5 events** as listed in `Commands::Checks::HooksCheck::EXPECTED_HOOKS`: `Stop`, `StopFailure`, `SessionStart`, `PreCompact`, `SessionEnd`. The `init` command also writes hooks for `TaskCompleted`, `TeammateIdle`, and `Notification` in projects that opt in. **Adding or removing the events that `init` writes is a stable-surface change.**
+
+### Hook subcommands (stable since 0.10.0)
+
+`claude-memory hook <ingest|sweep|publish|context|nudge>` reads JSON from stdin. The `nudge` subcommand was added 0.11.0.
+
+### Stable stdin payload fields
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `session_id` | string | yes for `ingest`, `context`, `nudge` | Claude Code session id. |
+| `transcript_path` | string | yes for `ingest` | Path to the session transcript JSONL. |
+| `project_path` | string | no | Defaults to `cwd`. |
+| `cwd` | string | no | Working directory. |
+| `source` | string | no | Hook fresh-session source (`startup`, `resume`, `clear`, etc.). Affects `context` injector behavior. |
+| `mode` | string | no | For `publish` — `shared`, `local`, `home`. |
+
+Unknown payload fields are **ignored** rather than rejected — this lets Claude Code add new fields without breaking older gem versions.
+
+### Stable stdout response
+
+For `claude-memory hook context` only:
+
+```json
+{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "<markdown>"}}
+```
+
+The shape and key names are stable. `additionalContext` content format (Markdown sections) is stable as listed in §6.
+
+### Stable `activity_events.detail_json` field set
+
+Each hook records an `activity_events` row whose `detail_json` carries telemetry. The **stable** field set per `event_type` is enumerated in [`spec/smoke/expected_fields.yml`](../spec/smoke/expected_fields.yml) — that file is the manifest, and `bin/pre-release-smoke` enforces it as a release gate.
+
+Adding a new field to `detail_json` is a stable-surface addition (non-breaking). Removing or renaming a listed field requires a deprecation cycle. The smoke gate refuses to ship a release if any listed field is unexpectedly null.
+
+Current covered events (0.11.0):
+
+- `hook_context`: `context_length`, `context_tokens` (since 0.11.0), `top_fact_ids`, `fact_count`.
+- `roi_nudge`: `n`, `used`, `pct`, `prior_count` (all since 0.11.0).
+
+`hook_ingest`, `hook_sweep`, `hook_publish` event detail fields are currently **internal** (not on the smoke-gate manifest). Promoting them to stable is a 0.12.x or later task.
+
+---
+
+## 5. Public Ruby API surface
+
+External Ruby callers (benchmark adapters, scripts, and downstream gems) may rely on these classes and methods. Default for everything else: **internal**.
+
+### Stable classes
+
+| Class | Public surface |
+|---|---|
+| `ClaudeMemory::Recall` | `#initialize(manager)`, `#query(query, limit:, scope:, intent:)`, `#query_index(...)`, `#query_semantic(...)`, return-shape: array of `{fact:, receipts:, source:}`. |
+| `ClaudeMemory::Configuration` | `#initialize(env = ENV)` and instance methods returning paths/flags. **Note:** instance methods only — no class-level helpers (e.g. `Configuration.global_db_path` does not exist; use `Configuration.new.global_db_path`). |
+| `ClaudeMemory::Store::StoreManager` | `#initialize(global_db_path:, project_db_path:, project_path:, env:)`, `#ensure_both!`, `#close`, `#default_store`, `#store_if_exists(scope)`, accessors `global_store`, `project_store`. |
+| `ClaudeMemory::Domain::Fact` | Read-only attribute accessors and predicate methods (`active?`, `superseded?`, `rejected?`). Frozen / immutable. |
+| `ClaudeMemory::Domain::Entity` | Same shape — frozen value object. Predicates: `database?`, `framework?`, etc. |
+| `ClaudeMemory::Domain::Provenance` | Frozen value object; `stated?`, `inferred?` predicates. |
+| `ClaudeMemory::Domain::Conflict` | Frozen value object; `open?`, `resolved?` predicates. |
+| `ClaudeMemory::Deprecations` | The deprecation-warning helper itself; `.warn(name:, replacement:, removed_in:, message:)`. |
+| `ClaudeMemory::VERSION` | Semver string constant. |
+
+### Experimental
+
+| Class | Why |
+|---|---|
+| `ClaudeMemory::Hook::ContextInjector` | Used by `claude-memory show` and benchmark fixtures, but its emitted_* accessors evolve as the injector is tuned. Method signatures stable; private internals not. |
+| `ClaudeMemory::Distill::Extraction` | Value object the LLM-distillation path produces. Field set may grow. |
+| `ClaudeMemory::Core::TokenEstimator` | Estimation heuristic may sharpen; returned counts are approximations regardless. |
+
+### Internal (do not rely on from external code)
+
+Everything else under `lib/claude_memory/`. Specifically:
+
+- All of `Resolve::*` (truth maintenance internals).
+- All of `Sweep::*` (maintenance internals).
+- All of `Index::*` (indexing internals — `LexicalFTS`, `VectorIndex`).
+- All of `Hook::Handler` and `Hook::DistillationRunner` (use the CLI hook subcommands instead).
+- All of `MCP::*` except via the public MCP-tool protocol (use `claude-memory serve-mcp` and the JSON-RPC interface).
+- All of `Commands::*` except via the CLI (don't call command classes directly from external Ruby).
+- All of `Dashboard::*` (treat the dashboard as a black box; don't import its panel classes).
+- `Distill::NullDistiller`, `Distill::ReferenceMaterialDetector`, `Distill::BareConclusionDetector` — these are pluggable internals; treat as "may change in any patch."
+
+If you need a feature from one of the internal classes, **open an issue** so we can promote it deliberately or expose it through a stable adapter.
+
+---
+
+## 6. Schema & predicate vocabulary
+
+### Schema migrations
+
+Schema is at v18 as of 0.12.0 with 18 migrations under `db/migrations/`. Migrations remain forward-compatible per the round-trip-spec convention (`feedback_round_trip_migration_specs.md`): each release's specs verify that DBs from the prior 3 schema boundaries can be migrated into the current schema without data loss.
+
+**What's stable:**
+
+- Existing **table names**: `content_items`, `entities`, `entity_aliases`, `facts`, `provenance`, `fact_links`, `conflicts`, `mcp_tool_calls`, `activity_events`, `moment_feedback`, `delta_cursors`, plus `content_fts` (FTS5) and `facts_vec` (sqlite-vec).
+- Existing **column names** on the above tables.
+- The **predicate vocabulary** in `Resolve::PredicatePolicy::POLICIES`: `convention`, `decision`, `architecture`, `reference`, `uses_framework`, `uses_language`, `uses_database`, `deployment_platform`, `auth_method`. Adding new predicates is non-breaking; renaming or removing an existing predicate requires a deprecation cycle (see `SYNONYMS` for prior canonicalizations).
+- **Cardinality** of each predicate (single vs multi). Reclassifying a predicate's cardinality is a breaking change — see the 0.9.0 `uses_framework` reclassification incident for context.
+
+**What's experimental:**
+
+- The `vec0` virtual-table internals — sqlite-vec evolution may shift representation.
+- `mcp_tool_calls` retention behavior (currently 90 days, configurable); the column set is stable, the retention default is not.
+
+**What's internal:**
+
+- Auxiliary FTS shadow tables (e.g. `content_fts_data`, `content_fts_idx`) — managed by SQLite, treat as opaque.
+- `schema_info` / `schema_migrations` housekeeping tables — managed by Sequel::Migrator.
+- Specific SQL indexes and triggers — may be added/dropped without notice as long as the user-visible columns and behaviors stay the same.
+
+### Removing a column or predicate
+
+Always a major-version change. Process:
+
+1. Mark the surface deprecated via `Deprecations.warn` in the next minor.
+2. Keep reading the column / accepting the predicate for ≥ 1 minor cycle.
+3. Migration to drop the column ships in the major bump.
+
+---
+
+## 7. Database signal-health audit (since 0.12.0)
+
+The memory database itself has stability contracts that, when violated, indicate either a regression in the distillation/resolve pipeline or contamination of the source documentation. These contracts are enforced at two layers:
+
+### `bin/memory-audit` (runtime audit script)
+
+Reports per-DB statistics and exits non-zero on threshold breach. Stable surface:
+
+- Output JSON shape (`--json` flag): `{project_path, global: {active_facts, predicate_counts}, project: {active_facts, predicate_counts, open_conflicts, pending_distillation}, single_cardinality_violations, warnings, failures, ok}`.
+- Exit code: `0` on `failures.empty?`, `1` otherwise. `--no-exit` always returns 0 (informational mode).
+
+Run before tagging a release; wire into CI on the project's own DB to catch in-conversation contamination.
+
+### `spec/benchmarks/health/database_signal_spec.rb`
+
+`:benchmark`-tagged RSpec suite that codifies the contracts:
+
+1. Zero open conflicts in both stores.
+2. At most one active fact per single-cardinality predicate (`uses_database`, `deployment_platform`, `auth_method`).
+3. `memory.conventions` returns at least one project-scope fact when project conventions exist (regression guard against the pre-0.12 global-only filter).
+4. `memory.decisions` returns only `decision`-predicate facts (no `uses_*` leakage).
+5. `memory.architecture` returns only predicates in `Shortcuts::SHORTCUTS[:architecture][:predicates]`.
+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`.
+
+---
+
+## 7. What is explicitly NOT public
+
+Listed here for honesty — these surfaces look public but are not.
+
+- **Dashboard JSON HTTP API.** The `claude-memory dashboard` server's endpoints are an internal interface for the bundled UI. Don't build scripts against `GET /api/trust` etc. — endpoints, response shapes, and even URL paths may change without notice.
+- **`activity_events.detail_json` fields not in `spec/smoke/expected_fields.yml`.** Inspecting a missing field during debugging is fine; relying on it in scripts is not.
+- **The exact text of `additionalContext`.** The Markdown sections (`## Decisions`, `## Conventions`, `## Architecture`, `## Pending Knowledge Extraction`, `## Auto-Memory Mirror`) and their order are stable; the per-fact rendering format inside each section is tuned for prompt quality and may change.
+- **Internal env vars** (anything not listed in `Configuration` instance methods or in this doc). Examples that exist but are internal: `CLAUDE_MEMORY_LOG_LEVEL`, debug flags surfaced during development.
+- **Test/spec/fixture infrastructure.** `spec/benchmarks/`, `spec/evals/`, `spec/support/` are not public APIs.
+- **Plugin-format paths.** `.claude-plugin/`, `scripts/serve-mcp.sh`, etc. are part of the Claude Code plugin format integration; treat them as opaque.
+
+---
+
+## 8. Reporting a stability concern
+
+If you depended on a surface that changed without a deprecation cycle, file an issue at [github.com/codenamev/claude_memory/issues](https://github.com/codenamev/claude_memory/issues) with:
+
+1. The surface (class, method, flag, tool, field).
+2. The version it worked in and the version that broke.
+3. The use case (so we can decide whether to revert or add a stable replacement).
+
+Surfaces listed here as **stable** that broke without warning are bugs and will be fixed in a patch release. Surfaces listed as **internal** or **experimental** may or may not be fixed — we'll triage based on reach.
+
+---
+
+*This doc is the contract; `lib/claude_memory/commands/registry.rb`, `lib/claude_memory/mcp/tool_definitions.rb`, `lib/claude_memory/resolve/predicate_policy.rb`, and `spec/smoke/expected_fields.yml` are the implementation. When they disagree, the manifest files in code are authoritative — but disagreement is itself a bug; keep them in sync.*

data/docs/architecture.md

@@ -40,7 +40,7 @@ ClaudeMemory is architected using Domain-Driven Design (DDD) principles with cle
 
 **Components:**
 - **CLI** (`cli.rb`): Thin router that dispatches to command classes
-- **Commands** (`commands/`): 32 command classes, each handling one CLI command
+- **Commands** (`commands/`): 34 command classes, each handling one CLI command
 - **Configuration** (`configuration.rb`): Centralized ENV access and path calculation
 
 **Key Principles:**
@@ -205,7 +205,7 @@ end
 - **Server**: WEBrick HTTP server (default port 3377), starts via `claude-memory dashboard`
 - **API**: HTTP-shape glue + per-endpoint formatting; routes/delegates to panel classes
 - **Panels** (each backed by a dedicated class with focused responsibility):
-  - `Trust`: weekly moments, fingerprint, utilization, feedback ratio, needs-review
+  - `Trust`: weekly moments, fingerprint, utilization, feedback ratio, needs-review, **token_budget** (p50/p95/avg over 30d, 0.11.0+), **quality_score** (live 30-day window + historical baseline, 0.11.0+)
   - `Moments`: feed-first activity stream with kind classification
   - `Knowledge`: predicate-grouped fact summary (incl. References section)
   - `Conflicts`: display-layer dedup with bulk-reject helper
@@ -361,7 +361,7 @@ FileSystem (write)
 - Value objects (SessionId, TranscriptPath, FactId)
 - Centralized Configuration
 - 4 domain models with business logic
-- 32 command classes
+- 34 command classes
 - 25 MCP tools
 - Semantic search with local embeddings (FastEmbed + TF-IDF fallback)
 - Schema v17 with WAL mode

data/docs/audit_runbook.md

@@ -0,0 +1,209 @@
+# Memory Audit Runbook
+
+This runbook explains every check the audit runs, why it matters, and how to remediate findings. It is the human-readable companion to `claude-memory audit` and the `/audit-memory` skill.
+
+## When to run
+
+- **After a release** — before tagging, confirm no contracts were silently broken.
+- **When `memory.recall` feels noisy** — if you ask for conventions and get unrelated stack facts, the shortcut filters may have regressed.
+- **When ingest seems slow** — a large distillation backlog or repeating contamination loop will compound over weeks.
+- **In CI on `main`** — wire `claude-memory audit --no-exit --json` into a workflow and post the output to a dashboard.
+
+## Quick start
+
+```bash
+claude-memory audit                 # human-readable, exits non-zero on error
+claude-memory audit --json          # machine-readable JSON
+claude-memory audit --severity=error  # only blocking findings
+/audit-memory                       # interactive walkthrough via Claude Code
+```
+
+## Output shape
+
+JSON payload:
+
+```json
+{
+  "ok": true,
+  "checks_run": 10,
+  "counts": {"error": 0, "warn": 1, "info": 2},
+  "stats": {
+    "global": {"active_facts": 4, "predicate_counts": {"convention": 4}},
+    "project": {"active_facts": 68, "predicate_counts": {...}}
+  },
+  "findings": [
+    {
+      "id": "C003",
+      "severity": "warn",
+      "title": "27 content items not yet deeply distilled",
+      "detail": "...",
+      "suggestion": "claude-memory sweep --mark-all-distilled OR /distill-transcripts",
+      "fact_ids": []
+    }
+  ]
+}
+```
+
+Exit code is `0` when `ok: true`, `1` otherwise. `--no-exit` always returns `0`.
+
+## Checks
+
+### C001 — Open conflicts
+
+**Severity:** error
+
+**Triggered when:** the project or global DB has any row in `conflicts` with `status='open'`.
+
+**Why it matters:** Conflicts pause supersession. Until they close, single-cardinality predicates can't reach a clean state. Every re-ingest of the contested content potentially adds noise.
+
+**Remediation:**
+1. List with `claude-memory conflicts`.
+2. For each pair, run `claude-memory explain <fact_a>` and `claude-memory explain <fact_b>` to inspect provenance.
+3. Reject the wrong claim with `claude-memory reject <fact_id> --reason "<why>"`. Rejection closes any conflict the fact was party to in the same transaction.
+
+### C002 — Single-cardinality multiplicity
+
+**Severity:** error
+
+**Triggered when:** `uses_database`, `deployment_platform`, or `auth_method` has more than one active fact.
+
+**Why it matters:** The single-cardinality contract is "at most one active value per predicate." Multiple actives mean either the resolver dropped a supersession or distillation produced contradictions. Downstream tools (snapshot publishing, `memory.architecture`) will list mutually exclusive values.
+
+**Remediation:**
+1. Identify the right value (the one the project actually uses).
+2. `claude-memory reject <fact_id>` on the others.
+3. Re-audit to confirm; if it keeps recurring, look at C010 (churn) and find the contamination source.
+
+### C003 — Distillation backlog
+
+**Severity:** warn (≥ 25) or error (≥ 100)
+
+**Triggered when:** content items are not present in `ingestion_metrics`, indicating they haven't been deep-distilled (Layer 2/3).
+
+**Why it matters:** Backlog grows when SessionStart distillation prompts don't get acknowledged via `memory.mark_distilled`. The same transcript text keeps getting re-extracted across sessions, multiplying hallucination opportunities.
+
+**Remediation:**
+- **Triage path (preserves signal):** `/distill-transcripts --limit 10` repeatedly until cleared. Slow, but extracts genuine facts.
+- **Bulk-clear path (accepts backlog is noise):** `claude-memory sweep --mark-all-distilled`. Use when the backlog is old transcripts unlikely to add value.
+
+### C004 — `memory.decisions` predicate leak
+
+**Severity:** error
+
+**Triggered when:** the `memory.decisions` MCP shortcut returns facts whose predicate is not `decision`.
+
+**Why it matters:** The shortcut should be a clean `predicate=decision` filter. Pre-2026-05-21, it ran an FTS text search on "decision constraint rule requirement" which matched `uses_database`/`uses_framework` rows. Any leakage means the shortcut has regressed.
+
+**Remediation:**
+- Open `lib/claude_memory/shortcuts.rb` and verify `SHORTCUTS[:decisions][:predicates]` is `%w[decision]`.
+- Run `bundle exec rspec spec/claude_memory/shortcuts_spec.rb`.
+- File a bug if the spec passes but real output leaks.
+
+### C005 — `memory.conventions` scope regression
+
+**Severity:** warn
+
+**Triggered when:** `memory.conventions` returns zero project-scoped facts despite the project DB containing active conventions.
+
+**Why it matters:** Pre-2026-05-21, `memory.conventions` was hardcoded to `scope=global` only. Project conventions were invisible to coding agents calling the shortcut. Resurfacing this regression means losing project knowledge.
+
+**Remediation:**
+- Inspect `Shortcuts.collect_facts` in `lib/claude_memory/shortcuts.rb` — it must query both `manager.project_store` and `manager.global_store`.
+- Re-run the shortcut spec.
+
+### C006 — Duplicate global conventions
+
+**Severity:** info
+
+**Triggered when:** the global DB has multiple `convention` facts whose object text normalizes to the same phrasing (after lowercasing, stripping `uses`/`prefers`/punctuation).
+
+**Why it matters:** Duplicates pollute the global convention list and inflate the apparent size of your memory. They don't break correctness, but they waste tokens.
+
+**Remediation:**
+1. Pick the cleanest phrasing.
+2. `claude-memory reject <duplicate_id>` on the rest.
+
+### C007 — Bare-conclusion rate
+
+**Severity:** info
+
+**Triggered when:** ≥ 30% of active `decision`/`convention` facts lack a reason clause ("because", "so that", "to avoid", etc.).
+
+**Why it matters:** Facts without justification are dead weight when the original context fades. A high bare-conclusion ratio means the LLM distillation is shipping low-quality extractions.
+
+**Remediation:**
+- Low-value bare facts: reject.
+- Important bare facts: rewrite via `memory.store_extraction` with a `quote` that embeds the reason, then reject the bare original.
+- See `Distill::BareConclusionDetector` for the canonical signal patterns.
+
+### C008 — Project starvation
+
+**Severity:** warn
+
+**Triggered when:** the project DB has fewer than 5 active facts.
+
+**Why it matters:** A nearly-empty DB suggests either a fresh install (ignore) or a broken ingest pipeline / overzealous cleanup. Distinguishing requires looking at ingest history.
+
+**Remediation:**
+- `claude-memory doctor` — verify hooks are firing.
+- `claude-memory stats` — check `content_items.total` vs `facts.active`; if many content items but few facts, distillation isn't running.
+- Check `.claude/settings.json` for hook configuration.
+
+### C009 — Auto-memory unimported
+
+**Severity:** info
+
+**Triggered when:** `~/.claude/projects/<slug>/memory/*.md` contains more files than the project DB has `content_items` with `source='auto_memory_import'`.
+
+**Why it matters:** Claude Code's auto-memory markdown files are durable user-curated knowledge. Until imported, they only surface transiently via `AutoMemoryMirror` at SessionStart — they're invisible to `memory.recall` and to the shortcut tools.
+
+**Remediation:**
+- Preview: `claude-memory import-auto-memory --dry-run`.
+- Apply: `claude-memory import-auto-memory`.
+
+### C010 — Single-cardinality churn
+
+**Severity:** warn
+
+**Triggered when:** any single-cardinality predicate has ≥ 5 historical non-active facts (superseded + disputed + rejected).
+
+**Why it matters:** Repeated supersession on a "must be exactly one" predicate is the signature of a persistent contamination source. Common culprits:
+- Example text in `CLAUDE.md` ("e.g., this app uses PostgreSQL") triggers extraction every session.
+- Comments in code/docs naming alternative stacks.
+- Audit/discussion documents (like this one) mentioning the contaminating value.
+
+**Remediation:**
+1. Find the trigger: `claude-memory recall "<bad_value>" --scope=project`. Inspect the matching content items and their source.
+2. Wrap the trigger text in `<no-memory>` tags at the source.
+3. Clean up: `claude-memory reject` the historical disputed/superseded rows (or accept them as historical record).
+4. Re-audit.
+
+## Adding a new check
+
+The audit is extensible by design.
+
+1. Add a method to `ClaudeMemory::Audit::Checks` returning `Array<Finding>`. Convention: pure read-only access to the StoreManager.
+2. Append the method name to `Audit::Runner::CHECK_METHODS`.
+3. Document the check in this runbook (this file) with the same `C###` ID.
+4. Write a spec at `spec/claude_memory/audit/checks_spec.rb`.
+
+## Integrating with CI
+
+A minimal GitHub Actions step:
+
+```yaml
+- name: ClaudeMemory health audit
+  run: bundle exec claude-memory audit --json | tee audit.json
+- uses: actions/upload-artifact@v4
+  with:
+    name: memory-audit
+    path: audit.json
+```
+
+Treat error-severity findings as build failures. Warnings can route to a Slack channel for periodic triage.
+
+## Related
+
+- `docs/memory_audit_2026-05-21.md` — the original audit and 4-phase remediation pipeline that established this workflow.
+- `docs/api_stability.md` Section 7 — stable surface of the audit script and benchmark spec.
+- `spec/benchmarks/health/database_signal_spec.rb` — runtime contract checks that mirror C001/C002/C004/C005.