claude_memory 0.10.0 → 0.12.0

data/lib/claude_memory/deprecations.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  # Soft-rename / soft-removal mechanism for public-API surfaces.
+  # Used to mark an old name (CLI flag, MCP tool, Ruby method, hook
+  # field, predicate) as deprecated in `N.x.0` releases while keeping it
+  # functional for at least one minor cycle, with explicit removal no
+  # earlier than `(N+1).0.0`. This deprecation policy is documented in
+  # `docs/api_stability.md`.
+  #
+  # @example Deprecate a renamed CLI flag
+  #   ClaudeMemory::Deprecations.warn(
+  #     name: "claude-memory recall --legacy-mode",
+  #     replacement: "--mode=legacy",
+  #     removed_in: "1.0.0"
+  #   )
+  #
+  # @example Deprecate a soft-renamed Ruby method
+  #   ClaudeMemory::Deprecations.warn(
+  #     name: "ClaudeMemory::Recall#legacy_query",
+  #     replacement: "Recall#query",
+  #     removed_in: "1.0.0",
+  #     message: "Pass `mode: :legacy` to #query instead."
+  #   )
+  #
+  # Two suppression mechanisms keep deprecation noise manageable:
+  #
+  # - **Per-call-site dedupe**: same (name, caller_file:line) pair only
+  #   emits once per process. Prevents tight loops or repeated callers
+  #   from drowning the terminal.
+  # - **Env var opt-out**: `CLAUDE_MEMORY_NO_DEPRECATIONS=1` silences
+  #   everything. Recommended for test fixtures and CI runs that
+  #   knowingly exercise legacy paths.
+  module Deprecations
+    ENV_OPT_OUT = "CLAUDE_MEMORY_NO_DEPRECATIONS"
+
+    # Tracks already-emitted (name, caller-location) pairs for dedupe.
+    # Bounded — this is a long-lived process state but the cardinality
+    # is at most "every deprecated surface × every call site that
+    # touches it", which stays small in practice.
+    @emitted = {}
+    @mutex = Mutex.new
+
+    class << self
+      # Emit a deprecation warning to `output` (stderr by default).
+      #
+      # @param name [String] the deprecated identifier (CLI flag, method,
+      #   tool name, etc.). Be specific: "ClaudeMemory::Recall#query(:legacy)"
+      #   beats "Recall#query".
+      # @param replacement [String, nil] what users should switch to.
+      #   Optional but strongly recommended — a deprecation without a
+      #   migration path is annoying.
+      # @param removed_in [String, nil] target removal version, semver
+      #   string. Conventionally the next major (`(N+1).0.0`).
+      # @param message [String, nil] free-form extra context. Use for
+      #   subtle migration nuance the replacement string can't capture.
+      # @param caller_location [String, nil] override for testing.
+      # @param output [IO] override for testing. Default: $stderr.
+      # @return [Boolean] true if a warning was emitted, false if
+      #   suppressed (env opt-out or already-emitted dedupe).
+      def warn(name:, replacement: nil, removed_in: nil, message: nil,
+        caller_location: nil, output: $stderr)
+        return false if suppressed?
+
+        location = caller_location || derive_caller_location
+        key = "#{name}@#{location}"
+
+        @mutex.synchronize do
+          return false if @emitted[key]
+          @emitted[key] = true
+        end
+
+        output.puts(format_warning(name: name, replacement: replacement,
+          removed_in: removed_in, message: message, location: location))
+        true
+      end
+
+      # Wipe the per-call-site dedupe state. Test-only — production
+      # callers should rely on the per-process behavior.
+      def reset!
+        @mutex.synchronize { @emitted.clear }
+      end
+
+      private
+
+      def suppressed?
+        ENV[ENV_OPT_OUT] == "1"
+      end
+
+      def derive_caller_location
+        # Skip: 0=this method, 1=warn, 2=actual caller
+        loc = caller_locations(3, 1)&.first
+        loc ? "#{loc.path}:#{loc.lineno}" : "unknown"
+      end
+
+      def format_warning(name:, replacement:, removed_in:, message:, location:)
+        parts = ["[ClaudeMemory] DEPRECATION: #{name} is deprecated"]
+        parts << "scheduled for removal in #{removed_in}" if removed_in
+        parts << "use #{replacement} instead" if replacement
+        head = parts.join(", ") + "."
+        head += " #{message}" if message
+        "#{head} (called from #{location})"
+      end
+    end
+  end
+end

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/distill/reference_material_detector.rb

@@ -43,11 +43,28 @@ module ClaudeMemory
         /\bby\s+[[:upper:]][[:alpha:]'-]+\s+[[:upper:]][[:alpha:]'-]+/
       ].freeze
 
-      # Predicates we inspect. Decisions stay decisions even when they cite
-      # external projects ("From QMD restudy: adopt X"); the guard targets
-      # only `convention`, where misclassification is most common.
+      # Predicates inspected for object-text reference signals. Decisions
+      # stay decisions even when they cite external projects ("From QMD
+      # restudy: adopt X"); the object-text guard targets only
+      # `convention`, where misclassification is most common.
       GUARDED_PREDICATES = %w[convention].freeze
 
+      # Stack-shaping single-value predicates that historically attract
+      # hallucinations from CLAUDE.md-style example text ("e.g., this app
+      # uses PostgreSQL"). For these predicates we additionally inspect the
+      # source quote for example markers — if the LLM extracted a stack
+      # fact from documentation example text, it's not a real project
+      # commitment. Added 2026-05-21 after the audit found 10 open
+      # conflicts driven by recurring example-text extraction.
+      QUOTE_GUARDED_PREDICATES = %w[uses_database uses_framework uses_language deployment_platform auth_method].freeze
+
+      # Example markers that signal the source text is documentation
+      # exemplifying a scope/predicate concept, not a real stack claim.
+      EXAMPLE_QUOTE_PATTERNS = [
+        /\b(?:e\.?g\.?|i\.?e\.?|for example|for instance|such as)[,:]?\s/i,
+        /\(\s*(?:e\.?g\.?|i\.?e\.?)[,.]/i
+      ].freeze
+
       def reclassify(extraction)
         return extraction if extraction.facts.nil? || extraction.facts.empty?
 
@@ -68,11 +85,27 @@ module ClaudeMemory
       end
 
       def reference_material?(fact)
-        return false unless GUARDED_PREDICATES.include?(fact[:predicate].to_s)
+        predicate = fact[:predicate].to_s
+        return true if convention_with_reference_object?(fact, predicate)
+        return true if stack_predicate_from_example_text?(fact, predicate)
+        false
+      end
+
+      private
+
+      def convention_with_reference_object?(fact, predicate)
+        return false unless GUARDED_PREDICATES.include?(predicate)
         object = fact[:object].to_s
         return false if object.empty?
         STRONG_PATTERNS.any? { |re| object.match?(re) }
       end
+
+      def stack_predicate_from_example_text?(fact, predicate)
+        return false unless QUOTE_GUARDED_PREDICATES.include?(predicate)
+        quote = fact[:quote].to_s
+        return false if quote.empty?
+        EXAMPLE_QUOTE_PATTERNS.any? { |re| quote.match?(re) }
+      end
     end
   end
 end

data/lib/claude_memory/hook/auto_memory_mirror.rb

@@ -21,10 +21,14 @@ module ClaudeMemory
       STATE_FILENAME = "auto_memory_mirror.json"
 
       # Derive auto-memory directory from a project path using Claude Code's
-      # slug convention (path separators → hyphens). E.g.
-      # `/Users/me/src/app` → `~/.claude/projects/-Users-me-src-app/memory`.
+      # slug convention. Both path separators and underscores are converted
+      # to hyphens — e.g. `/Users/me/src/my_app` →
+      # `~/.claude/projects/-Users-me-src-my-app/memory`. Before the
+      # underscore conversion was added (2026-05-21 audit), this method
+      # silently missed auto-memory for any project name containing `_`,
+      # including claude_memory itself.
       def self.default_dir(project_path, claude_config_dir)
-        slug = project_path.to_s.tr("/", "-")
+        slug = project_path.to_s.tr("/_", "-")
         File.join(claude_config_dir, "projects", slug, "memory")
       end
 

data/lib/claude_memory/hook/context_injector.rb

@@ -32,11 +32,12 @@ module ClaudeMemory
       # so a bare ID without scope is ambiguous.
       attr_reader :emitted_fact_ids, :emitted_subjects, :emitted_facts_by_scope
 
-      def initialize(manager, source: nil, auto_memory_mirror: nil)
+      def initialize(manager, source: nil, auto_memory_mirror: nil, stale_threshold_days: nil)
         @manager = manager
         @source = source
         @recall = Recall.new(manager)
         @auto_memory_mirror = auto_memory_mirror
+        @stale_threshold_days = stale_threshold_days
         @emitted_fact_ids = []
         @emitted_subjects = []
         @emitted_facts_by_scope = Hash.new { |h, k| h[k] = [] }
@@ -108,11 +109,19 @@ module ClaudeMemory
         predicate = fact[:predicate]
         object = fact[:object_literal]
 
-        if subject && predicate && object
+        line = if subject && predicate && object
           "#{subject}.#{predicate} = #{object}"
         elsif object
           object.to_s
         end
+        return nil unless line
+
+        marker = Recall::StalenessAnnotator.marker_for(fact, threshold_days: stale_threshold_days)
+        marker ? "#{line}  #{marker}" : line
+      end
+
+      def stale_threshold_days
+        @stale_threshold_days ||= Configuration.new.injection_stale_days
       end
 
       def fetch_undistilled(limit)

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/mcp/tool_definitions.rb

@@ -284,7 +284,7 @@ module ClaudeMemory
           },
           {
             name: "memory.decisions",
-            description: "List architectural decisions, constraints, and rules.",
+            description: "List facts with predicate=decision from both project and global memory (project first). Returns only `decision`-predicate facts — does not include `uses_database`, `uses_framework`, etc.",
             inputSchema: {
               type: "object",
               properties: {
@@ -295,7 +295,7 @@ module ClaudeMemory
           },
           {
             name: "memory.conventions",
-            description: "List coding conventions and style preferences from global memory.",
+            description: "List facts with predicate=convention from both project and global memory (project first). Use this to see project coding conventions alongside user-wide style preferences.",
             inputSchema: {
               type: "object",
               properties: {
@@ -306,7 +306,7 @@ module ClaudeMemory
           },
           {
             name: "memory.architecture",
-            description: "List framework choices and architectural patterns.",
+            description: "List architecture facts and stack-shaping constraints (predicates: architecture, uses_database, uses_framework, uses_language, deployment_platform, auth_method) from both project and global memory.",
             inputSchema: {
               type: "object",
               properties: {

data/lib/claude_memory/otel/attributes.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ClaudeMemory
+  module OTel
+    # Value object wrapping an OTel attribute hash (already flattened from
+    # the OTLP KeyValue representation by OtlpJsonEnvelope). Hides the
+    # primitive Hash from callers so panels and ingestors don't reach into
+    # raw JSON keys.
+    #
+    # All accessors return nil when the underlying attribute is missing.
+    # Frozen on construction — pass a fresh hash if you need to mutate.
+    class Attributes
+      # OTel keys we treat as "captured prompt content". Used by
+      # #contains_prompt_content? to flag privacy concerns regardless of
+      # which content flag was flipped (OTEL_LOG_USER_PROMPTS,
+      # OTEL_LOG_TOOL_CONTENT, OTEL_LOG_RAW_API_BODIES).
+      PROMPT_CONTENT_KEYS = %w[
+        prompt
+        body
+        tool_input
+        tool.output
+        full_command
+        user_prompt
+      ].freeze
+
+      # @param hash [Hash] flattened attributes (string keys)
+      def initialize(hash)
+        @hash = (hash || {}).dup.freeze
+        freeze
+      end
+
+      # Parse a JSON string into Attributes. Returns Attributes wrapping
+      # an empty hash for nil, blank, or unparseable input — matches the
+      # tolerance the existing dashboard panels expect.
+      #
+      # @param json_string [String, nil]
+      # @return [Attributes]
+      def self.from_json(json_string)
+        return new({}) if json_string.nil? || json_string.empty?
+        new(JSON.parse(json_string))
+      rescue JSON::ParserError
+        new({})
+      end
+
+      def to_h
+        @hash
+      end
+
+      def to_json(*args)
+        @hash.to_json(*args)
+      end
+
+      def [](key)
+        @hash[key.to_s]
+      end
+
+      # Claude Code attaches `prompt.id` to events that should be UNION'd into
+      # the prompt journey. See docs/claude_monitoring.md.
+      def prompt_id
+        @hash["prompt.id"] || @hash["prompt_id"]
+      end
+
+      def session_id
+        @hash["session.id"] || @hash["session_id"]
+      end
+
+      # GenAI semconv canonical key + Claude Code's `model` alias.
+      def model
+        @hash["gen_ai.request.model"] || @hash["model"]
+      end
+
+      def tool_name
+        @hash["tool_name"]
+      end
+
+      # Cost counter values arrive as the metric value, not as an attribute.
+      # The `type` attribute on token.usage tells us input/output/cacheRead/
+      # cacheCreation; this is only useful for token rows. Returns nil when
+      # missing so callers can guard with #compact.
+      def token_type
+        @hash["type"]
+      end
+
+      # Token count carried on a token.usage data point.
+      # @param row [Hash] otel_metrics row
+      def self.token_count(row)
+        (row[:value_int] || row[:value_float] || 0).to_i
+      end
+
+      # Tool execution duration in ms when the event is a tool_result.
+      # @return [Integer, nil]
+      def duration_ms
+        value = @hash["duration_ms"]
+        value&.to_i
+      end
+
+      def query_source
+        @hash["query_source"]
+      end
+
+      def speed
+        @hash["speed"]
+      end
+
+      # True when any attribute carries actual prompt or body content. Used
+      # by panels to render a one-line privacy notice without auto-flipping
+      # OTEL_LOG_USER_PROMPTS.
+      def contains_prompt_content?
+        PROMPT_CONTENT_KEYS.any? do |key|
+          value = @hash[key]
+          !value.nil? && !value.to_s.strip.empty?
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/otel/constants.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module OTel
+    # Canonical metric value types stored in otel_metrics.value_type.
+    module ValueType
+      INT = "int"
+      DOUBLE = "double"
+    end
+
+    # Canonical event names emitted by Claude Code's OTel instrumentation.
+    # Used by panels for filtering and by the parser when stripping the
+    # `claude_code.` prefix off `event.name` attributes.
+    module EventName
+      USER_PROMPT = "user_prompt"
+      TOOL_RESULT = "tool_result"
+      API_REQUEST = "api_request"
+      API_ERROR = "api_error"
+      API_REQUEST_BODY = "api_request_body"
+      API_RESPONSE_BODY = "api_response_body"
+
+      API_PAIR = [API_REQUEST, API_ERROR].freeze
+      PROMPT_BODY_FAMILY = [USER_PROMPT, TOOL_RESULT, API_REQUEST_BODY, API_RESPONSE_BODY].freeze
+    end
+
+    # Canonical metric names that the dashboard queries.
+    module MetricName
+      TOKEN_USAGE = "claude_code.token.usage"
+      COST_USAGE = "claude_code.cost.usage"
+    end
+  end
+end