claude_memory 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b42d582ddd17dd325f8048268c889d6c80c1ca9c229732da1a8d619279201af
-  data.tar.gz: 8853caacc212900483a4a3f9939e8261e18f53b886675f01b4c5a5b61a506d26
+  metadata.gz: a299c6ab2aeb95123dcb61f5c87a06b93d15a00a2ed9ff2c8343e7fde6b369cb
+  data.tar.gz: d09c02a2f5dcd4bd0dfcb625793505bd2218c7df04230411e813a7543e7e7382
 SHA512:
-  metadata.gz: a65038105334c741d26c5e485da7565016ae670ed24f04d4c23b2bb00329d729ee3bfd91cf333ea36ad518937e40e4c95c4d0846bcb423984b0ec683fee59b5a
-  data.tar.gz: d94e2ce5fbd1ed496a0c56f094b7f1fbb01b9eb255c819a95b2ffe6ecf79ea9c1706408fd658b2bcaee19d440a87d45a1185a7e471cb05fc7c003d433d6e5808
+  metadata.gz: 87fd7dab40cb2e5b190de071f99bcc1394e98e5f426951eedaff09b190fa66591b40f49580bca45f75819170ba939a0d3d9239f4825825b431fd4a83d388bb7d
+  data.tar.gz: ffb4ab50ba94a8f3c7bfb8129f01ea96fd27b981dd614f0addd7d65a9fc2b4b8562b9d23148bb5ea4ee90b5ae5a9fc183d1c82e68d3b009557967a00b96bfec1

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

@@ -1,7 +1,7 @@
 <!--
   This file is auto-generated by claude-memory.
   Do not edit manually - changes will be overwritten.
-  Generated: 2026-04-15T17:38:20Z
+  Generated: 2026-04-16T17:54:51Z
 -->
 
 # Project Memory
@@ -14,6 +14,14 @@
 
 ## Conventions
 
+- Curated predicate vocabulary has 8 entries: multi-value (convention, decision, architecture, uses_framework, uses_language) and single-value (uses_database, deployment_platform, auth_method). Pruned 7 dead predicates after multi-project survey confirmed zero usage.
+- Before making design changes to schemas, vocabularies, or policies, survey actual usage data across multiple project databases under ~/src/ — single-project analysis can validate wrong assumptions. The uses_framework cardinality bug was only visible across multi-project data.
+- A/B testing memory plugin: use 'claude --bare --mcp-config=/tmp/mcp-test.json -p' with serve-mcp.sh path. --plugin-dir doesn't work with --bare despite docs claiming it should. Architecture/convention/preference questions differentiate best; grep-able and one-shot code-gen questions don't.
+- NullDistiller emits uses_language for language-type entities (added 0.9.0), alongside existing uses_database, uses_framework, deployment_platform. Migration v14 canonicalizes stale predicate names (has_convention → convention, primary_language → uses_language) in existing facts.
+- CLAUDE.md scope-system example text ('this app uses PostgreSQL') causes recurring distiller hallucinations. Reject + re-ingest creates rejection churn because rejection metadata doesn't block re-insertion at content level. Open product gap — workaround: wrap example text in <no-memory> tags.
+- claude-memory restore --predicate NAME recovers facts superseded by obsolete single-value classifications. Uses Jaccard token overlap (threshold 0.5) to distinguish bug-caused supersession from real corrections. Only operates on predicates currently classified multi-value. Opt-in per DB, supports --dry-run.
+- claude-memory reject <id_or_docid> marks facts as rejected and resolves associated open conflicts in a single transaction. Accepts integer fact IDs or 8-char hex docids. memory.reject_fact MCP tool mirrors the CLI.
+- The /release skill automates gem releases in three phases: prepare (version bump across 3 files, bundle install, MCP verify, tests, lint, CHANGELOG check, commit), publish (user-driven: git push + rake release), announce (fix GitHub Latest flags, create gh release from CHANGELOG). Never auto-pushes.
 - Never use Sequel.sqlite for DB reads; this gem only depends on extralite. Use Sequel.connect("extralite://#{db_path}") or SQLiteStore.new. Sequel.sqlite requires the ungem'd sqlite3 adapter and fails at runtime.
 - Two distinct tool_calls tables exist: tool_calls (v3) for transcript-observed Claude Code tool usage, and mcp_tool_calls (v13) for MCP server telemetry. Disjoint purposes, never join.
 - MCP tool-call telemetry is recorded via MCP::Telemetry wrapping Server#handle_tools_call. Writes to mcp_tool_calls table in the project DB. Swallows DB errors so telemetry never breaks a real tool response. Viewable via 'claude-memory stats --tools [--since DAYS]'.
@@ -37,15 +45,69 @@
 
 ## Technical Constraints
 
+- **Uses framework**: rails
+- **Deployment platform**: aws
 - **Uses database**: sqlite
 
 ## Additional Knowledge
 
 ### Architecture
 
+- repo: PredicatePolicy is the single source of truth for predicate vocabulary (POLICIES), cardinality, snapshot section mapping (SECTION_MAP), synonym canonicalization (SYNONYMS), and LLM guidance. tool_definitions.rb, publish.rb, and distill-transcripts.md all derive from PredicatePolicy. Never hardcode predicate names elsewhere.
 - MCP::Tools: Thin 104-line dispatcher that includes 6 handler modules in mcp/handlers/: QueryHandlers, ShortcutHandlers, ContextHandlers, ManagementHandlers, StatsHandlers, SetupHandlers
 - Recall: 94-line facade delegating to @engine (DualEngine or LegacyEngine), both include shared QueryCore module with all store-level query logic
 - SQLiteStore: 386-line CRUD class that includes RetryHandler (retry/connection logic) and SchemaManager (migrations/version sync) modules
 - Embeddings: Pluggable providers via Embeddings.resolve(name, env:). Three providers: tfidf (default), fastembed, api. Duck-typed contract: name, dimensions, generate(text). ENV: CLAUDE_MEMORY_EMBEDDING_PROVIDER
 - Embeddings::DimensionCheck: Pure value object — DimensionCheck.call(store, provider) returns Data.define Result with :fresh/:match/:mismatch status. No side effects; caller decides how to handle mismatch.
 
+
+## Open Conflicts
+
+The following facts are in conflict and need resolution:
+
+- Conflict #12: Fact 21 vs Fact 43
+- Conflict #13: Fact 21 vs Fact 44
+- Conflict #14: Fact 45 vs Fact 46
+- Conflict #15: Fact 45 vs Fact 47
+- Conflict #16: Fact 48 vs Fact 49
+- Conflict #17: Fact 45 vs Fact 50
+- Conflict #18: Fact 21 vs Fact 51
+- Conflict #19: Fact 48 vs Fact 52
+- Conflict #20: Fact 21 vs Fact 53
+- Conflict #21: Fact 21 vs Fact 54
+- Conflict #22: Fact 21 vs Fact 55
+- Conflict #23: Fact 21 vs Fact 56
+- Conflict #24: Fact 21 vs Fact 57
+- Conflict #25: Fact 48 vs Fact 58
+- Conflict #26: Fact 48 vs Fact 59
+- Conflict #27: Fact 48 vs Fact 60
+- Conflict #28: Fact 21 vs Fact 61
+- Conflict #29: Fact 21 vs Fact 62
+- Conflict #30: Fact 21 vs Fact 63
+- Conflict #31: Fact 45 vs Fact 64
+- Conflict #32: Fact 21 vs Fact 65
+- Conflict #33: Fact 21 vs Fact 66
+- Conflict #34: Fact 21 vs Fact 67
+- Conflict #35: Fact 45 vs Fact 68
+- Conflict #36: Fact 45 vs Fact 69
+- Conflict #37: Fact 48 vs Fact 70
+- Conflict #38: Fact 48 vs Fact 71
+- Conflict #39: Fact 21 vs Fact 72
+- Conflict #40: Fact 21 vs Fact 73
+- Conflict #41: Fact 21 vs Fact 74
+- Conflict #42: Fact 21 vs Fact 75
+- Conflict #43: Fact 21 vs Fact 76
+- Conflict #44: Fact 45 vs Fact 77
+- Conflict #45: Fact 45 vs Fact 78
+- Conflict #46: Fact 45 vs Fact 79
+- Conflict #47: Fact 45 vs Fact 80
+- Conflict #48: Fact 45 vs Fact 81
+- Conflict #49: Fact 48 vs Fact 82
+- Conflict #50: Fact 48 vs Fact 83
+- Conflict #51: Fact 48 vs Fact 84
+- Conflict #52: Fact 48 vs Fact 85
+- Conflict #53: Fact 48 vs Fact 86
+- Conflict #54: Fact 48 vs Fact 87
+- Conflict #55: Fact 48 vs Fact 88
+- Conflict #56: Fact 48 vs Fact 89
+- Conflict #57: Fact 48 vs Fact 90

data/.claude/skills/dashboard/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: dashboard
+description: Launch a local web dashboard for ClaudeMemory debugging and observability
+---
+
+# Dashboard
+
+Launch the ClaudeMemory debugging dashboard to visualize memory system health, activity, and efficacy.
+
+## Task
+
+Start the dashboard web server so the user can inspect what's happening behind the scenes.
+
+## Steps
+
+1. Run the dashboard command:
+
+```bash
+claude-memory dashboard
+```
+
+This starts a local web server (default port 3377) and opens it in the browser.
+
+## What the Dashboard Shows
+
+- **Health Status**: Database health, hook configuration, vector index status
+- **Overview**: Fact/entity/content counts, top predicates, entity type distribution, 30-day activity timeline
+- **Activity**: Live event log of hook executions (ingest, context, sweep), memory recalls, and store extractions with timing and details
+- **Facts**: Searchable fact explorer with status filtering, predicate/object search
+- **Efficacy**: Recall hit rate, total results served, average results per query, top queries by result count
+
+## Options
+
+- `--port PORT` - Use a different port (default: 3377)
+- `--no-open` - Don't auto-open the browser
+
+## Notes
+
+- Dashboard auto-refreshes every 30 seconds
+- Activity events are recorded by hooks and MCP tools into the `activity_events` table
+- The dashboard reads from both global and project databases
+- Press Ctrl+C to stop the server

data/.claude/skills/release/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: release
+description: Prepare and publish a new gem release — bumps version across all required files, validates tests/linting/MCP server, commits, and creates the GitHub release. Use this skill when the user says "release", "publish a new version", "bump the version", "cut a release", "prepare for release", "ship it", or any variation of wanting to publish a new gem version. Also use when the user asks about the release process or what steps are needed to release.
+agent: general-purpose
+allowed-tools: Read, Grep, Edit, Write, Bash
+arguments:
+  - name: version
+    description: "The new version number (e.g., '0.10.0'). If omitted, you'll be asked."
+    required: false
+---
+
+# Release Workflow
+
+Automate the full release lifecycle for the ClaudeMemory gem. This workflow was codified from the actual 0.9.0 release process.
+
+The release has three phases: **prepare** (automated), **publish** (user-driven), and **announce** (automated). The middle phase requires user action because it pushes to a shared remote and publishes to RubyGems — destructive operations that must never happen without explicit confirmation.
+
+## Phase 1: Prepare
+
+### Step 1: Determine the new version
+
+If a version was passed as an argument, use it. Otherwise, read the current version from `lib/claude_memory/version.rb` and ask the user what the new version should be.
+
+### Step 2: Find and update all version references
+
+The version lives in exactly three files. Grep to confirm there are no others:
+
+```bash
+grep -rn "CURRENT_VERSION" --include="*.rb" --include="*.json" --include="*.gemspec" . | grep -v "CHANGELOG\|node_modules\|vendor\|\.git/"
+```
+
+Update all three:
+
+1. **`lib/claude_memory/version.rb`** — the `VERSION` constant (canonical source)
+2. **`.claude-plugin/plugin.json`** — the `"version"` field
+3. **`.claude-plugin/marketplace.json`** — the `"version"` field inside the plugins array
+
+If grep reveals any additional hardcoded references, update those too and flag them to the user as something that should be DRYed up.
+
+### Step 3: Update Gemfile.lock
+
+```bash
+bundle install
+```
+
+Verify both `claude_memory (X.Y.Z)` entries in Gemfile.lock match the new version.
+
+### Step 4: Verify MCP server reports the new version
+
+The MCP server reads `ClaudeMemory::VERSION` dynamically. Confirm it picks up the change:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bundle exec claude-memory serve-mcp 2>/dev/null | grep -o '"version":"[^"]*"'
+```
+
+Expected output: `"version":"X.Y.Z"` matching the new version. If it doesn't match, something is wrong with the require chain — investigate before proceeding.
+
+### Step 5: Run the full test suite
+
+```bash
+bundle exec rspec
+```
+
+All tests must pass. Do not proceed with any failures. Fix them first.
+
+### Step 6: Run the linter
+
+```bash
+bundle exec rake standard:fix
+```
+
+Ensure no remaining violations.
+
+### Step 7: Verify CHANGELOG.md
+
+The CHANGELOG should already have a release section written during development (via `/improve`, manual commits, or other workflow). **Do not auto-generate release notes** — they should reflect the actual development narrative.
+
+Check that:
+- The `## [X.Y.Z] - YYYY-MM-DD` section exists with today's date
+- It has Added, Changed, Fixed subsections as appropriate
+- Upgrade Notes are included if there are breaking changes or manual migration steps
+- The `## [Unreleased]` section above it is empty or ready for the next cycle
+
+If the CHANGELOG section is missing or incomplete, **stop and ask the user**. Do not fabricate release notes.
+
+### Step 8: Commit the version bump
+
+```bash
+git add lib/claude_memory/version.rb .claude-plugin/plugin.json .claude-plugin/marketplace.json Gemfile.lock
+git commit -m "[Release] Bump version to X.Y.Z"
+```
+
+Do NOT push yet. Report what was committed and proceed to Phase 2.
+
+## Phase 2: Publish (User-Driven)
+
+This phase involves pushing to a shared remote and publishing to RubyGems. These are **irreversible shared-state operations** — never execute them automatically.
+
+Tell the user:
+
+> Version X.Y.Z is prepared and committed locally. To publish:
+>
+> ```bash
+> git push origin main
+> rake release
+> ```
+>
+> `rake release` will create the git tag, build the gem, and push to RubyGems. Let me know when that's done and I'll create the GitHub release.
+
+Wait for the user to confirm before proceeding to Phase 3.
+
+## Phase 3: Announce
+
+### Step 9: Fix any stale "Latest" flags on GitHub releases
+
+Check current release state:
+
+```bash
+gh release list --limit 5
+```
+
+If an older release is incorrectly marked "Latest" (this happens when releases are created out of order or with `--latest` set manually):
+
+```bash
+gh release edit v<old-version> --latest=false
+```
+
+### Step 10: Create the GitHub release
+
+Extract the release notes from CHANGELOG.md — everything between `## [X.Y.Z]` and the next `## [` heading. Write to a temp file:
+
+```bash
+# Extract the section between the new version header and the next version header
+sed -n '/^## \[X\.Y\.Z\]/,/^## \[/{ /^## \[X\.Y\.Z\]/d; /^## \[/d; p; }' CHANGELOG.md > /tmp/release-notes.md
+```
+
+Create the release:
+
+```bash
+gh release create vX.Y.Z \
+  --title "vX.Y.Z — Short descriptive title" \
+  --latest \
+  --verify-tag \
+  --notes-file /tmp/release-notes.md
+```
+
+The title should capture the theme of the release in a few words (e.g., "Predicate Design Overhaul, Reject/Restore, Telemetry"). Read the CHANGELOG to derive this — don't ask the user unless the theme isn't obvious.
+
+### Step 11: Verify the release
+
+```bash
+gh release list --limit 5
+```
+
+Confirm:
+- The new release appears at the top
+- It's marked "Latest"
+- No older release is incorrectly marked "Latest"
+
+Report the release URL to the user.
+
+## Error Handling
+
+- **Tests fail**: Fix first. Never release with failing tests.
+- **CHANGELOG missing**: Ask the user. Never fabricate release notes.
+- **Version already tagged**: The tag may exist from a prior attempt. Ask the user whether to delete and recreate, or use a different version.
+- **`gh` not available**: Tell the user to create the GitHub release manually, providing the release notes content.
+- **`rake release` fails**: Common causes: not logged into RubyGems, tag already exists, uncommitted changes. Help the user diagnose but don't retry automatically.

data/.claude-plugin/marketplace.json

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

data/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-memory",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Long-term memory for Claude Code. Recalls architecture, conventions, and decisions across sessions — so Claude explains your codebase without file traversal, follows your patterns, and never re-asks what it already learned.",
   "author": {
     "name": "Valentino Stoll",

data/CHANGELOG.md

@@ -4,6 +4,98 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-04-28
+
+### Added
+
+**Dashboard — feed-first redesign with observability built in**
+
+- New feed-first dashboard UI with scope-aware moments, fact detail modal, query tester, and activity drilldown. Reuse, Trust, Knowledge, Conflicts, and Moments panels each backed by a dedicated module (`Dashboard::{Reuse, Trust, Knowledge, Conflicts, Moments}`) under unit tests, replacing the prior all-in-API-class layout.
+- 👍/👎 feedback on individual moments with persisted verdicts (schema v16, `moment_feedback` table). Trust panel surfaces a 30-day up/down ratio so the dashboard can answer "when memory surfaces something, are users marking it useful?".
+- Utilization ratio panel — of facts extracted in the last 30 days, how many has Claude actually used in a recall or context injection? Color-coded (green ≥40%, yellow ≥15%, red below). Hidden on fresh installs to avoid misleading zeros.
+- Conflict deduping at the display layer: identical (subject, predicate, object_pair) detections collapse into one row with a `×N` badge. Sidebar "Needs review" count now reflects distinct contradictions, not raw row count.
+- Activity events drilldown: each moment opens a payload modal with prettified JSONL, recall trigger correlation (which user prompt motivated this lookup), and linked-fact resolution scoped per database.
+- Vector index health threshold and clickable remediation hints in the health dashboard.
+
+**CLI — observability surfaces and one-shot cleanups**
+
+- `claude-memory digest [--since DAYS] [--output FILE]` — weekly markdown report. Sections: Activity, New knowledge by predicate, Utilization (extracted vs used), Conflicts, Feedback. No new schema; renders from existing aggregates.
+- `claude-memory census [--root DIR]` — privacy-safe cross-project vocabulary scan. Aggregates per-DB predicate × status counts, novel predicates, synonym candidates. Suppresses object literals, entity names, and paths; per-DB IDs are SHA256-prefixed.
+- `claude-memory dedupe-conflicts [--scope SCOPE] [--dry-run]` — one-shot cleanup for historical conflict-row duplication that predates the Resolver dedup fix (commit f571ba4). Groups by (subject, predicate, normalized object pair), keeps the earliest, migrates provenance to the keeper.
+- `claude-memory reclassify-references [--scope SCOPE] [--dry-run]` — retags active convention facts that the new `Distill::ReferenceMaterialDetector` flags as reference material (LOC counts, star counts, "X is a plugin..." templates, "by Firstname Lastname" attributions).
+
+**Memory quality**
+
+- Access-based staleness scoring (improvements.md #35). Schema v17 adds `last_recalled_at` to facts. `Sweep::RecallTimestampRefresher` derives the field periodically from activity_events; `claude-memory stats --stale [--stale-days N]` lists facts that haven't been recalled inside the threshold. Replaces the prior "active facts minus seen-in-recalls" approximation.
+- Auto-memory mirror (improvements.md #36). On fresh sessions, the SessionStart context hook scans `~/.claude/projects/<slug>/memory/*.md` and surfaces new or changed entries as extraction candidates so users can promote auto-memory observations into claude_memory without manual copy-paste.
+- Reasoning requirement enforced in distillation (improvements.md #34). The SessionStart prompt and the `/distill-transcripts` skill now require a why clause for `decision` and `convention` predicates ("because…", "so that…", etc.). Audit found ~75% of facts were bare conclusions before this change.
+- `Distill::ReferenceMaterialDetector` reclassifies convention facts whose object text matches reference patterns. New `reference` predicate registered in `PredicatePolicy` with its own `:references` snapshot section. Detector runs at write time in `ManagementHandlers#store_extraction` so mislabeling can't persist.
+- Predicate census command (#30) for cross-project vocabulary audits — see CLI section above.
+
+**Benchmarks and observability**
+
+- Repeat-correction benchmark harness (improvements.md #32). `spec/benchmarks/e2e/repeat_correction_spec.rb` pre-loads a past correction as a memory fact, runs the prompt through real Claude under `EVAL_MODE=real`, and reports pass rate (no violation patterns matched). Starter set of 2 scenarios drawn from this project's recurring gotchas.
+- Relevance ratio metric (improvements.md #31). `Hook::ContextInjector#emitted_subjects` exposes the subjects injected at SessionStart; `BenchmarkHelpers::RelevanceMetrics` measures whether they appear in Claude's response. Trend signal for memory-application quality, integrated into `devmemeval_spec.rb`.
+- MCP server embeds the V=R/C ("Verify before Recommend / Correct") mental model in agent instructions so memory recommendations come with built-in verification cues.
+
+**Schema v15 → v17 (additive only, automatic on first run)**
+
+- Migration 015: adds `activity_events` table for hook/recall/context/sweep telemetry. Powers the dashboard timeline, moments feed, and efficacy reports.
+- Migration 016: adds `moment_feedback` table (unique on event_id) for the dashboard 👍/👎 surface.
+- Migration 017: adds nullable `facts.last_recalled_at` for access-based staleness scoring.
+
+**1.0 readiness track**
+
+- New `docs/1_0_punchlist.md` opens the path to 1.0: token-budget telemetry, hallucination-rate metric, negative-fact harm benchmark, CLAUDE.md baseline publication, `claude-memory show`, benchmark scoreboard. Ten entries (#47-56) added to `docs/improvements.md` with concrete file:line plumbing notes.
+
+### Changed
+
+- `Resolver#apply_conflict` no longer creates a duplicate disputed fact + conflict row when the same contradicting value is re-extracted. Looks up disputed facts in the same (subject, predicate) slot and reinforces with provenance instead.
+- `Resolver` no longer treats the distiller's `scope_hint` as a scope override. `scope_hint` is advisory metadata; `fact.scope` must match the DB the row lives in. Earlier behavior caused scope leakage where global-hinted distillations landed in the project DB.
+- `Hook::ContextInjector` adds `emitted_fact_ids` and `emitted_subjects` accessors so benchmark harnesses can attribute injection contributions per session.
+- `SQLiteStore` decomposed via module inclusion: `LLMCache` and `MetricsAggregator` extracted into `lib/claude_memory/store/`. SQLiteStore back under 600 LOC.
+- `Dashboard::API` decomposed: `FactPresenter`, `Conflicts`, `Efficacy::Reporter`, `Timeline`, `Health` extracted into dedicated classes following the boundary pattern. API now routes/delegates rather than aggregating.
+- Dashboard releases DB connections after each HTTP request (was holding connections open for the lifetime of the WEBrick session).
+- `Sweep::Maintenance` gains `dedupe_open_conflicts` and `reclassify_references` for the one-shot CLI commands above.
+- Round-trip migration specs from v12, v13, v14 → v17 (per-version migrations covered by `spec/claude_memory/store/migrations/`). Codifies the release-blocker convention: any schema bump must round-trip from each prior major-release boundary back ~3 releases.
+
+### Fixed
+
+- Dashboard surfaces an actionable hint when Recall hits FTS5 corruption (run `claude-memory compact` rather than a generic error).
+- Dashboard query tester unwraps the nested Recall result shape rather than printing the raw envelope.
+- Dashboard health checks correctly detect the claude-memory hook installation across the two-level Claude Code hooks structure (was reporting false negatives when hooks were installed under a matcher block).
+- Dashboard Efficacy "this session" correlation falls back to a time window when the recall event has no `session_id` (MCP tool calls don't thread session_id).
+- Bulk-reject in the Conflicts modal now retries with an actionable message when the server-side state is stale.
+
+### Upgrade Notes
+
+**Schema bump v14 → v17.** Three migrations run automatically on first launch after upgrade. All three are additive (no existing data is rewritten):
+
+1. Migration 015 creates `activity_events` (hook/recall telemetry).
+2. Migration 016 creates `moment_feedback` (dashboard verdicts).
+3. Migration 017 adds `facts.last_recalled_at` (NULL by default; `Sweep::RecallTimestampRefresher` populates it on the next sweep cycle from existing activity_events).
+
+The migration delta has round-trip spec coverage in `spec/claude_memory/store/migrations/`. Forward-compatibility: 0.10.0 databases cannot be opened by 0.9.x or earlier. Downgrade is destructive — back up `~/.claude/memory.sqlite3` and `.claude/memory.sqlite3` before downgrading.
+
+**Optional historical cleanups.** Two new admin commands address data tails left by earlier bugs that have since been fixed at the source:
+
+```bash
+claude-memory dedupe-conflicts --dry-run   # preview duplicate conflict rows
+claude-memory dedupe-conflicts             # consolidate them
+claude-memory reclassify-references --dry-run   # preview reference-material mislabels
+claude-memory reclassify-references             # retag them
+```
+
+Both are opt-in. Neither runs in the regular sweep cycle. Use `--scope global` to clean the global DB.
+
+**Telemetry footprint.** The `activity_events` table grows with hook activity. The dashboard surfaces this by default and powers the timeline/moments/efficacy panels. Retention pruning is not yet automatic (planned for a follow-up); manual cleanup via `DELETE FROM activity_events WHERE occurred_at < ?` is safe — the dashboard tolerates missing history.
+
+## [0.9.1] - 2026-04-16
+
+### Fixed
+
+- MCP server now conforms to JSON-RPC 2.0: notifications (messages without an `id`) never receive a response. Previously, `notifications/initialized` — which Claude Code sends after every handshake — triggered a spurious `Method not found` error frame, causing strict MCP clients to mark the server failed on `/mcp` reconnect after the initial connection.
+
 ## [0.9.0] - 2026-04-16
 
 ### Added

data/CLAUDE.md

@@ -163,7 +163,7 @@ New MCP tools `memory.undistilled` and `memory.mark_distilled` support the pipel
   - Each command is a separate class (HelpCommand, DoctorCommand, etc.)
   - All commands inherit from BaseCommand
   - Dependency injection for I/O (stdout, stderr, stdin)
-  - 28 commands total, each focused on single responsibility
+  - 32 commands total, each focused on single responsibility
 
 - **`Configuration`**: Centralized ENV access (`configuration.rb`)
   - Single source of truth for paths and environment variables
@@ -208,6 +208,8 @@ New MCP tools `memory.undistilled` and `memory.mark_distilled` support the pipel
 - **`Distill`**: Fact extraction interface (`distill/`)
   - Pluggable distiller design (current: NullDistiller stub)
   - Extracts entities, facts, scope hints from content
+  - `ReferenceMaterialDetector`: classifies "X is a plugin/library/tool" templates, LOC counts, "by Firstname Lastname" attributions as reference material. Runs in `ManagementHandlers#store_extraction` so mislabeling can't persist
+  - SessionStart distillation prompt enforces reason clauses ("because…", "so that…") for `decision` and `convention` predicates — bare conclusions are explicitly disallowed
 
 - **`Resolve`**: Truth maintenance and conflict resolution (`resolve/`)
   - Determines equivalence, supersession, or conflicts
@@ -226,7 +228,7 @@ New MCP tools `memory.undistilled` and `memory.mark_distilled` support the pipel
   - Modes: shared (repo), local (uncommitted), home (user directory)
 
 - **`MCP`**: Model Context Protocol server and tools (`mcp/`)
-  - Exposes memory tools to Claude Code (24 tools total)
+  - Exposes memory tools to Claude Code (25 tools total)
   - `Telemetry`: Records tool invocations to `mcp_tool_calls` table for usage stats
   - Dual content/structuredContent responses with compact mode
 
@@ -234,6 +236,7 @@ New MCP tools `memory.undistilled` and `memory.mark_distilled` support the pipel
   - Reads stdin JSON from Claude Code hooks
   - Routes to ingest/sweep/publish commands
   - `DistillationRunner`: Manages context hook injection with undistilled content for LLM extraction
+  - `AutoMemoryMirror` (0.10.0): On fresh sessions, scans `~/.claude/projects/<slug>/memory/*.md` for new/changed entries and surfaces them as extraction candidates in the SessionStart context. State diffed by md5 in `.claude/auto_memory_mirror.json`; bounded to 5 candidates per session, 1500 chars each.
 
 ### Database Schema
 
@@ -246,16 +249,19 @@ Key tables (defined in `sqlite_store.rb`):
 - `fact_links`: Supersession and conflict relationships
 - `conflicts`: Open contradictions
 - `mcp_tool_calls`: MCP server tool invocation telemetry (schema v13)
+- `activity_events`: Hook/recall/context/sweep telemetry (schema v15) — powers the dashboard timeline, moments feed, efficacy reports
+- `moment_feedback`: Per-moment 👍/👎 verdicts with optional notes (schema v16) — unique on event_id, repeat clicks upsert
 
 Facts include:
 - `scope`: "global" or "project" (determines applicability)
 - `project_path`: Set for project-scoped facts
 - `valid_from`/`valid_to`: Temporal validity window
+- `last_recalled_at` (schema v17): Set by `Sweep::RecallTimestampRefresher` from activity_events; powers `claude-memory stats --stale` and the dashboard's "stale" needs-review count
 
 ### Scope System
 
 Facts are scoped to control where they apply:
-- **project**: Current project only (e.g., "this app uses PostgreSQL")
+- **project**: Current project only (e.g., "claude_memory uses SQLite for storage")
 - **global**: All projects (e.g., "I prefer 4-space indentation")
 
 Distiller detects signals like "always", "in all projects", "my preference" and sets `scope_hint: "global"`. Users can manually promote facts via `claude-memory promote <fact_id>` or the `memory.promote` MCP tool.
@@ -340,14 +346,14 @@ Also update `SECTION_MAP` if the predicate should appear in a specific snapshot
 
 The gem includes an MCP server (`claude-memory serve-mcp`) that exposes memory operations as tools. Configuration should be in `.mcp.json` at project root.
 
-Available MCP tools (24 total):
+Available MCP tools (25 total):
 - **Query & Recall**: `memory.recall`, `memory.recall_index`, `memory.recall_details`, `memory.recall_semantic`, `memory.search_concepts`
 - **Provenance**: `memory.explain`, `memory.fact_graph`
 - **Shortcuts**: `memory.decisions`, `memory.conventions`, `memory.architecture`
 - **Context**: `memory.facts_by_tool`, `memory.facts_by_context`
 - **Management**: `memory.promote`, `memory.reject_fact`, `memory.store_extraction`
 - **Distillation**: `memory.undistilled`, `memory.mark_distilled`
-- **Monitoring**: `memory.status`, `memory.stats`, `memory.changes`, `memory.conflicts`
+- **Monitoring**: `memory.status`, `memory.stats`, `memory.changes`, `memory.conflicts`, `memory.activity`
 - **Maintenance**: `memory.sweep_now`
 - **Discovery**: `memory.check_setup`, `memory.list_projects`
 
@@ -369,6 +375,16 @@ ClaudeMemory integrates with Claude Code via hooks in `.claude/settings.json`:
 
 Hook commands read JSON payloads from stdin for robustness. Supports `--async` flag for non-blocking execution.
 
+## Dashboard
+
+Local web UI for inspecting memory state. Started via `claude-memory dashboard` (default port 3377). Reads from both global and project databases; no write side effects from page loads.
+
+The dashboard is a thin web layer over the same `Recall`/`Conflicts`/`Trust`/`Moments`/`Knowledge`/`Reuse`/`Health`/`Timeline` classes the MCP server uses. Each panel is backed by a dedicated module under `lib/claude_memory/dashboard/`; `Dashboard::API` holds HTTP-shape glue and per-endpoint formatting (delegating non-trivial logic to the panel classes).
+
+Connections are released after each request — never holds a WAL writer lock open across page loads.
+
+See [docs/dashboard.md](docs/dashboard.md) for the user-facing guide (panels, common workflows, related CLI commands).
+
 ## Code Style
 
 This project uses [Standard Ruby](https://github.com/standardrb/standard) for linting. Run `bundle exec rake standard:fix` before committing.

data/README.md

@@ -140,6 +140,35 @@ File-searchable questions ("what version is this?") and one-shot code generation
 - **Claude-Powered**: Uses Claude's intelligence to extract facts (no API key needed)
 - **Token Efficient**: 10x reduction in memory queries with progressive disclosure
 - **Database Maintenance**: Compact, export, and backup commands
+- **Built-in Observability** (0.10.0+): `claude-memory dashboard` opens a local web UI with a moments feed, trust panel, conflicts dedup, knowledge index, 👍/👎 feedback, and a 30-day utilization ratio. See **[Dashboard guide →](docs/dashboard.md)**. `claude-memory digest` writes a weekly markdown report; `claude-memory census` audits the predicate vocabulary across projects.
+
+## What's New in 0.10.0
+
+Three behavior changes worth knowing about — they affect what you'll see in
+extracted facts and SessionStart context, even if you don't change anything:
+
+- **Auto-memory mirror** — On fresh sessions, the SessionStart context hook
+  scans `~/.claude/projects/<slug>/memory/*.md` and surfaces new or changed
+  entries as candidates for extraction into ClaudeMemory. You'll see a
+  "Pending Knowledge Extraction" section in Claude's startup context citing
+  files from your auto-memory directory. Claude reviews these and calls
+  `memory.store_extraction` for the high-signal ones; you don't need to
+  copy-paste manually anymore.
+- **Why-clause enforcement** — When Claude distills `decision` and
+  `convention` facts, it's now required to embed a reason ("…because…",
+  "…so that…", "…to avoid…"). A bare conclusion is dead weight; a fact with
+  a reason stays useful when the situation changes. You'll see this
+  reflected in fact text being longer and more justified.
+- **Reference predicate** — Active facts that look like reference material
+  (LOC counts, "X is a plugin/library/tool" templates, "by Firstname
+  Lastname" attributions) are auto-tagged `predicate=reference` instead of
+  `convention`. Keeps the conventions list signal-rich. Browse them in the
+  dashboard's Knowledge → References section, or run
+  `claude-memory reclassify-references --dry-run` to see candidates.
+
+Plus: **staleness detection** (`claude-memory stats --stale`) lists active
+facts that haven't been recalled in N days, so you can prune dead weight
+explicitly. The dashboard's Trust → Needs review panel surfaces the count.
 
 ## Privacy Control
 
@@ -241,7 +270,8 @@ The uninstall command removes:
 
 - 📖 [Getting Started](docs/GETTING_STARTED.md) - Step-by-step onboarding
 - 💡 [Examples](docs/EXAMPLES.md) - Use cases and workflows
-- 🔧 [Plugin Setup](docs/PLUGIN.md) - Claude Code integration
+- 📊 [Dashboard](docs/dashboard.md) - Local web UI for inspection and trust signals (0.10.0+)
+- 🔧 [Plugin Setup](docs/plugin.md) - Claude Code integration
 - 🏗️ [Architecture](docs/architecture.md) - Technical deep dive
 - 📝 [Changelog](CHANGELOG.md) - Release notes
 
@@ -292,7 +322,7 @@ The benchmark dataset draws from real CLAUDE.md patterns and is designed specifi
 
 - **Language:** Ruby 3.2+
 - **Storage:** SQLite3 (no external services)
-- **Testing:** 1477 examples (1375 unit/integration + 102 benchmarks/evals), 100% core coverage
+- **Testing:** 1964 examples (~1700 unit/integration + ~250 benchmarks/evals), 100% core coverage
 - **Code Style:** Standard Ruby
 
 ```bash

data/db/migrations/015_add_activity_events.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Migration v15: Add activity_events table for debugging and observability
+# Tracks hook executions, memory recalls, context injections, and sweep operations.
+# Powers the dashboard timeline and efficacy reports.
+Sequel.migration do
+  up do
+    create_table?(:activity_events) do
+      primary_key :id
+      String :event_type, null: false    # "hook_ingest", "hook_context", "hook_sweep", "recall", "store_extraction"
+      String :session_id                 # Claude session that triggered the event
+      String :status, null: false        # "success", "skipped", "error"
+      Integer :duration_ms               # How long the operation took
+      String :detail_json, text: true    # Event-specific details (JSON)
+      String :occurred_at, null: false   # ISO 8601 timestamp
+    end
+
+    run "CREATE INDEX IF NOT EXISTS idx_activity_events_type ON activity_events(event_type)"
+    run "CREATE INDEX IF NOT EXISTS idx_activity_events_occurred_at ON activity_events(occurred_at)"
+    run "CREATE INDEX IF NOT EXISTS idx_activity_events_session ON activity_events(session_id)"
+  end
+
+  down do
+    drop_table?(:activity_events)
+  end
+end

data/db/migrations/016_add_moment_feedback.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Migration v16: Per-moment feedback (improvements.md #43).
+# Tracks a single thumbs-up/down verdict (+ optional note) per activity_event
+# so the dashboard can surface a trust-calibration signal. Unique on event_id
+# so a given moment has at most one current verdict; repeat clicks upsert.
+Sequel.migration do
+  up do
+    create_table?(:moment_feedback) do
+      primary_key :id
+      Integer :event_id, null: false
+      String :verdict, null: false  # "up" | "down"
+      String :note, text: true      # optional freeform note
+      String :recorded_at, null: false
+      index :event_id, unique: true
+    end
+  end
+
+  down do
+    drop_table?(:moment_feedback)
+  end
+end

data/db/migrations/017_add_last_recalled_at.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Migration v17: Access-based staleness scoring (improvements.md #35).
+# Records the last time a fact was surfaced via memory.recall or context
+# injection, derived periodically from activity_events. Sweep-derived rather
+# than per-call so we avoid WAL write contention on the recall hot path.
+Sequel.migration do
+  up do
+    add_column :facts, :last_recalled_at, String
+  end
+
+  down do
+    drop_column :facts, :last_recalled_at
+  end
+end