claude_memory 0.11.0 → 0.12.0

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

data/lib/claude_memory/otel/otlp_json_envelope.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "time"
+
+module ClaudeMemory
+  module OTel
+    # Pure functional core for OTLP/HTTP/JSON payloads. Walks the canonical
+    # OTLP envelope shapes (resourceMetrics → scopeMetrics → metrics →
+    # dataPoints; resourceLogs → scopeLogs → logRecords; resourceSpans →
+    # scopeSpans → spans), flattens KeyValue attribute arrays into Ruby
+    # hashes, and returns plain row hashes ready to insert.
+    #
+    # No Time.now, no ENV reads, no DB. Pass a clock object that responds
+    # to `now` (or just `Time`) for fallback timestamps when the payload
+    # omits one. Required keys raise via Hash#fetch; optional containers
+    # default to empty arrays.
+    #
+    # All public methods return Arrays of Hashes whose keys match the
+    # SQLiteStore.insert_otel_* helpers exactly.
+    module OtlpJsonEnvelope
+      module_function
+
+      # @param payload [Hash] parsed OTLP MetricsServiceRequest JSON
+      # @param clock [#now] used for fallback when timeUnixNano is missing
+      # @return [Array<Hash>] rows for SQLiteStore#insert_otel_metric
+      def parse_metrics(payload, clock: Time)
+        rows = []
+        Array(payload["resourceMetrics"]).each do |resource_metric|
+          resource = flatten_attributes(dig_attributes(resource_metric["resource"]))
+          Array(resource_metric["scopeMetrics"]).each do |scope_metric|
+            Array(scope_metric["metrics"]).each do |metric|
+              metric_name = metric.fetch("name")
+              unit = metric["unit"]
+              data_points = collect_data_points(metric)
+              data_points.each do |point|
+                value_type, value_int, value_float = decode_metric_value(point)
+                next if value_type.nil?
+
+                rows << {
+                  name: metric_name,
+                  value_type: value_type,
+                  value_int: value_int,
+                  value_float: value_float,
+                  unit: unit,
+                  attributes: flatten_attributes(point["attributes"]),
+                  resource: resource,
+                  recorded_at: timestamp_from_point(point, clock)
+                }
+              end
+            end
+          end
+        end
+        rows
+      end
+
+      # @param payload [Hash] parsed OTLP LogsServiceRequest JSON
+      # @param clock [#now]
+      # @return [Array<Hash>] rows for SQLiteStore#insert_otel_event
+      def parse_logs(payload, clock: Time)
+        rows = []
+        Array(payload["resourceLogs"]).each do |resource_log|
+          resource = flatten_attributes(dig_attributes(resource_log["resource"]))
+          Array(resource_log["scopeLogs"]).each do |scope_log|
+            Array(scope_log["logRecords"]).each do |record|
+              attributes = flatten_attributes(record["attributes"])
+              rows << {
+                event_name: event_name_for(record, attributes),
+                occurred_at: timestamp_from_record(record, clock),
+                session_id: attributes["session.id"],
+                prompt_id: attributes["prompt.id"],
+                attributes: attributes,
+                resource: resource
+              }
+            end
+          end
+        end
+        rows
+      end
+
+      # @param payload [Hash] parsed OTLP TracesServiceRequest JSON
+      # @param clock [#now]
+      # @return [Array<Hash>] rows for SQLiteStore#insert_otel_trace_span
+      def parse_traces(payload, clock: Time)
+        rows = []
+        Array(payload["resourceSpans"]).each do |resource_span|
+          resource = flatten_attributes(dig_attributes(resource_span["resource"]))
+          Array(resource_span["scopeSpans"]).each do |scope_span|
+            Array(scope_span["spans"]).each do |span|
+              attributes = flatten_attributes(span["attributes"])
+              start_nano = parse_unix_nano(span["startTimeUnixNano"])
+              end_nano = parse_unix_nano(span["endTimeUnixNano"])
+              rows << {
+                trace_id: span.fetch("traceId"),
+                span_id: span.fetch("spanId"),
+                parent_span_id: span["parentSpanId"],
+                name: span.fetch("name"),
+                session_id: attributes["session.id"],
+                prompt_id: attributes["prompt.id"],
+                start_unix_nano: start_nano,
+                end_unix_nano: end_nano,
+                duration_ms: duration_ms_from(start_nano, end_nano),
+                status_code: span.dig("status", "code")&.to_s,
+                attributes: attributes,
+                resource: resource,
+                recorded_at: timestamp_from_unix_nano(start_nano, clock)
+              }
+            end
+          end
+        end
+        rows
+      end
+
+      # Flatten OTel KeyValue array (`[{key:, value: {stringValue: ...}}, ...]`)
+      # into a plain Hash.
+      def flatten_attributes(kv_array)
+        result = {}
+        Array(kv_array).each do |kv|
+          next unless kv.is_a?(Hash)
+          key = kv["key"]
+          next if key.nil? || key.empty?
+          result[key] = decode_any_value(kv["value"])
+        end
+        result
+      end
+
+      def decode_any_value(value)
+        return nil unless value.is_a?(Hash)
+        return value["stringValue"] if value.key?("stringValue")
+        # OTLP JSON encodes int64 as a string to avoid JS precision loss.
+        return decode_int_string(value["intValue"]) if value.key?("intValue")
+        return value["doubleValue"] if value.key?("doubleValue")
+        return value["boolValue"] if value.key?("boolValue")
+        if value.key?("arrayValue")
+          values = value.dig("arrayValue", "values") || []
+          return values.map { |v| decode_any_value(v) }
+        end
+        if value.key?("kvlistValue")
+          kvs = value.dig("kvlistValue", "values") || []
+          return flatten_attributes(kvs)
+        end
+        nil
+      end
+
+      private_class_method :decode_any_value
+
+      def decode_int_string(value)
+        return value if value.is_a?(Integer)
+        return nil if value.nil?
+        Integer(value.to_s, 10)
+      rescue ArgumentError
+        nil
+      end
+
+      private_class_method :decode_int_string
+
+      def dig_attributes(container)
+        container.is_a?(Hash) ? container["attributes"] : nil
+      end
+
+      private_class_method :dig_attributes
+
+      # Pull dataPoints out of whichever metric type wrapper is present.
+      # Histograms and summaries (rare in Claude Code's exports) return
+      # their data points; we record the count value when present.
+      def collect_data_points(metric)
+        %w[sum gauge histogram exponentialHistogram summary].each do |kind|
+          wrapper = metric[kind]
+          next unless wrapper.is_a?(Hash)
+          points = wrapper["dataPoints"]
+          return Array(points) if points
+        end
+        []
+      end
+
+      private_class_method :collect_data_points
+
+      # Returns [value_type, value_int, value_float] tuple. nil value_type
+      # means we couldn't decode anything storable.
+      def decode_metric_value(point)
+        if point.key?("asInt")
+          int_value = decode_int_string(point["asInt"])
+          return [ValueType::INT, int_value, nil] unless int_value.nil?
+        end
+        if point.key?("asDouble")
+          d = point["asDouble"]
+          return [ValueType::DOUBLE, nil, d.to_f] unless d.nil?
+        end
+        # Histogram / summary fall-back: store sum when present, count
+        # otherwise. Skip when neither is available.
+        if point.key?("sum")
+          s = point["sum"]
+          return [ValueType::DOUBLE, nil, s.to_f] unless s.nil?
+        end
+        if point.key?("count")
+          count = decode_int_string(point["count"])
+          return [ValueType::INT, count, nil] unless count.nil?
+        end
+        [nil, nil, nil]
+      end
+
+      private_class_method :decode_metric_value
+
+      def event_name_for(record, attributes)
+        # OTel logs/events: the event name lives on the attribute
+        # "event.name" by convention. Claude Code sets it as
+        # "claude_code.<name>" on its instrumentation scope, so we strip
+        # the prefix when present so panels see "user_prompt", not
+        # "claude_code.user_prompt".
+        raw = attributes["event.name"] || record["eventName"] || record.dig("body", "stringValue") || "log"
+        raw.to_s.sub(/\Aclaude_code\./, "")
+      end
+
+      private_class_method :event_name_for
+
+      def timestamp_from_point(point, clock)
+        nano = parse_unix_nano(point["timeUnixNano"]) || parse_unix_nano(point["startTimeUnixNano"])
+        timestamp_from_unix_nano(nano, clock)
+      end
+
+      private_class_method :timestamp_from_point
+
+      def timestamp_from_record(record, clock)
+        nano = parse_unix_nano(record["timeUnixNano"]) || parse_unix_nano(record["observedTimeUnixNano"])
+        timestamp_from_unix_nano(nano, clock)
+      end
+
+      private_class_method :timestamp_from_record
+
+      def timestamp_from_unix_nano(nano, clock)
+        return clock.now.utc.iso8601 if nano.nil?
+        Time.at(nano / 1_000_000_000.0).utc.iso8601
+      end
+
+      private_class_method :timestamp_from_unix_nano
+
+      def parse_unix_nano(value)
+        return nil if value.nil?
+        return value if value.is_a?(Integer)
+        Integer(value.to_s, 10)
+      rescue ArgumentError
+        nil
+      end
+
+      private_class_method :parse_unix_nano
+
+      def duration_ms_from(start_nano, end_nano)
+        return nil if start_nano.nil? || end_nano.nil?
+        ((end_nano - start_nano) / 1_000_000).to_i
+      end
+
+      private_class_method :duration_ms_from
+    end
+  end
+end

data/lib/claude_memory/otel/prompt_scope.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module OTel
+    # Back-tags activity_events with the OTel prompt.id after telemetry
+    # events arrive. Hook events (hook_ingest, hook_context, ...) fire
+    # ~immediately as the user's turn closes, but Claude Code batches OTel
+    # exports on the OTEL_METRIC_EXPORT_INTERVAL (default 60s), so by the
+    # time we see a prompt.id on the receiver, the activity_events for that
+    # turn already exist with prompt_id = NULL.
+    #
+    # Tagging strategy per (prompt_id, session_id) group:
+    #   1. session_id-match path — for activity_events carrying the same
+    #      session_id, update those that fall in the prompt's time window.
+    #      Hook events (hook_ingest, hook_context, hook_sweep, hook_publish,
+    #      roi_nudge) reliably carry session_id from the Claude Code hook
+    #      payload.
+    #   2. time-window path — for activity_events with NULL session_id
+    #      (recall, store_extraction — MCP-originated; Claude Code doesn't
+    #      thread session_id into plugin MCP calls per reference_mcp_session
+    #      _id_gap), tag by occurred_at falling in the prompt window only.
+    #
+    # Operates on both project_store and global_store when available.
+    # Cross-project tagging (projects other than the dashboard's loaded one)
+    # is out of scope — dashboard is per-project and other project DBs
+    # aren't in the manager.
+    class PromptScope
+      # Bound the prompt window so a long-running turn doesn't sweep up
+      # later activity events that belong to the NEXT prompt. The OTel
+      # spec only emits prompt.id between user_prompt and the next
+      # user_prompt, so the natural max is implicit; we add a safety
+      # ceiling.
+      MAX_WINDOW_SECONDS = 600
+      # Buffer added after the latest OTel event because hook_ingest fires
+      # AFTER the Stop event, which can be a few seconds after the last
+      # api_request.
+      POST_WINDOW_BUFFER_SECONDS = 30
+
+      def initialize(manager)
+        @manager = manager
+      end
+
+      # @param events [Array<Hash>] just-persisted OTel event rows
+      #   (each carrying :prompt_id, :session_id, :occurred_at) — the
+      #   same shape OtlpJsonEnvelope.parse_logs returns.
+      # @return [Hash] {tagged: count, groups: count}
+      def tag(events)
+        return {tagged: 0, groups: 0} if events.nil? || events.empty?
+
+        groups = group_by_prompt(events)
+        return {tagged: 0, groups: 0} if groups.empty?
+
+        tagged = 0
+        groups.each do |key, range|
+          prompt_id, session_id = key
+          [@manager.project_store, @manager.global_store].compact.each do |store|
+            tagged += tag_in_store(store, prompt_id, session_id, range)
+          end
+        end
+        {tagged: tagged, groups: groups.size}
+      rescue Sequel::DatabaseError => e
+        ClaudeMemory.logger.debug("prompt_scope tag failed: #{e.message}")
+        {tagged: 0, groups: 0, error: e.message}
+      end
+
+      private
+
+      # Returns {[prompt_id, session_id_or_nil] => (lo..hi)} where lo/hi
+      # are ISO 8601 strings derived from event occurred_at values.
+      def group_by_prompt(events)
+        events
+          .select { |e| e[:prompt_id] && !e[:prompt_id].to_s.empty? }
+          .group_by { |e| [e[:prompt_id], e[:session_id]] }
+          .each_with_object({}) do |(key, group), out|
+            timestamps = group.map { |e| e[:occurred_at] }.compact.sort
+            next if timestamps.empty?
+            lo = timestamps.first
+            hi = (Time.parse(timestamps.last) + POST_WINDOW_BUFFER_SECONDS).utc.iso8601
+            # Cap window length to MAX_WINDOW_SECONDS so a stale event
+            # batch can't sweep a wide range.
+            ceiling = (Time.parse(lo) + MAX_WINDOW_SECONDS).utc.iso8601
+            hi = [hi, ceiling].min
+            out[key] = (lo..hi)
+          end
+      end
+
+      def tag_in_store(store, prompt_id, session_id, range)
+        return 0 unless store&.db&.table_exists?(:activity_events)
+        return 0 unless store.activity_events.columns.include?(:prompt_id)
+
+        tagged_by_session = 0
+        if session_id && !session_id.to_s.empty?
+          tagged_by_session = store.activity_events
+            .where(session_id: session_id, prompt_id: nil)
+            .where { (occurred_at >= range.first) & (occurred_at <= range.last) }
+            .update(prompt_id: prompt_id)
+        end
+
+        tagged_by_window = store.activity_events
+          .where(session_id: nil, prompt_id: nil)
+          .where { (occurred_at >= range.first) & (occurred_at <= range.last) }
+          .update(prompt_id: prompt_id)
+
+        tagged_by_session + tagged_by_window
+      end
+    end
+  end
+end