llmemory 0.1.16 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 135c27c05f80b660972a5aa8df5ba315cbdd8235ac68c662ddcfe9249ca79109
-  data.tar.gz: 2e43bacc332ddb44613c79ebd7e4e832091fc68c451a75073860502962d496d9
+  metadata.gz: c302656888e6373faedb5732525f76d118fd98fb67ece22278d886faec5ba3cd
+  data.tar.gz: ec0897226ec378e51e86e01cb66e938fbeea3db7e4c49911d7e3d08a08959d07
 SHA512:
-  metadata.gz: 9b0d7d67c2647ec0392f993ed31aedc5d51fdc3dadf40bd1a511b90a55b24ce415a9b9a420cc6e676d5a3ba8eb780048e047eff9d0800618dc10e99c4c779a1f
-  data.tar.gz: 10184e66c86c94976d2c164f8717633fbb438e0e95cfb0dbffed4ce52f8bbf8c4266c0b3e48879c792250da15a385464983a886408c69598044c0f60c13f27e7
+  metadata.gz: 6cee9a244e42f198b9fd491d164d85d2524a30d6cf9ca0b4a4da3f1a012f7e2b4643ba1e4dd6838ba7ce32517d5425b77f62df1cb1334ac34d162a273cd6400f
+  data.tar.gz: 6d46031eda16a52b7c8b42b364dc5351a0eb18f0eeaa135271a3976a0ebba39db439e74fafa981b9cea062d70e2bd006b4576ccaccfff29bfd6ec6fe8011a411

data/README.md

@@ -70,6 +70,10 @@ Llmemory.configure do |config|
   config.prune_after_days = 90
   config.compact_max_bytes = 8192  # max bytes before compact! triggers
 
+  # Retrieval ranking signals (see "Cognitive Memory (CoALA)")
+  config.importance_weight = 1.0          # how strongly importance multiplies the score (0 = ignore)
+  config.retrieval_feedback_weight = 0.5  # how strongly useful/harmful feedback shifts ranking (0 = ignore)
+
   # Pre-compaction memory flush (prevents knowledge loss when compacting)
   config.memory_flush_enabled = true
   config.memory_flush_threshold_tokens = 4000
@@ -195,6 +199,174 @@ candidates = memory.search_candidates("job", top_k: 20)
 
 **Graph storage:** `:memory` (in-memory) or `:active_record` (Rails). For ActiveRecord, run `rails g llmemory:install` and migrate; the migration creates `llmemory_nodes`, `llmemory_edges`, and `llmemory_embeddings` (pgvector). Enable the `vector` extension in PostgreSQL for embeddings.
 
+## Cognitive Memory (CoALA)
+
+llmemory implements the memory and internal-action concepts from [CoALA — Cognitive Architectures for Language Agents](https://arxiv.org/abs/2309.02427) (Sumers et al., 2024), so a framework can build agents with episodic/semantic/procedural memory, structured working memory, and reasoning/retrieval/learning actions.
+
+| CoALA concept | llmemory |
+|---|---|
+| Working memory | `Llmemory::WorkingMemory` |
+| Episodic memory | `Llmemory::LongTerm::Episodic::Memory` |
+| Semantic memory | `FileBased::Memory` / `GraphBased::Memory` |
+| Procedural memory | `Llmemory::LongTerm::Procedural::Memory` |
+| Reasoning action | `Llmemory::Actions::Reason` |
+| Retrieval action | `Retrieval::Engine` (+ feedback, iterative) |
+| Learning action | `memorize` / `record_episode` / `register_skill` / reflection |
+| Uniform interface | `Llmemory::MemoryModule` (`read`/`write`/`list`/`stats`/`forget`) |
+
+All three long-term memories below are **additive** — episodic and procedural coexist with semantic memory rather than replacing it. Episodic/procedural ship with `:memory` and `:file` backends (SQL/ActiveRecord and vector search are roadmap items); retrieval there is keyword-based.
+
+### Working memory (structured, persists across LLM calls)
+
+A symbolic scratch space for the current session, distinct from the raw message buffer. Backed by the same pluggable short-term stores, under a namespaced session key so it never collides with messages.
+
+```ruby
+wm = Llmemory::WorkingMemory.new(user_id: "u1", session_id: "s1")
+# or, from the unified API: memory.working_memory
+
+wm.goals = ["plan a trip to Lisbon"]
+wm.current_task = "find flights"
+wm.set(:budget, 1000)           # arbitrary custom slot
+
+wm.goals                        # => ["plan a trip to Lisbon"]
+wm.custom_slots                 # => { budget: 1000 }
+wm.update(last_observation: "no direct flights", scratchpad: "try connections")
+wm.to_h                         # full state; wm.clear! to reset
+```
+
+Predefined slots: `goals`, `current_task`, `retrieved_context`, `scratchpad`, `last_observation`, `intermediate_reasoning`.
+
+### Reasoning action
+
+Read working memory, call the LLM, write the result back — CoALA's reasoning action. Composable (reason → retrieve → reason); it does not touch long-term memory.
+
+```ruby
+Llmemory::Actions::Reason.call(
+  working_memory: wm,
+  template: "Goal: {{goals}}. Observation: {{last_observation}}. What is the next step?",
+  into: :intermediate_reasoning           # slot to write to (nil to not write)
+)
+wm.intermediate_reasoning                 # => the LLM's answer
+
+# A callable template gets the working memory; `parse` transforms the output before storing:
+Llmemory::Actions::Reason.call(
+  working_memory: wm,
+  template: ->(w) { "List 3 options for #{w.current_task}" },
+  parse: ->(out) { out.split("\n") },
+  into: :scratchpad
+)
+```
+
+### Episodic memory (trajectories of experience)
+
+Records what happened — ordered steps `(observation → action → result)` plus a summary, outcome and importance — so experiences can be retrieved as examples or distilled into knowledge by reflection.
+
+```ruby
+episodic = Llmemory::LongTerm::Episodic::Memory.new(user_id: "u1")
+
+id = episodic.record_episode(
+  steps: [{ observation: "deploy failed", action: "rolled back", result: "service restored" }],
+  outcome: "recovered",
+  importance: 0.8
+)
+
+episodic.recent_episodes(limit: 5)        # newest first
+episodic.search_candidates("rolled back") # retrieval-compatible candidates
+```
+
+### Reflection (episodic → semantic)
+
+Distills durable, higher-order insights from recent episodes and writes them to semantic memory with provenance back to the source episodes (the Reflexion / Generative Agents pattern).
+
+```ruby
+semantic = Llmemory::LongTerm::FileBased::Memory.new(user_id: "u1")
+reflector = Llmemory::Reflection::Reflector.new(episodic: episodic, semantic: semantic)
+
+reflector.reflect(window: 10)             # reads recent episodes -> LLM -> writes insights
+# Each insight is stored with provenance { method: "reflection", sources: [{ type: "episode", id: ... }] }
+```
+
+`semantic` must respond to `remember_fact(content:, category:, importance:, provenance:)` (file-based does; graph-based is a roadmap target).
+
+### Procedural memory (skill library)
+
+A Voyager-style library of reusable skills (prompts, templates, code). Skills track success/failure, and their success rate is surfaced as `importance` so proven skills rank higher in retrieval.
+
+```ruby
+skills = Llmemory::LongTerm::Procedural::Memory.new(user_id: "u1")
+
+id = skills.register_skill(
+  name: "rollback", description: "revert a bad deploy",
+  body: "kubectl rollout undo deployment/$1", kind: "code"   # kind: prompt | template | code
+)
+skills.register_skill(name: "rollback", body: "...newer...") # same name -> version auto-increments
+
+skills.find_skill("revert deploy")        # best match (a Skill)
+skills.report_outcome(id, success: true)  # feeds ranking + adaptive retrieval
+```
+
+### Uniform interface (MemoryModule)
+
+The queryable long-term memories (file, graph, episodic, procedural) share one agent-facing contract, so a framework can treat them polymorphically:
+
+```ruby
+memory.read(query, limit: 10)   # retrieve relevant entries (delegates to search_candidates)
+memory.write(...)               # ingest (memorize / record_episode / register_skill)
+memory.list(limit: 50)          # enumerate stored entries
+memory.stats                    # counts, e.g. { items: 12 } / { episodes: 4 } / { skills: 7 }
+memory.forget(ids:, reason:)    # see "Forgetting" below
+```
+
+### Provenance (lineage of every semantic datum)
+
+Facts (items), graph nodes/edges and reflection insights carry provenance — where they came from, how they were produced, with what confidence — so a conclusion can be traced back to its source.
+
+```ruby
+item = storage.get_all_items("u1").first
+item[:provenance]
+# => { sources: [{ type: "resource", id: "res_3" }], method: "fact_extraction", confidence: 0.9, created_at: "..." }
+```
+
+Graph nodes/edges record a SHA-256 fingerprint of the ingested text (lineage without persisting the raw document). Build provenance directly with `Llmemory::Provenance.build(method:, sources:, confidence:)`.
+
+### Adaptive retrieval (feedback loop)
+
+Tell the retrieval engine which retrieved items were useful or noisy; repeatedly-useful items rank higher in future retrievals, noise is dampened. Item ids come from the candidates returned by `read` / `search_candidates`.
+
+```ruby
+engine = Retrieval::Engine.new(memory)
+results = memory.read("deployment incidents")        # candidates carry :id
+
+engine.report_feedback(useful_ids: [results.first[:id]], harmful_ids: [])
+# Next retrievals reweight accordingly. Set config.retrieval_feedback_weight = 0 to disable.
+```
+
+### Iterative retrieval (multi-hop)
+
+Retrieve, reason about what is still missing, then retrieve again — for multi-hop questions a single pass would miss.
+
+```ruby
+engine.iterative_retrieve(
+  "What is the capital of France and its population?",
+  max_hops: 3
+)
+# After each hop an LLM proposes a follow-up query (or "DONE"). Pass a custom
+# `reasoner: ->(question, accumulated, hop) { ... }` to drive the loop yourself.
+```
+
+### Forgetting (unlearning with audit)
+
+Remove entries by id, with an audit trail of what was forgotten, when and why.
+
+```ruby
+removed = memory.forget(ids: [item_id], reason: "user requested deletion")  # => count removed
+
+Llmemory::ForgetLog.new.entries("u1")
+# => [{ memory_type: "file_based", ids: ["item_7"], count: 1, reason: "user requested deletion", at: "..." }]
+```
+
+Supported for file-based, episodic and procedural memory (hard delete by id). Graph forgetting (edge/node lifecycle with orphan handling) is a roadmap item.
+
 ## Advanced Memory Management
 
 These features improve robustness and efficiency, inspired by OpenClaw's memory system.

data/lib/llmemory/actions/reason.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Actions
+    # CoALA's "reasoning" action: read working memory, call the LLM, write the
+    # result back to working memory. Unlike retrieval (long-term -> working) or
+    # learning (working -> long-term), reasoning reads from and writes to working
+    # memory, producing new information for the current decision.
+    #
+    # It is a small, composable primitive — agents can chain reason -> retrieve
+    # -> reason — and deliberately does NOT touch long-term memory.
+    #
+    #   Llmemory::Actions::Reason.call(
+    #     working_memory: wm,
+    #     template: "Given goals {{goals}}, what is the next step?",
+    #     into: :intermediate_reasoning
+    #   )
+    #
+    # `template` is either a String (with {{slot}} placeholders filled from
+    # working memory) or a callable that receives the WorkingMemory and returns
+    # the prompt. `parse` optionally transforms the raw LLM output before it is
+    # stored. `into` is the slot to write to (nil to reason without writing).
+    # Returns the parsed result.
+    class Reason
+      DEFAULT_SLOT = :intermediate_reasoning
+
+      def self.call(working_memory:, template:, into: DEFAULT_SLOT, parse: nil, llm: nil)
+        client = llm || Llmemory::LLM.client
+        prompt = render(template, working_memory)
+        output = client.invoke(prompt).to_s
+        result = parse ? parse.call(output) : output
+        working_memory.set(into, result) unless into.nil?
+        result
+      end
+
+      def self.render(template, working_memory)
+        return template.call(working_memory).to_s if template.respond_to?(:call)
+        interpolate(template.to_s, working_memory.to_h)
+      end
+
+      def self.interpolate(text, slots)
+        text.gsub(/\{\{(\w+)\}\}/) do
+          key = Regexp.last_match(1).to_sym
+          slots.key?(key) ? slots[key].to_s : ""
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/actions.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "actions/reason"
+
+module Llmemory
+  module Actions
+  end
+end

data/lib/llmemory/configuration.rb

@@ -15,6 +15,7 @@ module Llmemory
                   :vector_store,
                   :time_decay_half_life_days,
                   :importance_weight,
+                  :retrieval_feedback_weight,
                   :max_retrieval_tokens,
                   :prune_after_days,
                   :compact_max_bytes,
@@ -58,6 +59,7 @@ module Llmemory
       @vector_store = nil
       @time_decay_half_life_days = 30
       @importance_weight = 1.0
+      @retrieval_feedback_weight = 0.5
       @max_retrieval_tokens = 2000
       @prune_after_days = 90
       @compact_max_bytes = 8192

data/lib/llmemory/forget_log.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "short_term/stores"
+
+module Llmemory
+  # Append-only audit trail of forgotten memory entries. CoALA notes that
+  # modifying and deleting memory ("unlearning") are understudied; when an agent
+  # removes knowledge it should remain accountable for what was removed, when and
+  # why. ForgetLog records that trail, unified per user across memory types.
+  #
+  # Backed by the same pluggable short-term stores as the rest of the session
+  # layer, under a per-user pseudo-session key.
+  class ForgetLog
+    SESSION_KEY = "__forget_log__"
+
+    def initialize(store: nil)
+      @store = store || ShortTerm::Stores.build
+    end
+
+    def record(user_id, memory_type:, ids:, reason: nil)
+      ids = Array(ids).map(&:to_s)
+      entry = {
+        memory_type: memory_type.to_s,
+        ids: ids,
+        count: ids.size,
+        reason: reason,
+        at: Time.now.iso8601
+      }
+      log = entries(user_id)
+      log << entry
+      @store.save(user_id, SESSION_KEY, { "entries" => log })
+      entry
+    end
+
+    def entries(user_id)
+      state = @store.load(user_id, SESSION_KEY)
+      return [] unless state.is_a?(Hash)
+      list = state[:entries] || state["entries"]
+      list.is_a?(Array) ? list.map { |e| symbolize(e) } : []
+    end
+
+    private
+
+    def symbolize(entry)
+      return entry unless entry.is_a?(Hash)
+      entry.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+    end
+  end
+end

data/lib/llmemory/long_term/episodic/episode.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Llmemory
+  module LongTerm
+    module Episodic
+      # An Episode is a trajectory of an agent's experience: an ordered list of
+      # steps (observation -> action -> result) plus a summary, an outcome label
+      # and an importance score. This is CoALA's "episodic memory" — distinct
+      # from semantic memory (facts), it stores what happened so it can later be
+      # retrieved as examples or distilled into semantic knowledge (see P2,
+      # reflection).
+      class Episode
+        attr_reader :id, :user_id, :steps, :summary, :outcome, :importance, :provenance, :created_at
+
+        STEP_KEYS = %i[observation action result timestamp].freeze
+
+        def initialize(id:, user_id:, steps: [], summary: nil, outcome: nil, importance: 0.5, provenance: nil, created_at: nil)
+          @id = id
+          @user_id = user_id
+          @steps = self.class.normalize_steps(steps)
+          @summary = summary
+          @outcome = outcome
+          @importance = importance.nil? ? 0.5 : importance.to_f
+          @provenance = provenance
+          @created_at = created_at || Time.now
+        end
+
+        # Flat, searchable representation used for keyword retrieval and, in the
+        # future, embedding. Combines summary, outcome and every step field.
+        def searchable_text
+          parts = [summary, outcome]
+          steps.each do |s|
+            parts << s[:observation]
+            parts << s[:action]
+            parts << s[:result]
+          end
+          parts.compact.map(&:to_s).reject(&:empty?).join("\n")
+        end
+
+        def self.normalize_steps(steps)
+          Array(steps).filter_map do |step|
+            next nil unless step.is_a?(Hash)
+            {
+              observation: step[:observation] || step["observation"],
+              action: step[:action] || step["action"],
+              result: step[:result] || step["result"],
+              timestamp: normalize_time(step[:timestamp] || step["timestamp"])
+            }
+          end
+        end
+
+        def self.normalize_time(value)
+          return nil if value.nil?
+          value.respond_to?(:iso8601) ? value.iso8601 : value.to_s
+        end
+
+        def self.from_h(hash)
+          new(
+            id: hash[:id] || hash["id"],
+            user_id: hash[:user_id] || hash["user_id"],
+            steps: hash[:steps] || hash["steps"] || [],
+            summary: hash[:summary] || hash["summary"],
+            outcome: hash[:outcome] || hash["outcome"],
+            importance: hash[:importance] || hash["importance"] || 0.5,
+            provenance: hash[:provenance] || hash["provenance"],
+            created_at: parse_created_at(hash[:created_at] || hash["created_at"])
+          )
+        end
+
+        def self.parse_created_at(value)
+          return value if value.nil? || value.is_a?(Time)
+          Time.parse(value.to_s)
+        rescue ArgumentError
+          nil
+        end
+
+        def to_h
+          {
+            id: id,
+            user_id: user_id,
+            steps: steps,
+            summary: summary,
+            outcome: outcome,
+            importance: importance,
+            provenance: provenance,
+            created_at: created_at.respond_to?(:iso8601) ? created_at.iso8601(6) : created_at
+          }
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/long_term/episodic/memory.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "episode"
+require_relative "storage"
+require_relative "../../memory_module"
+
+module Llmemory
+  module LongTerm
+    module Episodic
+      # Episodic long-term memory: records agent trajectories and retrieves them
+      # by recency, importance and relevance. Designed to coexist with semantic
+      # memory (file/graph), not replace it, and to feed reflection (P2), which
+      # distills episodes into semantic knowledge.
+      #
+      # Deliberately LLM-free: recording and retrieval are deterministic. Higher
+      # order summarization belongs to reflection.
+      class Memory
+        include Llmemory::MemoryModule
+
+        attr_reader :user_id, :storage
+
+        def initialize(user_id:, storage: nil)
+          @user_id = user_id
+          @storage = storage || Storages.build
+        end
+
+        # Records a trajectory. `steps` is an array of hashes with any of
+        # :observation, :action, :result, :timestamp. Returns the episode id.
+        def record_episode(steps:, summary: nil, outcome: nil, importance: 0.5)
+          episode = Episode.new(
+            id: nil,
+            user_id: @user_id,
+            steps: steps,
+            summary: summary || derive_summary(steps),
+            outcome: outcome,
+            importance: importance
+          )
+          provenance = Llmemory::Provenance.from_text_fingerprint(
+            episode.searchable_text, method: "episode_recording", confidence: episode.importance
+          )
+          record = episode.to_h.merge(provenance: provenance)
+          @storage.save_episode(@user_id, record)
+        end
+
+        def recent_episodes(limit: 10)
+          @storage.list_episodes(@user_id, limit: limit).map { |e| Episode.from_h(e) }
+        end
+
+        def episodes(limit: nil)
+          @storage.list_episodes(@user_id, limit: limit).map { |e| Episode.from_h(e) }
+        end
+
+        def find_episode(id)
+          raw = @storage.get_episode(@user_id, id)
+          raw && Episode.from_h(raw)
+        end
+
+        def count
+          @storage.count_episodes(@user_id)
+        end
+
+        # Retrieval Engine integration. Returns candidates shaped like the other
+        # long-term memories so the Engine can rank episodes by relevance,
+        # recency (temporal decay) and importance (P3), with provenance (P10).
+        def search_candidates(query, user_id: nil, top_k: 20)
+          uid = user_id || @user_id
+          return [] unless uid == @user_id
+
+          @storage.search_episodes(uid, query).first(top_k).map do |e|
+            episode = Episode.from_h(e)
+            {
+              id: episode.id,
+              text: episode.summary.to_s.empty? ? episode.searchable_text : episode.summary,
+              timestamp: episode.created_at,
+              score: 1.0,
+              importance: episode.importance,
+              evergreen: false,
+              provenance: e[:provenance] || e["provenance"]
+            }
+          end
+        end
+
+        # --- MemoryModule uniform interface ---
+
+        def write(steps:, summary: nil, outcome: nil, importance: 0.5, **_meta)
+          record_episode(steps: steps, summary: summary, outcome: outcome, importance: importance)
+        end
+
+        def list(user_id: nil, limit: nil)
+          episodes(limit: limit)
+        end
+
+        def stats(user_id: nil)
+          { episodes: count }
+        end
+
+        def forget(ids:, reason: nil)
+          requested = Array(ids).map(&:to_s)
+          existing = @storage.list_episodes(@user_id).map { |e| (e[:id] || e["id"]).to_s }
+          removed = requested & existing
+          @storage.delete_episodes(@user_id, removed)
+          forget_log.record(@user_id, memory_type: "episodic", ids: removed, reason: reason)
+          removed.size
+        end
+
+        private
+
+        # Cheap, deterministic summary when the caller does not provide one.
+        # LLM-based summarization is reflection's job (P2).
+        def derive_summary(steps)
+          normalized = Episode.normalize_steps(steps)
+          return nil if normalized.empty?
+          actions = normalized.filter_map { |s| s[:action] }.reject { |a| a.to_s.strip.empty? }
+          return nil if actions.empty?
+          "Episode with #{normalized.size} step(s): #{actions.join(' -> ')}"
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/long_term/episodic/storage.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "storages/base"
+require_relative "storages/memory_storage"
+require_relative "storages/file_storage"
+
+module Llmemory
+  module LongTerm
+    module Episodic
+      # Backward compatibility: Storage points to the in-memory backend.
+      Storage = Storages::MemoryStorage
+
+      module Storages
+        def self.build(store: nil, base_path: nil)
+          case (store || Llmemory.configuration.long_term_store).to_s.to_sym
+          when :memory
+            MemoryStorage.new
+          when :file
+            FileStorage.new(base_path: base_path || Llmemory.configuration.long_term_storage_path)
+          when :postgres, :database, :active_record, :activerecord
+            raise NotImplementedError,
+              "Episodic SQL/ActiveRecord storage is not implemented yet; use :memory or :file " \
+              "(or pass an explicit storage instance)."
+          else
+            MemoryStorage.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/long_term/episodic/storages/base.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module LongTerm
+    module Episodic
+      module Storages
+        # Storage contract for episodic memory. Implementations persist Episode
+        # hashes and expose recency-ordered listing plus keyword search so the
+        # retrieval Engine can rank episodes alongside other memory types.
+        class Base
+          def save_episode(user_id, episode)
+            raise NotImplementedError, "#{self.class}#save_episode must be implemented"
+          end
+
+          def get_episode(user_id, id)
+            raise NotImplementedError, "#{self.class}#get_episode must be implemented"
+          end
+
+          # Newest first. Optionally capped by limit.
+          def list_episodes(user_id, limit: nil)
+            raise NotImplementedError, "#{self.class}#list_episodes must be implemented"
+          end
+
+          def search_episodes(user_id, query)
+            raise NotImplementedError, "#{self.class}#search_episodes must be implemented"
+          end
+
+          def count_episodes(user_id)
+            raise NotImplementedError, "#{self.class}#count_episodes must be implemented"
+          end
+
+          # Deletes episodes by id. Returns the number actually removed.
+          def delete_episodes(user_id, ids)
+            raise NotImplementedError, "#{self.class}#delete_episodes must be implemented"
+          end
+
+          def list_users
+            raise NotImplementedError, "#{self.class}#list_users must be implemented"
+          end
+        end
+      end
+    end
+  end
+end