llmemory 0.2.11 → 0.3.0

data/lib/llmemory/zero_mem/trace_state_link.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Llmemory
+  module ZeroMem
+    class TraceStateLink
+      SOURCES = %i[explicit deterministic].freeze
+
+      attr_reader :user_id, :state_key, :trace_id, :valid_from, :valid_to,
+                  :supersedes_trace_id, :source, :created_at
+
+      def self.build(user_id:, state_key:, trace_id:, valid_from:, valid_to: nil,
+                     supersedes_trace_id: nil, source: :explicit, created_at: nil)
+        src = source.to_sym
+        raise ValidationError, "invalid state link source" unless SOURCES.include?(src)
+
+        new(
+          user_id: user_id.to_s,
+          state_key: state_key.to_s,
+          trace_id: trace_id.to_s,
+          valid_from: Trace.coerce_time(valid_from),
+          valid_to: valid_to ? Trace.coerce_time(valid_to) : nil,
+          supersedes_trace_id: supersedes_trace_id&.to_s,
+          source: src,
+          created_at: created_at ? Trace.coerce_time(created_at) : Time.now
+        )
+      end
+
+      def initialize(user_id:, state_key:, trace_id:, valid_from:, valid_to:,
+                     supersedes_trace_id:, source:, created_at:)
+        @user_id = user_id
+        @state_key = state_key
+        @trace_id = trace_id
+        @valid_from = valid_from
+        @valid_to = valid_to
+        @supersedes_trace_id = supersedes_trace_id
+        @source = source
+        @created_at = created_at
+      end
+
+      def active_at?(as_of)
+        t = as_of.is_a?(Time) ? as_of : Time.parse(as_of.to_s)
+        return false if t < valid_from
+        return true if valid_to.nil?
+
+        t <= valid_to
+      end
+
+      def to_h
+        {
+          user_id: user_id,
+          state_key: state_key,
+          trace_id: trace_id,
+          valid_from: valid_from.utc.iso8601(6),
+          valid_to: valid_to&.utc&.iso8601(6),
+          supersedes_trace_id: supersedes_trace_id,
+          source: source,
+          created_at: created_at.utc.iso8601(6)
+        }
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/trace_unit.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Llmemory
+  module ZeroMem
+    class TraceUnit
+      KINDS = %i[turn window episode].freeze
+
+      attr_reader :id, :user_id, :kind, :session_id, :boundary_id, :start_sequence, :end_sequence,
+                  :occurred_from, :occurred_to, :member_trace_ids, :embedding_ref, :index_version
+
+      def self.build(user_id:, kind:, session_id:, member_trace_ids:, start_sequence:, end_sequence:,
+                     occurred_from:, occurred_to:, id: nil, boundary_id: nil, embedding_ref: nil,
+                     index_version: 0)
+        k = kind.to_sym
+        raise ValidationError, "invalid trace unit kind" unless KINDS.include?(k)
+
+        new(
+          id: id || "tu_#{SecureRandom.hex(10)}",
+          user_id: user_id.to_s,
+          kind: k,
+          session_id: session_id.to_s,
+          boundary_id: boundary_id&.to_s,
+          start_sequence: start_sequence.to_i,
+          end_sequence: end_sequence.to_i,
+          occurred_from: Trace.coerce_time(occurred_from),
+          occurred_to: Trace.coerce_time(occurred_to),
+          member_trace_ids: Array(member_trace_ids).map(&:to_s),
+          embedding_ref: embedding_ref,
+          index_version: index_version.to_i
+        )
+      end
+
+      def initialize(id:, user_id:, kind:, session_id:, boundary_id:, start_sequence:, end_sequence:,
+                     occurred_from:, occurred_to:, member_trace_ids:, embedding_ref:, index_version:)
+        @id = id
+        @user_id = user_id
+        @kind = kind
+        @session_id = session_id
+        @boundary_id = boundary_id
+        @start_sequence = start_sequence
+        @end_sequence = end_sequence
+        @occurred_from = occurred_from
+        @occurred_to = occurred_to
+        @member_trace_ids = member_trace_ids
+        @embedding_ref = embedding_ref
+        @index_version = index_version
+      end
+
+      def episode_key
+        boundary_id || session_id
+      end
+
+      def to_h
+        {
+          id: id,
+          user_id: user_id,
+          kind: kind,
+          session_id: session_id,
+          boundary_id: boundary_id,
+          start_sequence: start_sequence,
+          end_sequence: end_sequence,
+          occurred_from: occurred_from.utc.iso8601(6),
+          occurred_to: occurred_to.utc.iso8601(6),
+          member_trace_ids: member_trace_ids,
+          embedding_ref: embedding_ref,
+          index_version: index_version
+        }
+      end
+
+      def with(**changes)
+        attrs = {
+          id: id, user_id: user_id, kind: kind, session_id: session_id, boundary_id: boundary_id,
+          start_sequence: start_sequence, end_sequence: end_sequence,
+          occurred_from: occurred_from, occurred_to: occurred_to,
+          member_trace_ids: member_trace_ids, embedding_ref: embedding_ref, index_version: index_version
+        }.merge(changes)
+        self.class.new(**attrs)
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "zero_mem/mode"
+require_relative "zero_mem/errors"
+require_relative "zero_mem/trace"
+require_relative "zero_mem/trace_state_link"
+require_relative "zero_mem/storage"
+require_relative "zero_mem/storages"
+require_relative "zero_mem/indexer"
+require_relative "zero_mem/repair"
+require_relative "zero_mem/backfill"
+require_relative "zero_mem/trace_unit"
+require_relative "zero_mem/hierarchy_builder"
+require_relative "zero_mem/query_profile"
+require_relative "zero_mem/query_profiler"
+require_relative "zero_mem/hierarchy_retriever"
+require_relative "zero_mem/evidence"
+require_relative "zero_mem/evidence_set"
+require_relative "zero_mem/evidence_calibrator"
+require_relative "zero_mem/budget_assembler"
+require_relative "zero_mem/router"
+require_relative "zero_mem/evidence_fusion"
+require_relative "zero_mem/evidence_closure"
+require_relative "zero_mem/answer_calibrator"
+require_relative "zero_mem/engine"
+require_relative "zero_mem/embedding_provider"
+require_relative "zero_mem/entity_extractor"
+require_relative "zero_mem/extractors/heuristic"
+require_relative "zero_mem/extractors/http"
+require_relative "zero_mem/entity"
+require_relative "zero_mem/entity_mention"
+require_relative "zero_mem/entity_index"
+require_relative "zero_mem/pagerank"
+require_relative "zero_mem/graph_retriever"
+require_relative "zero_mem/circuit_breaker"
+require_relative "zero_mem/sidecar_client"
+
+module Llmemory
+  module ZeroMem
+    MEMORY_TYPE = "zero_mem_trace"
+  end
+end

data/lib/llmemory.rb

@@ -26,7 +26,14 @@ module Llmemory
   class ConfigurationError < Error; end
   class StoreError < Error; end
   class LLMError < Error; end
+  class GenerativeOperationDisabled < Error
+    def initialize(message = "Generative memory operation is disabled in this memory mode")
+      super
+    end
+  end
 end
 
+require_relative "llmemory/zero_mem"
+
 require_relative "llmemory/crypto/cipher"
 require_relative "llmemory/railtie" if defined?(Rails::Railtie)

data/lib/tasks/llmemory.rake

@@ -1,6 +1,58 @@
 # frozen_string_literal: true
 
 namespace :llmemory do
+  namespace :zero_mem do
+    desc "Repair Zero-Mem trace watermarks vs checkpoint (requires trace_store configured in app)"
+    task :repair, %i[user_id session_id] do |_t, args|
+      require "llmemory"
+      user_id = args[:user_id] || ENV["USER_ID"] || abort("USER_ID or user_id argument required")
+      session_id = args[:session_id] || ENV["SESSION_ID"] || Llmemory::Memory::DEFAULT_SESSION_ID
+      store = Llmemory::ZeroMem::Storages.build
+      memory = Llmemory::Memory.new(user_id: user_id, session_id: session_id, trace_store: store, memory_mode: :zero_mem)
+      report = Llmemory::ZeroMem::Repair.new(storage: store).run!(
+        user_id: user_id,
+        session_id: session_id,
+        checkpoint_messages: memory.messages
+      )
+      puts "Zero-Mem repair user_id=#{user_id} session_id=#{session_id}: #{report.inspect}"
+    end
+
+    desc "Reindex Zero-Mem traces for a user session (ENV: USER_ID, SESSION_ID)"
+    task :reindex, %i[user_id session_id] do |_t, args|
+      require "llmemory"
+      user_id = args[:user_id] || ENV["USER_ID"] || abort("USER_ID or user_id argument required")
+      session_id = args[:session_id] || ENV["SESSION_ID"] || Llmemory::Memory::DEFAULT_SESSION_ID
+      store = Llmemory::ZeroMem::Storages.build
+      memory = Llmemory::Memory.new(user_id: user_id, session_id: session_id, trace_store: store, memory_mode: :zero_mem)
+      status = memory.reindex_traces!(session_id: session_id)
+      puts "Zero-Mem reindex: #{status.inspect}"
+    end
+
+    desc "Backfill checkpoint messages into traces (ENV: USER_ID, SESSION_ID)"
+    task :backfill, %i[user_id session_id] do |_t, args|
+      require "llmemory"
+      user_id = args[:user_id] || ENV["USER_ID"] || abort("USER_ID required")
+      session_id = args[:session_id] || ENV["SESSION_ID"] || Llmemory::Memory::DEFAULT_SESSION_ID
+      store = Llmemory::ZeroMem::Storages.build
+      memory = Llmemory::Memory.new(user_id: user_id, session_id: session_id, trace_store: store, memory_mode: :zero_mem)
+      report = Llmemory::ZeroMem::Backfill.new(storage: store).run!(
+        user_id: user_id,
+        session_id: session_id,
+        messages: memory.messages
+      )
+      puts "Zero-Mem backfill: #{report.inspect}"
+    end
+
+    desc "Archive Zero-Mem traces past TTL (ENV: USER_ID, DRY_RUN=1)"
+    task :expire, [:user_id] do |_t, args|
+      require "llmemory"
+      user_id = args[:user_id] || ENV["USER_ID"] || abort("USER_ID required")
+      store = Llmemory::ZeroMem::Storages.build
+      dry_run = ENV["DRY_RUN"].to_s == "1"
+      report = Llmemory::Maintenance::ZeroMemTTL.new(storage: store).run!(user_id: user_id, dry_run: dry_run)
+      puts "Zero-Mem expire: #{report.inspect}"
+    end
+  end
   desc "Backfill search_tokens blind index (and name_det on skills) for encrypted keyword search. " \
        "Env: FORCE=1 (re-backfill all rows), DRY_RUN=1 (count only), STORE=active_record|postgres"
   task :backfill_search_tokens, [:user_id] do |_t, args|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llmemory
 version: !ruby/object:Gem::Version
-  version: 0.2.11
+  version: 0.3.0
 platform: ruby
 authors:
 - llmemory
@@ -124,6 +124,8 @@ files:
 - exe/llmemory-mcp
 - lib/generators/llmemory/install/install_generator.rb
 - lib/generators/llmemory/install/templates/create_llmemory_tables.rb
+- lib/generators/llmemory/upgrade_zero_mem/templates/create_llmemory_zero_mem_tables.rb
+- lib/generators/llmemory/upgrade_zero_mem/upgrade_zero_mem_generator.rb
 - lib/llmemory.rb
 - lib/llmemory/actions.rb
 - lib/llmemory/actions/reason.rb
@@ -148,6 +150,7 @@ files:
 - lib/llmemory/cli/commands/stats.rb
 - lib/llmemory/cli/commands/users.rb
 - lib/llmemory/cli/commands/working.rb
+- lib/llmemory/cli/commands/zero_mem.rb
 - lib/llmemory/configuration.rb
 - lib/llmemory/consolidation.rb
 - lib/llmemory/consolidation/filter.rb
@@ -227,6 +230,7 @@ files:
 - lib/llmemory/maintenance/search_tokens_backfill.rb
 - lib/llmemory/maintenance/summarizer.rb
 - lib/llmemory/maintenance/ttl_expiry.rb
+- lib/llmemory/maintenance/zero_mem_ttl.rb
 - lib/llmemory/mcp.rb
 - lib/llmemory/mcp/authentication.rb
 - lib/llmemory/mcp/server.rb
@@ -240,6 +244,7 @@ files:
 - lib/llmemory/mcp/tools/memory_maintain.rb
 - lib/llmemory/mcp/tools/memory_mine_skills.rb
 - lib/llmemory/mcp/tools/memory_retrieve.rb
+- lib/llmemory/mcp/tools/memory_retrieve_evidence.rb
 - lib/llmemory/mcp/tools/memory_save.rb
 - lib/llmemory/mcp/tools/memory_search.rb
 - lib/llmemory/mcp/tools/memory_skill_register.rb
@@ -287,6 +292,47 @@ files:
 - lib/llmemory/vector_store/openai_embeddings.rb
 - lib/llmemory/version.rb
 - lib/llmemory/working_memory.rb
+- lib/llmemory/zero_mem.rb
+- lib/llmemory/zero_mem/answer_calibrator.rb
+- lib/llmemory/zero_mem/backfill.rb
+- lib/llmemory/zero_mem/budget_assembler.rb
+- lib/llmemory/zero_mem/circuit_breaker.rb
+- lib/llmemory/zero_mem/embedding_provider.rb
+- lib/llmemory/zero_mem/engine.rb
+- lib/llmemory/zero_mem/entity.rb
+- lib/llmemory/zero_mem/entity_extractor.rb
+- lib/llmemory/zero_mem/entity_index.rb
+- lib/llmemory/zero_mem/entity_mention.rb
+- lib/llmemory/zero_mem/errors.rb
+- lib/llmemory/zero_mem/evidence.rb
+- lib/llmemory/zero_mem/evidence_calibrator.rb
+- lib/llmemory/zero_mem/evidence_closure.rb
+- lib/llmemory/zero_mem/evidence_fusion.rb
+- lib/llmemory/zero_mem/evidence_set.rb
+- lib/llmemory/zero_mem/extractors/heuristic.rb
+- lib/llmemory/zero_mem/extractors/http.rb
+- lib/llmemory/zero_mem/graph_retriever.rb
+- lib/llmemory/zero_mem/hierarchy_builder.rb
+- lib/llmemory/zero_mem/hierarchy_retriever.rb
+- lib/llmemory/zero_mem/indexer.rb
+- lib/llmemory/zero_mem/mode.rb
+- lib/llmemory/zero_mem/pagerank.rb
+- lib/llmemory/zero_mem/query_profile.rb
+- lib/llmemory/zero_mem/query_profiler.rb
+- lib/llmemory/zero_mem/repair.rb
+- lib/llmemory/zero_mem/router.rb
+- lib/llmemory/zero_mem/sidecar_client.rb
+- lib/llmemory/zero_mem/storage.rb
+- lib/llmemory/zero_mem/storages.rb
+- lib/llmemory/zero_mem/storages/active_record.rb
+- lib/llmemory/zero_mem/storages/active_record_models.rb
+- lib/llmemory/zero_mem/storages/file.rb
+- lib/llmemory/zero_mem/storages/memory.rb
+- lib/llmemory/zero_mem/storages/postgres.rb
+- lib/llmemory/zero_mem/storages/snapshot_codec.rb
+- lib/llmemory/zero_mem/trace.rb
+- lib/llmemory/zero_mem/trace_state_link.rb
+- lib/llmemory/zero_mem/trace_unit.rb
 - lib/tasks/llmemory.rake
 - lib/tasks/release.rake
 homepage: https://github.com/entaina/llmemory
@@ -309,7 +355,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Persistent memory system for LLM agents
 test_files: []