llmemory 0.1.17 → 0.2.1

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

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "time"
+require_relative "base"
+
+module Llmemory
+  module LongTerm
+    module Procedural
+      module Storages
+        # PostgreSQL backend. Each skill is stored as a JSONB `data` document
+        # (plus id/user_id/created_at and a denormalized search_text), mirroring
+        # the file-based DatabaseStorage pattern.
+        class DatabaseStorage < Base
+          def initialize(database_url: nil)
+            @database_url = database_url || Llmemory.configuration.database_url
+            @connection = nil
+          end
+
+          def save_skill(user_id, skill)
+            ensure_tables!
+            id = skill[:id] || skill["id"] || "skill_#{SecureRandom.hex(8)}"
+            data = symbolize(skill).merge(id: id, user_id: user_id)
+            data[:created_at] ||= Time.now.utc.iso8601
+            conn.exec_params(
+              "INSERT INTO llmemory_skills (id, user_id, data, search_text, created_at) " \
+              "VALUES ($1, $2, $3::jsonb, $4, $5) " \
+              "ON CONFLICT (id) DO UPDATE SET data = $3::jsonb, search_text = $4",
+              [id, user_id, JSON.generate(data), searchable_text(data), created_at_value(data)]
+            )
+            id
+          end
+
+          def get_skill(user_id, id)
+            ensure_tables!
+            rows = conn.exec_params("SELECT data FROM llmemory_skills WHERE user_id = $1 AND id = $2", [user_id, id])
+            rows.any? ? parse_data(rows.first["data"]) : nil
+          end
+
+          def list_skills(user_id, limit: nil)
+            ensure_tables!
+            sql = "SELECT data FROM llmemory_skills WHERE user_id = $1 ORDER BY created_at DESC"
+            sql += " LIMIT #{limit.to_i}" if limit && limit.to_i.positive?
+            conn.exec_params(sql, [user_id]).map { |r| parse_data(r["data"]) }
+          end
+
+          def search_skills(user_id, query)
+            ensure_tables!
+            suffix, params = token_filter("search_text", query, 2)
+            conn.exec_params(
+              "SELECT data FROM llmemory_skills WHERE user_id = $1#{suffix} ORDER BY created_at DESC",
+              [user_id, *params]
+            ).map { |r| parse_data(r["data"]) }
+          end
+
+          def find_skills_by_name(user_id, name)
+            ensure_tables!
+            conn.exec_params(
+              "SELECT data FROM llmemory_skills WHERE user_id = $1 AND data->>'name' = $2",
+              [user_id, name.to_s]
+            ).map { |r| parse_data(r["data"]) }
+          end
+
+          def record_outcome(user_id, skill_id, success:)
+            ensure_tables!
+            data = get_skill(user_id, skill_id)
+            return nil unless data
+            key = success ? :success_count : :failure_count
+            data[key] = (data[key] || 0).to_i + 1
+            data[:updated_at] = Time.now.utc.iso8601
+            conn.exec_params(
+              "UPDATE llmemory_skills SET data = $3::jsonb, search_text = $4 WHERE user_id = $1 AND id = $2",
+              [user_id, skill_id, JSON.generate(data), searchable_text(data)]
+            )
+            data
+          end
+
+          def count_skills(user_id)
+            ensure_tables!
+            conn.exec_params("SELECT COUNT(*) AS c FROM llmemory_skills WHERE user_id = $1", [user_id]).first["c"].to_i
+          end
+
+          def delete_skills(user_id, ids)
+            ensure_tables!
+            Array(ids).sum do |id|
+              conn.exec_params("DELETE FROM llmemory_skills WHERE user_id = $1 AND id = $2", [user_id, id]).cmd_tuples
+            end
+          end
+
+          def list_users
+            ensure_tables!
+            conn.exec("SELECT DISTINCT user_id FROM llmemory_skills").map { |r| r["user_id"] }
+          end
+
+          private
+
+          def conn
+            @connection ||= begin
+              require "pg"
+              PG.connect(@database_url)
+            end
+          end
+
+          def ensure_tables!
+            conn.exec(<<~SQL)
+              CREATE TABLE IF NOT EXISTS llmemory_skills (
+                id TEXT NOT NULL PRIMARY KEY,
+                user_id TEXT NOT NULL,
+                data JSONB NOT NULL DEFAULT '{}'::jsonb,
+                search_text TEXT,
+                created_at TIMESTAMPTZ NOT NULL
+              );
+              CREATE INDEX IF NOT EXISTS idx_llmemory_skills_user_id ON llmemory_skills(user_id);
+            SQL
+          end
+
+          def token_filter(column, query, start_index)
+            tokens = Llmemory::Tokenizer.tokenize(query)
+            return ["", []] if tokens.empty?
+            likes = tokens.each_index.map { |i| "LOWER(#{column}) LIKE $#{start_index + i}" }
+            [" AND (#{likes.join(' OR ')})", tokens.map { |t| "%#{t}%" }]
+          end
+
+          def parse_data(value)
+            JSON.parse(value.to_s, symbolize_names: true)
+          rescue JSON::ParserError
+            {}
+          end
+
+          def symbolize(hash)
+            hash.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+          end
+
+          def searchable_text(data)
+            [data[:name], data[:description], data[:body]].compact.join("\n")
+          end
+
+          def created_at_value(data)
+            ca = data[:created_at]
+            return Time.now.utc.iso8601 if ca.nil?
+            ca.respond_to?(:iso8601) ? ca.iso8601 : ca.to_s
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,135 @@
+# 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)
+            return list_skills(user_id) if query.to_s.strip.empty?
+            all_skills(user_id).select { |s| Llmemory::Tokenizer.matches?(skill_text(s), query) }
+          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,79 @@
+# 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)
+            return list_skills(user_id) if query.to_s.strip.empty?
+            @skills[user_id].select { |s| Llmemory::Tokenizer.matches?(skill_text(s), query) }
+          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,8 +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/mcp/server.rb

@@ -11,6 +11,12 @@ require_relative "tools/memory_consolidate"
 require_relative "tools/memory_stats"
 require_relative "tools/memory_info"
 require_relative "tools/memory_timeline_context"
+require_relative "tools/memory_episode_record"
+require_relative "tools/memory_episodes"
+require_relative "tools/memory_skill_register"
+require_relative "tools/memory_skill_report"
+require_relative "tools/memory_skills"
+require_relative "tools/memory_forget"
 
 module Llmemory
   module MCP
@@ -157,7 +163,13 @@ module Llmemory
           Tools::MemoryAddMessage,
           Tools::MemoryConsolidate,
           Tools::MemoryStats,
-          Tools::MemoryInfo
+          Tools::MemoryInfo,
+          Tools::MemoryEpisodeRecord,
+          Tools::MemoryEpisodes,
+          Tools::MemorySkillRegister,
+          Tools::MemorySkillReport,
+          Tools::MemorySkills,
+          Tools::MemoryForget
         ]
       end
 

data/lib/llmemory/mcp/tools/memory_episode_record.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module MCP
+    module Tools
+      class MemoryEpisodeRecord < ::MCP::Tool
+        description "Record an experience (episodic memory): a trajectory of steps with an optional summary, outcome and importance. Use to remember what just happened so it can be retrieved or distilled into knowledge later."
+
+        input_schema(
+          properties: {
+            user_id: { type: "string", description: "User identifier" },
+            steps: {
+              type: "array",
+              description: "Ordered list of steps (objects with observation/action/result)",
+              items: {
+                type: "object",
+                properties: {
+                  observation: { type: "string" },
+                  action: { type: "string" },
+                  result: { type: "string" }
+                }
+              }
+            },
+            summary: { type: "string", description: "Optional summary (derived from steps if omitted)" },
+            outcome: { type: "string", description: "Outcome label, e.g. 'success', 'failure', 'recovered'" },
+            importance: { type: "number", description: "Importance 0-1 (default 0.5)" }
+          },
+          required: ["user_id", "steps"]
+        )
+
+        class << self
+          def call(user_id:, steps:, summary: nil, outcome: nil, importance: nil, server_context: nil)
+            memory = Llmemory::LongTerm::Episodic::Memory.new(user_id: user_id)
+            id = memory.record_episode(
+              steps: Array(steps),
+              summary: summary,
+              outcome: outcome,
+              importance: importance.nil? ? 0.5 : importance.to_f
+            )
+            ::MCP::Tool::Response.new([{ type: "text", text: "Episode recorded: #{id}" }])
+          rescue => e
+            ::MCP::Tool::Response.new([{ type: "text", text: "Error recording episode: #{e.message}" }], error: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/mcp/tools/memory_episodes.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module MCP
+    module Tools
+      class MemoryEpisodes < ::MCP::Tool
+        description "List recent episodes (episodic memory) for a user. Optionally filter by a keyword query."
+
+        input_schema(
+          properties: {
+            user_id: { type: "string", description: "User identifier" },
+            query: { type: "string", description: "Optional keyword filter" },
+            limit: { type: "integer", description: "Max episodes to return (default 10)" }
+          },
+          required: ["user_id"]
+        )
+
+        class << self
+          def call(user_id:, query: nil, limit: nil, server_context: nil)
+            memory = Llmemory::LongTerm::Episodic::Memory.new(user_id: user_id)
+            cap = (limit || 10).to_i
+            episodes = if query.to_s.strip.empty?
+              memory.recent_episodes(limit: cap)
+            else
+              memory.search_candidates(query, top_k: cap).filter_map { |c| memory.find_episode(c[:id]) }
+            end
+
+            if episodes.empty?
+              return ::MCP::Tool::Response.new([{ type: "text", text: "No episodes for user #{user_id}." }])
+            end
+
+            lines = episodes.map do |ep|
+              "[#{ep.id}] (importance: #{ep.importance}; outcome: #{ep.outcome || 'n/a'}) #{ep.summary || ep.searchable_text[0, 120]}"
+            end
+            ::MCP::Tool::Response.new([{ type: "text", text: lines.join("\n") }])
+          rescue => e
+            ::MCP::Tool::Response.new([{ type: "text", text: "Error listing episodes: #{e.message}" }], error: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/mcp/tools/memory_forget.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module MCP
+    module Tools
+      class MemoryForget < ::MCP::Tool
+        description "Remove entries from a memory by their ids (the ids returned by retrieval / listing tools), recording the removal in the audit log. memory_type: file_based | graph_based | episodic | procedural."
+
+        input_schema(
+          properties: {
+            user_id: { type: "string", description: "User identifier" },
+            memory_type: { type: "string", description: "file_based | graph_based | episodic | procedural" },
+            ids: { type: "array", items: { type: "string" }, description: "Entry ids to forget" },
+            reason: { type: "string", description: "Optional reason (recorded in audit)" }
+          },
+          required: ["user_id", "memory_type", "ids"]
+        )
+
+        class << self
+          def call(user_id:, memory_type:, ids:, reason: nil, server_context: nil)
+            memory = build_memory(user_id, memory_type)
+            removed = memory.forget(ids: Array(ids), reason: reason)
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: "Forgot #{removed} entries from #{memory_type} memory for user #{user_id}."
+            }])
+          rescue NotImplementedError => e
+            ::MCP::Tool::Response.new([{ type: "text", text: "Not supported: #{e.message}" }], error: true)
+          rescue => e
+            ::MCP::Tool::Response.new([{ type: "text", text: "Error forgetting: #{e.message}" }], error: true)
+          end
+
+          private
+
+          def build_memory(user_id, memory_type)
+            case memory_type.to_s
+            when "file_based"
+              Llmemory::LongTerm::FileBased::Memory.new(user_id: user_id)
+            when "graph_based"
+              Llmemory::LongTerm::GraphBased::Memory.new(user_id: user_id)
+            when "episodic"
+              Llmemory::LongTerm::Episodic::Memory.new(user_id: user_id)
+            when "procedural"
+              Llmemory::LongTerm::Procedural::Memory.new(user_id: user_id)
+            else
+              raise ArgumentError, "Unknown memory_type: #{memory_type} (expected file_based|graph_based|episodic|procedural)"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/mcp/tools/memory_retrieve.rb

@@ -59,8 +59,10 @@ module Llmemory
             items = storage.search_items(user_id, query)
             return "" if items.empty?
 
-            # Get timeline context around the first match
-            top_item = items.first
+            # Anchor on the most precise match: keyword search is recall-oriented
+            # (tokenized OR), so prefer the item whose content contains the full
+            # query verbatim, falling back to the first match.
+            top_item = best_match(items, query)
             item_id = top_item[:id] || top_item["id"]
             return "" unless item_id
 
@@ -70,6 +72,12 @@ module Llmemory
             ""
           end
 
+          def best_match(items, query)
+            q = query.to_s.downcase.strip
+            return items.first if q.empty?
+            items.find { |i| (i[:content] || i["content"]).to_s.downcase.include?(q) } || items.first
+          end
+
           def build_storage
             if Llmemory.configuration.long_term_type.to_s == "graph_based"
               LongTerm::GraphBased::Storages.build

data/lib/llmemory/mcp/tools/memory_skill_register.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module MCP
+    module Tools
+      class MemorySkillRegister < ::MCP::Tool
+        description "Register a reusable skill (procedural memory): a prompt, template or code snippet the agent can retrieve later. Re-registering the same name auto-increments the version."
+
+        input_schema(
+          properties: {
+            user_id: { type: "string", description: "User identifier" },
+            name: { type: "string", description: "Short identifier (skills with the same name get auto-versioned)" },
+            body: { type: "string", description: "The skill content (prompt / template / code)" },
+            description: { type: "string", description: "Optional human-readable description" },
+            kind: { type: "string", description: "prompt | template | code (default: prompt)" }
+          },
+          required: ["user_id", "name", "body"]
+        )
+
+        class << self
+          def call(user_id:, name:, body:, description: nil, kind: nil, server_context: nil)
+            memory = Llmemory::LongTerm::Procedural::Memory.new(user_id: user_id)
+            id = memory.register_skill(
+              name: name, body: body, description: description,
+              kind: kind || Llmemory::LongTerm::Procedural::Skill::DEFAULT_KIND
+            )
+            ::MCP::Tool::Response.new([{ type: "text", text: "Skill registered: #{id} (#{name})" }])
+          rescue => e
+            ::MCP::Tool::Response.new([{ type: "text", text: "Error registering skill: #{e.message}" }], error: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/mcp/tools/memory_skill_report.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module MCP
+    module Tools
+      class MemorySkillReport < ::MCP::Tool
+        description "Report the outcome of applying a skill (success or failure). Feeds retrieval ranking: proven skills surface higher next time."
+
+        input_schema(
+          properties: {
+            user_id: { type: "string", description: "User identifier" },
+            skill_id: { type: "string", description: "Skill id (from MemorySkillRegister / MemorySkills)" },
+            success: { type: "boolean", description: "True if the skill worked; false otherwise" }
+          },
+          required: ["user_id", "skill_id", "success"]
+        )
+
+        class << self
+          def call(user_id:, skill_id:, success:, server_context: nil)
+            memory = Llmemory::LongTerm::Procedural::Memory.new(user_id: user_id)
+            skill = memory.report_outcome(skill_id, success: success == true)
+            if skill.nil?
+              return ::MCP::Tool::Response.new([{ type: "text", text: "Skill not found: #{skill_id}" }], error: true)
+            end
+
+            text = "Outcome recorded for #{skill.name} (#{skill_id}): success #{skill.success_count} / failure #{skill.failure_count} (rate #{format('%.2f', skill.success_rate)})"
+            ::MCP::Tool::Response.new([{ type: "text", text: text }])
+          rescue => e
+            ::MCP::Tool::Response.new([{ type: "text", text: "Error reporting outcome: #{e.message}" }], error: true)
+          end
+        end
+      end
+    end
+  end
+end