claude_memory 0.13.0 → 0.13.2

data/lib/claude_memory/observe/reflector.rb

@@ -11,8 +11,12 @@ module ClaudeMemory
     # timer (Claude Code has no cron hook) and without extra API cost.
     #
     # Two passes, both provenance-preserving (tombstone, never hard-delete):
-    #   - dedupe: collapse near-identical active observations (same scope,
-    #     normalized body) into the newest, linking losers via consolidated_into.
+    #   - dedupe: collapse near-duplicate active observations (same scope) into
+    #     the newest, linking losers via consolidated_into. Similarity is decided
+    #     by an injected matcher (default: lexical token-overlap, #73) so the
+    #     promotion gate can actually accumulate corroboration — exact-string
+    #     matching never folded varied wording, leaving every observation at
+    #     corroboration 1 (the 2026-06-23 audit finding).
     #   - expire_stale_info: retire info-level (🟢 / priority 3) observations
     #     older than the TTL to bound context size. Important (🔴) and maybe
     #     (🟡) are never expired — only the lowest-signal tier ages out.
@@ -31,9 +35,10 @@ module ClaudeMemory
         end
       end
 
-      def initialize(store, info_ttl_days: DEFAULT_INFO_TTL_DAYS)
+      def initialize(store, info_ttl_days: DEFAULT_INFO_TTL_DAYS, matcher: TokenOverlapMatcher.new)
         @store = store
         @info_ttl_days = info_ttl_days
+        @matcher = matcher
       end
 
       # @return [Result] number of observations deduped and expired
@@ -51,21 +56,36 @@ module ClaudeMemory
 
       def dedupe
         active = @store.observations.where(status: "active").order(:id).all
+        active.group_by { |o| o[:scope] }.sum { |_scope, rows| dedupe_scope(rows) }
+      end
+
+      # Greedy clustering within one scope: the newest observation in a cluster
+      # is the keeper; older near-duplicates fold into it. O(n²) matcher calls,
+      # but n is bounded (#74 cut the inflow; expire_stale_info bounds the tail).
+      def dedupe_scope(rows)
+        return 0 if rows.size < 2
+
+        ordered = rows.sort_by { |r| [r[:observed_at].to_s, r[:id]] }.reverse
+        folded = {}
         merged = 0
 
-        active.group_by { |o| [o[:scope], normalize(o[:body])] }.each_value do |rows|
-          next if rows.size < 2
+        ordered.each do |keeper|
+          next if folded[keeper[:id]]
+
+          ordered.each do |other|
+            next if other[:id] == keeper[:id] || folded[other[:id]]
+            next unless @matcher.similar?(keeper[:body], other[:body])
 
-          keeper = rows.max_by { |r| [r[:observed_at].to_s, r[:id]] }
-          rows.each do |loser|
-            next if loser[:id] == keeper[:id]
-            # Fold the loser's sightings into the keeper before tombstoning so
-            # corroboration survives consolidation and can cross the promotion
+            # Fold the duplicate's sightings into the keeper before tombstoning
+            # so corroboration survives consolidation and can cross the promotion
             # threshold. A duplicate IS a repeated sighting.
-            @store.increment_corroboration(keeper[:id], by: loser[:corroboration_count] || 1)
-            @store.tombstone_observation(loser[:id], into_id: keeper[:id])
+            @store.increment_corroboration(keeper[:id], by: other[:corroboration_count] || 1)
+            @store.tombstone_observation(other[:id], into_id: keeper[:id])
+            folded[other[:id]] = true
             merged += 1
           end
+
+          folded[keeper[:id]] = true
         end
 
         merged
@@ -82,10 +102,6 @@ module ClaudeMemory
         ids.each { |id| @store.expire_observation(id) }
         ids.size
       end
-
-      def normalize(body)
-        body.to_s.downcase.gsub(/\s+/, " ").strip
-      end
     end
   end
 end

data/lib/claude_memory/observe/token_overlap_matcher.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Observe
+    # Default observation-similarity matcher: lexical token-overlap (Jaccard).
+    #
+    # Deterministic, free, no embedding dependency — so it runs shell-side in
+    # the Reflector's sweep pass at no extra cost. Two bodies are "the same
+    # sighting" when their significant-word sets overlap past the threshold.
+    # This folds the common case (one event re-observed with slightly different
+    # wording — "PreCompact hook set." / "PreCompact hook set — the design
+    # analog", Jaccard 0.6) while keeping unrelated observations apart (distinct
+    # developer statements share ~no content words → Jaccard ~0).
+    #
+    # It does NOT capture pure synonym paraphrases ("use SQLite" vs "chose
+    # SQLite") — no free lexical method can on short text (measured 2026-06-23:
+    # tfidf cosine 0.32 for that pair, indistinguishable from unrelated pairs
+    # at 0.13). For paraphrase folding, inject a semantic matcher backed by real
+    # embeddings: the Reflector accepts any object responding to
+    # `similar?(body_a, body_b)`.
+    class TokenOverlapMatcher
+      DEFAULT_THRESHOLD = 0.5
+
+      # Function words carry no episodic signal; dropping them focuses the
+      # overlap on subject/verb content.
+      STOPWORDS = %w[
+        a an the to of in on at for and or but we i it is are was were be been
+        this that these those with as by from into our your their its do does
+      ].to_set.freeze
+
+      def initialize(threshold: DEFAULT_THRESHOLD)
+        @threshold = threshold
+      end
+
+      # @return [Boolean] true when the two bodies are near-duplicate sightings
+      def similar?(body_a, body_b)
+        a = significant_tokens(body_a)
+        b = significant_tokens(body_b)
+        return false if a.empty? || b.empty?
+
+        intersection = (a & b).size.to_f
+        union = (a | b).size
+        (intersection / union) >= @threshold
+      end
+
+      private
+
+      def significant_tokens(body)
+        body.to_s.downcase.scan(/[a-z0-9]+/)
+          .reject { |word| word.length < 2 || STOPWORDS.include?(word) }
+          .to_set
+      end
+    end
+  end
+end

data/lib/claude_memory/sweep/maintenance.rb

@@ -408,6 +408,28 @@ module ClaudeMemory
         {deduped: result.deduped, expired: result.expired}
       end
 
+      # Self-heal the FTS5 rank index (improvement #69). Concurrent writers
+      # (the ingest hook vs the MCP server) can leave content_fts in a state
+      # where plain MATCH works but `ORDER BY rank` raises "malformed" —
+      # silently breaking recall while integrity_check passes. Sweep runs on
+      # PreCompact/SessionEnd, so probing the rank path here and rebuilding on
+      # failure lets recall self-repair within the session that broke it, with
+      # no manual `claude-memory compact`. (Detection is also surfaced by the
+      # doctor FtsRankCheck; this is the automatic repair.) A rebuild on a very
+      # large index runs to completion — corruption is rare and the rebuild is
+      # the only fix; the per-step budget gate keeps it from *starting* late.
+      # Returns: true if a rebuild was performed, false otherwise.
+      def repair_fts_rank
+        fts = ClaudeMemory::Index::LexicalFTS.new(@store)
+        fts.search("a", limit: 1)
+        false
+      rescue ClaudeMemory::Index::LexicalFTS::CorruptRankIndexError
+        fts.rebuild!
+        true
+      rescue
+        false
+      end
+
       # Run SQLite VACUUM to reclaim space.
       # Returns: true
       def vacuum

data/lib/claude_memory/sweep/sweeper.rb

@@ -57,6 +57,7 @@ module ClaudeMemory
           @stats[:observations_deduped] = reflection[:deduped]
           @stats[:observations_expired] = reflection[:expired]
         end
+        run_if_within_budget { @stats[:fts_rank_repaired] = maintenance.repair_fts_rank }
         run_if_within_budget { @stats[:wal_checkpointed] = maintenance.checkpoint_wal }
 
         @stats[:elapsed_seconds] = Time.now - @start_time

data/lib/claude_memory/version.rb

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

data/lib/claude_memory.rb

@@ -40,6 +40,7 @@ require_relative "claude_memory/commands/checks/reporter"
 require_relative "claude_memory/commands/checks/vec_check"
 require_relative "claude_memory/commands/checks/embeddings_check"
 require_relative "claude_memory/commands/checks/distill_check"
+require_relative "claude_memory/commands/checks/fts_rank_check"
 require_relative "claude_memory/commands/help_command"
 require_relative "claude_memory/commands/version_command"
 require_relative "claude_memory/commands/doctor_command"
@@ -126,6 +127,7 @@ require_relative "claude_memory/domain/provenance"
 require_relative "claude_memory/domain/conflict"
 require_relative "claude_memory/domain/observation"
 require_relative "claude_memory/observe/observations_renderer"
+require_relative "claude_memory/observe/token_overlap_matcher"
 require_relative "claude_memory/observe/reflector"
 require_relative "claude_memory/embeddings/model_registry"
 require_relative "claude_memory/embeddings/inspector"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_memory
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.13.2
 platform: ruby
 authors:
 - Valentino Stoll
@@ -90,30 +90,6 @@ files:
 - ".claude-plugin/scripts/hook-runner.sh"
 - ".claude-plugin/scripts/serve-mcp.sh"
 - ".claude.json"
-- ".claude/CLAUDE.md"
-- ".claude/memory.sqlite3"
-- ".claude/output-styles/memory-aware.md"
-- ".claude/rules/claude_memory.generated.md"
-- ".claude/settings.json"
-- ".claude/settings.local.json"
-- ".claude/skills/check-memory/DEPRECATED.md"
-- ".claude/skills/check-memory/SKILL.md"
-- ".claude/skills/dashboard/SKILL.md"
-- ".claude/skills/debug-memory"
-- ".claude/skills/improve/SKILL.md"
-- ".claude/skills/improve/feature-patterns.md"
-- ".claude/skills/memory-first-workflow"
-- ".claude/skills/quality-update/SKILL.md"
-- ".claude/skills/quality-update/implementation-guide.md"
-- ".claude/skills/release/SKILL.md"
-- ".claude/skills/review-commit/SKILL.md"
-- ".claude/skills/review-for-quality/SKILL.md"
-- ".claude/skills/review-for-quality/expert-checklists.md"
-- ".claude/skills/setup-memory"
-- ".claude/skills/study-repo/SKILL.md"
-- ".claude/skills/study-repo/analysis-template.md"
-- ".claude/skills/study-repo/focus-examples.md"
-- ".claude/skills/upgrade-dependencies/SKILL.md"
 - ".gitattributes"
 - ".lefthook/map_specs.rb"
 - ".mcp.json"
@@ -217,6 +193,7 @@ files:
 - lib/claude_memory/commands/checks/database_check.rb
 - lib/claude_memory/commands/checks/distill_check.rb
 - lib/claude_memory/commands/checks/embeddings_check.rb
+- lib/claude_memory/commands/checks/fts_rank_check.rb
 - lib/claude_memory/commands/checks/hooks_check.rb
 - lib/claude_memory/commands/checks/reporter.rb
 - lib/claude_memory/commands/checks/snapshot_check.rb
@@ -368,6 +345,7 @@ files:
 - lib/claude_memory/mcp/tools.rb
 - lib/claude_memory/observe/observations_renderer.rb
 - lib/claude_memory/observe/reflector.rb
+- lib/claude_memory/observe/token_overlap_matcher.rb
 - lib/claude_memory/otel/attributes.rb
 - lib/claude_memory/otel/constants.rb
 - lib/claude_memory/otel/ingestor.rb

data/.claude/CLAUDE.md

@@ -1,4 +0,0 @@
-<!-- ClaudeMemory v0.7.0 -->
-# Project Memory
-
-@.claude/rules/claude_memory.generated.md

data/.claude/output-styles/memory-aware.md

@@ -1 +0,0 @@
-../../output-styles/memory-aware.md

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

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

data/.claude/settings.json

@@ -1,113 +0,0 @@
-{
-  "hooks": {
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 5,
-            "statusMessage": "Saving memory..."
-          }
-        ]
-      }
-    ],
-    "StopFailure": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 5,
-            "statusMessage": "Saving memory..."
-          }
-        ]
-      }
-    ],
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "claude-memory hook context",
-            "timeout": 5,
-            "statusMessage": "Loading memory..."
-          }
-        ]
-      }
-    ],
-    "PreCompact": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 30,
-            "statusMessage": "Saving memory..."
-          },
-          {
-            "type": "command",
-            "command": "claude-memory hook sweep --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 30,
-            "statusMessage": "Sweeping memory..."
-          }
-        ]
-      }
-    ],
-    "SessionEnd": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 30,
-            "statusMessage": "Saving memory..."
-          },
-          {
-            "type": "command",
-            "command": "claude-memory hook sweep --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 30,
-            "statusMessage": "Sweeping memory..."
-          }
-        ]
-      }
-    ],
-    "TaskCompleted": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 10,
-            "statusMessage": "Saving memory..."
-          }
-        ]
-      }
-    ],
-    "TeammateIdle": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 15,
-            "statusMessage": "Saving memory..."
-          }
-        ]
-      }
-    ],
-    "Notification": [
-      {
-        "matcher": "idle_prompt",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "claude-memory hook sweep --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 10,
-            "statusMessage": "Sweeping memory..."
-          }
-        ]
-      }
-    ]
-  }
-}

data/.claude/settings.local.json

@@ -1,59 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "mcp__claude-memory__memory_changes",
-      "mcp__claude-memory__memory_status",
-      "mcp__claude-memory__memory_recall",
-      "Bash(./exe/claude-memory:*)",
-      "mcp__claude-memory__memory_store_extraction",
-      "mcp__plugin_claude-memory_claude-memory__memory_store_extraction",
-      "mcp__plugin_claude-memory_claude-memory__memory_recall",
-      "mcp__plugin_claude-memory_claude-memory__memory_status",
-      "mcp__plugin_claude-memory_memory__memory_recall",
-      "mcp__memory__memory_recall",
-      "mcp__memory__memory_changes",
-      "mcp__memory__memory_status",
-      "mcp__memory__memory_store_extraction",
-      "mcp__memory__memory_explain",
-      "Bash(bundle exec rspec:*)",
-      "Bash(bundle exec rake:*)",
-      "mcp__plugin_claude-memory_memory__memory_store_extraction",
-      "WebFetch(domain:raw.githubusercontent.com)",
-      "Bash(grep:*)",
-      "Bash(gem list:*)",
-      "Bash(ag:*)",
-      "Bash(git log:*)",
-      "Bash(find:*)",
-      "Bash(wc:*)",
-      "mcp__plugin_claude-memory_memory__memory_architecture",
-      "mcp__plugin_claude-memory_memory__memory_recall_index",
-      "Bash(./bin/run-evals:*)",
-      "WebSearch",
-      "mcp__memory__memory_check_setup",
-      "WebFetch(domain:docs.anthropic.com)",
-      "Bash(export PATH=\"$HOME/.bun/bin:/usr/bin:/bin:$PATH\")",
-      "Bash(qmd search:*)",
-      "Skill(study-repo)",
-      "WebFetch(domain:www.rubydoc.info)",
-      "Bash(git status:*)",
-      "WebFetch(domain:github.com)",
-      "mcp__memory__memory_stats",
-      "mcp__memory__memory_recall_index",
-      "Bash(mkdir -p /tmp/study-repos)",
-      "Read(//tmp/**)",
-      "Bash(ls:*)",
-      "Bash(sort -k2 -rn)",
-      "Bash(claude-memory recall:*)",
-      "Bash(claude-memory stats:*)",
-      "Bash(claude-memory search:*)",
-      "Bash(bundle exec:*)",
-      "Skill(improve)",
-      "Skill(improve:*)",
-      "WebFetch(domain:arxiv.org)",
-      "mcp__memory__memory_conflicts"
-    ]
-  },
-  "enableAllProjectMcpServers": false,
-  "disabledMcpjsonServers": ["memory"],
-  "outputStyle": "memory-aware"
-}

data/.claude/skills/check-memory/DEPRECATED.md

@@ -1,29 +0,0 @@
-# Deprecated: /check-memory
-
-This skill is **no longer needed** and should not be used.
-
-## Why Deprecated?
-
-The `/check-memory` skill was created to force a "check memory before file exploration" workflow. However, this should be **automatic**, not manual.
-
-## What Replaced It?
-
-The enhanced `memory-aware` output style now handles this automatically by:
-- Explicitly instructing Claude to check memory FIRST before file reads
-- Providing clear workflow: memory.recall → then file exploration if needed
-- Making this behavior persistent across all conversations
-
-## If You Need Debugging
-
-Use `/debug-memory` instead to troubleshoot ClaudeMemory installation issues.
-
-## Migration
-
-If you were using `/check-memory`:
-- **Remove** any references to it
-- **Use** the `memory-aware` output style (automatically applied)
-- **Trust** that Claude will check memory first automatically
-
-## Archive Date
-
-Deprecated: 2026-01-29