claude_memory 0.11.0 → 0.12.1

data/lib/claude_memory/dashboard/telemetry.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Dashboard
+    # Cost & Tokens dashboard panel. Aggregates Claude Code's OTel metric
+    # exports — server-side via Sequel datasets so the API returns
+    # final-rendered bins and the JS does no reduce.
+    #
+    # Returns the empty shape ({status:, cost_over_time: [], ...}) when no
+    # store or no rows exist so the dashboard renders before the first
+    # ingest.
+    class Telemetry
+      LOOKBACK_DAYS = 7
+      TOP_TOOLS_LIMIT = 10
+
+      def initialize(manager)
+        @manager = manager
+      end
+
+      def snapshot
+        store = @manager.default_store(prefer: :global)
+        return empty_snapshot(store) unless store&.db&.table_exists?(:otel_metrics)
+
+        cutoff = (Time.now - LOOKBACK_DAYS * 86_400).utc.iso8601
+        metrics = store.otel_metrics.where { recorded_at >= cutoff }
+        events = events_dataset(store, cutoff)
+
+        {
+          status: status_payload(store),
+          cost_over_time: cost_over_time(metrics),
+          tokens_by_model: tokens_by_model(metrics),
+          top_tools_by_latency: top_tools(events),
+          error_rate: error_rate(events),
+          recent_metrics: recent_metrics(metrics),
+          contains_prompt_content: contains_prompt_content?(events)
+        }
+      end
+
+      private
+
+      def empty_snapshot(store)
+        {
+          status: status_payload(store),
+          cost_over_time: [],
+          tokens_by_model: [],
+          top_tools_by_latency: [],
+          error_rate: {total: 0, errors: 0, ratio: 0.0},
+          recent_metrics: [],
+          contains_prompt_content: false
+        }
+      end
+
+      def status_payload(store)
+        OTel::Status.new(store, configuration: ClaudeMemory::Configuration.new).snapshot
+      end
+
+      def cost_over_time(metrics)
+        rows = metrics
+          .where(name: OTel::MetricName::COST_USAGE)
+          .select_group(Sequel.lit("substr(recorded_at, 1, 13)").as(:hour))
+          .select_append { sum(value_float).as(:cost_usd) }
+          .select_append { count(id).as(:requests) }
+          .order(:hour)
+          .all
+        rows.map { |r|
+          {
+            hour: r[:hour],
+            cost_usd: (r[:cost_usd] || 0.0).to_f.round(6),
+            requests: r[:requests].to_i
+          }
+        }
+      end
+
+      # SQLite's json_extract was added in 3.38.0 (2022-02). Sequel runs it
+      # via Sequel.lit so we group by (model, type) at the DB layer instead
+      # of materializing the whole window into Ruby.
+      def tokens_by_model(metrics)
+        model_expr = Sequel.lit("json_extract(attributes_json, '$.model')")
+        type_expr = Sequel.lit("json_extract(attributes_json, '$.type')")
+        rows = metrics
+          .where(name: OTel::MetricName::TOKEN_USAGE)
+          .select_group(model_expr.as(:model), type_expr.as(:type))
+          .select_append { sum(Sequel.function(:coalesce, :value_int, :value_float)).as(:tokens) }
+          .order(Sequel.desc(:tokens))
+          .all
+        rows.map { |r|
+          {model: r[:model] || "unknown", type: r[:type] || "unknown", tokens: r[:tokens].to_i}
+        }
+      end
+
+      def top_tools(events)
+        return [] if events.nil?
+        tool_expr = Sequel.lit("json_extract(attributes_json, '$.tool_name')")
+        duration_expr = Sequel.lit("json_extract(attributes_json, '$.duration_ms')")
+        rows = events
+          .where(event_name: OTel::EventName::TOOL_RESULT)
+          .select_group(tool_expr.as(:tool))
+          .select_append { count(id).as(:count) }
+          .select_append { avg(duration_expr).as(:avg_duration_ms) }
+          .order(Sequel.desc(:avg_duration_ms))
+          .limit(TOP_TOOLS_LIMIT)
+          .all
+        rows.map { |r|
+          {tool: r[:tool] || "unknown", count: r[:count].to_i, avg_duration_ms: r[:avg_duration_ms].to_i}
+        }
+      end
+
+      def error_rate(events)
+        return {total: 0, errors: 0, ratio: 0.0} if events.nil?
+        total = events.where(event_name: OTel::EventName::API_PAIR).count
+        errors = events.where(event_name: OTel::EventName::API_ERROR).count
+        ratio = total.zero? ? 0.0 : (errors.to_f / total).round(4)
+        {total: total, errors: errors, ratio: ratio}
+      end
+
+      def recent_metrics(metrics)
+        rows = metrics
+          .where(name: OTel::MetricName::TOKEN_USAGE)
+          .order(Sequel.desc(:recorded_at))
+          .limit(100)
+          .all
+        rows.map { |row|
+          attrs = OTel::Attributes.from_json(row[:attributes_json])
+          {
+            recorded_at: row[:recorded_at],
+            model: attrs.model,
+            type: attrs.token_type,
+            tokens: OTel::Attributes.token_count(row),
+            session_id: attrs.session_id,
+            prompt_id: attrs.prompt_id
+          }.compact
+        }
+      end
+
+      def events_dataset(store, cutoff)
+        return nil unless store.db.table_exists?(:otel_events)
+        store.otel_events.where { occurred_at >= cutoff }
+      end
+
+      # SQL pre-filter via LIKE on each prompt-content key, short-circuited
+      # by .any?. JSON encodes object keys as `"key":` (compact), so the
+      # patterns can't false-match longer keys (e.g. "prompt_length").
+      def contains_prompt_content?(events)
+        return false if events.nil?
+        clauses = OTel::Attributes::PROMPT_CONTENT_KEYS.map { |key|
+          Sequel.lit("attributes_json LIKE ?", %("#{key}":))
+        }
+        events
+          .where(event_name: OTel::EventName::PROMPT_BODY_FAMILY)
+          .where(Sequel.|(*clauses))
+          .limit(1)
+          .any?
+      end
+    end
+  end
+end

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/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/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

data/lib/claude_memory/otel/ingestor.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "../core/result"
+
+module ClaudeMemory
+  module OTel
+    # Imperative shell for OTel ingestion. Takes the parsed-row hashes
+    # produced by OtlpJsonEnvelope and writes them in a single batched
+    # transaction. Returns Core::Result so the HTTP server can map outcome
+    # to status code without rescue clauses.
+    #
+    # The ingestor accepts a `:metrics`, `:events`, or `:traces` payload —
+    # one kind per call, matching how OTLP/HTTP separates the three
+    # endpoints. Wrap each batch in transaction_with_retry so a partial
+    # failure mid-insert leaves zero rows behind.
+    class Ingestor
+      def initialize(store)
+        @store = store
+      end
+
+      # @param payload [Hash] one of {metrics: [...]}, {events: [...]},
+      #   {traces: [...]}. Other keys are ignored.
+      # @return [Core::Result] success carries inserted-count Hash;
+      #   failure carries an error message
+      def ingest(payload)
+        return Core::Result.failure("payload must be a Hash") unless payload.is_a?(Hash)
+
+        counts = {metrics: 0, events: 0, traces: 0}
+        @store.transaction_with_retry do
+          counts[:metrics] = insert_metrics(payload[:metrics] || payload["metrics"])
+          counts[:events] = insert_events(payload[:events] || payload["events"])
+          counts[:traces] = insert_traces(payload[:traces] || payload["traces"])
+        end
+        Core::Result.success(counts)
+      rescue Sequel::DatabaseError, Extralite::Error, ArgumentError, KeyError => e
+        Core::Result.failure(e.message)
+      end
+
+      private
+
+      def insert_metrics(rows)
+        rows.is_a?(Array) ? @store.bulk_insert_otel_metrics(rows) : 0
+      end
+
+      def insert_events(rows)
+        rows.is_a?(Array) ? @store.bulk_insert_otel_events(rows) : 0
+      end
+
+      def insert_traces(rows)
+        rows.is_a?(Array) ? @store.bulk_insert_otel_traces(rows) : 0
+      end
+    end
+  end
+end