claude_memory 0.9.0 → 0.10.0

data/lib/claude_memory/dashboard/knowledge.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Dashboard
+    # Groups active facts into the categories a human cares about:
+    # decisions, conventions/principles, quality guards, architecture, and
+    # hard constraints. This is the bridge between internal predicate
+    # vocabulary and the value categories the user expects to see —
+    # "what decisions has Claude learned?" not "show me facts where
+    # predicate='decision'".
+    #
+    # Quality guards are a heuristic split inside the conventions section:
+    # convention-predicate facts whose object text starts with a prohibitive
+    # or imperative ("Never", "Always", "Must", "Do not", "Don't"). These
+    # are the rules that catch mistakes, not just describe preferences.
+    class Knowledge
+      QUALITY_GUARD_RE = /\A\s*(never|always|must|do not|don't)\b/i
+
+      # Order matches how they appear in the UI — decisions first (highest
+      # signal to a skeptical reader), references last (study notes about
+      # external projects, kept distinct from conventions the user applies).
+      SECTIONS = [
+        {key: :decisions, label: "Decisions", description: "Explicit choices with a reason"},
+        {key: :quality_guards, label: "Quality guards", description: "Rules that prevent mistakes"},
+        {key: :conventions, label: "Conventions & principles", description: "Style, patterns, preferences"},
+        {key: :architecture, label: "Architecture", description: "Structural knowledge"},
+        {key: :constraints, label: "Constraints", description: "Hard tech-stack facts"},
+        {key: :references, label: "References", description: "Study notes about external projects"}
+      ].freeze
+
+      TOP_PER_SECTION = 6
+
+      def initialize(manager)
+        @manager = manager
+      end
+
+      # @param params [Hash]
+      #   "scope" — "project" (default), "global", or "all"
+      #   "limit" — max facts returned per section (default 6)
+      #   "section" — when set, returns *all* facts in that section (for the
+      #     drawer "browse" view) instead of top N per section
+      def summary(params = {})
+        scope = params["scope"] || "all"
+        limit = (params["limit"] || TOP_PER_SECTION).to_i
+        section_filter = params["section"]&.to_sym
+
+        rows = collect_rows(scope)
+        sections = SECTIONS.map do |meta|
+          all_in_section = rows.select { |r| classify_row(r[:fact]) == meta[:key] }
+          shown = section_filter ? all_in_section : all_in_section.first(limit)
+          {
+            key: meta[:key],
+            label: meta[:label],
+            description: meta[:description],
+            count: all_in_section.size,
+            facts: shown.map { |r| r[:presented] }
+          }
+        end
+
+        if section_filter
+          sections = sections.select { |s| s[:key] == section_filter }
+        end
+
+        {
+          scope: scope,
+          section: section_filter,
+          totals: {
+            project: count_for_scope("project"),
+            global: count_for_scope("global")
+          },
+          sections: sections
+        }
+      end
+
+      private
+
+      def count_for_scope(scope)
+        store = @manager.store_if_exists(scope)
+        return 0 unless store
+        store.facts.where(status: "active").count
+      rescue Sequel::DatabaseError
+        0
+      end
+
+      def collect_rows(scope)
+        stores = stores_for(scope)
+        stores.flat_map do |source, store|
+          rows = store.facts.where(status: "active").order(Sequel.desc(:confidence), Sequel.desc(:created_at)).all
+          presenter = FactPresenter.new(store)
+          presented = presenter.list_summary(rows)
+          rows.zip(presented).map do |raw, p|
+            {fact: raw, presented: p.merge(source: source)}
+          end
+        end
+      end
+
+      def stores_for(scope)
+        case scope
+        when "project"
+          {"project" => @manager.store_if_exists("project")}.compact
+        when "global"
+          {"global" => @manager.store_if_exists("global")}.compact
+        else
+          {
+            "project" => @manager.store_if_exists("project"),
+            "global" => @manager.store_if_exists("global")
+          }.compact
+        end
+      end
+
+      # Maps a raw facts row to one of the SECTIONS keys. Uses PredicatePolicy
+      # for the base section, then overlays the quality-guard heuristic on
+      # convention facts.
+      def classify_row(fact_row)
+        predicate = fact_row[:predicate]
+        object = fact_row[:object_literal].to_s
+
+        base = Resolve::PredicatePolicy.section_for(predicate)
+        case base
+        when :decisions
+          :decisions
+        when :conventions
+          object.match?(QUALITY_GUARD_RE) ? :quality_guards : :conventions
+        when :constraints
+          :constraints
+        when :references
+          :references
+        else
+          # :additional — architecture predicate lands here; split it out
+          # explicitly since users reason about it differently.
+          (predicate == "architecture") ? :architecture : :conventions
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/dashboard/moments.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ClaudeMemory
+  module Dashboard
+    # Turns the flat activity_events log into enriched "moments" — the user-visible
+    # primitive for the feed-first dashboard. Each moment inlines the data needed
+    # to render its card (content preview, linked facts, resolved top_fact_ids)
+    # so the client never needs a second round trip per row.
+    #
+    # A moment's {:kind} is a stable narrative category the client uses to pick
+    # a card renderer. It's derived from event_type + status so the client
+    # doesn't have to re-derive the same mapping.
+    class Moments
+      DEFAULT_LIMIT = 50
+      CONTENT_PREVIEW_BYTES = 800
+      FEED_EVENT_TYPES = %w[hook_context recall store_extraction hook_ingest hook_sweep].freeze
+
+      # Kind → underlying event_type(s). Used to pull only relevant rows from
+      # the DB when the caller specifies kinds; without this, a noisy stream
+      # of ingests pushes the value moments past the query limit.
+      KIND_TO_EVENT_TYPES = {
+        "context_injection" => %w[hook_context],
+        "context_skipped" => %w[hook_context],
+        "recall_hit" => %w[recall],
+        "recall_empty" => %w[recall],
+        "extraction" => %w[store_extraction],
+        "ingest" => %w[hook_ingest],
+        "ingest_skipped" => %w[hook_ingest],
+        "sweep" => %w[hook_sweep]
+      }.freeze
+
+      def initialize(manager)
+        @manager = manager
+      end
+
+      # @param params [Hash]
+      #   "limit" — max moments (default 50, clamped 1..200)
+      #   "before" — ISO 8601 cursor; return moments strictly older than this
+      #   "kinds" — comma-separated kinds to include (default: all feed kinds)
+      def list(params = {})
+        store = default_store
+        return empty_response unless store
+
+        limit = (params["limit"] || DEFAULT_LIMIT).to_i.clamp(1, 200)
+        before = params["before"]
+        kinds = parse_kinds(params["kinds"])
+
+        event_types = resolve_event_types(kinds)
+        dataset = store.activity_events
+          .where(event_type: event_types)
+          .order(Sequel.desc(:occurred_at))
+        dataset = dataset.where { occurred_at < before } if before && !before.empty?
+
+        # Fetch up to 2x limit so per-kind filtering still produces a full
+        # page (e.g. recall_hit vs recall_empty both live under event_type=recall).
+        rows = dataset.limit(limit * 2).all
+        events = rows.map { |r|
+          r[:details] = r[:detail_json] ? JSON.parse(r[:detail_json], symbolize_names: true) : nil
+          r.delete(:detail_json)
+          r
+        }
+
+        moments = events.map { |e| build_moment(store, e) }
+        moments = moments.select { |m| kinds.include?(m[:kind]) } unless kinds.empty?
+        has_more = moments.size > limit
+        moments = moments.first(limit)
+        attach_feedback(store, moments)
+
+        {
+          moments: moments,
+          next_before: moments.last&.dig(:occurred_at),
+          has_more: has_more
+        }
+      end
+
+      private
+
+      # When no kinds are specified, pull all feed event types. When kinds
+      # are specified, union the event_types they map to so the DB query
+      # only loads the relevant rows.
+      def resolve_event_types(kinds)
+        return FEED_EVENT_TYPES if kinds.empty?
+        kinds.flat_map { |k| KIND_TO_EVENT_TYPES.fetch(k, []) }.uniq
+      end
+
+      def empty_response
+        {moments: [], next_before: nil, has_more: false}
+      end
+
+      def parse_kinds(raw)
+        return [] if raw.nil? || raw.empty?
+        raw.split(",").map(&:strip).reject(&:empty?)
+      end
+
+      def default_store
+        @manager.default_store(prefer: :project)
+      end
+
+      # Stable narrative kinds drive card rendering on the client. Keep this
+      # map small; any edge case becomes "event" with the raw detail exposed.
+      def kind_for(event)
+        case event[:event_type]
+        when "hook_context"
+          (event[:status] == "success") ? "context_injection" : "context_skipped"
+        when "recall"
+          details = event[:details] || {}
+          if (details[:result_count] || 0).zero?
+            "recall_empty"
+          else
+            "recall_hit"
+          end
+        when "store_extraction"
+          "extraction"
+        when "hook_ingest"
+          (event[:status] == "success") ? "ingest" : "ingest_skipped"
+        when "hook_sweep"
+          "sweep"
+        else
+          "event"
+        end
+      end
+
+      def build_moment(store, event)
+        details = event[:details] || {}
+        kind = kind_for(event)
+        base = {
+          id: event[:id],
+          event_type: event[:event_type],
+          status: event[:status],
+          kind: kind,
+          occurred_at: event[:occurred_at],
+          occurred_ago: Core::RelativeTime.format(event[:occurred_at]),
+          session_id: event[:session_id],
+          duration_ms: event[:duration_ms],
+          details: details
+        }
+
+        enrich(base, kind, store, details)
+      end
+
+      def enrich(moment, kind, store, details)
+        case kind
+        when "context_injection"
+          moment.merge(
+            context_preview: details[:preview],
+            context_length: details[:context_length],
+            fact_count: details[:fact_count] || (details[:top_fact_ids] || []).size,
+            top_subjects: details[:top_subjects] || [],
+            top_facts: resolve_scoped_facts(details),
+            truncated: details[:truncated]
+          )
+        when "recall_hit", "recall_empty"
+          moment.merge(
+            tool: details[:tool],
+            query: details[:query],
+            result_count: details[:result_count] || 0,
+            scope: details[:scope],
+            top_facts: resolve_scoped_facts(details),
+            results_by_scope: details[:results_by_scope]
+          )
+        when "extraction"
+          moment.merge(
+            tool: details[:tool],
+            facts_created: details[:facts_created] || 0,
+            entities_created: details[:entities_created] || 0,
+            content_item: resolve_content(store, details[:content_item_id] || details[:content_id]),
+            extracted_facts: extracted_facts(store, details[:content_item_id] || details[:content_id])
+          )
+        when "ingest"
+          moment.merge(
+            bytes_read: details[:bytes_read],
+            content_item: resolve_content(store, details[:content_id]),
+            extracted_facts: extracted_facts(store, details[:content_id])
+          )
+        when "ingest_skipped"
+          moment.merge(reason: details[:reason])
+        when "sweep"
+          moment.merge(
+            elapsed_seconds: details[:elapsed_seconds],
+            budget_honored: details[:budget_honored]
+          )
+        else
+          moment
+        end
+      end
+
+      def resolve_scoped_facts(details)
+        scoped = ScopedFactResolver.scoped_ids_from_details(details)
+        ScopedFactResolver.resolve(@manager, scoped)
+      end
+
+      def resolve_content(store, id)
+        return nil unless id
+        row = store.content_items.where(id: id.to_i).first
+        return nil unless row
+
+        raw = row[:raw_text].to_s
+        truncated = raw.bytesize > CONTENT_PREVIEW_BYTES
+        {
+          id: row[:id],
+          source: row[:source],
+          session_id: row[:session_id],
+          byte_len: row[:byte_len],
+          occurred_at: row[:occurred_at],
+          preview: truncated ? raw.byteslice(0, CONTENT_PREVIEW_BYTES) : raw,
+          truncated: truncated
+        }
+      rescue Sequel::DatabaseError
+        nil
+      end
+
+      def attach_feedback(store, moments)
+        return if moments.empty?
+        ids = moments.map { |m| m[:id] }
+        feedback_by_event = store.moment_feedback.where(event_id: ids).all.each_with_object({}) do |row, h|
+          h[row[:event_id]] = {
+            verdict: row[:verdict],
+            note: row[:note],
+            recorded_at: row[:recorded_at]
+          }
+        end
+        moments.each do |m|
+          m[:feedback] = feedback_by_event[m[:id]]
+        end
+      rescue Sequel::DatabaseError
+        # Table missing on older DBs — skip silently.
+      end
+
+      def extracted_facts(store, content_item_id)
+        return [] unless content_item_id
+        rows = store.db[:facts]
+          .join(:provenance, fact_id: :id)
+          .where(Sequel[:provenance][:content_item_id] => content_item_id.to_i)
+          .select(Sequel[:facts].*)
+          .all
+        FactPresenter.new(store).list_summary(rows)
+      rescue Sequel::DatabaseError
+        []
+      end
+    end
+  end
+end

data/lib/claude_memory/dashboard/reuse.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Dashboard
+    # Tracks which facts Claude actually *uses* in sessions — the ROI number.
+    # A fact that was taught once and then cited 10 times over the following
+    # month is earning its keep. A fact that's been sitting active for six
+    # months with zero recalls is just database weight.
+    #
+    # Counts both recall events (explicit memory.recall calls) and context
+    # injections (hook_context emitted_fact_ids), because both represent
+    # memory shaping what Claude sees.
+    class Reuse
+      DEFAULT_WINDOW_SECONDS = 7 * 86_400
+      DEFAULT_LIMIT = 10
+
+      COUNTING_EVENT_TYPES = %w[recall hook_context].freeze
+
+      def initialize(manager)
+        @manager = manager
+      end
+
+      # @param params [Hash]
+      #   "since" — ISO 8601 cutoff, defaults to 7 days ago
+      #   "limit" — max facts to return (default 10)
+      def top(params = {})
+        store = @manager.default_store(prefer: :project)
+        return {facts: [], window: default_window, event_count: 0} unless store
+
+        since = params["since"] || (Time.now.utc - DEFAULT_WINDOW_SECONDS).iso8601
+        limit = (params["limit"] || DEFAULT_LIMIT).to_i.clamp(1, 50)
+
+        event_rows = store.activity_events
+          .where(event_type: COUNTING_EVENT_TYPES)
+          .where(status: "success")
+          .where { occurred_at >= since }
+          .select(:id, :event_type, :occurred_at, :detail_json)
+          .all
+
+        # Count by (scope, id) pair. Project fact #5 and global fact #5
+        # are different facts — never merge their counts.
+        counts = Hash.new(0)
+        last_seen = {}
+        event_rows.each do |row|
+          details = row[:detail_json] ? JSON.parse(row[:detail_json]) : {}
+          scoped = ScopedFactResolver.scoped_ids_from_details(details)
+          ScopedFactResolver.flat_pairs(scoped).each do |pair|
+            counts[pair] += 1
+            last_seen[pair] = [last_seen[pair], row[:occurred_at]].compact.max
+          end
+        end
+
+        return {facts: [], window: {since: since}, event_count: event_rows.size} if counts.empty?
+
+        top_pairs = counts.sort_by { |_, c| -c }.first(limit).to_h.keys
+
+        # Resolve each (scope, id) in the correct DB, preserving recall
+        # count + last_recalled metadata.
+        facts = []
+        top_pairs.group_by(&:first).each do |scope, pairs|
+          s = @manager.store_if_exists(scope)
+          next unless s
+          ids = pairs.map(&:last)
+          rows = s.facts.where(id: ids, status: "active").all
+          next if rows.empty?
+          presented = FactPresenter.new(s).list_summary(rows)
+          rows.zip(presented).each do |raw, p|
+            pair = [scope, raw[:id]]
+            facts << p.merge(
+              source: scope,
+              recall_count: counts[pair],
+              last_recalled_at: last_seen[pair],
+              last_recalled_ago: Core::RelativeTime.format(last_seen[pair])
+            )
+          end
+        end
+
+        facts.sort_by! { |f| -f[:recall_count] }
+
+        {
+          window: {since: since},
+          event_count: event_rows.size,
+          facts: facts.first(limit)
+        }
+      rescue Sequel::DatabaseError, JSON::ParserError => e
+        ClaudeMemory.logger.debug("Reuse#top failed: #{e.message}")
+        {facts: [], window: default_window, event_count: 0, error: e.message}
+      end
+
+      private
+
+      def default_window
+        {since: (Time.now.utc - DEFAULT_WINDOW_SECONDS).iso8601}
+      end
+    end
+  end
+end

data/lib/claude_memory/dashboard/scoped_fact_resolver.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Dashboard
+    # Resolves fact IDs from recall/context-injection event details back to
+    # the facts they actually referenced, respecting scope. Fact IDs
+    # autoincrement per-DB, so a bare numeric ID is ambiguous — project fact
+    # #1 and global fact #1 are different facts.
+    #
+    # Reads in priority order:
+    #
+    # 1. top_facts_by_scope (new, authoritative) — already scope-tagged
+    # 2. top_fact_ids + single-scope results_by_scope — historical events
+    #    from before the fix; if the recall only touched one scope, every
+    #    ID must belong to that scope
+    # 3. top_fact_ids alone — last-resort fallback; default to project
+    #
+    # Every reader in the dashboard goes through this so the scope bug
+    # can't reappear in one spot while being fixed in another.
+    module ScopedFactResolver
+      module_function
+
+      # Normalize event details into a {scope => [ids]} hash. Returns an
+      # empty hash when no fact-ID references are present.
+      #
+      # @param details [Hash] parsed detail_json from an activity_event row
+      # @return [Hash{String => Array<Integer>}]
+      def scoped_ids_from_details(details)
+        return {} unless details.is_a?(Hash)
+        authoritative = extract_top_facts_by_scope(details)
+        return authoritative if authoritative.any?
+
+        flat_ids = Array(details[:top_fact_ids] || details["top_fact_ids"]).map(&:to_i).reject(&:zero?)
+        return {} if flat_ids.empty?
+
+        scope = single_scope_from(details[:results_by_scope] || details["results_by_scope"])
+        {scope || "project" => flat_ids}
+      end
+
+      # Resolve an entire {scope => [ids]} hash into ordered fact rows.
+      # Preserves the input order per scope so "top fact" ordering
+      # survives the round trip.
+      #
+      # @param manager [Store::StoreManager]
+      # @return [Array<Hash>] presenter-ready fact summaries with :source
+      def resolve(manager, scoped_ids)
+        return [] if scoped_ids.nil? || scoped_ids.empty?
+        results = []
+        scoped_ids.each do |scope, ids|
+          next if ids.nil? || ids.empty?
+          store = manager.store_if_exists(scope.to_s)
+          next unless store
+          rows = store.facts.where(id: ids.map(&:to_i)).all
+          next if rows.empty?
+          index = ids.each_with_index.to_h { |id, i| [id.to_i, i] }
+          rows.sort_by! { |r| index[r[:id]] || Float::INFINITY }
+          presented = FactPresenter.new(store).list_summary(rows)
+          presented.each { |f| results << f.merge(source: scope.to_s) }
+        end
+        results
+      rescue Sequel::DatabaseError => e
+        ClaudeMemory.logger.debug("ScopedFactResolver#resolve failed: #{e.message}")
+        []
+      end
+
+      # Flat list of unique scoped pairs — handy for counting unique facts
+      # referenced across a set of events.
+      #
+      # @return [Array<Array(String, Integer)>] [[scope, id], ...]
+      def flat_pairs(scoped_ids)
+        return [] if scoped_ids.nil? || scoped_ids.empty?
+        scoped_ids.flat_map { |scope, ids| ids.map { |id| [scope.to_s, id.to_i] } }.uniq
+      end
+
+      def extract_top_facts_by_scope(details)
+        raw = details[:top_facts_by_scope] || details["top_facts_by_scope"]
+        return {} unless raw.is_a?(Hash)
+        raw.each_with_object({}) do |(scope, ids), acc|
+          cleaned = Array(ids).map(&:to_i).reject(&:zero?)
+          acc[scope.to_s] = cleaned unless cleaned.empty?
+        end
+      end
+
+      # If a recall's results came from exactly one scope, every fact ID
+      # must belong to that scope. Returns the scope name, or nil when the
+      # recall touched multiple scopes (can't disambiguate) or none.
+      def single_scope_from(results_by_scope)
+        return nil unless results_by_scope.is_a?(Hash)
+        scopes_with_hits = results_by_scope.reject { |_, count| count.nil? || count.zero? }.keys
+        return nil unless scopes_with_hits.size == 1
+        scopes_with_hits.first.to_s
+      end
+    end
+  end
+end