smart_brain 0.1.1 → 0.2.0

data/lib/smart_brain/governance/lifecycle.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'tiers'
+
+module SmartBrain
+  module Governance
+    # Stage-1 knowledge lifecycle (mempal parity):
+    #
+    #   evidence → distill(candidate) → gate → promote(promoted) → demote/retire
+    #
+    # Operates over a MemoryStore (independent of backend). distill creates a
+    # candidate knowledge item at tier dao_ren|qi; gate is a read-only readiness
+    # check; promote/demote are evidence-backed transitions that append to the
+    # knowledge_events audit trail. Orthogonal to the conflict `status`.
+    class Lifecycle
+      DEMOTE_REASONS = %w[contradicted obsolete superseded].freeze
+
+      def initialize(memory_store:, config:, model_provider: nil)
+        @memory_store = memory_store
+        @config = config
+        @model_provider = model_provider
+      end
+
+      def distill(session_id:, statement:, content: nil, tier:, supporting_refs: [], domain: nil, field: nil,
+                  reviewer: nil, key: nil, scope_id: nil, scope: nil)
+        tier = tier.to_s
+        raise ArgumentError, "tier must be one of #{Tiers::DISTILLABLE.join('/')}" unless Tiers.distillable?(tier)
+
+        statement = draft_statement(statement, supporting_refs: supporting_refs, content: content) if statement.nil? || statement.strip.empty?
+        raise ArgumentError, 'statement is required (provide one or wire an LLM provider)' if statement.nil? || statement.strip.empty?
+
+        item = {
+          type: 'knowledge',
+          key: key || "knowledge:#{tier}:#{slugify(statement)}",
+          value_json: {
+            statement: statement,
+            content: content,
+            tier: tier,
+            domain: domain,
+            field: field,
+            supporting_refs: Array(supporting_refs)
+          },
+          confidence: 0.5,
+          status: 'active',
+          tier: tier,
+          lifecycle_status: 'candidate',
+          source_turn_id: nil,
+          updated_at: Time.now.utc.iso8601
+        }
+        record = memory_store.create_item(session_id: session_id, item: item, scope_id: scope_id, scope: scope)
+        memory_store.record_event(
+          memory_item_id: record[:id], event_type: 'distill',
+          from_lifecycle: nil, to_lifecycle: 'candidate',
+          reason: 'distilled from evidence', reviewer: reviewer,
+          evidence_refs: Array(supporting_refs)
+        )
+        { memory_item: record, event: last_event(record[:id]) }
+      end
+
+      # Read-only promotion readiness check.
+      def gate(memory_item_id:)
+        item = memory_store.find_item(id: memory_item_id)
+        raise ArgumentError, "memory item not found: #{memory_item_id}" unless item
+
+        refs = Array(item.dig(:value_json, :supporting_refs) || item.dig(:value_json, 'supporting_refs'))
+        min = min_supporting_refs
+        reviewer = item.dig(:value_json, :reviewer) || item.dig(:value_json, 'reviewer')
+        checks = {
+          lifecycle: item[:lifecycle_status],
+          supporting_refs: refs.size,
+          min_required: min,
+          reviewer: reviewer
+        }
+        ready = item[:lifecycle_status] == 'candidate' && (refs.size >= min || reviewer == 'human')
+        { ready: ready, target_status: 'promoted', checks: checks }
+      end
+
+      def promote(memory_item_id:, verification_refs:, reason:, reviewer: nil, force: false)
+        item = memory_store.find_item(id: memory_item_id)
+        raise ArgumentError, "memory item not found: #{memory_item_id}" unless item
+
+        decision = gate(memory_item_id: memory_item_id)
+        if !decision[:ready] && !force
+          raise LifecycleGateError, "promotion gate failed: #{decision[:checks].inspect}"
+        end
+
+        from = item[:lifecycle_status]
+        updated = memory_store.set_lifecycle(
+          id: memory_item_id, lifecycle_status: 'promoted',
+          merge_value: { verification_refs: Array(verification_refs), reviewer: reviewer }
+        )
+        memory_store.record_event(
+          memory_item_id: memory_item_id, event_type: 'promote',
+          from_lifecycle: from, to_lifecycle: 'promoted',
+          reason: reason, reviewer: reviewer, evidence_refs: Array(verification_refs)
+        )
+        { memory_item: updated, event: last_event(memory_item_id) }
+      end
+
+      def demote(memory_item_id:, evidence_refs:, reason:, reason_type:, reviewer: nil)
+        raise ArgumentError, "reason_type must be one of #{DEMOTE_REASONS.join('/')}" unless DEMOTE_REASONS.include?(reason_type.to_s)
+
+        item = memory_store.find_item(id: memory_item_id)
+        raise ArgumentError, "memory item not found: #{memory_item_id}" unless item
+
+        from = item[:lifecycle_status]
+        updated = memory_store.set_lifecycle(
+          id: memory_item_id, lifecycle_status: 'demoted',
+          merge_value: { demotion_reason: reason, reason_type: reason_type }
+        )
+        memory_store.record_event(
+          memory_item_id: memory_item_id, event_type: 'demote',
+          from_lifecycle: from, to_lifecycle: 'demoted',
+          reason: reason, reason_type: reason_type, reviewer: reviewer, evidence_refs: Array(evidence_refs)
+        )
+        { memory_item: updated, event: last_event(memory_item_id) }
+      end
+
+      def promote_to_scope(source_item:, target_scope:, session_id:, verification_refs:, reason:, reviewer: nil)
+        refs = Array(verification_refs)
+        unless reviewer == 'human' || refs.size >= min_supporting_refs
+          raise LifecycleGateError, "scope promotion requires human review or #{min_supporting_refs} verification refs"
+        end
+
+        provenance = {
+          source_memory_item_id: source_item[:id],
+          source_scope: source_item[:scope],
+          target_scope: { type: target_scope[:type], id: target_scope[:id] },
+          source_session_id: source_item[:source_session_id] || source_item[:session_id],
+          verification_refs: refs,
+          reviewer: reviewer,
+          reason: reason
+        }
+        item = source_item.slice(:type, :key, :confidence, :tier).merge(
+          value_json: (source_item[:value_json] || {}).merge(provenance: provenance),
+          status: 'active', lifecycle_status: 'promoted', source_turn_id: source_item[:source_turn_id],
+          source_message_id: source_item[:source_message_id],
+          source_session_id: source_item[:source_session_id] || source_item[:session_id],
+          updated_at: Time.now.utc.iso8601
+        )
+        target = memory_store.create_item(
+          session_id: session_id, item: item, scope_id: target_scope[:scope_id],
+          scope: { type: target_scope[:type], id: target_scope[:id] }
+        )
+        event = memory_store.record_event(
+          memory_item_id: target[:id], event_type: 'promote_to_scope',
+          from_lifecycle: source_item[:lifecycle_status], to_lifecycle: 'promoted',
+          reason: reason, reviewer: reviewer, evidence_refs: refs
+        )
+        target = memory_store.set_lifecycle(
+          id: target[:id], lifecycle_status: 'promoted',
+          merge_value: { provenance: provenance.merge(promotion_event_id: event[:id]) }
+        )
+        { source_memory_item: source_item, memory_item: target, event: event }
+      end
+
+      def retract(memory_item_id:, evidence_refs:, reason:, reviewer: nil)
+        item = memory_store.find_item(id: memory_item_id)
+        raise ArgumentError, "memory item not found: #{memory_item_id}" unless item
+
+        updated = memory_store.set_status(id: memory_item_id, status: 'retracted', merge_value: { retraction_reason: reason })
+        event = memory_store.record_event(
+          memory_item_id: memory_item_id, event_type: 'retract',
+          from_lifecycle: item[:lifecycle_status], to_lifecycle: item[:lifecycle_status],
+          reason: reason, reviewer: reviewer, evidence_refs: Array(evidence_refs)
+        )
+        { memory_item: updated, event: event }
+      end
+
+      def lineage(memory_item_id:)
+        lineage = []
+        current = memory_store.find_item(id: memory_item_id)
+        while current
+          lineage << current
+          source_id = current.dig(:value_json, :provenance, :source_memory_item_id)
+          break unless source_id
+
+          current = memory_store.find_item(id: source_id)
+        end
+        lineage
+      end
+
+      def events(memory_item_id:)
+        memory_store.events_for(memory_item_id: memory_item_id)
+      end
+
+      private
+
+      attr_reader :memory_store, :config, :model_provider
+
+      def min_supporting_refs
+        config.lifecycle.fetch(:min_supporting_refs, 2) rescue 2
+      end
+
+      def last_event(memory_item_id)
+        memory_store.events_for(memory_item_id: memory_item_id).last
+      end
+
+      def draft_statement(statement, supporting_refs:, content:)
+        return statement unless model_provider&.llm?
+        return nil if Array(supporting_refs).empty?
+
+        refs_text = supporting_refs_for(supporting_refs).map { |i| "- #{i[:key]}: #{i.dig(:value_json, :statement) || i[:value_json]}" }.join("\n")
+        result = model_provider.complete(
+          prompt: "Distill ONE concise knowledge statement (<= 1 line) from these observations; reply with only the statement.\n#{refs_text}",
+          temperature: 0.2, max_tokens: 120
+        )
+        result[:error] ? nil : result[:text]
+      rescue StandardError
+        nil
+      end
+
+      def supporting_refs_for(refs)
+        Array(refs).filter_map { |id| memory_store.find_item(id: id) }
+      end
+
+      def slugify(text)
+        text.to_s.downcase.scan(/[[:alnum:]]+/).first(6).join('-')[0, 60]
+      end
+    end
+
+    class LifecycleGateError < StandardError; end
+  end
+end

data/lib/smart_brain/governance/tiers.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module SmartBrain
+  module Governance
+    # Mind-model tiers (mempal parity): dao_tian 天道 / dao_ren 人道 / shu 术 /
+    # qi 器 / evidence 证据. Lower ORDER index = higher assembly priority.
+    module Tiers
+      ORDER = %w[dao_tian dao_ren shu qi evidence].freeze
+      PRIORITY = ORDER.each_with_index.to_h.freeze
+
+      # Default tier per memory type. dao_tian is never auto-assigned — it is
+      # reserved for user-pinned immutable principles.
+      DEFAULT_TIER_BY_TYPE = {
+        'profile' => 'dao_ren',
+        'decisions' => 'dao_ren',
+        'patterns' => 'dao_ren',
+        'goals' => 'shu',
+        'tasks' => 'shu',
+        'preferences' => 'qi',
+        'cases' => 'qi',
+        'entities' => 'evidence',
+        'events' => 'evidence'
+      }.freeze
+
+      # Only dao_ren / qi knowledge can enter the candidate stage via distill
+      # (mempal rule: dao_tian and shu are not open to candidate state).
+      DISTILLABLE = %w[dao_ren qi].freeze
+
+      # lifecycle statuses that participate in automatic context assembly.
+      CONTEXT_LIFECYCLE = %w[raw promoted].freeze
+
+      module_function
+
+      def tier_for(type)
+        DEFAULT_TIER_BY_TYPE.fetch(type.to_s, 'evidence')
+      end
+
+      def priority(tier)
+        PRIORITY.fetch(tier.to_s, PRIORITY.fetch('evidence'))
+      end
+
+      def distillable?(tier)
+        DISTILLABLE.include?(tier.to_s)
+      end
+
+      def valid?(tier)
+        PRIORITY.key?(tier.to_s)
+      end
+
+      def dao_tian_limit(config)
+        (config.tiers.fetch(:dao_tian_limit, 1) rescue 1)
+      end
+
+      # Sort by tier priority asc (dao_tian first); stable on equal priority.
+      def sort_by_tier(items)
+        items.sort_by.with_index { |i, idx| [priority(i[:tier] || i['tier'] || 'evidence'), idx] }
+      end
+    end
+  end
+end

data/lib/smart_brain/memory_extractor/extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../governance/tiers'
+
 module SmartBrain
   module MemoryExtractor
     class Extractor
@@ -16,11 +18,14 @@ module SmartBrain
         collect(items, explain, events[:decisions], type: 'decisions', confidence: confidence(:user_asserted), source_turn_id: turn[:id])
         collect(items, explain, events[:goals], type: 'goals', confidence: confidence(:user_asserted), source_turn_id: turn[:id])
         collect(items, explain, events[:events], type: 'events', confidence: confidence(:tool_derived), source_turn_id: turn[:id])
+        collect(items, explain, events[:profile], type: 'profile', confidence: confidence(:user_asserted), source_turn_id: turn[:id])
+        collect(items, explain, events[:cases], type: 'cases', confidence: confidence(:tool_derived), source_turn_id: turn[:id])
+        collect(items, explain, events[:patterns], type: 'patterns', confidence: confidence(:inferred), source_turn_id: turn[:id])
 
         Array(events[:preferences]).each do |preference|
           key = preference.fetch(:key)
           if preference[:confirmed]
-            items << build_item(type: 'preferences', key: key, value_json: preference, source_turn_id: turn[:id], confidence: confidence(:user_asserted))
+            items << build_item(type: 'preferences', key: key, value_json: preference, source_turn_id: turn[:id], confidence: confidence(:user_asserted), scope_ref: preference[:scope_ref])
             explain << "write preferences:#{key}"
           else
             explain << "skip preferences:#{key} not confirmed"
@@ -32,7 +37,7 @@ module SmartBrain
           canonical = (entity[:canonical] || entity[:name]).to_s.downcase
           should_write = entity[:remember] || entity_structure_signal?(entity) || entity_frequencies[canonical] >= freq_threshold
           if should_write
-            items << build_item(type: 'entities', key: key, value_json: entity, source_turn_id: turn[:id], confidence: confidence(:inferred))
+            items << build_item(type: 'entities', key: key, value_json: entity, source_turn_id: turn[:id], confidence: confidence(:inferred), scope_ref: entity[:scope_ref])
             explain << "write entities:#{key}"
           else
             explain << "skip entities:#{key} below threshold"
@@ -40,14 +45,24 @@ module SmartBrain
         end
 
         Array(events[:retractions]).each do |retraction|
-          items << build_item(type: retraction.fetch(:type), key: retraction.fetch(:key), value_json: retraction, source_turn_id: turn[:id], confidence: confidence(:user_asserted), status: 'retracted')
+          items << build_item(type: retraction.fetch(:type), key: retraction.fetch(:key), value_json: retraction, source_turn_id: turn[:id], confidence: confidence(:user_asserted), status: 'retracted', scope_ref: retraction[:scope_ref])
           explain << "retract #{retraction.fetch(:type)}:#{retraction.fetch(:key)}"
         end
 
+        # KG edges: pass-through (subject/predicate/object). Orthogonal to
+        # memory_items — runtime persists them to kg_edges via KnowledgeGraph.
+        edges = Array(events[:edges]).map do |edge|
+          next unless edge[:subject] && edge[:predicate] && edge[:object]
+
+          { subject: edge[:subject], predicate: edge[:predicate],
+            object: edge[:object], confidence: edge[:confidence], scope_ref: edge[:scope_ref] }
+        end.compact
+
         {
           session_id: session_id,
           items: items,
-          explain: explain
+          explain: explain,
+          edges: edges
         }
       end
 
@@ -58,12 +73,12 @@ module SmartBrain
       def collect(items, explain, raw_items, type:, confidence:, source_turn_id:)
         Array(raw_items).each do |entry|
           key = entry.fetch(:key)
-          items << build_item(type: type, key: key, value_json: entry, source_turn_id: source_turn_id, confidence: confidence)
+          items << build_item(type: type, key: key, value_json: entry, source_turn_id: source_turn_id, confidence: confidence, scope_ref: entry[:scope_ref])
           explain << "write #{type}:#{key}"
         end
       end
 
-      def build_item(type:, key:, value_json:, source_turn_id:, confidence:, status: 'active')
+      def build_item(type:, key:, value_json:, source_turn_id:, confidence:, status: 'active', scope_ref: nil)
         {
           type: type,
           key: key,
@@ -71,7 +86,10 @@ module SmartBrain
           source_turn_id: source_turn_id,
           confidence: confidence,
           status: status,
-          updated_at: Time.now.utc.iso8601
+          tier: Governance::Tiers.tier_for(type),
+          lifecycle_status: 'raw',
+          updated_at: Time.now.utc.iso8601,
+          scope_ref: scope_ref
         }
       end
 

data/lib/smart_brain/memory_store/in_memory.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'securerandom'
+require_relative '../governance/tiers'
+require_relative '../retrievers/exact_retriever'
 
 module SmartBrain
   module MemoryStore
@@ -8,8 +10,12 @@ module SmartBrain
       OVERWRITE_TYPES = %w[preferences goals tasks].freeze
 
       def initialize
-        @by_session = Hash.new { |h, k| h[k] = [] }
+        @by_scope = Hash.new { |h, k| h[k] = [] }
         @entities_index = Hash.new { |h, k| h[k] = [] }
+        @summaries = {}
+        @events = []
+        @edges = []
+        @exact = Retrievers::ExactRetriever.new
       end
 
       def upsert(extracted)
@@ -19,7 +25,9 @@ module SmartBrain
         conflicts = []
 
         items.each do |item|
-          existing = active_item(session_id: session_id, type: item[:type], key: item[:key])
+          scope_id = item[:scope_id] || legacy_scope_id(session_id)
+          scope = item[:scope] || { type: 'session', id: session_id }
+          existing = active_item(scope_id: scope_id, type: item[:type], key: item[:key])
 
           if existing && item[:status] == 'retracted'
             existing[:status] = 'retracted'
@@ -32,47 +40,224 @@ module SmartBrain
             conflicts << { type: 'overwrite', key: item[:key], previous_memory_item_id: existing[:id] }
           end
 
-          record = item.merge(id: SecureRandom.uuid, status: item[:status] || 'active')
-          by_session[session_id] << record
-          update_entities(session_id: session_id, record: record)
-          written << record.slice(:id, :type, :key, :status, :confidence)
+          record = item.merge(
+            id: SecureRandom.uuid, status: item[:status] || 'active', session_id: session_id,
+            source_session_id: item[:source_session_id] || session_id, scope_id: scope_id, scope: scope
+          )
+          by_scope[scope_id] << record
+          update_entities(scope_id: scope_id, record: record)
+          written << record.slice(:id, :type, :key, :status, :confidence, :scope_id, :scope, :source_session_id)
         end
 
         { count: written.size, items: written, conflicts: conflicts }
       end
 
-      def active_items(session_id:)
-        by_session[session_id].select { |item| item[:status] == 'active' }
+      def active_items(session_id: nil, scope_ids: nil)
+        selected_scope_ids = normalize_scope_ids(session_id, scope_ids)
+        selected_scope_ids.flat_map { |scope_id| by_scope[scope_id] }
+                          .select { |item| item[:status] == 'active' && included_lifecycle?(item) }
       end
 
-      def entities(session_id:)
-        entities_index[session_id]
+      def entities(session_id: nil, scope_ids: nil)
+        normalize_scope_ids(session_id, scope_ids).flat_map { |scope_id| entities_index[scope_id] }
+      end
+
+      # Substring/exact search over active memory_items. Mirrors the FTS path of
+      # MemoryStore::Postgres#search_memory so MemoryRetriever is backend-agnostic.
+      def search_memory(query:, session_id: nil, scope_ids: nil, limit:)
+        @exact.retrieve(
+          query: query, memory_items: active_items(session_id: session_id, scope_ids: scope_ids), recent_turns: [], limit: limit
+        )
+      end
+
+      def save_summary(session_id:, summary:)
+        summaries[session_id] = summary
+        summary
+      end
+
+      def latest_summary(session_id:)
+        summaries[session_id]
+      end
+
+      def all_summaries
+        summaries.each_with_object({}) { |(sid, s), h| h[sid] = s }
+      end
+
+      # --- knowledge lifecycle -------------------------------------------------
+      def create_item(session_id:, item:, scope_id: nil, scope: nil)
+        resolved_scope_id = scope_id || item[:scope_id] || legacy_scope_id(session_id)
+        record = item.merge(
+          id: SecureRandom.uuid, session_id: session_id, source_session_id: item[:source_session_id] || session_id,
+          scope_id: resolved_scope_id, scope: scope || item[:scope] || { type: 'session', id: session_id }
+        )
+        by_scope[resolved_scope_id] << record
+        update_entities(scope_id: resolved_scope_id, record: record)
+        record
+      end
+
+      def find_item(id:)
+        by_scope.values.flatten.find { |i| i[:id] == id }
+      end
+
+      def set_lifecycle(id:, lifecycle_status:, merge_value: nil)
+        item = find_item(id: id)
+        return nil unless item
+
+        item[:lifecycle_status] = lifecycle_status
+        item[:value_json] = (item[:value_json] || {}).merge(merge_value || {})
+        item[:updated_at] = Time.now.utc.iso8601
+        item
+      end
+
+      def set_status(id:, status:, merge_value: nil)
+        item = find_item(id: id)
+        return nil unless item
+
+        item[:status] = status
+        item[:value_json] = (item[:value_json] || {}).merge(merge_value || {})
+        item[:updated_at] = Time.now.utc.iso8601
+        item
+      end
+
+      def record_event(memory_item_id:, event_type:, from_lifecycle: nil, to_lifecycle: nil,
+                       reason: nil, reason_type: nil, reviewer: nil, evidence_refs: [])
+        event = {
+          id: SecureRandom.uuid,
+          memory_item_id: memory_item_id,
+          event_type: event_type,
+          from_lifecycle: from_lifecycle,
+          to_lifecycle: to_lifecycle,
+          reason: reason,
+          reason_type: reason_type,
+          reviewer: reviewer,
+          evidence_refs: Array(evidence_refs),
+          created_at: Time.now.utc.iso8601
+        }
+        events << event
+        event
+      end
+
+      def events_for(memory_item_id:)
+        events.select { |e| e[:memory_item_id] == memory_item_id }
+      end
+
+      # --- knowledge graph -----------------------------------------------------
+      def add_edge(session_id:, edge:, scope_id: nil, scope: nil, source_session_id: nil)
+        resolved_scope_id = scope_id || edge[:scope_id] || legacy_scope_id(session_id)
+        record = {
+          id: SecureRandom.uuid,
+          session_id: session_id,
+          source_session_id: source_session_id || edge[:source_session_id] || session_id,
+          scope_id: resolved_scope_id,
+          scope: scope || edge[:scope] || { type: 'session', id: session_id },
+          subject: edge[:subject].to_s,
+          predicate: edge[:predicate].to_s,
+          object: edge[:object].to_s,
+          subject_entity_id: resolve_entity_id(nil, edge[:subject], scope_ids: [resolved_scope_id]),
+          object_entity_id: resolve_entity_id(nil, edge[:object], scope_ids: [resolved_scope_id]),
+          valid_from: edge[:valid_from] || Time.now.utc.iso8601,
+          valid_to: edge[:valid_to],
+          source_turn_id: edge[:source_turn_id],
+          source_memory_item_id: edge[:source_memory_item_id],
+          confidence: edge[:confidence] || 0.6,
+          status: edge[:status] || 'active',
+          meta: edge[:meta] || {},
+          created_at: Time.now.utc.iso8601
+        }
+        edges << record
+        record
+      end
+
+      def query_edges(session_id: nil, scope_ids: nil, subject: nil, predicate: nil, object: nil, include_invalid: false)
+        selected_scope_ids = normalize_scope_ids(session_id, scope_ids)
+        edges.select do |e|
+          next false unless selected_scope_ids.include?(e[:scope_id])
+          next false if !include_invalid && e[:status] != 'active'
+          next false if subject && e[:subject].downcase != subject.to_s.downcase
+          next false if predicate && e[:predicate].downcase != predicate.to_s.downcase
+          next false if object && e[:object].downcase != object.to_s.downcase
+
+          true
+        end.sort_by { |e| e[:valid_from].to_s }
+      end
+
+      def edges_for_subject(session_id: nil, scope_ids: nil, subject:)
+        query_edges(session_id: session_id, scope_ids: scope_ids, subject: subject, include_invalid: true)
+      end
+
+      def invalidate_edge(id:, reason: nil)
+        edge = edges.find { |e| e[:id] == id }
+        return nil unless edge
+
+        edge[:valid_to] = Time.now.utc.iso8601
+        edge[:status] = 'invalidated'
+        edge[:meta] = (edge[:meta] || {}).merge(invalidated_reason: reason)
+        edge
+      end
+
+      def find_edge(id:)
+        edges.find { |edge| edge[:id] == id }
+      end
+
+      def edge_stats(session_id: nil, scope_ids: nil)
+        selected_scope_ids = normalize_scope_ids(session_id, scope_ids)
+        scoped = edges.select { |e| selected_scope_ids.include?(e[:scope_id]) }
+        { total: scoped.size,
+          active: scoped.count { |e| e[:status] == 'active' },
+          invalidated: scoped.count { |e| e[:status] == 'invalidated' } }
+      end
+
+      def resolve_entity_id(session_id, name, scope_ids: nil)
+        return nil if name.nil? || name.to_s.empty?
+
+        match = entities(session_id: session_id, scope_ids: scope_ids).find do |e|
+          e[:canonical].to_s.downcase == name.to_s.downcase ||
+            e[:name].to_s.downcase == name.to_s.downcase
+        end
+        match && match[:id]
       end
 
       private
 
-      attr_reader :by_session, :entities_index
+      attr_reader :by_scope, :entities_index, :summaries, :events, :edges
 
-      def active_item(session_id:, type:, key:)
-        by_session[session_id].find { |row| row[:type] == type && row[:key] == key && row[:status] == 'active' }
+      def active_item(scope_id:, type:, key:)
+        by_scope[scope_id].find { |row| row[:type] == type && row[:key] == key && row[:status] == 'active' }
       end
 
-      def update_entities(session_id:, record:)
+      def included_lifecycle?(item)
+        Governance::Tiers::CONTEXT_LIFECYCLE.include?(item[:lifecycle_status] || 'raw')
+      end
+
+      def update_entities(scope_id:, record:)
         return unless record[:type] == 'entities'
 
         value = record[:value_json]
         canonical = value[:canonical] || value[:name]
-        existing = entities_index[session_id].find { |e| e[:canonical] == canonical && e[:kind] == value[:kind] }
+        existing = entities_index[scope_id].find { |e| e[:canonical] == canonical && e[:kind] == value[:kind] }
         return if existing
 
-        entities_index[session_id] << {
+        entities_index[scope_id] << {
           id: SecureRandom.uuid,
           name: value[:name] || canonical,
           kind: value[:kind] || 'other',
           canonical: canonical,
-          memory_item_id: record[:id]
+          memory_item_id: record[:id],
+          scope_id: record[:scope_id],
+          scope: record[:scope],
+          source_session_id: record[:source_session_id]
         }
       end
+
+      def normalize_scope_ids(session_id, scope_ids)
+        ids = Array(scope_ids).compact
+        ids = [legacy_scope_id(session_id)] if ids.empty? && session_id
+        ids
+      end
+
+      def legacy_scope_id(session_id)
+        "legacy:session:#{session_id}"
+      end
     end
   end
 end