claude_memory 0.10.0 → 0.11.0

data/lib/claude_memory/commands/show_command.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module ClaudeMemory
+  module Commands
+    # Prints what memory would inject on the next SessionStart.
+    #
+    # The trust answer to "is this still worth it?" requires
+    # inspectability: a user who can't see what memory will inject can't
+    # develop confidence in it. The CLAUDE.md alternative is `cat
+    # CLAUDE.md` — instant, plain English, no tooling. This command is
+    # the same one-line inspect surface for the curated facts the
+    # injector picks each session.
+    #
+    # Runs the exact `Hook::ContextInjector` path real sessions use, so
+    # what you see here is what Claude actually receives — not a
+    # rebuilt approximation that could drift.
+    #
+    # The default suppresses the "Pending Knowledge Extraction" dump
+    # (which contains raw transcript JSON intended for LLM distillation)
+    # so the output stays human-readable. Pass `--pending` to see the
+    # full fresh-session payload, including those raw items.
+    class ShowCommand < BaseCommand
+      VALID_SOURCES = %w[startup resume clear].freeze
+
+      # Any string outside FRESH_SESSION_SOURCES skips the pending-knowledge
+      # block. "preview" reads naturally in any debug log this surfaces in.
+      NON_FRESH_SOURCE = "preview"
+
+      def call(args)
+        opts = parse_options(args, {source: nil, pending: false}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory show [--source SOURCE] [--pending]"
+            parser.on("--source SOURCE", VALID_SOURCES,
+              "Simulate fresh-session source (#{VALID_SOURCES.join(", ")}). " \
+              "Forces inclusion of pending-knowledge and auto-memory-mirror " \
+              "sections regardless of --pending.") { |v| o[:source] = v }
+            parser.on("--pending",
+              "Include the pending-knowledge dump (raw transcript JSON " \
+              "for LLM distillation). Default suppresses it for readability.") { o[:pending] = true }
+          end
+        end
+        return 1 if opts.nil?
+
+        effective_source = opts[:source] || (opts[:pending] ? nil : NON_FRESH_SOURCE)
+
+        manager = Store::StoreManager.new
+        manager.ensure_both!
+        injector = Hook::ContextInjector.new(manager, source: effective_source)
+        context = injector.generate_context
+
+        print_header(opts[:source])
+        stdout.puts ""
+
+        if context.nil? || context.strip.empty?
+          stdout.puts "_Memory has no facts to inject yet._"
+          stdout.puts ""
+          stdout.puts "Run a few Claude Code sessions in this project, or use"
+          stdout.puts "`memory.store_extraction` from a session to seed facts."
+        else
+          stdout.puts context
+          stdout.puts ""
+          print_footer(injector, context)
+        end
+
+        manager.close
+        0
+      rescue Sequel::DatabaseError => e
+        failure("Database error: #{e.message}")
+      end
+
+      private
+
+      def print_header(source)
+        label = source ? " (source=#{source})" : ""
+        stdout.puts "## Memory snapshot — would be injected at next SessionStart#{label}"
+      end
+
+      def print_footer(injector, context)
+        tokens = Core::TokenEstimator.estimate(context)
+        fact_count = injector.emitted_fact_ids.size
+        stdout.puts "---"
+        stdout.puts "#{fact_count} fact#{"s" unless fact_count == 1} • " \
+          "~#{tokens} token#{"s" unless tokens == 1} • " \
+          "#{context.length} chars"
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/stats_command.rb

@@ -13,14 +13,15 @@ module ClaudeMemory
       SCOPE_PROJECT = "project"
 
       def call(args)
-        opts = parse_options(args, {scope: SCOPE_ALL, tools: false, stale: false, since_days: nil, stale_days: nil}) do |o|
+        opts = parse_options(args, {scope: SCOPE_ALL, tools: false, tokens: false, stale: false, since_days: nil, stale_days: nil}) do |o|
           OptionParser.new do |parser|
             parser.banner = "Usage: claude-memory stats [options]"
             parser.on("--scope SCOPE", ["all", "global", "project"],
               "Show stats for: all (default), global, or project") { |v| o[:scope] = v }
             parser.on("--tools", "Show MCP tool-call usage stats") { o[:tools] = true }
+            parser.on("--tokens", "Show SessionStart context-injection token budget") { o[:tokens] = true }
             parser.on("--stale", "Show facts not recalled in CLAUDE_MEMORY_STALE_DAYS (default 14)") { o[:stale] = true }
-            parser.on("--since DAYS", Integer, "Limit --tools to last N days") { |v| o[:since_days] = v }
+            parser.on("--since DAYS", Integer, "Limit --tools/--tokens to last N days") { |v| o[:since_days] = v }
             parser.on("--stale-days N", Integer, "Override staleness threshold for --stale") { |v| o[:stale_days] = v }
           end
         end
@@ -30,6 +31,10 @@ module ClaudeMemory
           return print_mcp_tool_call_stats(opts[:since_days])
         end
 
+        if opts[:tokens]
+          return print_token_budget_stats(opts[:since_days])
+        end
+
         if opts[:stale]
           return print_stale_facts(opts[:stale_days])
         end
@@ -349,6 +354,93 @@ module ClaudeMemory
         1
       end
 
+      TOKEN_BUCKETS = [
+        ["<500", 0, 500],
+        ["500-1000", 500, 1000],
+        ["1000-2000", 1000, 2000],
+        ["2000-5000", 2000, 5000],
+        ["5000+", 5000, Float::INFINITY]
+      ].freeze
+
+      def print_token_budget_stats(since_days)
+        manager = ClaudeMemory::Store::StoreManager.new
+        db_path = manager.project_db_path
+
+        stdout.puts "SessionStart Context Token Budget"
+        stdout.puts "=" * 50
+
+        unless File.exist?(db_path)
+          stdout.puts "Project database does not exist: #{db_path}"
+          manager.close
+          return 0
+        end
+
+        db = open_readonly(db_path)
+
+        unless db.table_exists?(:activity_events)
+          stdout.puts "No activity telemetry recorded yet."
+          db.disconnect
+          manager.close
+          return 0
+        end
+
+        dataset = db[:activity_events]
+          .where(event_type: "hook_context", status: "success")
+        if since_days
+          cutoff = (Time.now - since_days * 86400).utc.iso8601
+          dataset = dataset.where { occurred_at >= cutoff }
+          stdout.puts "Window: last #{since_days} day#{"s" unless since_days == 1}"
+        else
+          stdout.puts "Window: all time"
+        end
+        stdout.puts
+
+        tokens = dataset.select_map(:detail_json).filter_map do |json|
+          next unless json
+          value = JSON.parse(json)["context_tokens"]
+          value if value.is_a?(Integer) && value > 0
+        end
+
+        if tokens.empty?
+          stdout.puts "No context injections recorded in window."
+          stdout.puts ""
+          stdout.puts "Token telemetry is recorded automatically on SessionStart hooks."
+          stdout.puts "Run a Claude Code session in this project to populate."
+          db.disconnect
+          manager.close
+          return 0
+        end
+
+        sorted = tokens.sort
+        total = sorted.size
+        stdout.puts "Sessions: #{format_number(total)}"
+        stdout.puts "p50: #{format_number(percentile(sorted, 0.50))} tokens"
+        stdout.puts "p95: #{format_number(percentile(sorted, 0.95))} tokens"
+        stdout.puts "Avg: #{format_number((sorted.sum.to_f / total).round)} tokens"
+        stdout.puts "Min: #{format_number(sorted.first)} tokens"
+        stdout.puts "Max: #{format_number(sorted.last)} tokens"
+        stdout.puts ""
+        print_token_distribution(sorted)
+
+        db.disconnect
+        manager.close
+        0
+      rescue Sequel::DatabaseError, JSON::ParserError, Extralite::Error => e
+        stderr.puts "Error reading token telemetry: #{e.message}"
+        1
+      end
+
+      def print_token_distribution(sorted)
+        total = sorted.size
+        stdout.puts "Distribution:"
+        TOKEN_BUCKETS.each do |label, low, high|
+          count = sorted.count { |t| t >= low && t < high }
+          pct = (count * 100.0 / total).round(1)
+          bar = "█" * (pct / 5).round
+          stdout.puts "  #{label.ljust(12)} #{count.to_s.rjust(5)} (#{pct.to_s.rjust(5)}%) #{bar}"
+        end
+      end
+
       def print_per_tool_breakdown(dataset)
         stdout.puts "Per-tool breakdown:"
         stdout.puts "  #{"Tool".ljust(28)} #{"Calls".rjust(7)}  #{"Avg ms".rjust(8)}  #{"P95 ms".rjust(8)}  #{"Err %".rjust(6)}"

data/lib/claude_memory/dashboard/trust.rb

@@ -2,20 +2,37 @@
 
 module ClaudeMemory
   module Dashboard
-    # Sidebar data for the feed-first dashboard. Three things:
+    # Sidebar data for the feed-first dashboard. Six surfaces, each
+    # answering a different "is memory helping/costing/clean?" question:
     #
-    # 1. Moments this week + week-over-week delta — the headline value number.
-    #    A moment is any meaningful activity event (recall hit, extraction,
-    #    context injection, conflict detected). Ingest-only events don't count
-    #    because they're not directly user-visible value.
+    # 1. Moments this week + week-over-week delta — the headline value
+    #    number. A moment is any meaningful activity event (recall hit,
+    #    extraction, context injection, conflict detected). Ingest-only
+    #    events don't count because they're not directly user-visible value.
     #
     # 2. "What memory knows about you" — up to 5 global facts rendered as
-    #    plain English. This is the trust panel's most compelling surface:
-    #    users can sanity-check what's being injected into their sessions.
+    #    plain English. The trust panel's most compelling surface: users
+    #    can sanity-check what's being injected into their sessions.
     #
-    # 3. Needs review — open conflicts plus facts that have gone stale
-    #    (active but never recalled in the last N days). A single actionable
-    #    count; the feed surfaces the individual items.
+    # 3. Needs review — open conflicts plus stale facts (active but never
+    #    recalled in the last N days) plus empty recalls (queries that
+    #    returned nothing). A single actionable count; the feed surfaces
+    #    the individual items.
+    #
+    # 4. Utilization (30d) — of facts extracted in the last 30 days, how
+    #    many has Claude actually surfaced via recall or context injection.
+    #    Low ratios are a signal too: memory accumulating knowledge that
+    #    Claude isn't reaching for.
+    #
+    # 5. Token budget (30d, 0.11.0+) — p50/p95/avg `context_tokens`
+    #    injected per SessionStart. Answers "what does memory cost per
+    #    session?" via numbers a skeptical user can read.
+    #
+    # 6. Quality score (live + historical, 0.11.0+) — hallucination-rate
+    #    proxy: 100 - (suspect_pct + bare_pct), clamped 0..100. Live is
+    #    over the last UTILIZATION_DAYS; historical mirrors the same
+    #    calculation across all active facts as a supplementary baseline.
+    #    See `quality_review.md` 2026-04-30 note for why the split exists.
     class Trust
       WEEK_SECONDS = 7 * 86_400
       UTILIZATION_DAYS = 30
@@ -31,8 +48,160 @@ module ClaudeMemory
           fingerprint: fingerprint,
           needs_review: needs_review,
           utilization: utilization,
-          feedback: feedback_summary
+          feedback: feedback_summary,
+          token_budget: token_budget,
+          quality_score: quality_score
+        }
+      end
+
+      # The trust panel's hallucination-rate proxy. Counts two pollution
+      # signals:
+      #
+      #   - suspect: facts that ReferenceMaterialDetector retagged from
+      #     `convention` to `reference` predicate (descriptions of external
+      #     projects mislabeled as user conventions).
+      #   - bare_conclusion: `decision` / `convention` facts whose object
+      #     skipped the prompt-mandated reason clause and so are dead
+      #     weight once the originating context is gone.
+      #
+      # Reports two windows so users can distinguish historical noise from
+      # live extraction quality (per `quality_review.md` 2026-04-30
+      # investigation): the headline `score` is computed over facts
+      # created within the last UTILIZATION_DAYS — that's the actionable
+      # signal. The `historical` block reports the same counts over all
+      # active facts so legacy data is visible without dominating.
+      #
+      # Score = 100 - (suspect_pct + bare_pct), clamped 0..100. Lower is
+      # worse. Returns 100 (perfect) when there are no facts in the
+      # window so a quiet week isn't penalized.
+      def quality_score
+        cutoff = (Time.now.utc - UTILIZATION_DAYS * 86_400).iso8601
+        live = compute_quality(cutoff: cutoff)
+        historical = compute_quality(cutoff: nil)
+
+        live.merge(
+          window_days: UTILIZATION_DAYS,
+          historical: historical
+        )
+      rescue Sequel::DatabaseError => e
+        ClaudeMemory.logger.debug("Trust#quality_score failed: #{e.message}")
+        quality_score_zero
+      end
+      public :quality_score
+
+      def quality_score_zero
+        {
+          total_active: 0,
+          suspect_count: 0,
+          bare_conclusion_count: 0,
+          suspect_pct: 0.0,
+          bare_pct: 0.0,
+          score: 100,
+          window_days: UTILIZATION_DAYS,
+          historical: {
+            total_active: 0,
+            suspect_count: 0,
+            bare_conclusion_count: 0,
+            suspect_pct: 0.0,
+            bare_pct: 0.0,
+            score: 100
+          }
+        }
+      end
+
+      def compute_quality(cutoff:)
+        breakdown = aggregate_quality_counts(cutoff: cutoff)
+        total = breakdown[:total_active]
+
+        return zero_breakdown if total.zero?
+
+        suspect_pct = (breakdown[:suspect_count] * 100.0 / total).round(1)
+        bare_pct = (breakdown[:bare_conclusion_count] * 100.0 / total).round(1)
+        score = (100 - (suspect_pct + bare_pct)).clamp(0, 100).round
+
+        breakdown.merge(
+          suspect_pct: suspect_pct,
+          bare_pct: bare_pct,
+          score: score
+        )
+      end
+
+      def zero_breakdown
+        {total_active: 0, suspect_count: 0, bare_conclusion_count: 0,
+         suspect_pct: 0.0, bare_pct: 0.0, score: 100}
+      end
+
+      def aggregate_quality_counts(cutoff: nil)
+        detector = Distill::BareConclusionDetector.new
+        suspect = 0
+        bare = 0
+        total = 0
+
+        %w[project global].each do |scope|
+          store = @manager.store_if_exists(scope)
+          next unless store
+          dataset = store.facts.where(status: "active")
+          dataset = dataset.where { created_at >= cutoff } if cutoff
+          total += dataset.count
+          suspect += dataset.where(predicate: "reference").count
+          dataset.where(predicate: %w[decision convention])
+            .select(:predicate, :object_literal)
+            .all
+            .each { |row| bare += 1 if detector.bare_conclusion?(row) }
+        end
+
+        {total_active: total, suspect_count: suspect, bare_conclusion_count: bare}
+      end
+
+      # What does memory cost? Aggregates `context_tokens` from successful
+      # `hook_context` activity events over the last UTILIZATION_DAYS so a
+      # skeptical user can see the per-session token cost in p50/p95.
+      #
+      # Shape: {p50:, p95:, avg:, sample_size:, window_days:}
+      # All ints. Returns zeros when there are no events in the window.
+      def token_budget
+        store = @manager.default_store(prefer: :project)
+        return token_budget_zero unless store
+
+        cutoff = (Time.now.utc - UTILIZATION_DAYS * 86_400).iso8601
+        rows = store.activity_events
+          .where(event_type: "hook_context", status: "success")
+          .where { occurred_at >= cutoff }
+          .select(:detail_json)
+          .all
+
+        tokens = rows.filter_map do |row|
+          details = row[:detail_json] ? JSON.parse(row[:detail_json]) : {}
+          value = details["context_tokens"]
+          value if value.is_a?(Integer) && value > 0
+        end
+
+        return token_budget_zero if tokens.empty?
+
+        sorted = tokens.sort
+        {
+          p50: percentile(sorted, 0.50),
+          p95: percentile(sorted, 0.95),
+          avg: (sorted.sum.to_f / sorted.size).round,
+          sample_size: sorted.size,
+          window_days: UTILIZATION_DAYS
         }
+      rescue Sequel::DatabaseError, JSON::ParserError => e
+        ClaudeMemory.logger.debug("Trust#token_budget failed: #{e.message}")
+        token_budget_zero
+      end
+      public :token_budget
+
+      def token_budget_zero
+        {p50: 0, p95: 0, avg: 0, sample_size: 0, window_days: UTILIZATION_DAYS}
+      end
+
+      def percentile(sorted, pct)
+        return 0 if sorted.empty?
+        idx = (sorted.size * pct).ceil - 1
+        idx = 0 if idx < 0
+        idx = sorted.size - 1 if idx >= sorted.size
+        sorted[idx]
       end
 
       private

data/lib/claude_memory/distill/bare_conclusion_detector.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Distill
+    # Catches facts that survived distillation without a reason clause.
+    # The SessionStart distillation prompt explicitly requires `decision`
+    # and `convention` facts to embed the reason ("— because …", "so that
+    # …", "to avoid …", "caused by …", "breaks when …"); facts that ship
+    # without one are dead weight once they go stale because nobody can
+    # recover the original justification by re-reading the row.
+    #
+    # This detector is the production-side mirror of that prompt
+    # constraint. It exists so the dashboard can quantify how many facts
+    # are slipping through the prompt's reason-clause requirement —
+    # higher bare-conclusion ratio means the LLM is producing low-quality
+    # extractions, which is a hallucination-rate proxy worth surfacing.
+    #
+    # Pure function, no side effects, safe to call in tight loops.
+    class BareConclusionDetector
+      # Predicates the prompt requires reasons for. Other predicates
+      # (uses_framework, uses_database, etc.) carry their meaning in the
+      # subject-predicate-object shape itself, so a bare object is fine.
+      GUARDED_PREDICATES = %w[decision convention].freeze
+
+      # Reason-clause signals lifted from the distill-transcripts skill
+      # prompt plus a small set of common natural-language variants. The
+      # match is case-insensitive and substring-anchored — any one signal
+      # qualifies the fact as "explained" even without an em dash.
+      REASON_PATTERNS = [
+        /\bbecause\b/i,
+        /\bso\s+that\b/i,
+        /\bso\s+the\b/i,
+        /\bso\s+we\b/i,
+        /\bin\s+order\s+to\b/i,
+        /\bto\s+avoid\b/i,
+        /\bto\s+prevent\b/i,
+        /\bto\s+ensure\b/i,
+        /\bto\s+support\b/i,
+        /\bto\s+allow\b/i,
+        /\bto\s+enable\b/i,
+        /\bto\s+make\b/i,
+        /\bto\s+fix\b/i,
+        /\bto\s+handle\b/i,
+        /\bcaused\s+by\b/i,
+        /\bbreaks\s+when\b/i,
+        /\bdue\s+to\b/i,
+        /\botherwise\b/i,
+        /\bwithout\s+(?:which|this|it)\b/i
+      ].freeze
+
+      # Returns true when the fact has a guarded predicate AND its object
+      # text shows no reason-clause signal. Returns false for any fact
+      # outside the guarded predicates so the metric isn't polluted by
+      # legitimately-bare facts (uses_database "sqlite" doesn't need a
+      # rationale embedded in its object).
+      #
+      # @param fact [Hash] with :predicate and :object_literal keys (or
+      #   :predicate / :object — accepts both shapes used in the codebase)
+      # @return [Boolean]
+      def bare_conclusion?(fact)
+        predicate = fact[:predicate].to_s
+        return false unless GUARDED_PREDICATES.include?(predicate)
+
+        object = (fact[:object_literal] || fact[:object]).to_s
+        return false if object.empty?
+
+        REASON_PATTERNS.none? { |re| object.match?(re) }
+      end
+    end
+  end
+end

data/lib/claude_memory/hook/handler.rb

@@ -93,6 +93,59 @@ module ClaudeMemory
         result
       end
 
+      # First-week ROI nudge. Computes per-session metrics (facts
+      # contributed via Stop-hook ingest, percentage of those Claude
+      # actually used in recall/context-injection) and decides whether
+      # to print to the user. Quiets after MAX_NUDGES successful runs
+      # or when CLAUDE_MEMORY_NO_NUDGE=1.
+      #
+      # The "first ~10 sessions" gate is enforced by counting prior
+      # `roi_nudge` activity events with status=success across both
+      # stores. Once the user has seen the nudge enough times, memory
+      # gets out of the way; trust is established or it isn't.
+      MAX_NUDGES = 10
+      ENV_NUDGE_OPT_OUT = "CLAUDE_MEMORY_NO_NUDGE"
+
+      def nudge(payload)
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        session_id = payload["session_id"] || @config.session_id
+
+        # Cleanly silent on opt-out — no activity event, no record of
+        # having tried. Users who set the env var don't want a paper
+        # trail of suppressed nudges.
+        return {status: :silent, reason: "opt_out"} if @env[ENV_NUDGE_OPT_OUT] == "1"
+        return {status: :silent, reason: "no_session_id"} if session_id.nil? || session_id.empty?
+
+        prior = prior_nudge_count
+        if prior >= MAX_NUDGES
+          return {status: :silent, reason: "first_week_complete", prior_count: prior}
+        end
+
+        contributed_ids = session_contributed_facts(session_id)
+        n = contributed_ids.size
+
+        if n.zero?
+          # Don't burn one of the user's 10 nudge slots on an empty
+          # session. Memory contributed nothing → no trust signal to
+          # surface; come back next session with real data.
+          return {status: :silent, reason: "no_contributions", prior_count: prior}
+        end
+
+        used = session_used_facts(session_id, contributed_ids)
+        pct = (used * 100.0 / n).round
+        message = "memory contributed #{n} fact#{"s" unless n == 1} this session, %used = #{pct}%"
+
+        log_activity("roi_nudge", status: "success", session_id: session_id, t0: t0,
+          details: {n: n, used: used, pct: pct, prior_count: prior})
+
+        {
+          status: :emitted,
+          message: message,
+          n: n, used: used, pct: pct,
+          remaining: MAX_NUDGES - prior - 1
+        }
+      end
+
       def context(payload)
         t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
@@ -105,7 +158,11 @@ module ClaudeMemory
 
         log_activity("hook_context",
           status: context_text ? "success" : "skipped", t0: t0,
-          details: {context_length: context_text&.length, source: source})
+          details: {
+            context_length: context_text&.length,
+            context_tokens: Core::TokenEstimator.estimate(context_text),
+            source: source
+          })
 
         {status: :ok, context: context_text}
       rescue => e
@@ -126,6 +183,90 @@ module ClaudeMemory
         project_path = payload["project_path"] || @config.project_dir
         Store::StoreManager.new(project_path: project_path, env: @env)
       end
+
+      # Cross-scope nudge counter. Counts both stores so a user with
+      # global facts only doesn't bypass the first-week limit.
+      def prior_nudge_count
+        manager_or_self.then do |m|
+          %w[project global].sum do |scope|
+            store = m.respond_to?(:store_if_exists) ? m.store_if_exists(scope) : nil
+            next 0 unless store
+            store.activity_events.where(event_type: "roi_nudge", status: "success").count
+          end
+        end
+      rescue Sequel::DatabaseError
+        # If we can't read the count, err on the side of "still in
+        # first week" so users keep getting feedback while we figure
+        # out what's wrong with the DB.
+        0
+      end
+
+      # Facts whose provenance points to content_items captured in
+      # this session. Active facts only — superseded/rejected ones
+      # don't count as memory contributing.
+      def session_contributed_facts(session_id)
+        return [] unless @store
+        @store.facts
+          .join(:provenance, fact_id: :id)
+          .join(:content_items, id: Sequel[:provenance][:content_item_id])
+          .where(Sequel[:content_items][:session_id] => session_id)
+          .where(Sequel[:facts][:status] => "active")
+          .select(Sequel[:facts][:id])
+          .distinct
+          .map { |row| row[:id] }
+      rescue Sequel::DatabaseError => e
+        ClaudeMemory.logger.debug("session_contributed_facts failed: #{e.message}")
+        []
+      end
+
+      # Of the given fact ids, how many appear in top_fact_ids of any
+      # recall or hook_context activity event tagged with this
+      # session_id?
+      def session_used_facts(session_id, fact_ids)
+        return 0 if fact_ids.empty?
+        return 0 unless @store
+        target = fact_ids.to_set
+        used = Set.new
+
+        @store.activity_events
+          .where(event_type: %w[recall hook_context], status: "success")
+          .where(session_id: session_id)
+          .select(:detail_json)
+          .all
+          .each do |row|
+            details = row[:detail_json] ? JSON.parse(row[:detail_json]) : {}
+            (details["top_fact_ids"] || []).each { |id| used << id if target.include?(id) }
+          end
+
+        used.size
+      rescue Sequel::DatabaseError, JSON::ParserError => e
+        ClaudeMemory.logger.debug("session_used_facts failed: #{e.message}")
+        0
+      end
+
+      def manager_or_self
+        return @manager if @manager
+        # When the Handler was given only a single store (no manager),
+        # we still want to count nudges; treat the store like a single-
+        # scope manager via a tiny wrapper.
+        @_handler_store_facade ||= SingleStoreFacade.new(@store)
+      end
+
+      class SingleStoreFacade
+        def initialize(store)
+          @store = store
+        end
+
+        def store_if_exists(scope)
+          # The manager's store_if_exists returns nil for the absent
+          # scope; we don't know which scope this single store
+          # represents, so return it for "project" and nil for
+          # "global". Counts undercount global-only setups, which is
+          # acceptable — global-only users would normally pass a
+          # manager.
+          (scope == "project") ? @store : nil
+        end
+      end
     end
   end
 end

data/lib/claude_memory/templates/hooks.example.json

@@ -68,6 +68,11 @@
             "command": "claude-memory hook sweep",
             "timeout": 30,
             "statusMessage": "Sweeping memory..."
+          },
+          {
+            "type": "command",
+            "command": "claude-memory hook nudge",
+            "timeout": 5
           }
         ]
       }

data/lib/claude_memory/version.rb

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