llmemory 0.1.16 → 0.2.0

data/lib/llmemory/long_term/procedural/storages/file_storage.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+require_relative "base"
+
+module Llmemory
+  module LongTerm
+    module Procedural
+      module Storages
+        class FileStorage < Base
+          def initialize(base_path: nil)
+            @base_path = base_path || Llmemory.configuration.long_term_storage_path || "./llmemory_data"
+            @base_path = File.expand_path(@base_path)
+          end
+
+          def save_skill(user_id, skill)
+            id = skill[:id] || skill["id"] || "skill_#{next_seq(user_id)}"
+            data = stringify_for_json(skill).merge("id" => id, "user_id" => user_id)
+            data["created_at"] ||= Time.now.iso8601(6)
+            File.write(skill_path(user_id, id), JSON.generate(data))
+            id
+          end
+
+          def get_skill(user_id, id)
+            path = skill_path(user_id, id)
+            return nil unless File.file?(path)
+            load_skill(path)
+          end
+
+          def list_skills(user_id, limit: nil)
+            sorted = all_skills(user_id).sort_by { |s| s[:created_at] }.reverse
+            limit && limit.to_i.positive? ? sorted.first(limit.to_i) : sorted
+          end
+
+          def search_skills(user_id, query)
+            q = query.to_s.downcase
+            return list_skills(user_id) if q.strip.empty?
+            all_skills(user_id).select { |s| skill_text(s).downcase.include?(q) }
+          end
+
+          def find_skills_by_name(user_id, name)
+            all_skills(user_id).select { |s| s[:name].to_s == name.to_s }
+          end
+
+          def record_outcome(user_id, skill_id, success:)
+            skill = get_skill(user_id, skill_id)
+            return nil unless skill
+            key = success ? :success_count : :failure_count
+            skill[key] = (skill[key] || 0).to_i + 1
+            skill[:updated_at] = Time.now.iso8601(6)
+            File.write(skill_path(user_id, skill_id), JSON.generate(stringify_for_json(skill)))
+            skill
+          end
+
+          def count_skills(user_id)
+            dir = user_path(user_id, "skills")
+            return 0 unless Dir.exist?(dir)
+            Dir.children(dir).count { |f| f.end_with?(".json") }
+          end
+
+          def delete_skills(user_id, ids)
+            Array(ids).map(&:to_s).count do |id|
+              path = skill_path(user_id, id)
+              next false unless File.file?(path)
+              File.delete(path)
+              true
+            end
+          end
+
+          def list_users
+            return [] unless Dir.exist?(@base_path)
+            Dir.children(@base_path).select { |d| Dir.exist?(File.join(@base_path, d, "skills")) }
+          end
+
+          private
+
+          def all_skills(user_id)
+            dir = user_path(user_id, "skills")
+            return [] unless Dir.exist?(dir)
+            Dir.children(dir).select { |f| f.end_with?(".json") }.map { |f| load_skill(File.join(dir, f)) }.compact
+          end
+
+          def load_skill(path)
+            data = JSON.parse(File.read(path), symbolize_names: true)
+            data[:created_at] = parse_time(data[:created_at])
+            data[:updated_at] = parse_time(data[:updated_at]) if data[:updated_at]
+            data
+          rescue JSON::ParserError
+            nil
+          end
+
+          def skill_text(skill)
+            [skill[:name], skill[:description], skill[:body]].compact.join("\n")
+          end
+
+          def stringify_for_json(skill)
+            JSON.parse(JSON.generate(skill))
+          end
+
+          def user_path(user_id, *parts)
+            safe = user_id.to_s.gsub(%r{[^\w\-.]}, "_")
+            File.join(@base_path, safe, *parts)
+          end
+
+          def skill_path(user_id, id)
+            dir = user_path(user_id, "skills")
+            FileUtils.mkdir_p(dir)
+            File.join(dir, "#{id}.json")
+          end
+
+          def meta_path(user_id)
+            FileUtils.mkdir_p(user_path(user_id))
+            File.join(user_path(user_id), "meta.json")
+          end
+
+          def next_seq(user_id)
+            path = meta_path(user_id)
+            meta = File.file?(path) ? JSON.parse(File.read(path)) : {}
+            meta["skill_id_seq"] = (meta["skill_id_seq"] || 0) + 1
+            File.write(path, JSON.generate(meta))
+            meta["skill_id_seq"]
+          end
+
+          def parse_time(val)
+            return val if val.is_a?(Time)
+            Time.parse(val.to_s)
+          rescue ArgumentError
+            Time.now
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/long_term/procedural/storages/memory_storage.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module LongTerm
+    module Procedural
+      module Storages
+        class MemoryStorage < Base
+          def initialize
+            @skills = Hash.new { |h, k| h[k] = [] }
+            @seq = 0
+          end
+
+          def save_skill(user_id, skill)
+            @seq += 1
+            id = skill[:id] || skill["id"] || "skill_#{@seq}"
+            record = symbolize(skill).merge(id: id, user_id: user_id)
+            record[:created_at] ||= Time.now
+            @skills[user_id] << record
+            id
+          end
+
+          def get_skill(user_id, id)
+            @skills[user_id].find { |s| s[:id] == id }
+          end
+
+          def list_skills(user_id, limit: nil)
+            sorted = @skills[user_id].sort_by { |s| s[:created_at] }.reverse
+            limit && limit.to_i.positive? ? sorted.first(limit.to_i) : sorted
+          end
+
+          def search_skills(user_id, query)
+            q = query.to_s.downcase
+            return list_skills(user_id) if q.strip.empty?
+            @skills[user_id].select { |s| skill_text(s).downcase.include?(q) }
+          end
+
+          def find_skills_by_name(user_id, name)
+            @skills[user_id].select { |s| s[:name].to_s == name.to_s }
+          end
+
+          def record_outcome(user_id, skill_id, success:)
+            skill = get_skill(user_id, skill_id)
+            return nil unless skill
+            key = success ? :success_count : :failure_count
+            skill[key] = (skill[key] || 0).to_i + 1
+            skill[:updated_at] = Time.now
+            skill
+          end
+
+          def count_skills(user_id)
+            @skills[user_id].size
+          end
+
+          def delete_skills(user_id, ids)
+            ids = Array(ids).map(&:to_s)
+            before = @skills[user_id].size
+            @skills[user_id].reject! { |s| ids.include?(s[:id].to_s) }
+            before - @skills[user_id].size
+          end
+
+          def list_users
+            @skills.keys
+          end
+
+          private
+
+          def symbolize(hash)
+            hash.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+          end
+
+          def skill_text(skill)
+            [skill[:name], skill[:description], skill[:body]].compact.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/long_term/procedural.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "procedural/skill"
+require_relative "procedural/storage"
+require_relative "procedural/memory"
+
+module Llmemory
+  module LongTerm
+    module Procedural
+    end
+  end
+end

data/lib/llmemory/long_term.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
+require_relative "memory_module"
 require_relative "long_term/file_based"
 require_relative "long_term/graph_based"
+require_relative "long_term/episodic"
+require_relative "long_term/procedural"
 
 module Llmemory
   module LongTerm

data/lib/llmemory/memory.rb

@@ -10,16 +10,24 @@ module Llmemory
     DEFAULT_SESSION_ID = "default"
     STATE_KEY_MESSAGES = :messages
 
-    def initialize(user_id:, session_id: DEFAULT_SESSION_ID, checkpoint: nil, long_term: nil, long_term_type: nil, retrieval_engine: nil, api_key: nil)
+    def initialize(user_id:, session_id: DEFAULT_SESSION_ID, checkpoint: nil, long_term: nil, long_term_type: nil, retrieval_engine: nil, working_memory: nil, api_key: nil)
       @user_id = user_id
       @session_id = session_id
       @checkpoint = checkpoint || ShortTerm::Checkpoint.new(user_id: user_id, session_id: session_id)
+      @working_memory = working_memory
       @llm = api_key.to_s.empty? ? nil : Llmemory::LLM.client(api_key: api_key)
       type = long_term_type || Llmemory.configuration.long_term_type || :file_based
       @long_term = long_term || build_long_term(type)
       @retrieval_engine = retrieval_engine || Retrieval::Engine.new(@long_term, llm: @llm)
     end
 
+    # Structured working memory for this session (CoALA working memory),
+    # parallel to the message checkpoint. Lazily built so it costs nothing
+    # unless an agent uses it.
+    def working_memory
+      @working_memory ||= WorkingMemory.new(user_id: @user_id, session_id: @session_id)
+    end
+
     def add_message(role:, content:)
       msgs = messages
       msgs << { role: role.to_sym, content: content.to_s }

data/lib/llmemory/memory_module.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Llmemory
+  # Uniform contract for queryable long-term memories (file-based, graph-based,
+  # episodic). CoALA argues agents should be modular with standardized
+  # abstractions; this mixin gives any memory store the same agent-facing
+  # surface so frameworks can treat them polymorphically:
+  #
+  #   read(query, user_id:, limit:)  -> relevant entries (retrieval)
+  #   write(payload, ...)            -> ingest into the store (learning)
+  #   list(user_id:, limit:)         -> enumerate stored entries
+  #   stats(user_id:)                -> counts and metadata
+  #
+  # `read` defaults to the de-facto `search_candidates` interface the retrieval
+  # Engine already relies on. `write`, `list` and `stats` are implemented by each
+  # including class over its native API.
+  #
+  # Deliberately excluded: session-state stores (Checkpoint, WorkingMemory) are a
+  # different abstraction (K/V session state, not a retrievable corpus), and
+  # deletion/forgetting semantics are deferred to a coherent unlearning API.
+  module MemoryModule
+    def read(query, user_id: nil, limit: 20)
+      unless respond_to?(:search_candidates)
+        raise NotImplementedError, "#{self.class} must implement #read or #search_candidates"
+      end
+      search_candidates(query, user_id: user_id, top_k: limit)
+    end
+
+    def write(*, **)
+      raise NotImplementedError, "#{self.class} must implement #write"
+    end
+
+    def list(user_id: nil, limit: nil)
+      raise NotImplementedError, "#{self.class} must implement #list"
+    end
+
+    def stats(user_id: nil)
+      raise NotImplementedError, "#{self.class} must implement #stats"
+    end
+
+    # Removes entries by id (the same ids returned by #read) and records the
+    # removal in a ForgetLog audit. Returns the number of entries removed.
+    # Implemented by stores with a clear deletion model; others may not support
+    # it (CoALA-style "unlearning" is understudied; deletion semantics differ).
+    def forget(ids:, reason: nil)
+      raise NotImplementedError, "#{self.class} does not support #forget"
+    end
+
+    # Shared audit trail for #forget. Lazily built; override or inject by setting
+    # @forget_log if a specific backend/store is required.
+    def forget_log
+      @forget_log ||= Llmemory::ForgetLog.new
+    end
+  end
+end

data/lib/llmemory/reflection/reflector.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Llmemory
+  module Reflection
+    # Reflection distills an agent's recent episodes (episodic memory) into
+    # durable, higher-order insights and writes them to semantic memory. This is
+    # CoALA's "updating semantic memory with knowledge" (Reflexion / Generative
+    # Agents): unlike one-shot extraction from raw text, it reasons over lived
+    # experience to generalize lessons and patterns.
+    #
+    # Each insight is stored with provenance { method: "reflection",
+    # sources: [{ type: "episode", id: ... }] } so it stays traceable to the
+    # experiences that produced it.
+    #
+    # `semantic` must respond to:
+    #   remember_fact(content:, category:, importance:, provenance:)
+    # (FileBased::Memory implements this; graph-based is a future target.)
+    class Reflector
+      DEFAULT_CATEGORY = "insights"
+      DEFAULT_IMPORTANCE = 0.6
+
+      def initialize(episodic:, semantic:, llm: nil)
+        @episodic = episodic
+        @semantic = semantic
+        @llm = llm || Llmemory::LLM.client
+      end
+
+      # Reflects over the most recent `window` episodes and writes the resulting
+      # insights to semantic memory. Returns the ids of the stored insights.
+      def reflect(window: 10, category: DEFAULT_CATEGORY)
+        episodes = @episodic.recent_episodes(limit: window)
+        return [] if episodes.empty?
+
+        insights = distill(episodes)
+        return [] if insights.empty?
+
+        sources = episodes.map(&:id).compact.map { |id| { type: "episode", id: id } }
+
+        insights.filter_map do |insight|
+          provenance = Llmemory::Provenance.build(
+            method: "reflection",
+            sources: sources,
+            confidence: insight[:confidence]
+          )
+          @semantic.remember_fact(
+            content: insight[:content],
+            category: category,
+            importance: insight[:confidence] || DEFAULT_IMPORTANCE,
+            provenance: provenance
+          )
+        end
+      end
+
+      private
+
+      def distill(episodes)
+        response = @llm.invoke(build_prompt(episodes))
+        parse_insights(response)
+      rescue Llmemory::LLMError
+        []
+      end
+
+      def build_prompt(episodes)
+        episodes_text = episodes.each_with_index.map do |ep, i|
+          "Episode #{i + 1} (outcome: #{ep.outcome || 'n/a'}):\n#{ep.searchable_text}"
+        end.join("\n\n")
+
+        <<~PROMPT
+          You are reflecting on an agent's recent experiences to distill durable,
+          higher-order insights: lessons learned, recurring patterns, and stable
+          preferences that will help in future situations. Generalize; do not
+          restate raw events.
+
+          Recent episodes:
+          #{episodes_text}
+
+          Return a JSON array of objects with "content" (the insight) and
+          "confidence" (0-1) keys. Return an empty array if nothing durable can
+          be concluded.
+          Example: [{"content": "Rolling back on deploy failure reliably restores service", "confidence": 0.8}]
+        PROMPT
+      end
+
+      def parse_insights(response)
+        json = extract_json_array(response)
+        return [] unless json
+
+        json.filter_map do |item|
+          next nil unless item.is_a?(Hash)
+          content = item["content"] || item[:content]
+          next nil if content.to_s.strip.empty?
+          { content: content.to_s, confidence: normalize_confidence(item["confidence"] || item[:confidence]) }
+        end
+      end
+
+      def normalize_confidence(value)
+        return nil if value.nil?
+        v = value.to_f
+        v.between?(0, 1) ? v : nil
+      end
+
+      def extract_json_array(response)
+        response = response.to_s.strip
+        start_idx = response.index("[")
+        end_idx = response.rindex("]")
+        return nil unless start_idx && end_idx
+
+        JSON.parse(response[start_idx..end_idx])
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/llmemory/reflection.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "reflection/reflector"
+
+module Llmemory
+  module Reflection
+  end
+end

data/lib/llmemory/retrieval/engine.rb

@@ -4,34 +4,142 @@ require_relative "temporal_ranker"
 require_relative "context_assembler"
 require_relative "bm25_scorer"
 require_relative "mmr_reranker"
+require_relative "feedback_store"
 
 module Llmemory
   module Retrieval
     class Engine
       RELEVANCE_THRESHOLD = 0.7
+      FEEDBACK_CAP = 5
 
-      def initialize(memory, llm: nil)
+      def initialize(memory, llm: nil, feedback: nil)
         @memory = memory
         @llm = llm || Llmemory::LLM.client
         @ranker = TemporalRanker.new
         @assembler = ContextAssembler.new
         @bm25_scorer = Bm25Scorer.new
         @mmr_reranker = MmrReranker.new(lambda: Llmemory.configuration.mmr_lambda)
+        @feedback = feedback || FeedbackStore.new
       end
 
       def retrieve_for_inference(user_message, user_id: nil, max_tokens: nil)
         user_id ||= @memory.respond_to?(:user_id) ? @memory.user_id : nil
         search_query = generate_query(user_message)
+        ranked = ranked_candidates(search_query, user_id, user_message)
+        @assembler.assemble(ranked, max_tokens: max_tokens)
+      end
+
+      # Multi-hop retrieval (CoALA: integrating retrieval and reasoning). After
+      # each hop, a reasoner inspects what has been retrieved and proposes a
+      # follow-up query for the missing piece, enabling multi-hop questions a
+      # single retrieval would miss. Candidates accumulate (deduped) across hops.
+      #
+      # `reasoner` is a callable (user_message, accumulated_candidates, hop) ->
+      # next query String, or "DONE"/blank to stop. Defaults to an LLM that
+      # proposes the next sub-query. Converges on `max_hops`, "DONE", a blank
+      # query, or a repeated query.
+      def iterative_retrieve(user_message, user_id: nil, max_tokens: nil, max_hops: 2, reasoner: nil)
+        user_id ||= @memory.respond_to?(:user_id) ? @memory.user_id : nil
+        reasoner ||= method(:default_followup_query)
+
+        query = generate_query(user_message)
+        seen = []
+        accumulated = []
+        hop = 0
+
+        while hop < max_hops && live_query?(query) && !seen.include?(query)
+          seen << query
+          accumulated = merge_candidates(accumulated, ranked_candidates(query, user_id, query))
+          hop += 1
+          break if hop >= max_hops
+
+          query = reasoner.call(user_message, accumulated, hop).to_s.strip
+        end
+
+        final = accumulated.sort_by { |c| -(c[:temporal_score] || c[:score] || 0) }
+        @assembler.assemble(final, max_tokens: max_tokens)
+      end
+
+      # Records that previously-retrieved items were useful or harmful for the
+      # agent's task. Repeatedly useful items rank higher in future retrievals;
+      # noisy ones are dampened. Item ids come from the candidates returned by
+      # the memory's #read / #search_candidates.
+      def report_feedback(useful_ids: [], harmful_ids: [], user_id: nil)
+        user_id ||= @memory.respond_to?(:user_id) ? @memory.user_id : nil
+        Array(useful_ids).each { |id| @feedback.record(user_id, id, 1) }
+        Array(harmful_ids).each { |id| @feedback.record(user_id, id, -1) }
+        true
+      end
+
+      private
+
+      # One retrieval hop: fetch -> hybrid -> relevance filter -> temporal rank
+      # -> feedback adjust -> (optional) MMR. Returns ranked candidates.
+      def ranked_candidates(search_query, user_id, relevance_text)
         candidates = fetch_candidates(search_query, user_id)
         candidates = apply_hybrid_scoring(candidates, search_query) if Llmemory.configuration.hybrid_search_enabled
-
-        relevant = filter_by_relevance(candidates, user_message)
+        relevant = filter_by_relevance(candidates, relevance_text)
         ranked = @ranker.rank(relevant)
-        ranked = @mmr_reranker.rerank(ranked) if Llmemory.configuration.mmr_enabled
-        @assembler.assemble(ranked, max_tokens: max_tokens)
+        ranked = apply_feedback(ranked, user_id)
+        Llmemory.configuration.mmr_enabled ? @mmr_reranker.rerank(ranked) : ranked
       end
 
-      private
+      def live_query?(query)
+        !query.nil? && !query.to_s.strip.empty? && query.to_s.strip.upcase != "DONE"
+      end
+
+      def merge_candidates(accumulated, additions)
+        by_key = {}
+        (accumulated + additions).each do |c|
+          key = c[:id] || c[:text]
+          current = by_key[key]
+          if current.nil? || score_of(c) > score_of(current)
+            by_key[key] = c
+          end
+        end
+        by_key.values
+      end
+
+      def score_of(candidate)
+        (candidate[:temporal_score] || candidate[:score] || 0).to_f
+      end
+
+      def default_followup_query(user_message, accumulated, _hop)
+        context = accumulated.first(10).map { |c| c[:text] }.compact.join("\n")
+        prompt = <<~PROMPT
+          Question: #{user_message}
+          Information retrieved so far:
+          #{context}
+
+          If more information is needed to fully answer the question, reply with a
+          single short search query for the missing piece. If what was retrieved is
+          sufficient, reply with exactly "DONE".
+        PROMPT
+        @llm.invoke(prompt.strip).to_s.strip
+      rescue Llmemory::LLMError
+        "DONE"
+      end
+
+      def apply_feedback(ranked, user_id)
+        weight = Llmemory.configuration.retrieval_feedback_weight.to_f
+        return ranked if user_id.nil? || weight <= 0
+
+        adjusted = ranked.map do |c|
+          id = c[:id] || c["id"]
+          net = id.nil? ? 0 : @feedback.net(user_id, id)
+          next c if net.zero?
+
+          base = (c[:temporal_score] || c[:score] || 0).to_f
+          c.merge(temporal_score: base * feedback_factor(net, weight))
+        end
+        adjusted.sort_by { |c| -(c[:temporal_score] || 0) }
+      end
+
+      # Maps net feedback to a bounded multiplier in [1 - weight, 1 + weight].
+      def feedback_factor(net, weight)
+        capped = [[net, -FEEDBACK_CAP].max, FEEDBACK_CAP].min
+        1.0 + (weight * (capped.to_f / FEEDBACK_CAP))
+      end
 
       def generate_query(user_message)
         return user_message.to_s if user_message.to_s.length <= 100
@@ -51,6 +159,7 @@ module Llmemory
         raw = @memory.search_candidates(search_query, user_id: user_id, top_k: 20)
         raw.map do |c|
           {
+            id: c[:id] || c["id"],
             text: c[:text] || c["text"],
             timestamp: parse_timestamp(c[:timestamp] || c["timestamp"] || c[:created_at] || c["created_at"]),
             score: (c[:score] || c["score"] || 1.0).to_f,

data/lib/llmemory/retrieval/feedback_store.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../short_term/stores"
+
+module Llmemory
+  module Retrieval
+    # Persists retrieval feedback: a net utility signal per (user, memory item),
+    # accumulated from agents marking retrieved items useful (+1) or harmful (-1).
+    #
+    # CoALA flags adaptive retrieval — "learning better retrieval procedures" — as
+    # understudied. This is the minimal substrate for it: a feedback ledger the
+    # Engine consults to boost repeatedly-useful items and dampen noise.
+    #
+    # Backed by the same pluggable short-term stores as Checkpoint/WorkingMemory,
+    # under a per-user pseudo-session key.
+    class FeedbackStore
+      SESSION_KEY = "__retrieval_feedback__"
+
+      def initialize(store: nil)
+        @store = store || ShortTerm::Stores.build
+      end
+
+      def record(user_id, item_id, delta)
+        return if user_id.nil? || item_id.nil?
+        state = load(user_id)
+        key = item_id.to_s
+        state[key] = (state[key] || 0) + delta.to_i
+        @store.save(user_id, SESSION_KEY, state)
+        state[key]
+      end
+
+      def net(user_id, item_id)
+        return 0 if user_id.nil? || item_id.nil?
+        load(user_id)[item_id.to_s] || 0
+      end
+
+      def all(user_id)
+        load(user_id)
+      end
+
+      private
+
+      def load(user_id)
+        state = @store.load(user_id, SESSION_KEY)
+        return {} unless state.is_a?(Hash)
+        state.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v.to_i }
+      end
+    end
+  end
+end

data/lib/llmemory/short_term/checkpoint.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "stores/base"
-require_relative "stores/memory_store"
-require_relative "stores/redis_store"
-require_relative "stores/postgres_store"
+require_relative "stores"
 
 module Llmemory
   module ShortTerm
@@ -31,16 +28,7 @@ module Llmemory
       private
 
       def build_store
-        case Llmemory.configuration.short_term_store.to_sym
-        when :memory then Stores::MemoryStore.new
-        when :redis then Stores::RedisStore.new
-        when :postgres then Stores::PostgresStore.new
-        when :active_record, :activerecord
-          require_relative "stores/active_record_store"
-          Stores::ActiveRecordStore.new
-        else
-          Stores::MemoryStore.new
-        end
+        Stores.build
       end
     end
   end