llmemory 0.1.1

data/lib/llmemory/short_term/stores/postgres_store.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module ShortTerm
+    module Stores
+      class PostgresStore < Base
+        def initialize(database_url: nil)
+          @database_url = database_url || Llmemory.configuration.database_url
+          @connection = nil
+        end
+
+        def save(user_id, session_id, state)
+          ensure_table!
+          conn.exec_params(
+            <<~SQL,
+              INSERT INTO llmemory_checkpoints (user_id, session_id, state, updated_at)
+              VALUES ($1, $2, $3, $4)
+              ON CONFLICT (user_id, session_id)
+              DO UPDATE SET state = $3, updated_at = $4
+            SQL
+            [user_id, session_id, serialize(state), Time.now.utc.iso8601]
+          )
+          true
+        end
+
+        def load(user_id, session_id)
+          ensure_table!
+          result = conn.exec_params(
+            "SELECT state FROM llmemory_checkpoints WHERE user_id = $1 AND session_id = $2",
+            [user_id, session_id]
+          )
+          row = result.first
+          row ? deserialize(row["state"]) : nil
+        end
+
+        def delete(user_id, session_id)
+          ensure_table!
+          conn.exec_params(
+            "DELETE FROM llmemory_checkpoints WHERE user_id = $1 AND session_id = $2",
+            [user_id, session_id]
+          )
+          true
+        end
+
+        private
+
+        def conn
+          @connection ||= begin
+            require "pg"
+            PG.connect(@database_url)
+          end
+        end
+
+        def ensure_table!
+          conn.exec(<<~SQL)
+            CREATE TABLE IF NOT EXISTS llmemory_checkpoints (
+              user_id TEXT NOT NULL,
+              session_id TEXT NOT NULL,
+              state JSONB NOT NULL,
+              updated_at TIMESTAMPTZ NOT NULL,
+              PRIMARY KEY (user_id, session_id)
+            )
+          SQL
+        end
+
+        def serialize(state)
+          require "json"
+          JSON.generate(state)
+        end
+
+        def deserialize(data)
+          require "json"
+          JSON.parse(data, symbolize_names: true)
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/short_term/stores/redis_store.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module ShortTerm
+    module Stores
+      class RedisStore < Base
+        def initialize(redis_url: nil)
+          @redis_url = redis_url || Llmemory.configuration.redis_url
+          @redis = nil
+        end
+
+        def save(user_id, session_id, state)
+          redis.set(key_for(user_id, session_id), serialize(state), ex: 86400 * 7) # 7 days TTL
+          true
+        end
+
+        def load(user_id, session_id)
+          data = redis.get(key_for(user_id, session_id))
+          data ? deserialize(data) : nil
+        end
+
+        def delete(user_id, session_id)
+          redis.del(key_for(user_id, session_id))
+          true
+        end
+
+        private
+
+        def redis
+          @redis ||= begin
+            require "redis"
+            Redis.new(url: @redis_url)
+          end
+        end
+
+        def key_for(user_id, session_id)
+          "llmemory:checkpoint:#{user_id}:#{session_id}"
+        end
+
+        def serialize(state)
+          require "json"
+          JSON.generate(state)
+        end
+
+        def deserialize(data)
+          require "json"
+          JSON.parse(data, symbolize_names: true)
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/short_term.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "short_term/checkpoint"
+
+module Llmemory
+  module ShortTerm
+  end
+end

data/lib/llmemory/vector_store/base.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module VectorStore
+    class Base
+      def embed(text)
+        raise NotImplementedError, "#{self.class}#embed must be implemented"
+      end
+
+      def store(id:, embedding:, metadata: {})
+        raise NotImplementedError, "#{self.class}#store must be implemented"
+      end
+
+      def search(query_embedding, top_k: 10)
+        raise NotImplementedError, "#{self.class}#search must be implemented"
+      end
+    end
+  end
+end

data/lib/llmemory/vector_store/memory_store.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module VectorStore
+    class MemoryStore < Base
+      def initialize(embedding_provider: nil)
+        @entries = {}
+        @embedding_provider = embedding_provider
+      end
+
+      def embed(text)
+        return Array.new(1536, 0.0) unless @embedding_provider&.respond_to?(:embed)
+        @embedding_provider.embed(text)
+      end
+
+      def store(id:, embedding:, metadata: {}, user_id: nil)
+        key = user_id ? "#{user_id}:#{id}" : id.to_s
+        @entries[key] = { embedding: embedding.to_a.map(&:to_f), metadata: (metadata || {}).merge("user_id" => user_id) }
+        id
+      end
+
+      def search(query_embedding, top_k: 10, user_id: nil)
+        query = query_embedding.to_a.map(&:to_f)
+        return [] if query.empty?
+        entries = user_id ? @entries.select { |k, _| k.to_s.start_with?("#{user_id}:") } : @entries
+        scores = entries.map do |id, data|
+          sim = cosine_similarity(query, data[:embedding])
+          { id: id, score: sim, metadata: data[:metadata] }
+        end
+        scores.sort_by { |s| -s[:score] }.first(top_k)
+      end
+
+      def search_by_text(query_text, top_k: 10, user_id: nil)
+        return [] unless @embedding_provider&.respond_to?(:embed)
+        query_embedding = @embedding_provider.embed(query_text)
+        search(query_embedding, top_k: top_k, user_id: user_id)
+      end
+
+      private
+
+      def cosine_similarity(a, b)
+        return 0.0 if a.size != b.size || a.empty?
+        dot = a.zip(b).sum { |x, y| x * y }
+        norm_a = Math.sqrt(a.sum { |x| x * x })
+        norm_b = Math.sqrt(b.sum { |x| x * x })
+        return 0.0 if norm_a.zero? || norm_b.zero?
+        dot / (norm_a * norm_b)
+      end
+    end
+  end
+end

data/lib/llmemory/vector_store/openai_embeddings.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require_relative "base"
+
+module Llmemory
+  module VectorStore
+    class OpenAIEmbeddings < Base
+      DEFAULT_MODEL = "text-embedding-3-small"
+      DEFAULT_DIMS = 1536
+
+      def initialize(api_key: nil, model: nil)
+        @api_key = api_key || Llmemory.configuration.llm_api_key
+        @model = model || DEFAULT_MODEL
+      end
+
+      def embed(text)
+        return Array.new(DEFAULT_DIMS, 0.0) if text.to_s.strip.empty?
+        response = connection.post("/embeddings") do |req|
+          req.headers["Authorization"] = "Bearer #{@api_key}"
+          req.headers["Content-Type"] = "application/json"
+          req.body = { input: text.to_s.strip, model: @model }.to_json
+        end
+        raise Llmemory::LLMError, "OpenAI Embeddings API error: #{response.body}" unless response.success?
+        body = response.body.is_a?(Hash) ? response.body : JSON.parse(response.body.to_s)
+        body.dig("data", 0, "embedding")&.map(&:to_f) || Array.new(DEFAULT_DIMS, 0.0)
+      end
+
+      def store(id:, embedding:, metadata: {})
+        raise NotImplementedError, "OpenAIEmbeddings does not store; use a VectorStore backend (e.g. MemoryStore)"
+      end
+
+      def search(query_embedding, top_k: 10)
+        raise NotImplementedError, "OpenAIEmbeddings does not search; use a VectorStore backend"
+      end
+
+      private
+
+      def connection
+        @connection ||= Faraday.new(url: "https://api.openai.com/v1") do |f|
+          f.request :json
+          f.response :json
+          f.adapter Faraday.default_adapter
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/vector_store.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "vector_store/base"
+require_relative "vector_store/openai_embeddings"
+require_relative "vector_store/memory_store"
+
+module Llmemory
+  module VectorStore
+  end
+end

data/lib/llmemory/version.rb

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

data/lib/llmemory.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "llmemory/version"
+require_relative "llmemory/configuration"
+require_relative "llmemory/llm"
+require_relative "llmemory/short_term"
+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/memory"
+
+module Llmemory
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class StoreError < Error; end
+  class LLMError < Error; end
+end

metadata

@@ -0,0 +1,163 @@
+--- !ruby/object:Gem::Specification
+name: llmemory
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- llmemory
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-02-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+description: 'Memory infrastructure for agents: short-term checkpointing, long-term
+  file-based and graph-based memory, retrieval with time decay, and maintenance jobs.'
+email:
+- ''
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/generators/llmemory/install/install_generator.rb
+- lib/generators/llmemory/install/templates/create_llmemory_tables.rb
+- lib/llmemory.rb
+- lib/llmemory/configuration.rb
+- lib/llmemory/extractors.rb
+- lib/llmemory/extractors/entity_relation_extractor.rb
+- lib/llmemory/extractors/fact_extractor.rb
+- lib/llmemory/llm.rb
+- lib/llmemory/llm/anthropic.rb
+- lib/llmemory/llm/base.rb
+- lib/llmemory/llm/openai.rb
+- lib/llmemory/long_term.rb
+- lib/llmemory/long_term/file_based.rb
+- lib/llmemory/long_term/file_based/category.rb
+- lib/llmemory/long_term/file_based/item.rb
+- lib/llmemory/long_term/file_based/memory.rb
+- lib/llmemory/long_term/file_based/resource.rb
+- lib/llmemory/long_term/file_based/retrieval.rb
+- lib/llmemory/long_term/file_based/storage.rb
+- lib/llmemory/long_term/file_based/storages/active_record_models.rb
+- lib/llmemory/long_term/file_based/storages/active_record_storage.rb
+- lib/llmemory/long_term/file_based/storages/base.rb
+- lib/llmemory/long_term/file_based/storages/database_storage.rb
+- lib/llmemory/long_term/file_based/storages/file_storage.rb
+- lib/llmemory/long_term/file_based/storages/memory_storage.rb
+- lib/llmemory/long_term/graph_based.rb
+- lib/llmemory/long_term/graph_based/conflict_resolver.rb
+- lib/llmemory/long_term/graph_based/edge.rb
+- lib/llmemory/long_term/graph_based/knowledge_graph.rb
+- lib/llmemory/long_term/graph_based/memory.rb
+- lib/llmemory/long_term/graph_based/node.rb
+- lib/llmemory/long_term/graph_based/storage.rb
+- lib/llmemory/long_term/graph_based/storages/active_record_models.rb
+- 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/maintenance.rb
+- lib/llmemory/maintenance/consolidator.rb
+- lib/llmemory/maintenance/reindexer.rb
+- lib/llmemory/maintenance/runner.rb
+- lib/llmemory/maintenance/summarizer.rb
+- lib/llmemory/memory.rb
+- lib/llmemory/retrieval.rb
+- lib/llmemory/retrieval/context_assembler.rb
+- lib/llmemory/retrieval/engine.rb
+- lib/llmemory/retrieval/temporal_ranker.rb
+- lib/llmemory/short_term.rb
+- lib/llmemory/short_term/checkpoint.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
+- lib/llmemory/short_term/stores/memory_store.rb
+- lib/llmemory/short_term/stores/postgres_store.rb
+- lib/llmemory/short_term/stores/redis_store.rb
+- lib/llmemory/vector_store.rb
+- lib/llmemory/vector_store/base.rb
+- lib/llmemory/vector_store/memory_store.rb
+- lib/llmemory/vector_store/openai_embeddings.rb
+- lib/llmemory/version.rb
+homepage: https://github.com/entaina/llmemory
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/entaina/llmemory
+  source_code_uri: https://github.com/entaina/llmemory
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: Persistent memory system for LLM agents
+test_files: []