llmemory 0.1.17 → 0.2.0

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

data/lib/llmemory/short_term/session_lifecycle.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "stores"
+
 module Llmemory
   module ShortTerm
     class SessionLifecycle
@@ -72,16 +74,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

data/lib/llmemory/short_term/stores.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "stores/base"
+require_relative "stores/memory_store"
+require_relative "stores/redis_store"
+require_relative "stores/postgres_store"
+
+module Llmemory
+  module ShortTerm
+    module Stores
+      # Single source of truth for selecting a short-term store backend.
+      # Shared by Checkpoint, SessionLifecycle and WorkingMemory.
+      def self.build(store_type = nil)
+        case (store_type || Llmemory.configuration.short_term_store).to_sym
+        when :memory then MemoryStore.new
+        when :redis then RedisStore.new
+        when :postgres then PostgresStore.new
+        when :active_record, :activerecord
+          require_relative "stores/active_record_store"
+          ActiveRecordStore.new
+        else
+          MemoryStore.new
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Llmemory
-  VERSION = "0.1.17"
+  VERSION = "0.2.0"
 end

data/lib/llmemory/working_memory.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "short_term/stores"
+
+module Llmemory
+  # CoALA's "working memory": a structured, symbolic scratch space that persists
+  # across LLM calls within a session — distinct from the raw message buffer
+  # (Checkpoint). It is the central hub an agent reads from and writes to while
+  # reasoning (goals, current task, retrieved context, intermediate reasoning,
+  # last observation, free-form scratchpad), plus arbitrary custom slots.
+  #
+  # Backed by the same pluggable short-term stores as Checkpoint, but under a
+  # namespaced session key so working-memory slots never collide with messages.
+  class WorkingMemory
+    DEFAULT_SESSION_ID = "default"
+    SESSION_SUFFIX = ":working_memory"
+    SLOTS = %i[goals current_task retrieved_context scratchpad last_observation intermediate_reasoning].freeze
+
+    attr_reader :user_id, :session_id
+
+    def initialize(user_id:, session_id: DEFAULT_SESSION_ID, store: nil)
+      @user_id = user_id
+      @session_id = session_id
+      @store_key = "#{session_id}#{SESSION_SUFFIX}"
+      @store = store || ShortTerm::Stores.build
+    end
+
+    SLOTS.each do |slot|
+      define_method(slot) { read[slot] }
+      define_method("#{slot}=") { |value| set(slot, value) }
+    end
+
+    # Read/write an arbitrary slot (typed or custom).
+    def get(slot)
+      read[slot.to_sym]
+    end
+
+    def set(slot, value)
+      state = read
+      state[slot.to_sym] = value
+      persist(state)
+      value
+    end
+
+    # Bulk update in a single write.
+    def update(**slots)
+      state = read
+      slots.each { |k, v| state[k.to_sym] = v }
+      persist(state)
+      state
+    end
+
+    # Slots set by the caller beyond the predefined typed ones.
+    def custom_slots
+      read.reject { |k, _| SLOTS.include?(k) }
+    end
+
+    def to_h
+      read
+    end
+
+    def clear!
+      @store.delete(@user_id, @store_key)
+      true
+    end
+
+    private
+
+    def read
+      state = @store.load(@user_id, @store_key)
+      return {} unless state.is_a?(Hash)
+      symbolize(state)
+    end
+
+    def persist(state)
+      @store.save(@user_id, @store_key, state)
+    end
+
+    def symbolize(hash)
+      hash.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+    end
+  end
+end

data/lib/llmemory.rb

@@ -3,14 +3,18 @@
 require_relative "llmemory/version"
 require_relative "llmemory/configuration"
 require_relative "llmemory/provenance"
+require_relative "llmemory/memory_module"
+require_relative "llmemory/forget_log"
 require_relative "llmemory/llm"
 require_relative "llmemory/short_term"
+require_relative "llmemory/working_memory"
 require_relative "llmemory/long_term"
 require_relative "llmemory/retrieval"
 require_relative "llmemory/vector_store"
 require_relative "llmemory/maintenance"
 require_relative "llmemory/extractors"
 require_relative "llmemory/reflection"
+require_relative "llmemory/actions"
 require_relative "llmemory/memory"
 
 module Llmemory

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llmemory
 version: !ruby/object:Gem::Version
-  version: 0.1.17
+  version: 0.2.0
 platform: ruby
 authors:
 - llmemory
@@ -127,6 +127,8 @@ files:
 - lib/generators/llmemory/install/install_generator.rb
 - lib/generators/llmemory/install/templates/create_llmemory_tables.rb
 - lib/llmemory.rb
+- lib/llmemory/actions.rb
+- lib/llmemory/actions/reason.rb
 - lib/llmemory/cli.rb
 - lib/llmemory/cli/commands/base.rb
 - lib/llmemory/cli/commands/long_term.rb
@@ -147,6 +149,7 @@ files:
 - lib/llmemory/extractors.rb
 - lib/llmemory/extractors/entity_relation_extractor.rb
 - lib/llmemory/extractors/fact_extractor.rb
+- lib/llmemory/forget_log.rb
 - lib/llmemory/llm.rb
 - lib/llmemory/llm/anthropic.rb
 - lib/llmemory/llm/base.rb
@@ -183,6 +186,13 @@ files:
 - lib/llmemory/long_term/graph_based/storages/active_record_storage.rb
 - lib/llmemory/long_term/graph_based/storages/base.rb
 - lib/llmemory/long_term/graph_based/storages/memory_storage.rb
+- lib/llmemory/long_term/procedural.rb
+- lib/llmemory/long_term/procedural/memory.rb
+- lib/llmemory/long_term/procedural/skill.rb
+- lib/llmemory/long_term/procedural/storage.rb
+- lib/llmemory/long_term/procedural/storages/base.rb
+- lib/llmemory/long_term/procedural/storages/file_storage.rb
+- lib/llmemory/long_term/procedural/storages/memory_storage.rb
 - lib/llmemory/maintenance.rb
 - lib/llmemory/maintenance/consolidator.rb
 - lib/llmemory/maintenance/reindexer.rb
@@ -201,6 +211,7 @@ files:
 - lib/llmemory/mcp/tools/memory_timeline.rb
 - lib/llmemory/mcp/tools/memory_timeline_context.rb
 - lib/llmemory/memory.rb
+- lib/llmemory/memory_module.rb
 - lib/llmemory/noise_filter.rb
 - lib/llmemory/provenance.rb
 - lib/llmemory/reflection.rb
@@ -209,6 +220,7 @@ files:
 - lib/llmemory/retrieval/bm25_scorer.rb
 - lib/llmemory/retrieval/context_assembler.rb
 - lib/llmemory/retrieval/engine.rb
+- lib/llmemory/retrieval/feedback_store.rb
 - lib/llmemory/retrieval/mmr_reranker.rb
 - lib/llmemory/retrieval/temporal_ranker.rb
 - lib/llmemory/short_term.rb
@@ -216,6 +228,7 @@ files:
 - lib/llmemory/short_term/message_sanitizer.rb
 - lib/llmemory/short_term/pruner.rb
 - lib/llmemory/short_term/session_lifecycle.rb
+- lib/llmemory/short_term/stores.rb
 - lib/llmemory/short_term/stores/active_record_checkpoint.rb
 - lib/llmemory/short_term/stores/active_record_store.rb
 - lib/llmemory/short_term/stores/base.rb
@@ -229,6 +242,7 @@ files:
 - lib/llmemory/vector_store/memory_store.rb
 - lib/llmemory/vector_store/openai_embeddings.rb
 - lib/llmemory/version.rb
+- lib/llmemory/working_memory.rb
 - lib/tasks/release.rake
 homepage: https://github.com/entaina/llmemory
 licenses: