claude_memory 0.10.0 → 0.12.0

data/lib/claude_memory/resolve/predicate_policy.rb

@@ -62,9 +62,25 @@ module ClaudeMemory
 
       # Return the canonical form of a predicate name, applying known
       # synonym mappings. Leaves unmapped predicates unchanged.
+      #
+      # Emits a deprecation warning via `ClaudeMemory::Deprecations` when
+      # an actual synonym is hit, since the predicate vocabulary is part
+      # of the public API contract (`docs/api_stability.md` §6) and
+      # silent canonicalization makes the legacy form indistinguishable
+      # from the current one. Removal of the SYNONYMS entries is
+      # scheduled for `1.0.0`.
       def self.canonicalize(predicate)
         return predicate if predicate.nil?
-        SYNONYMS.fetch(predicate, predicate)
+        canonical = SYNONYMS.fetch(predicate, predicate)
+        if canonical != predicate
+          ClaudeMemory::Deprecations.warn(
+            name: "predicate=#{predicate}",
+            replacement: "predicate=#{canonical}",
+            removed_in: "1.0.0",
+            message: "PredicatePolicy::SYNONYMS will be removed; emit canonical predicate names directly."
+          )
+        end
+        canonical
       end
 
       # Return the snapshot section a predicate belongs to.

data/lib/claude_memory/resolve/resolver.rb

@@ -120,15 +120,36 @@ module ClaudeMemory
 
         # No exact match: for multi-value predicates the new object is
         # genuinely a new coexisting value. For single-value, either the
-        # user signaled supersession ("now we use X instead") or the new
-        # claim contradicts the current one.
+        # user signaled supersession ("now we use X instead"), the new
+        # claim is example text (silently discarded), or the new claim
+        # contradicts the current one (conflict).
         if PredicatePolicy.single?(fact_data[:predicate])
-          supersession_signal?(fact_data) ? :supersede : :conflict
+          return :supersede if supersession_signal?(fact_data)
+          return :discard if example_text_quote?(fact_data)
+          :conflict
         else
           :insert
         end
       end
 
+      # Single-cardinality stack predicates extracted from CLAUDE.md-style
+      # example text ('e.g., "this app uses PostgreSQL"') used to create a
+      # disputed fact + conflict row every ingest cycle. The
+      # ReferenceMaterialDetector handles this for the MCP
+      # `store_extraction` path; the resolver-side guard catches the same
+      # pattern when Layer-1 NullDistiller produces a stack fact from
+      # documentation text. Added 2026-05-21 audit Phase 3.6.
+      EXAMPLE_QUOTE_PATTERNS = [
+        /\b(?:e\.?g\.?|i\.?e\.?|for example|for instance|such as)[,:]?\s/i,
+        /\(\s*(?:e\.?g\.?|i\.?e\.?)[,.]/i
+      ].freeze
+
+      def example_text_quote?(fact_data)
+        quote = fact_data[:quote].to_s
+        return false if quote.empty?
+        EXAMPLE_QUOTE_PATTERNS.any? { |re| quote.match?(re) }
+      end
+
       def apply_resolution(resolution, fact_data, subject_id, entity_ids, content_item_id, occurred_at, existing_facts, project_path:, scope:)
         case resolution
         when :reinforce
@@ -136,6 +157,12 @@ module ClaudeMemory
         when :conflict
           apply_conflict(existing_facts, fact_data, subject_id, content_item_id, occurred_at,
             project_path: project_path, scope: scope)
+        when :discard
+          # Silently drop the fact — its quote looked like documentation
+          # example text against a single-cardinality predicate that
+          # already has a confirmed value. Returning zero across the
+          # board keeps the resolver-result accounting consistent.
+          {created: 0, superseded: 0, conflicts: 0, provenance: 0}
         else
           apply_insert(fact_data, subject_id, entity_ids, content_item_id, occurred_at, existing_facts, resolution,
             project_path: project_path, scope: scope)

data/lib/claude_memory/shortcuts.rb

@@ -1,40 +1,53 @@
 # frozen_string_literal: true
 
 module ClaudeMemory
+  # Predicate-based shortcuts for the three common "give me X" queries that
+  # MCP clients (and humans via CLI) expect to be trivially fast and
+  # noise-free.
+  #
+  # Prior implementation did FTS text search ("convention style format
+  # pattern prefer") with a hardcoded global-only scope on `conventions`.
+  # That produced cross-predicate matches (uses_database rows leaking into
+  # the decisions shortcut) and silently dropped every project convention
+  # on the floor. Switching to predicate-based filtering at the store level
+  # eliminates both classes of bug; the cost is we no longer rank by FTS
+  # relevance, but for "list the project's conventions" that's the correct
+  # trade.
   class Shortcuts
-    QUERIES = {
+    SHORTCUTS = {
       decisions: {
-        query: "decision constraint rule requirement",
-        scope: "all",
+        predicates: %w[decision],
         limit: 10
       },
       architecture: {
-        query: "uses framework implements architecture pattern",
-        scope: "all",
+        # Includes the stack-shaping predicates so an agent asking
+        # "what's the architecture?" gets both narrative architecture
+        # facts AND the constraints (uses_database, uses_framework, ...).
+        # Without these the shortcut returns only freeform architecture
+        # facts and the constraints section stays invisible.
+        predicates: %w[architecture uses_database uses_framework uses_language deployment_platform auth_method],
         limit: 10
       },
       conventions: {
-        query: "convention style format pattern prefer",
-        scope: "global",
+        predicates: %w[convention],
         limit: 20
       },
       project_config: {
-        query: "uses requires depends_on configuration",
-        scope: "project",
+        predicates: %w[uses_database uses_framework uses_language deployment_platform auth_method],
         limit: 10
       }
     }.freeze
 
+    # @param shortcut_name [Symbol] :decisions, :architecture, :conventions, or :project_config
+    # @param manager [Store::StoreManager] dual-database manager
+    # @param overrides [Hash] :limit override
+    # @return [Array<Hash>] result hashes with :fact, :receipts (empty), :source ("project"/"global")
     def self.for(shortcut_name, manager, **overrides)
-      config = QUERIES.fetch(shortcut_name)
-      options = config.merge(overrides)
-
-      recall = Recall.new(manager)
-      recall.query(
-        options[:query],
-        limit: options[:limit],
-        scope: options[:scope]
-      )
+      config = SHORTCUTS.fetch(shortcut_name)
+      limit = overrides[:limit] || config[:limit]
+      predicates = config[:predicates]
+
+      collect_facts(manager, predicates, limit)
     end
 
     def self.decisions(manager, **overrides)
@@ -52,5 +65,35 @@ module ClaudeMemory
     def self.project_config(manager, **overrides)
       self.for(:project_config, manager, **overrides)
     end
+
+    # Query both stores for active facts matching the given predicates.
+    # Project facts take precedence (returned first); global facts fill
+    # any remaining slots up to the limit. Does NOT create missing DBs —
+    # callers like activity_logging's "orphan manager" depend on this
+    # surface staying read-only when the project DB hasn't been
+    # initialized yet.
+    def self.collect_facts(manager, predicates, limit)
+      project_store = manager.store_if_exists("project")
+      global_store = manager.store_if_exists("global")
+
+      project_rows = fetch_active_facts(project_store, predicates, limit)
+      global_rows = fetch_active_facts(global_store, predicates, limit)
+
+      results = project_rows.map { |row| {fact: row, receipts: [], source: "project"} } +
+        global_rows.map { |row| {fact: row, receipts: [], source: "global"} }
+
+      results.first(limit)
+    end
+
+    def self.fetch_active_facts(store, predicates, limit)
+      return [] unless store
+
+      Core::FactQueryBuilder.build_facts_dataset(store)
+        .where(Sequel[:facts][:predicate] => predicates,
+          Sequel[:facts][:status] => "active")
+        .reverse_order(Sequel[:facts][:id])
+        .limit(limit)
+        .all
+    end
   end
 end

data/lib/claude_memory/store/prompt_journey_query.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Store
+    # Cross-store query for the dashboard's Prompt Journey panel. OTel
+    # events live in the global DB (writes hit the receiver, which is
+    # process-wide); activity_events with a back-tagged prompt_id can
+    # live in either store (hooks fire per-project, so hook_ingest /
+    # hook_context rows land in the project DB, while global may carry
+    # cross-project events). The query reads from all available stores
+    # and orders the merged stream by occurred_at.
+    #
+    # Accepts either a single store (legacy callers) or a StoreManager.
+    # Returns plain row hashes shaped uniformly so the panel renders
+    # both sources without branching.
+    class PromptJourneyQuery
+      def initialize(store_or_manager)
+        @stores = if store_or_manager.respond_to?(:project_store) || store_or_manager.respond_to?(:global_store)
+          [store_or_manager.respond_to?(:project_store) ? store_or_manager.project_store : nil,
+            store_or_manager.respond_to?(:global_store) ? store_or_manager.global_store : nil].compact
+        else
+          [store_or_manager].compact
+        end
+      end
+
+      # @param prompt_id [String] OTel prompt.id UUID
+      # @return [Array<Hash>] rows ordered by occurred_at ascending
+      def fetch(prompt_id)
+        return [] if prompt_id.nil? || prompt_id.empty?
+
+        rows = @stores.flat_map { |store|
+          otel_rows(store, prompt_id) + activity_rows(store, prompt_id)
+        }
+        rows.sort_by { |r| r[:occurred_at].to_s }
+      end
+
+      private
+
+      def otel_rows(store, prompt_id)
+        return [] unless store&.db&.table_exists?(:otel_events)
+        store.otel_events
+          .where(prompt_id: prompt_id)
+          .order(:occurred_at)
+          .limit(500)
+          .all
+          .map { |row| present_otel(row) }
+      end
+
+      def activity_rows(store, prompt_id)
+        return [] unless store&.db&.table_exists?(:activity_events)
+        return [] unless store.activity_events.columns.include?(:prompt_id)
+        store.activity_events
+          .where(prompt_id: prompt_id)
+          .order(:occurred_at)
+          .limit(500)
+          .all
+          .map { |row| present_activity(row) }
+      end
+
+      def present_otel(row)
+        {
+          source: "otel",
+          id: row[:id],
+          name: row[:event_name],
+          session_id: row[:session_id],
+          prompt_id: row[:prompt_id],
+          occurred_at: row[:occurred_at],
+          attributes_json: row[:attributes_json]
+        }
+      end
+
+      def present_activity(row)
+        {
+          source: "activity",
+          id: row[:id],
+          name: row[:event_type],
+          session_id: row[:session_id],
+          prompt_id: row[:prompt_id],
+          occurred_at: row[:occurred_at],
+          status: row[:status],
+          duration_ms: row[:duration_ms],
+          detail_json: row[:detail_json]
+        }
+      end
+    end
+  end
+end

data/lib/claude_memory/store/schema_manager.rb

@@ -5,7 +5,7 @@ module ClaudeMemory
     # Schema migration and version management for SQLiteStore.
     # Handles Sequel migrations, legacy version syncing, and initial setup.
     module SchemaManager
-      SCHEMA_VERSION = 17
+      SCHEMA_VERSION = 18
 
       private
 

data/lib/claude_memory/store/sqlite_store.rb

@@ -111,6 +111,15 @@ module ClaudeMemory
       # @return [Sequel::Dataset]
       def moment_feedback = @db[:moment_feedback]
 
+      # @return [Sequel::Dataset]
+      def otel_metrics = @db[:otel_metrics]
+
+      # @return [Sequel::Dataset]
+      def otel_events = @db[:otel_events]
+
+      # @return [Sequel::Dataset]
+      def otel_traces = @db[:otel_traces]
+
       # Upsert a thumbs-up/down verdict for a moment. One row per event_id
       # (unique constraint on the column) — repeat clicks overwrite. Returns
       # the persisted row.
@@ -170,6 +179,133 @@ module ClaudeMemory
         )
       end
 
+      # Insert one OTel metric data point. Two value columns let us preserve
+      # int64 precision for counters (token counts) without losing fidelity in
+      # Float — see migration 018.
+      #
+      # @param name [String] OTel metric name (e.g. "claude_code.token.usage")
+      # @param value_type [String] "int" or "double"
+      # @param value_int [Integer, nil] integer value when value_type == "int"
+      # @param value_float [Float, nil] float value when value_type == "double"
+      # @param unit [String, nil] OTel unit string ("tokens", "USD", "s", ...)
+      # @param attributes [Hash, nil] flattened attribute map
+      # @param resource [Hash, nil] resource attribute map
+      # @param recorded_at [String] ISO 8601 timestamp
+      # @return [Integer] inserted row id
+      def insert_otel_metric(name:, value_type:, recorded_at:, value_int: nil, value_float: nil,
+        unit: nil, attributes: nil, resource: nil)
+        otel_metrics.insert(otel_metric_row(
+          name: name, value_type: value_type, recorded_at: recorded_at,
+          value_int: value_int, value_float: value_float, unit: unit,
+          attributes: attributes, resource: resource
+        ))
+      end
+
+      # Bulk insert OTel metric rows in a single SQL statement. Hot-path
+      # callers (the OTLP receiver) batch dozens of points per request;
+      # multi_insert avoids the per-row prepare/bind overhead.
+      def bulk_insert_otel_metrics(rows)
+        return 0 if rows.empty?
+        otel_metrics.multi_insert(rows.map { |r| otel_metric_row(**r) })
+        rows.size
+      end
+
+      # Insert one OTel log-style event row.
+      #
+      # @param event_name [String] e.g. "user_prompt", "tool_result", "api_request"
+      # @param occurred_at [String] ISO 8601 timestamp
+      # @param session_id [String, nil]
+      # @param prompt_id [String, nil] UUID correlating events from one prompt
+      # @param attributes [Hash, nil]
+      # @param resource [Hash, nil]
+      # @return [Integer] inserted row id
+      def insert_otel_event(event_name:, occurred_at:, session_id: nil, prompt_id: nil,
+        attributes: nil, resource: nil)
+        otel_events.insert(otel_event_row(
+          event_name: event_name, occurred_at: occurred_at,
+          session_id: session_id, prompt_id: prompt_id,
+          attributes: attributes, resource: resource
+        ))
+      end
+
+      def bulk_insert_otel_events(rows)
+        return 0 if rows.empty?
+        otel_events.multi_insert(rows.map { |r| otel_event_row(**r) })
+        rows.size
+      end
+
+      # Insert one OTel trace span row. Only used when traces are explicitly
+      # opted in via Configuration#otel_traces_enabled?.
+      #
+      # @param trace_id [String]
+      # @param span_id [String]
+      # @param name [String]
+      # @param recorded_at [String]
+      # @param parent_span_id [String, nil]
+      # @param session_id [String, nil]
+      # @param prompt_id [String, nil]
+      # @param start_unix_nano [Integer, nil]
+      # @param end_unix_nano [Integer, nil]
+      # @param duration_ms [Integer, nil]
+      # @param status_code [String, nil]
+      # @param attributes [Hash, nil]
+      # @param resource [Hash, nil]
+      # @return [Integer] inserted row id
+      def insert_otel_trace_span(trace_id:, span_id:, name:, recorded_at:,
+        parent_span_id: nil, session_id: nil, prompt_id: nil,
+        start_unix_nano: nil, end_unix_nano: nil, duration_ms: nil,
+        status_code: nil, attributes: nil, resource: nil)
+        otel_traces.insert(otel_trace_row(
+          trace_id: trace_id, span_id: span_id, name: name, recorded_at: recorded_at,
+          parent_span_id: parent_span_id, session_id: session_id, prompt_id: prompt_id,
+          start_unix_nano: start_unix_nano, end_unix_nano: end_unix_nano,
+          duration_ms: duration_ms, status_code: status_code,
+          attributes: attributes, resource: resource
+        ))
+      end
+
+      def bulk_insert_otel_traces(rows)
+        return 0 if rows.empty?
+        otel_traces.multi_insert(rows.map { |r| otel_trace_row(**r) })
+        rows.size
+      end
+
+      private
+
+      def otel_metric_row(name:, value_type:, recorded_at:, value_int: nil, value_float: nil,
+        unit: nil, attributes: nil, resource: nil)
+        {
+          name: name, value_type: value_type, value_int: value_int, value_float: value_float,
+          unit: unit, attributes_json: attributes&.to_json, resource_json: resource&.to_json,
+          recorded_at: recorded_at
+        }
+      end
+
+      def otel_event_row(event_name:, occurred_at:, session_id: nil, prompt_id: nil,
+        attributes: nil, resource: nil)
+        {
+          event_name: event_name, session_id: session_id, prompt_id: prompt_id,
+          attributes_json: attributes&.to_json, resource_json: resource&.to_json,
+          occurred_at: occurred_at
+        }
+      end
+
+      def otel_trace_row(trace_id:, span_id:, name:, recorded_at:,
+        parent_span_id: nil, session_id: nil, prompt_id: nil,
+        start_unix_nano: nil, end_unix_nano: nil, duration_ms: nil,
+        status_code: nil, attributes: nil, resource: nil)
+        {
+          trace_id: trace_id, span_id: span_id, parent_span_id: parent_span_id,
+          name: name, session_id: session_id, prompt_id: prompt_id,
+          start_unix_nano: start_unix_nano, end_unix_nano: end_unix_nano,
+          duration_ms: duration_ms, status_code: status_code,
+          attributes_json: attributes&.to_json, resource_json: resource&.to_json,
+          recorded_at: recorded_at
+        }
+      end
+
+      public
+
       # --- Content items ---
 
       # Insert a content item or return the existing id if a duplicate

data/lib/claude_memory/sweep/maintenance.rb

@@ -17,7 +17,10 @@ module ClaudeMemory
         proposed_fact_ttl_days: 14,
         disputed_fact_ttl_days: 30,
         content_retention_days: 30,
-        mcp_tool_call_retention_days: 90
+        mcp_tool_call_retention_days: 90,
+        otel_metric_retention_days: 30,
+        otel_event_retention_days: 14,
+        otel_trace_retention_days: 7
       }.freeze
 
       attr_reader :store
@@ -249,6 +252,33 @@ module ClaudeMemory
         @store.mcp_tool_calls.where { called_at < cutoff }.delete
       end
 
+      # Delete OTel metric data points older than retention window.
+      # Returns: Integer count of deleted rows (0 if table missing).
+      def prune_old_otel_metrics
+        return 0 unless @store.db.table_exists?(:otel_metrics)
+
+        cutoff = cutoff_time(@config[:otel_metric_retention_days])
+        @store.otel_metrics.where { recorded_at < cutoff }.delete
+      end
+
+      # Delete OTel log-style events older than retention window.
+      # Returns: Integer count of deleted rows (0 if table missing).
+      def prune_old_otel_events
+        return 0 unless @store.db.table_exists?(:otel_events)
+
+        cutoff = cutoff_time(@config[:otel_event_retention_days])
+        @store.otel_events.where { occurred_at < cutoff }.delete
+      end
+
+      # Delete OTel trace spans older than retention window.
+      # Returns: Integer count of deleted rows (0 if table missing).
+      def prune_old_otel_traces
+        return 0 unless @store.db.table_exists?(:otel_traces)
+
+        cutoff = cutoff_time(@config[:otel_trace_retention_days])
+        @store.otel_traces.where { recorded_at < cutoff }.delete
+      end
+
       # Checkpoint the SQLite WAL file for compaction.
       # Returns: true
       def checkpoint_wal

data/lib/claude_memory/sweep/sweeper.rb

@@ -8,6 +8,9 @@ module ClaudeMemory
         disputed_fact_ttl_days: 30,
         content_retention_days: 30,
         mcp_tool_call_retention_days: 90,
+        otel_metric_retention_days: 30,
+        otel_event_retention_days: 14,
+        otel_trace_retention_days: 7,
         default_budget_seconds: 5
       }.freeze
 
@@ -43,6 +46,9 @@ module ClaudeMemory
         run_if_within_budget { @stats[:orphaned_provenance_deleted] = maintenance.prune_orphaned_provenance }
         run_if_within_budget { @stats[:old_content_pruned] = maintenance.prune_old_content }
         run_if_within_budget { @stats[:mcp_tool_calls_pruned] = maintenance.prune_old_mcp_tool_calls }
+        run_if_within_budget { @stats[:otel_metrics_pruned] = maintenance.prune_old_otel_metrics }
+        run_if_within_budget { @stats[:otel_events_pruned] = maintenance.prune_old_otel_events }
+        run_if_within_budget { @stats[:otel_traces_pruned] = maintenance.prune_old_otel_traces }
         run_if_within_budget { @stats[:vec_backfilled] = maintenance.backfill_vec_index }
         run_if_within_budget { @stats[:vec_cleaned] = maintenance.cleanup_vec_expired }
         run_if_within_budget { @stats[:wal_checkpointed] = maintenance.checkpoint_wal }

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.12.0"
 end

data/lib/claude_memory.rb

@@ -77,6 +77,14 @@ require_relative "claude_memory/commands/dedupe_conflicts_command"
 require_relative "claude_memory/commands/reclassify_references_command"
 require_relative "claude_memory/commands/census_command"
 require_relative "claude_memory/commands/dashboard_command"
+require_relative "claude_memory/otel/constants"
+require_relative "claude_memory/otel/attributes"
+require_relative "claude_memory/otel/otlp_json_envelope"
+require_relative "claude_memory/otel/ingestor"
+require_relative "claude_memory/otel/settings_writer"
+require_relative "claude_memory/otel/status"
+require_relative "claude_memory/otel/prompt_scope"
+require_relative "claude_memory/store/prompt_journey_query"
 require_relative "claude_memory/dashboard/fact_presenter"
 require_relative "claude_memory/dashboard/scoped_fact_resolver"
 require_relative "claude_memory/dashboard/conflicts"
@@ -87,16 +95,27 @@ require_relative "claude_memory/dashboard/knowledge"
 require_relative "claude_memory/dashboard/reuse"
 require_relative "claude_memory/dashboard/timeline"
 require_relative "claude_memory/dashboard/health"
+require_relative "claude_memory/dashboard/telemetry"
+require_relative "claude_memory/dashboard/prompt_journey"
 require_relative "claude_memory/dashboard/api"
 require_relative "claude_memory/dashboard/server"
 require_relative "claude_memory/commands/digest_command"
+require_relative "claude_memory/commands/show_command"
+require_relative "claude_memory/commands/otel_command"
+require_relative "claude_memory/commands/import_auto_memory_command"
+require_relative "claude_memory/audit/finding"
+require_relative "claude_memory/audit/checks"
+require_relative "claude_memory/audit/runner"
+require_relative "claude_memory/commands/audit_command"
 require_relative "claude_memory/commands/registry"
 require_relative "claude_memory/cli"
 require_relative "claude_memory/configuration"
+require_relative "claude_memory/deprecations"
 require_relative "claude_memory/distill/distiller"
 require_relative "claude_memory/distill/extraction"
 require_relative "claude_memory/distill/null_distiller"
 require_relative "claude_memory/distill/reference_material_detector"
+require_relative "claude_memory/distill/bare_conclusion_detector"
 require_relative "claude_memory/domain/fact"
 require_relative "claude_memory/domain/entity"
 require_relative "claude_memory/domain/provenance"
@@ -147,6 +166,7 @@ require_relative "claude_memory/recall/query_core"
 require_relative "claude_memory/recall/legacy_engine"
 require_relative "claude_memory/recall/dual_engine"
 require_relative "claude_memory/recall/stale_detector"
+require_relative "claude_memory/recall/staleness_annotator"
 require_relative "claude_memory/recall"
 require_relative "claude_memory/shortcuts"
 require_relative "claude_memory/resolve/predicate_policy"