agentf 0.4.7 → 0.6.0

data/lib/agentf/memory.rb

@@ -10,17 +10,33 @@ module Agentf
   module Memory
     # Redis-backed memory system for agent learning
     class RedisMemory
+      EPISODIC_INDEX = "episodic:logs"
       EDGE_INDEX = "edge:links"
+      DEFAULT_SEMANTIC_SCAN_LIMIT = 200
+      VECTOR_DIMENSIONS = defined?(Agentf::EmbeddingProvider::DIMENSIONS) ? Agentf::EmbeddingProvider::DIMENSIONS : 64
 
       attr_reader :project
 
-      def initialize(redis_url: nil, project: nil)
+      def initialize(redis_url: nil, project: nil, embedding_provider: Agentf::EmbeddingProvider.new)
         @redis_url = redis_url || Agentf.config.redis_url
         @project = project || Agentf.config.project_name
+        @embedding_provider = embedding_provider
         @client = Redis.new(client_options)
         @json_supported = detect_json_support
         @search_supported = detect_search_support
+        @vector_search_supported = false
         ensure_indexes if @search_supported
+        @vector_search_supported = detect_vector_search_support if @search_supported
+      end
+
+      # Raised when a write requires explicit user confirmation (ask_first).
+      class ConfirmationRequired < StandardError
+        attr_reader :details
+
+        def initialize(message = "confirmation required to persist memory", details = {})
+          super(message)
+          @details = details
+        end
       end
 
       def store_task(content:, embedding: [], language: nil, task_type: nil, success: true, agent: Agentf::AgentRoles::PLANNER)
@@ -44,10 +60,16 @@ module Agentf
         task_id
       end
 
-      def store_episode(type:, title:, description:, context: "", code_snippet: "", tags: [], agent: Agentf::AgentRoles::ENGINEER,
+      def store_episode(type:, title:, description:, context: "", code_snippet: "", agent: Agentf::AgentRoles::ORCHESTRATOR,
+                        outcome: nil, embedding: nil,
                         related_task_id: nil, metadata: {}, entity_ids: [], relationships: [], parent_episode_id: nil, causal_from: nil, confirm: nil)
         # Determine persistence preference from the agent's policy boundaries.
-        # Precedence: never > always > ask_first > none.
+        # Precedence: never > ask_first > always > none.
+        # For local/dev testing we may bypass interactive confirmation when
+        # AGENTF_AUTO_CONFIRM_MEMORIES=true. Otherwise, when an agent declares
+        # an "ask_first" persistence preference we raise ConfirmationRequired
+        # so higher-level code (MCP server / workflow engine / CLI) can prompt
+        # the user and retry the write with confirm: true.
         auto_confirm = ENV['AGENTF_AUTO_CONFIRM_MEMORIES'] == 'true'
         pref = persistence_preference_for(agent)
 
@@ -58,24 +80,13 @@ module Agentf
           rescue StandardError
           end
           return nil
-        when :always
-          # proceed without requiring explicit confirm
         when :ask_first
-          unless agent == Agentf::AgentRoles::ORCHESTRATOR || confirm == true || auto_confirm
-            begin
-              puts "[MEMORY] Skipping persistence for #{agent}: confirmation required by policy"
-            rescue StandardError
-            end
-            return nil
-          end
-        else
-          # default conservative behavior: require explicit confirm (or env opt-in)
-          unless agent == Agentf::AgentRoles::ORCHESTRATOR || confirm == true || auto_confirm
-            begin
-              puts "[MEMORY] Skipping persistence for #{agent}: confirmation required"
-            rescue StandardError
-            end
-            return nil
+          # If the agent's policy requires asking first, and we do not have
+          # an explicit confirmation (confirm: true) and auto_confirm is not
+          # enabled, raise ConfirmationRequired so callers can handle prompting.
+          unless auto_confirm || confirm == true
+            details = { "reason" => "ask_first", "agent" => agent.to_s, "attempted" => { "type" => type, "title" => title } }
+            raise ConfirmationRequired.new("confirm", details)
           end
         end
         episode_id = "episode_#{SecureRandom.hex(4)}"
@@ -83,22 +94,28 @@ module Agentf
           metadata: metadata,
           agent: agent,
           type: type,
-          tags: tags,
           entity_ids: entity_ids,
           relationships: relationships,
           parent_episode_id: parent_episode_id,
-          causal_from: causal_from
+          causal_from: causal_from,
+          outcome: outcome
         )
+        supplied_embedding = parse_embedding(embedding)
+        embedding_vector = if supplied_embedding.any?
+                             normalize_vector_dimensions(supplied_embedding)
+                           else
+                             embed_text(episode_embedding_text(title: title, description: description, context: context, code_snippet: code_snippet, metadata: normalized_metadata))
+                           end
 
         data = {
           "id" => episode_id,
           "type" => type,
+          "outcome" => normalize_outcome(outcome),
           "title" => title,
           "description" => description,
           "project" => @project,
           "context" => context,
           "code_snippet" => code_snippet,
-          "tags" => tags,
           "created_at" => Time.now.to_i,
           "agent" => agent,
           "related_task_id" => related_task_id || "",
@@ -106,7 +123,8 @@ module Agentf
           "relationships" => relationships,
           "parent_episode_id" => parent_episode_id.to_s,
           "causal_from" => causal_from.to_s,
-          "metadata" => normalized_metadata
+          "metadata" => normalized_metadata,
+          "embedding" => embedding_vector
         }
 
         key = "episodic:#{episode_id}"
@@ -132,63 +150,34 @@ module Agentf
           related_task_id: related_task_id,
           relationships: relationships,
           metadata: normalized_metadata,
-          tags: tags,
           agent: agent
         )
 
         episode_id
       end
 
-      def store_success(title:, description:, context: "", code_snippet: "", tags: [], agent: Agentf::AgentRoles::ENGINEER, confirm: nil)
+       def store_lesson(title:, description:, context: "", code_snippet: "", agent: Agentf::AgentRoles::ORCHESTRATOR, confirm: nil)
          store_episode(
-          type: "success",
-          title: title,
-          description: description,
-          context: context,
-          code_snippet: code_snippet,
-          tags: tags,
-           agent: agent,
-           confirm: confirm
-        )
-      end
-
-      def store_pitfall(title:, description:, context: "", code_snippet: "", tags: [], agent: Agentf::AgentRoles::ENGINEER, confirm: nil)
-         store_episode(
-          type: "pitfall",
-          title: title,
-          description: description,
-          context: context,
-          code_snippet: code_snippet,
-          tags: tags,
-           agent: agent,
-           confirm: confirm
-        )
-      end
-
-      def store_lesson(title:, description:, context: "", code_snippet: "", tags: [], agent: Agentf::AgentRoles::ENGINEER, confirm: nil)
-         store_episode(
-          type: "lesson",
-          title: title,
-          description: description,
-          context: context,
-          code_snippet: code_snippet,
-          tags: tags,
-           agent: agent,
-           confirm: confirm
-        )
-      end
+           type: "lesson",
+           title: title,
+           description: description,
+           context: context,
+           code_snippet: code_snippet,
+            agent: agent,
+            confirm: confirm
+         )
+       end
 
-      def store_business_intent(title:, description:, constraints: [], tags: [], agent: Agentf::AgentRoles::ORCHESTRATOR, priority: 1, confirm: nil)
+      def store_business_intent(title:, description:, constraints: [], agent: Agentf::AgentRoles::ORCHESTRATOR, priority: 1, confirm: nil)
         context = constraints.any? ? "Constraints: #{constraints.join('; ')}" : ""
 
          store_episode(
           type: "business_intent",
-          title: title,
-          description: description,
-          context: context,
-          tags: tags,
-           agent: agent,
-           confirm: confirm,
+           title: title,
+           description: description,
+           context: context,
+            agent: agent,
+            confirm: confirm,
           metadata: {
             "intent_kind" => "business",
             "constraints" => constraints,
@@ -197,7 +186,7 @@ module Agentf
         )
       end
 
-      def store_feature_intent(title:, description:, acceptance_criteria: [], non_goals: [], tags: [], agent: Agentf::AgentRoles::PLANNER,
+      def store_feature_intent(title:, description:, acceptance_criteria: [], non_goals: [], agent: Agentf::AgentRoles::PLANNER,
                                 related_task_id: nil, confirm: nil)
         context_parts = []
         context_parts << "Acceptance: #{acceptance_criteria.join('; ')}" if acceptance_criteria.any?
@@ -205,12 +194,11 @@ module Agentf
 
          store_episode(
           type: "feature_intent",
-          title: title,
-          description: description,
-          context: context_parts.join(" | "),
-          tags: tags,
-          agent: agent,
-           confirm: confirm,
+           title: title,
+           description: description,
+           context: context_parts.join(" | "),
+           agent: agent,
+            confirm: confirm,
           related_task_id: related_task_id,
           metadata: {
             "intent_kind" => "feature",
@@ -220,15 +208,15 @@ module Agentf
         )
       end
 
-      def store_incident(title:, description:, root_cause: "", resolution: "", tags: [], agent: Agentf::AgentRoles::INCIDENT_RESPONDER,
-                         business_capability: nil)
+      def store_incident(title:, description:, root_cause: "", resolution: "", agent: Agentf::AgentRoles::INCIDENT_RESPONDER,
+                         business_capability: nil, confirm: nil)
         store_episode(
           type: "incident",
           title: title,
           description: description,
           context: ["Root cause: #{root_cause}", "Resolution: #{resolution}"].reject { |entry| entry.end_with?(": ") }.join(" | "),
-          tags: tags,
           agent: agent,
+          confirm: confirm,
           metadata: {
             "root_cause" => root_cause,
             "resolution" => resolution,
@@ -238,14 +226,14 @@ module Agentf
         )
       end
 
-      def store_playbook(title:, description:, steps: [], tags: [], agent: Agentf::AgentRoles::PLANNER, feature_area: nil)
+      def store_playbook(title:, description:, steps: [], agent: Agentf::AgentRoles::PLANNER, feature_area: nil, confirm: nil)
         store_episode(
           type: "playbook",
           title: title,
           description: description,
           context: steps.any? ? "Steps: #{steps.join('; ')}" : "",
-          tags: tags,
           agent: agent,
+          confirm: confirm,
           metadata: {
             "steps" => steps,
             "feature_area" => feature_area,
@@ -306,13 +294,18 @@ module Agentf
       end
 
       def get_relevant_context(agent:, query_embedding: nil, task_type: nil, limit: 8)
-        get_agent_context(agent: agent, query_embedding: query_embedding, task_type: task_type, limit: limit)
+        get_agent_context(agent: agent, query_embedding: query_embedding, query_text: nil, task_type: task_type, limit: limit)
       end
 
-      def get_agent_context(agent:, query_embedding: nil, task_type: nil, limit: 8)
+      def get_agent_context(agent:, query_embedding: nil, query_text: nil, task_type: nil, limit: 8)
         profile = context_profile(agent)
-        candidates = get_recent_memories(limit: [limit * 8, 200].min)
-        ranked = rank_memories(candidates: candidates, agent: agent, profile: profile)
+        query_vector = normalized_query_embedding(query_embedding: query_embedding, query_text: query_text)
+        candidates = if vector_search_supported? && query_vector.any?
+                       vector_search_candidates(query_embedding: query_vector, limit: DEFAULT_SEMANTIC_SCAN_LIMIT)
+                     else
+                       collect_episode_records(scope: "project").sort_by { |mem| -(mem["created_at"] || 0) }.first(DEFAULT_SEMANTIC_SCAN_LIMIT)
+                     end
+        ranked = rank_memories(candidates: candidates, agent: agent, profile: profile, query_embedding: query_vector)
 
         {
           "agent" => agent,
@@ -323,12 +316,11 @@ module Agentf
         }
       end
 
-      def get_pitfalls(limit: 10)
-        if @search_supported
-          search_episodic(query: "@type:pitfall @project:{#{@project}}", limit: limit)
-        else
-          fetch_memories_without_search(limit: [limit * 4, 100].min).select { |mem| mem["type"] == "pitfall" }.first(limit)
-        end
+      def get_episodes(limit: 10, outcome: nil)
+        memories = fetch_memories_without_search(limit: [limit * 8, DEFAULT_SEMANTIC_SCAN_LIMIT].min)
+        memories = memories.select { |mem| mem["type"] == "episode" }
+        memories = memories.select { |mem| mem["outcome"].to_s == normalize_outcome(outcome) } if outcome
+        memories.first(limit)
       end
 
       def get_recent_memories(limit: 10)
@@ -339,16 +331,6 @@ module Agentf
         end
       end
 
-      def get_all_tags
-        memories = get_recent_memories(limit: 100)
-        all_tags = Set.new
-        memories.each do |mem|
-          tags = mem["tags"]
-          all_tags.merge(tags) if tags.is_a?(Array)
-        end
-        all_tags.to_a
-      end
-
       def delete_memory_by_id(id:, scope: "project", dry_run: false)
         normalized_scope = normalize_scope(scope)
         episode_id = normalize_episode_id(id)
@@ -411,7 +393,7 @@ module Agentf
         )
       end
 
-      def store_edge(source_id:, target_id:, relation:, weight: 1.0, tags: [], agent: Agentf::AgentRoles::ORCHESTRATOR, metadata: {})
+      def store_edge(source_id:, target_id:, relation:, weight: 1.0, agent: Agentf::AgentRoles::ORCHESTRATOR, metadata: {})
         edge_id = "edge_#{SecureRandom.hex(5)}"
         data = {
           "id" => edge_id,
@@ -419,7 +401,6 @@ module Agentf
           "target_id" => target_id,
           "relation" => relation,
           "weight" => weight.to_f,
-          "tags" => tags,
           "project" => @project,
           "agent" => agent,
           "metadata" => metadata,
@@ -471,34 +452,12 @@ module Agentf
       end
 
       def create_episodic_index
-        @client.call(
-          "FT.CREATE", "episodic:logs",
-          "ON", "JSON",
-          "PREFIX", "1", "episodic:",
-          "SCHEMA",
-          "$.id", "AS", "id", "TEXT",
-          "$.type", "AS", "type", "TEXT",
-          "$.title", "AS", "title", "TEXT",
-          "$.description", "AS", "description", "TEXT",
-          "$.project", "AS", "project", "TAG",
-          "$.context", "AS", "context", "TEXT",
-          "$.code_snippet", "AS", "code_snippet", "TEXT",
-          "$.tags", "AS", "tags", "TAG",
-          "$.created_at", "AS", "created_at", "NUMERIC",
-          "$.agent", "AS", "agent", "TEXT",
-          "$.related_task_id", "AS", "related_task_id", "TEXT",
-          "$.metadata.intent_kind", "AS", "intent_kind", "TAG",
-          "$.metadata.priority", "AS", "priority", "NUMERIC",
-          "$.metadata.confidence", "AS", "confidence", "NUMERIC",
-          "$.metadata.business_capability", "AS", "business_capability", "TAG",
-          "$.metadata.feature_area", "AS", "feature_area", "TAG",
-          "$.metadata.agent_role", "AS", "agent_role", "TAG",
-          "$.metadata.division", "AS", "division", "TAG",
-          "$.metadata.specialty", "AS", "specialty", "TAG",
-          "$.entity_ids[*]", "AS", "entity_ids", "TAG",
-          "$.parent_episode_id", "AS", "parent_episode_id", "TEXT",
-          "$.causal_from", "AS", "causal_from", "TEXT"
-        )
+        @client.call("FT.CREATE", EPISODIC_INDEX, *episodic_index_schema(include_vector: true))
+      rescue Redis::CommandError => e
+        raise if index_already_exists?(e)
+        raise unless vector_query_unsupported?(e)
+
+        @client.call("FT.CREATE", EPISODIC_INDEX, *episodic_index_schema(include_vector: false))
       end
 
       def create_edge_index
@@ -514,38 +473,19 @@ module Agentf
           "$.project", "AS", "project", "TAG",
           "$.agent", "AS", "agent", "TAG",
           "$.weight", "AS", "weight", "NUMERIC",
-          "$.created_at", "AS", "created_at", "NUMERIC",
-          "$.tags", "AS", "tags", "TAG"
+          "$.created_at", "AS", "created_at", "NUMERIC"
         )
       end
 
       def search_episodic(query:, limit:)
         results = @client.call(
-          "FT.SEARCH", "episodic:logs",
+          "FT.SEARCH", EPISODIC_INDEX,
           query,
           "SORTBY", "created_at", "DESC",
           "LIMIT", "0", limit.to_s
         )
 
-        return [] unless results && results[0] > 0
-
-        memories = []
-        (2...results.length).step(2) do |i|
-          item = results[i]
-          if item.is_a?(Array)
-            item.each_with_index do |part, j|
-              if part == "$" && j + 1 < item.length
-                begin
-                  memory = JSON.parse(item[j + 1])
-                  memories << memory
-                rescue JSON::ParserError
-                  # Skip invalid JSON
-                end
-              end
-            end
-          end
-        end
-        memories
+        parse_search_results(results)
       end
 
       def index_already_exists?(error)
@@ -579,7 +519,7 @@ module Agentf
       end
 
       def detect_search_support
-        @client.call("FT.INFO", "episodic:logs")
+        @client.call("FT.INFO", EPISODIC_INDEX)
         true
       rescue Redis::CommandError => e
         return true if index_missing_error?(e)
@@ -588,6 +528,28 @@ module Agentf
         raise Redis::CommandError, "Failed to check RediSearch availability: #{e.message}"
       end
 
+      def detect_vector_search_support
+        return false unless @search_supported
+
+        info = @client.call("FT.INFO", EPISODIC_INDEX)
+        return false unless info.to_s.upcase.include?("VECTOR")
+
+        @client.call(
+          "FT.SEARCH", EPISODIC_INDEX,
+          "*=>[KNN 1 @embedding $query_vector AS vector_distance]",
+          "PARAMS", "2", "query_vector", pack_vector(Array.new(VECTOR_DIMENSIONS, 0.0)),
+          "SORTBY", "vector_distance", "ASC",
+          "RETURN", "2", "$", "vector_distance",
+          "DIALECT", "2",
+          "LIMIT", "0", "1"
+        )
+        true
+      rescue Redis::CommandError => e
+        return false if index_missing_error?(e) || vector_query_unsupported?(e)
+
+        raise Redis::CommandError, "Failed to check Redis vector search availability: #{e.message}"
+      end
+
       def index_missing_error?(error)
         message = error.message
         return false unless message
@@ -617,7 +579,7 @@ module Agentf
           cursor, batch = @client.scan(cursor, match: "episodic:*", count: 100)
           batch.each do |key|
             memory = load_episode(key)
-            memories << memory if memory
+            memories << memory if memory && memory["project"].to_s == @project.to_s
           end
           break if cursor == "0"
         end
@@ -628,21 +590,21 @@ module Agentf
       def context_profile(agent)
         case agent.to_s.upcase
         when Agentf::AgentRoles::PLANNER
-          { "preferred_types" => %w[business_intent feature_intent lesson playbook pitfall], "pitfall_penalty" => 0.1 }
+          { "preferred_types" => %w[business_intent feature_intent lesson playbook episode], "negative_outcome_penalty" => 0.1 }
         when Agentf::AgentRoles::ENGINEER
-          { "preferred_types" => %w[playbook success lesson pitfall], "pitfall_penalty" => 0.05 }
+          { "preferred_types" => %w[playbook episode lesson], "negative_outcome_penalty" => 0.05 }
         when Agentf::AgentRoles::QA_TESTER
-          { "preferred_types" => %w[lesson pitfall incident success], "pitfall_penalty" => 0.0 }
+          { "preferred_types" => %w[lesson episode incident], "negative_outcome_penalty" => 0.0 }
         when Agentf::AgentRoles::INCIDENT_RESPONDER
-          { "preferred_types" => %w[incident pitfall lesson], "pitfall_penalty" => 0.0 }
+          { "preferred_types" => %w[incident episode lesson], "negative_outcome_penalty" => 0.0 }
         when Agentf::AgentRoles::SECURITY_REVIEWER
-          { "preferred_types" => %w[pitfall lesson incident], "pitfall_penalty" => 0.0 }
+          { "preferred_types" => %w[episode lesson incident], "negative_outcome_penalty" => 0.0 }
         else
-          { "preferred_types" => %w[lesson pitfall success business_intent feature_intent], "pitfall_penalty" => 0.05 }
+          { "preferred_types" => %w[lesson episode business_intent feature_intent], "negative_outcome_penalty" => 0.05 }
         end
       end
 
-      def rank_memories(candidates:, agent:, profile:)
+      def rank_memories(candidates:, agent:, profile:, query_embedding: nil)
         now = Time.now.to_i
         preferred_types = Array(profile["preferred_types"])
 
@@ -654,19 +616,41 @@ module Agentf
             confidence = metadata.fetch("confidence", 0.6).to_f
             confidence = 0.0 if confidence.negative?
             confidence = 1.0 if confidence > 1.0
+            semantic_score = cosine_similarity(query_embedding, parse_embedding(memory["embedding"]))
 
             type_score = preferred_types.include?(type) ? 1.0 : 0.25
             agent_score = (memory["agent"] == agent || memory["agent"] == Agentf::AgentRoles::ORCHESTRATOR) ? 1.0 : 0.2
             age_seconds = [now - memory.fetch("created_at", now).to_i, 0].max
             recency_score = 1.0 / (1.0 + (age_seconds / 86_400.0))
 
-            pitfall_penalty = type == "pitfall" ? profile.fetch("pitfall_penalty", 0.0).to_f : 0.0
-            memory["rank_score"] = ((0.45 * type_score) + (0.3 * agent_score) + (0.2 * recency_score) + (0.05 * confidence) - pitfall_penalty).round(6)
+            negative_outcome_penalty = memory["outcome"] == "negative" ? profile.fetch("negative_outcome_penalty", 0.0).to_f : 0.0
+            memory["rank_score"] = ((0.4 * semantic_score) + (0.22 * type_score) + (0.18 * agent_score) + (0.15 * recency_score) + (0.05 * confidence) - negative_outcome_penalty).round(6)
             memory
           end
           .sort_by { |memory| -memory["rank_score"] }
       end
 
+      public def search_memories(query:, limit: 10, type: nil, agent: nil, outcome: nil)
+        query_vector = embed_text(query)
+        candidates = if vector_search_supported? && query_vector.any?
+                       native = vector_search_episodes(query_embedding: query_vector, limit: limit, type: type, agent: agent, outcome: outcome)
+                       native.empty? ? collect_episode_records(scope: "project", type: type, agent: agent) : native
+                     else
+                       collect_episode_records(scope: "project", type: type, agent: agent)
+                     end
+        candidates = candidates.select { |mem| mem["outcome"].to_s == normalize_outcome(outcome) } if outcome
+
+        ranked = candidates.map do |memory|
+          score = cosine_similarity(query_vector, parse_embedding(memory["embedding"]))
+          lexical = lexical_overlap_score(query, memory)
+          next if score <= 0 && lexical <= 0
+
+          memory.merge("score" => ((0.75 * score) + (0.25 * lexical)).round(6))
+        end.compact
+
+        ranked.sort_by { |memory| -memory["score"] }.first(limit)
+      end
+
       def load_episode(key)
         raw = if @json_supported
                 begin
@@ -701,6 +685,37 @@ module Agentf
         []
       end
 
+      def parse_search_results(results)
+        return [] unless results && results[0].to_i.positive?
+
+        records = []
+        (2...results.length).step(2) do |i|
+          item = results[i]
+          next unless item.is_a?(Array)
+
+          record = {}
+          item.each_slice(2) do |field, value|
+            next if value.nil?
+
+            if field == "$"
+              begin
+                payload = JSON.parse(value)
+                record.merge!(payload) if payload.is_a?(Hash)
+              rescue JSON::ParserError
+                record = nil
+                break
+              end
+            else
+              record[field] = value
+            end
+          end
+
+          records << record if record.is_a?(Hash) && record.any?
+        end
+
+        records
+      end
+
       def cosine_similarity(a, b)
         return 0.0 if a.empty? || b.empty? || a.length != b.length
 
@@ -748,6 +763,53 @@ module Agentf
         memories
       end
 
+      def vector_search_episodes(query_embedding:, limit:, type: nil, agent: nil, outcome: nil)
+        return [] unless vector_search_supported?
+
+        requested_limit = [limit.to_i, 1].max
+        search_limit = [requested_limit * 4, 10].max
+        filters = ["@project:{#{escape_tag(@project)}}"]
+        normalized_outcome = normalize_outcome(outcome)
+        filters << "@outcome:{#{escape_tag(normalized_outcome)}}" if normalized_outcome
+        base_query = filters.join(" ")
+
+        results = @client.call(
+          "FT.SEARCH", EPISODIC_INDEX,
+          "#{base_query}=>[KNN #{search_limit} @embedding $query_vector AS vector_distance]",
+          "PARAMS", "2", "query_vector", pack_vector(query_embedding),
+          "SORTBY", "vector_distance", "ASC",
+          "RETURN", "2", "$", "vector_distance",
+          "DIALECT", "2",
+          "LIMIT", "0", search_limit.to_s
+        )
+
+        parse_search_results(results)
+          .select do |memory|
+            next false unless memory["project"].to_s == @project.to_s
+            next false unless type.to_s.empty? || memory["type"].to_s == type.to_s
+            next false unless agent.to_s.empty? || memory["agent"].to_s == agent.to_s
+            next false unless normalized_outcome.nil? || memory["outcome"].to_s == normalized_outcome
+
+            true
+          end
+          .each { |memory| memory["vector_distance"] = memory["vector_distance"].to_f if memory.key?("vector_distance") }
+          .first(requested_limit)
+      rescue Redis::CommandError => e
+        if vector_query_unsupported?(e)
+          @vector_search_supported = false
+          return []
+        end
+
+        raise
+      end
+
+      def vector_search_candidates(query_embedding:, limit:)
+        native = vector_search_episodes(query_embedding: query_embedding, limit: limit)
+        return native if native.any?
+
+        collect_episode_records(scope: "project").sort_by { |mem| -(mem["created_at"] || 0) }.first(DEFAULT_SEMANTIC_SCAN_LIMIT)
+      end
+
       def collect_related_edge_keys(episode_ids:, scope:)
         ids = episode_ids.map(&:to_s).reject(&:empty?).to_set
         return [] if ids.empty?
@@ -844,9 +906,9 @@ module Agentf
         }
       end
 
-      def persist_relationship_edges(episode_id:, related_task_id:, relationships:, metadata:, tags:, agent:)
+      def persist_relationship_edges(episode_id:, related_task_id:, relationships:, metadata:, agent:)
         if related_task_id && !related_task_id.to_s.strip.empty?
-          store_edge(source_id: episode_id, target_id: related_task_id, relation: "relates_to", tags: tags, agent: agent)
+          store_edge(source_id: episode_id, target_id: related_task_id, relation: "relates_to", agent: agent)
         end
 
         Array(relationships).each do |relation|
@@ -861,7 +923,6 @@ module Agentf
             target_id: target,
             relation: relation_type,
             weight: (relation["weight"] || relation[:weight] || 1.0).to_f,
-            tags: tags,
             agent: agent,
             metadata: { "source_metadata" => extract_metadata_slice(metadata, %w[intent_kind agent_role division]) }
           )
@@ -869,58 +930,89 @@ module Agentf
 
         parent = metadata["parent_episode_id"].to_s
         unless parent.empty?
-          store_edge(source_id: episode_id, target_id: parent, relation: "child_of", tags: tags, agent: agent)
+          store_edge(source_id: episode_id, target_id: parent, relation: "child_of", agent: agent)
         end
 
         causal_from = metadata["causal_from"].to_s
         unless causal_from.empty?
-          store_edge(source_id: episode_id, target_id: causal_from, relation: "caused_by", tags: tags, agent: agent)
+          store_edge(source_id: episode_id, target_id: causal_from, relation: "caused_by", agent: agent)
         end
       rescue StandardError
         nil
       end
 
-      def enrich_metadata(metadata:, agent:, type:, tags:, entity_ids:, relationships:, parent_episode_id:, causal_from:)
+      def enrich_metadata(metadata:, agent:, type:, entity_ids:, relationships:, parent_episode_id:, causal_from:, outcome:)
         base = metadata.is_a?(Hash) ? metadata.dup : {}
         base["agent_role"] = agent
         base["division"] = infer_division(agent)
         base["specialty"] = infer_specialty(agent)
         base["capabilities"] = infer_capabilities(agent)
         base["episode_type"] = type
-        base["tag_count"] = Array(tags).length
         base["relationship_count"] = Array(relationships).length
         base["entity_ids"] = Array(entity_ids)
+        base["outcome"] = normalize_outcome(outcome) if outcome
         base["parent_episode_id"] = parent_episode_id.to_s unless parent_episode_id.to_s.empty?
         base["causal_from"] = causal_from.to_s unless causal_from.to_s.empty?
         base
       end
 
-      # Determine whether writes from the given agent should require explicit
-      # confirmation. We consider agents that declare "ask_first" policy
-      # boundaries to be conservative and require confirmation before persisting
-      # memories. Agent classes register policy boundaries on their class
-      # definitions (see agents/*). When agent is provided as a role string
-      # (eg. "ENGINEER") we try to match against known agent classes.
-      def agent_requires_confirmation?(agent)
-        begin
-          # If a developer passed an agent class-like string, try to map it to
-          # the loaded agent class and inspect its policy_boundaries.
-          candidate = Agentf::Agents.constants
-                      .map { |c| Agentf::Agents.const_get(c) }
-                      .find do |klass|
-                        klass.is_a?(Class) && klass.respond_to?(:policy_boundaries) && klass.typed_name == agent
-                      end
+      def normalized_query_embedding(query_embedding:, query_text:)
+        embedded = parse_embedding(query_embedding)
+        return embedded if embedded.any?
 
-          return false unless candidate
+        embed_text(query_text)
+      end
 
-          boundaries = candidate.policy_boundaries
-          ask_first = Array(boundaries["ask_first"]) rescue []
-          !ask_first.empty?
-        rescue StandardError
-          false
-        end
+      def episode_embedding_text(title:, description:, context:, code_snippet:, metadata:)
+        [
+          title,
+          description,
+          context,
+          code_snippet,
+          metadata["feature_area"],
+          metadata["business_capability"],
+          metadata["intent_kind"],
+          metadata["resolution"],
+          metadata["root_cause"]
+        ].compact.join("\n")
       end
 
+      def lexical_overlap_score(query, memory)
+        query_tokens = normalize_tokens(query)
+        return 0.0 if query_tokens.empty?
+
+        memory_tokens = normalize_tokens([memory["title"], memory["description"], memory["context"], memory["code_snippet"]].compact.join(" "))
+        return 0.0 if memory_tokens.empty?
+
+        overlap = (query_tokens & memory_tokens).length
+        overlap.to_f / query_tokens.length.to_f
+      end
+
+      def normalize_tokens(text)
+        text.to_s.downcase.scan(/[a-z0-9_]+/).reject { |token| token.length < 2 }
+      end
+
+      def embed_text(text)
+        @embedding_provider.embed(text)
+      end
+
+      def normalize_outcome(value)
+        normalized = value.to_s.strip.downcase
+        return nil if normalized.empty?
+        return "positive" if %w[positive success succeeded passed pass completed approved].include?(normalized)
+        return "negative" if %w[negative failure failed fail pitfall error blocked violated].include?(normalized)
+        return "neutral" if %w[neutral info informational lesson observation].include?(normalized)
+
+        normalized
+      end
+
+      # NOTE: previous implementations exposed an `agent_requires_confirmation?`
+      # helper here. That functionality is superseded by
+      # `persistence_preference_for(agent)` which returns explicit preferences
+      # (:always, :ask_first, :never) and is used by callers to decide whether
+      # interactive confirmation is required. Keep this file lean and avoid
+      # duplicate helpers.
+
       # Inspect loaded agent classes for explicit persistence preference.
       # Returns one of: :always, :ask_first, :never, or nil when unknown.
       def persistence_preference_for(agent)
@@ -934,9 +1026,15 @@ module Agentf
           return nil unless candidate
 
           boundaries = candidate.policy_boundaries
-          return :never if Array(boundaries["never"]).any?
-          return :always if Array(boundaries["always"]).any? && Array(boundaries["ask_first"]).empty?
-          return :ask_first if Array(boundaries["ask_first"]).any?
+          persist_pattern = /persist|store|save/i
+
+          never_matches = Array(boundaries["never"]).select { |s| s =~ persist_pattern }
+          ask_matches = Array(boundaries["ask_first"]).select { |s| s =~ persist_pattern }
+          always_matches = Array(boundaries["always"]).select { |s| s =~ persist_pattern }
+
+          return :never if never_matches.any?
+          return :ask_first if ask_matches.any?
+          return :always if always_matches.any? && ask_matches.empty?
           nil
         rescue StandardError
           nil
@@ -1071,24 +1169,7 @@ module Agentf
           "SORTBY", "created_at", "DESC",
           "LIMIT", "0", limit.to_s
         )
-        return [] unless results && results[0] > 0
-
-        records = []
-        (2...results.length).step(2) do |i|
-          item = results[i]
-          next unless item.is_a?(Array)
-
-          item.each_with_index do |part, j|
-            next unless part == "$" && j + 1 < item.length
-
-            begin
-              records << JSON.parse(item[j + 1])
-            rescue JSON::ParserError
-              nil
-            end
-          end
-        end
-        records
+        parse_search_results(results)
       end
 
       def fetch_edges_without_search(node_id:, relation_filters:, limit:)
@@ -1115,6 +1196,65 @@ module Agentf
         value.to_s.gsub(/[\-{}\[\]|\\]/) { |m| "\\#{m}" }
       end
 
+      def episodic_index_schema(include_vector:)
+        schema = [
+          "ON", "JSON",
+          "PREFIX", "1", "episodic:",
+          "SCHEMA",
+          "$.id", "AS", "id", "TEXT",
+          "$.type", "AS", "type", "TEXT",
+          "$.outcome", "AS", "outcome", "TAG",
+          "$.title", "AS", "title", "TEXT",
+          "$.description", "AS", "description", "TEXT",
+          "$.project", "AS", "project", "TAG",
+          "$.context", "AS", "context", "TEXT",
+          "$.code_snippet", "AS", "code_snippet", "TEXT",
+          "$.created_at", "AS", "created_at", "NUMERIC",
+          "$.agent", "AS", "agent", "TEXT",
+          "$.related_task_id", "AS", "related_task_id", "TEXT",
+          "$.metadata.intent_kind", "AS", "intent_kind", "TAG",
+          "$.metadata.priority", "AS", "priority", "NUMERIC",
+          "$.metadata.confidence", "AS", "confidence", "NUMERIC",
+          "$.metadata.business_capability", "AS", "business_capability", "TAG",
+          "$.metadata.feature_area", "AS", "feature_area", "TAG",
+          "$.metadata.agent_role", "AS", "agent_role", "TAG",
+          "$.metadata.division", "AS", "division", "TAG",
+          "$.metadata.specialty", "AS", "specialty", "TAG",
+          "$.entity_ids[*]", "AS", "entity_ids", "TAG",
+          "$.parent_episode_id", "AS", "parent_episode_id", "TEXT",
+          "$.causal_from", "AS", "causal_from", "TEXT"
+        ]
+
+        return schema unless include_vector
+
+        schema + [
+          "$.embedding", "AS", "embedding", "VECTOR", "FLAT", "6",
+          "TYPE", "FLOAT32",
+          "DIM", VECTOR_DIMENSIONS.to_s,
+          "DISTANCE_METRIC", "COSINE"
+        ]
+      end
+
+      def vector_search_supported?
+        @search_supported && @vector_search_supported
+      end
+
+      def normalize_vector_dimensions(vector)
+        values = Array(vector).map(&:to_f).first(VECTOR_DIMENSIONS)
+        values.fill(0.0, values.length...VECTOR_DIMENSIONS)
+      end
+
+      def pack_vector(vector)
+        normalize_vector_dimensions(vector).pack("e*")
+      end
+
+      def vector_query_unsupported?(error)
+        message = error.message.to_s.downcase
+        return false if message.empty?
+
+        message.include?("vector") || message.include?("knn") || message.include?("dialect") || message.include?("syntax error")
+      end
+
       def extract_metadata_slice(metadata, keys)
         keys.each_with_object({}) do |key, acc|
           acc[key] = metadata[key] if metadata.key?(key)