llmemory 0.1.17 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b86647810e47140fff5732a066da4a16188704249d09db14720d8c565b6eaf0e
-  data.tar.gz: 7c52c551746d22c29e41015098a68e166788bb614b0e0c2b064fa5fc0824989f
+  metadata.gz: c302656888e6373faedb5732525f76d118fd98fb67ece22278d886faec5ba3cd
+  data.tar.gz: ec0897226ec378e51e86e01cb66e938fbeea3db7e4c49911d7e3d08a08959d07
 SHA512:
-  metadata.gz: f584d487eca13280b13f7a3e9f4b8eda60ed10ec8dbb45ff72483acbc76b7feb7f79fb5ae572640a31e87ade05b0762f07cacbecb778dffa6d62a7096231fb12
-  data.tar.gz: c68e284c21fc22ccdf20160d9082575a47482b03c5a91fb3b52ec5a6c51b7f5cf13a8915bfd3fe2f5933aa6a52fe8c382e2373393b27d68d8ed1c7ac83766e49
+  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/memory.rb

@@ -2,6 +2,7 @@
 
 require_relative "episode"
 require_relative "storage"
+require_relative "../../memory_module"
 
 module Llmemory
   module LongTerm
@@ -14,6 +15,8 @@ module Llmemory
       # 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)
@@ -66,6 +69,7 @@ module Llmemory
           @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,
@@ -76,6 +80,29 @@ module Llmemory
           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.

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

@@ -29,6 +29,11 @@ module Llmemory
             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

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

@@ -46,6 +46,15 @@ module Llmemory
             Dir.children(dir).count { |f| f.end_with?(".json") }
           end
 
+          def delete_episodes(user_id, ids)
+            Array(ids).map(&:to_s).count do |id|
+              path = episode_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, "episodes")) }

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

@@ -40,6 +40,13 @@ module Llmemory
             @episodes[user_id].size
           end
 
+          def delete_episodes(user_id, ids)
+            ids = Array(ids).map(&:to_s)
+            before = @episodes[user_id].size
+            @episodes[user_id].reject! { |e| ids.include?(e[:id].to_s) }
+            before - @episodes[user_id].size
+          end
+
           def list_users
             @episodes.keys
           end

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

@@ -5,11 +5,14 @@ require_relative "item"
 require_relative "category"
 require_relative "storage"
 require_relative "../../noise_filter"
+require_relative "../../memory_module"
 
 module Llmemory
   module LongTerm
     module FileBased
       class Memory
+        include Llmemory::MemoryModule
+
         def initialize(user_id:, storage: nil, llm: nil, extractor: nil)
           @user_id = user_id
           @storage = storage || Storages.build
@@ -63,6 +66,7 @@ module Llmemory
 
           items.first(top_k).each do |i|
             out << {
+              id: i[:id] || i["id"],
               text: i[:content] || i["content"],
               timestamp: i[:created_at] || i["created_at"],
               score: 1.0,
@@ -72,6 +76,7 @@ module Llmemory
           end
           resources.first([top_k - out.size, 0].max).each do |r|
             out << {
+              id: r[:id] || r["id"],
               text: r[:text] || r["text"],
               timestamp: r[:created_at] || r["created_at"],
               score: 0.9
@@ -100,6 +105,32 @@ module Llmemory
           )
         end
 
+        # --- MemoryModule uniform interface ---
+
+        def write(payload, **_meta)
+          memorize(payload)
+        end
+
+        def list(user_id: nil, limit: nil)
+          @storage.list_items(user_id: user_id || @user_id, limit: limit)
+        end
+
+        def stats(user_id: nil)
+          { items: @storage.count_items(user_id: user_id || @user_id) }
+        end
+
+        # Removes items/resources by id and records the removal in the audit log.
+        def forget(ids:, reason: nil)
+          requested = Array(ids).map(&:to_s)
+          existing = (@storage.get_all_items(@user_id) + @storage.get_all_resources(@user_id))
+            .map { |r| (r[:id] || r["id"]).to_s }
+          removed = requested & existing
+          @storage.archive_items(@user_id, removed)
+          @storage.archive_resources(@user_id, removed)
+          forget_log.record(@user_id, memory_type: "file_based", ids: removed, reason: reason)
+          removed.size
+        end
+
         attr_reader :storage, :user_id
 
         private

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

@@ -6,11 +6,14 @@ require_relative "knowledge_graph"
 require_relative "conflict_resolver"
 require_relative "storage"
 require_relative "../../noise_filter"
+require_relative "../../memory_module"
 
 module Llmemory
   module LongTerm
     module GraphBased
       class Memory
+        include Llmemory::MemoryModule
+
         def initialize(user_id:, storage: nil, vector_store: nil, llm: nil, extractor: nil)
           @user_id = user_id
           @graph_storage = storage || Storages.build
@@ -88,6 +91,7 @@ module Llmemory
           results = hybrid_search(query, top_k: top_k)
           results.map do |r|
             {
+              id: r[:id],
               text: r[:text],
               timestamp: r[:created_at] || r[:timestamp],
               score: r[:score] || 1.0,
@@ -102,6 +106,29 @@ module Llmemory
           @graph_storage
         end
 
+        # --- MemoryModule uniform interface ---
+
+        def write(payload, **_meta)
+          memorize(payload)
+        end
+
+        def list(user_id: nil, limit: nil)
+          @graph_storage.list_nodes(user_id || @user_id, limit: limit)
+        end
+
+        def stats(user_id: nil)
+          uid = user_id || @user_id
+          { nodes: @graph_storage.count_nodes(uid), edges: @graph_storage.count_edges(uid) }
+        end
+
+        # Forgetting a knowledge graph is not a simple delete-by-id: edges are
+        # soft-archived and nodes can be left orphaned. A dedicated graph
+        # edge/node lifecycle (with orphan handling) is a deliberate follow-up.
+        def forget(ids:, reason: nil)
+          raise NotImplementedError,
+            "Graph forget is not implemented yet; edge/node lifecycle (archival + orphan handling) is a follow-up."
+        end
+
         private
 
         def build_vector_store
@@ -127,7 +154,7 @@ module Llmemory
           out = vector_results.map do |v|
             id = v[:id] || v["id"]
             meta = v[:metadata] || v["metadata"] || {}
-            { text: meta["text"] || meta[:text] || id.to_s, score: v[:score] || v["score"] || 1.0, created_at: meta["created_at"] || meta[:created_at] }
+            { id: id, text: meta["text"] || meta[:text] || id.to_s, score: v[:score] || v["score"] || 1.0, created_at: meta["created_at"] || meta[:created_at] }
           end
 
           node_ids = out.flat_map { |r| extract_node_ids_from_text(r[:text]) }.compact.uniq
@@ -139,7 +166,7 @@ module Llmemory
               subj = @kg.find_node_by_id(e.subject_id)
               obj = @kg.find_node_by_id(e.target_id)
               edge_text = "#{subj&.name} #{e.predicate} #{obj&.name}"
-              out << { text: edge_text, score: 0.85, created_at: e.created_at } unless out.any? { |o| o[:text] == edge_text }
+              out << { id: (e.id ? "edge_#{e.id}" : nil), text: edge_text, score: 0.85, created_at: e.created_at } unless out.any? { |o| o[:text] == edge_text }
             end
           end
 
@@ -152,7 +179,7 @@ module Llmemory
               obj = @kg.find_node_by_id(e.target_id)
               next unless subj && obj
               edge_text = "#{subj.name} #{e.predicate} #{obj.name}"
-              out << { text: edge_text, score: 0.7, created_at: e.created_at }
+              out << { id: (e.id ? "edge_#{e.id}" : nil), text: edge_text, score: 0.7, created_at: e.created_at }
             end
           end
 

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "skill"
+require_relative "storage"
+require_relative "../../memory_module"
+
+module Llmemory
+  module LongTerm
+    module Procedural
+      # Procedural long-term memory: a Voyager-style skill library. Agents
+      # register reusable skills (prompts, templates, code), retrieve them by
+      # relevance to the current task, and report outcomes so proven skills are
+      # preferred over unproven ones.
+      #
+      # Retrieval is keyword-based for now (vector search is a follow-up). The
+      # success rate of each skill is surfaced as `importance`, so the retrieval
+      # Engine ranks battle-tested skills higher (P3 importance weighting).
+      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
+
+        # Registers a skill. If `version` is omitted and a skill with the same
+        # name exists, the version auto-increments (skill evolution).
+        def register_skill(name:, body:, description: nil, kind: Skill::DEFAULT_KIND, version: nil)
+          version ||= next_version_for(name)
+          skill = Skill.new(
+            id: nil, user_id: @user_id, name: name, body: body,
+            description: description, kind: kind, version: version
+          )
+          @storage.save_skill(@user_id, skill.to_h)
+        end
+
+        def find_skill(query)
+          raw = @storage.search_skills(@user_id, query).first
+          raw && Skill.from_h(raw)
+        end
+
+        def get_skill(id)
+          raw = @storage.get_skill(@user_id, id)
+          raw && Skill.from_h(raw)
+        end
+
+        def skills(limit: nil)
+          @storage.list_skills(@user_id, limit: limit).map { |s| Skill.from_h(s) }
+        end
+
+        def count
+          @storage.count_skills(@user_id)
+        end
+
+        # Records that applying a skill succeeded or failed. Feeds retrieval
+        # ranking and adaptive retrieval (P8). Returns the updated Skill.
+        def report_outcome(skill_id, success:)
+          raw = @storage.record_outcome(@user_id, skill_id, success: success)
+          raw && Skill.from_h(raw)
+        end
+
+        # Retrieval Engine integration: skills ranked by relevance, recency and
+        # proven utility (success rate exposed as importance).
+        def search_candidates(query, user_id: nil, top_k: 20)
+          uid = user_id || @user_id
+          return [] unless uid == @user_id
+
+          @storage.search_skills(uid, query).first(top_k).map do |raw|
+            skill = Skill.from_h(raw)
+            {
+              id: skill.id,
+              text: skill.searchable_text,
+              timestamp: skill.created_at,
+              score: 1.0,
+              importance: skill.success_rate,
+              evergreen: false
+            }
+          end
+        end
+
+        # --- MemoryModule uniform interface ---
+
+        def write(name:, body:, description: nil, kind: Skill::DEFAULT_KIND, version: nil, **_meta)
+          register_skill(name: name, body: body, description: description, kind: kind, version: version)
+        end
+
+        def list(user_id: nil, limit: nil)
+          skills(limit: limit)
+        end
+
+        def stats(user_id: nil)
+          { skills: count }
+        end
+
+        def forget(ids:, reason: nil)
+          requested = Array(ids).map(&:to_s)
+          existing = @storage.list_skills(@user_id).map { |s| (s[:id] || s["id"]).to_s }
+          removed = requested & existing
+          @storage.delete_skills(@user_id, removed)
+          forget_log.record(@user_id, memory_type: "procedural", ids: removed, reason: reason)
+          removed.size
+        end
+
+        private
+
+        def next_version_for(name)
+          existing = @storage.find_skills_by_name(@user_id, name)
+          return 1 if existing.empty?
+          existing.map { |s| (s[:version] || s["version"] || 1).to_i }.max + 1
+        end
+      end
+    end
+  end
+end