llmemory 0.2.11 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c52d2f218d44057a93d247a535d06a4f4d0877d3ff67fdc48bf9011886ac9199
-  data.tar.gz: 1934ecd2e82c9518cbb9806c297c172fa5d3c2baa2c676da81943646309cf4bc
+  metadata.gz: 004e6d5f30c9eba38319382257934d0644635fd63555e854043f32d7ec4aa7b0
+  data.tar.gz: 9295714e79963b31a2c23eb6834a4c31b75c2d83a044ecce905726c5ad8a41b1
 SHA512:
-  metadata.gz: 5879fda1878fe865b8e9391f36270cbb85b74b41461a06f66e2c86f3c33475fb383f98ae6dc06391764ad9ec65055b97b146908d3b96d39cff39e4971aeb134b
-  data.tar.gz: e7f3f99792aa601b49b6c96f3d960acbf4969b5df6b7341aa8074a46e87ab6a96245752a758902300a8c40b7b2683d5bcc4ba8d0517b978169526647a3d4e64c
+  metadata.gz: e56b9d1b8a537b1a134be39cc9e0f563eed3f7e20f0cef23bb8dc12aa7881c30512382e027ed5926f507faf09ee2ca691fc2c489fd16bdbf1e1562c7e5e74ca2
+  data.tar.gz: a34a15a7eab1202fe44ebcf85e828c81d99941b1102f88242b8efada40884328a22369dd7860f27449401bd8a123c80cdf02305c9d19b5a0215f1a30ebcd6f31

data/README.md

@@ -153,6 +153,29 @@ Llmemory.configure do |config|
 end
 ```
 
+### Zero-Mem (experimental, opt-in)
+
+Zero-Mem keeps **immutable traces** as the source of truth and retrieves evidence with deterministic profiling, hierarchy, and entity-graph ranking — **without generative LLM calls** in memory operations (`memory_mode: :zero_mem`). Default remains `:classic`. This is experimental: it does not reproduce published benchmark numbers.
+
+```ruby
+Llmemory.configure do |config|
+  config.memory_mode = :zero_mem   # or :hybrid (traces + classic long-term; not zero-token)
+  config.zero_mem_trace_store = :memory  # or :active_record in Rails apps
+end
+
+memory = Llmemory::Memory.new(user_id: "u1", session_id: "s1")
+memory.add_message(role: :user, content: "Project Atlas uses Nimbus")
+context = memory.retrieve("Which database does Atlas use?")
+evidence = memory.retrieve_evidence("Which database does Atlas use?", explain: true)
+
+# Explicit generative ops raise in :zero_mem
+# memory.consolidate!  # => Llmemory::GenerativeOperationDisabled
+```
+
+CLI: `llmemory zero-mem traces USER`, `status`, `reindex`, `search USER "query"`. MCP: `memory_retrieve` (text, same as before) and `memory_retrieve_evidence` (structured JSON + context).
+
+Rollout: enable `zero_mem_shadow_write` while staying on `:classic` for reads; see [docs/zero_mem_limitations.md](docs/zero_mem_limitations.md). Benchmarks: [benchmarks/zero_mem/README.md](benchmarks/zero_mem/README.md).
+
 ## Consolidation policy
 
 By default, llmemory consolidates every extracted fact into long-term memory. For agents with **authoritative live data** (tools, DB snapshots), configure a `Consolidation::Policy` to **drop** or **mark volatile** facts that should not be treated as stable memory (e.g. current job, plan status, task lists).

data/lib/generators/llmemory/install/templates/create_llmemory_tables.rb

@@ -94,9 +94,80 @@ class CreateLlmemoryTables < ActiveRecord::Migration[7.0]
       t.string :source_type, null: false
       t.string :source_id, null: false
       t.vector :embedding, limit: 1536
+      t.string :embedding_model
+      t.integer :embedding_dimensions
       t.text :text_content
       t.timestamps
     end
     add_index :llmemory_embeddings, [:user_id, :source_type, :source_id], unique: true
+
+    create_table :llmemory_traces, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      t.string :user_id, null: false
+      t.string :session_id, null: false
+      t.string :boundary_id
+      t.bigint :sequence, null: false
+      t.string :role, null: false
+      t.text :content, null: false
+      t.text :search_tokens
+      t.string :content_sha256, null: false
+      t.datetime :occurred_at, null: false
+      t.datetime :ingested_at, null: false
+      t.jsonb :metadata, null: false, default: {}
+      t.string :idempotency_key
+      t.datetime :archived_at
+      t.timestamps
+    end
+    add_index :llmemory_traces, [:user_id, :session_id, :sequence], unique: true
+    add_index :llmemory_traces, [:user_id, :idempotency_key], unique: true, where: "idempotency_key IS NOT NULL"
+    add_index :llmemory_traces, [:user_id, :session_id, :occurred_at]
+    add_index :llmemory_traces, [:user_id, :boundary_id]
+    add_index :llmemory_traces, [:user_id, :archived_at]
+
+    create_table :llmemory_trace_state_links do |t|
+      t.string :user_id, null: false
+      t.string :state_key, null: false
+      t.string :trace_id, null: false
+      t.datetime :valid_from, null: false
+      t.datetime :valid_to
+      t.string :supersedes_trace_id
+      t.string :source, null: false, default: "explicit"
+      t.datetime :created_at, null: false
+    end
+    add_index :llmemory_trace_state_links, [:user_id, :state_key, :valid_from, :valid_to]
+    add_index :llmemory_trace_state_links, :trace_id
+
+    create_table :llmemory_trace_units, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      t.string :user_id, null: false
+      t.string :trace_id, null: false
+      t.string :unit_type, null: false
+      t.jsonb :data, null: false, default: {}
+      t.datetime :archived_at
+      t.timestamps
+    end
+    add_index :llmemory_trace_units, [:user_id, :trace_id]
+
+    create_table :llmemory_trace_entities, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      t.string :user_id, null: false
+      t.string :name, null: false
+      t.string :entity_type
+      t.datetime :archived_at
+      t.timestamps
+    end
+    add_index :llmemory_trace_entities, [:user_id, :name]
+
+    create_table :llmemory_entity_mentions, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      t.string :user_id, null: false
+      t.string :trace_id, null: false
+      t.string :entity_id, null: false
+      t.integer :offset_start
+      t.integer :offset_end
+      t.datetime :archived_at
+      t.timestamps
+    end
+    add_index :llmemory_entity_mentions, [:user_id, :trace_id]
   end
 end

data/lib/generators/llmemory/upgrade_zero_mem/templates/create_llmemory_zero_mem_tables.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+class CreateLlmemoryZeroMemTables < ActiveRecord::Migration[7.0]
+  def change
+    create_table :llmemory_traces, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      t.string :user_id, null: false
+      t.string :session_id, null: false
+      t.string :boundary_id
+      t.bigint :sequence, null: false
+      t.string :role, null: false
+      t.text :content, null: false
+      t.text :search_tokens
+      t.string :content_sha256, null: false
+      t.datetime :occurred_at, null: false
+      t.datetime :ingested_at, null: false
+      t.jsonb :metadata, null: false, default: {}
+      t.string :idempotency_key
+      t.datetime :archived_at
+      t.timestamps
+    end
+    add_index :llmemory_traces, [:user_id, :session_id, :sequence], unique: true, name: "idx_llmemory_traces_user_session_sequence"
+    add_index :llmemory_traces, [:user_id, :idempotency_key], unique: true, where: "idempotency_key IS NOT NULL",
+              name: "idx_llmemory_traces_user_idempotency"
+    add_index :llmemory_traces, [:user_id, :session_id, :occurred_at], name: "idx_llmemory_traces_user_session_occurred"
+    add_index :llmemory_traces, [:user_id, :boundary_id], name: "idx_llmemory_traces_user_boundary"
+    add_index :llmemory_traces, [:user_id, :archived_at], name: "idx_llmemory_traces_user_archived"
+
+    create_table :llmemory_trace_state_links do |t|
+      t.string :user_id, null: false
+      t.string :state_key, null: false
+      t.string :trace_id, null: false
+      t.datetime :valid_from, null: false
+      t.datetime :valid_to
+      t.string :supersedes_trace_id
+      t.string :source, null: false, default: "explicit"
+      t.datetime :created_at, null: false
+    end
+    add_index :llmemory_trace_state_links, [:user_id, :state_key, :valid_from, :valid_to],
+              name: "idx_llmemory_trace_state_links_validity"
+    add_index :llmemory_trace_state_links, :trace_id, name: "idx_llmemory_trace_state_links_trace"
+
+    # Reserved for ZM2/ZM3 — created now to avoid chained migrations later.
+    create_table :llmemory_trace_units, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      t.string :user_id, null: false
+      t.string :trace_id, null: false
+      t.string :unit_type, null: false
+      t.jsonb :data, null: false, default: {}
+      t.datetime :archived_at
+      t.timestamps
+    end
+    add_index :llmemory_trace_units, [:user_id, :trace_id], name: "idx_llmemory_trace_units_user_trace"
+
+    create_table :llmemory_trace_entities, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      t.string :user_id, null: false
+      t.string :name, null: false
+      t.string :entity_type
+      t.datetime :archived_at
+      t.timestamps
+    end
+    add_index :llmemory_trace_entities, [:user_id, :name], name: "idx_llmemory_trace_entities_user_name"
+
+    create_table :llmemory_entity_mentions, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      t.string :user_id, null: false
+      t.string :trace_id, null: false
+      t.string :entity_id, null: false
+      t.integer :offset_start
+      t.integer :offset_end
+      t.datetime :archived_at
+      t.timestamps
+    end
+    add_index :llmemory_entity_mentions, [:user_id, :trace_id], name: "idx_llmemory_entity_mentions_user_trace"
+  end
+end

data/lib/generators/llmemory/upgrade_zero_mem/upgrade_zero_mem_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Llmemory
+  module Generators
+    class UpgradeZeroMemGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Add Zero-Mem trace tables (llmemory_traces, state links, reserved index tables)"
+
+      def copy_migration
+        timestamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
+        template "create_llmemory_zero_mem_tables.rb",
+                 "db/migrate/#{timestamp}_create_llmemory_zero_mem_tables.rb"
+      end
+    end
+  end
+end

data/lib/llmemory/cli/commands/zero_mem.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "base"
+
+module Llmemory
+  module Cli
+    module Commands
+      class ZeroMem < Base
+        def option_parser(parser)
+          parser.on("--session SESSION", "Session id (default: default)") { |v| @session_id = v }
+          parser.on("--explain", "Include explain payload on search") { @explain = true }
+        end
+
+        def execute(argv, _opts)
+          sub = argv.shift
+          case sub
+          when "traces"
+            run_traces(argv)
+          when "reindex"
+            run_reindex(argv)
+          when "status"
+            run_status(argv)
+          when "search"
+            run_search(argv)
+          else
+            print_usage
+            exit 1
+          end
+        end
+
+        private
+
+        def print_usage
+          $stderr.puts <<~HELP
+            Usage:
+              llmemory zero-mem traces USER_ID [--session SESSION]
+              llmemory zero-mem reindex USER_ID [--session SESSION]
+              llmemory zero-mem status USER_ID [--session SESSION]
+              llmemory zero-mem search USER_ID "query" [--explain]
+          HELP
+        end
+
+        def build_memory(user_id)
+          trace_store = Llmemory::ZeroMem::Storages.build
+          Llmemory::Memory.new(
+            user_id: user_id,
+            session_id: @session_id || "default",
+            trace_store: trace_store,
+            memory_mode: :zero_mem
+          )
+        end
+
+        def run_traces(argv)
+          user_id = argv.shift
+          unless user_id
+            print_usage
+            exit 1
+          end
+
+          memory = build_memory(user_id)
+          traces = memory.trace_store.list_traces(user_id, session_id: @session_id || "default")
+          traces.each do |t|
+            puts "[#{t.id}] seq=#{t.sequence} #{t.role}: #{t.content[0, 120]}"
+          end
+        end
+
+        def run_reindex(argv)
+          user_id = argv.shift
+          unless user_id
+            print_usage
+            exit 1
+          end
+
+          memory = build_memory(user_id)
+          status = memory.reindex_traces!(session_id: @session_id || "default")
+          puts JSON.generate(status)
+        end
+
+        def run_status(argv)
+          user_id = argv.shift
+          unless user_id
+            print_usage
+            exit 1
+          end
+
+          memory = build_memory(user_id)
+          puts JSON.generate(memory.zero_mem_status(session_id: @session_id || "default"))
+        end
+
+        def run_search(argv)
+          user_id = argv.shift
+          query = argv.join(" ").strip
+          unless user_id && !query.empty?
+            print_usage
+            exit 1
+          end
+
+          memory = build_memory(user_id)
+          result = memory.retrieve_evidence(query, explain: @explain == true)
+          puts result.to_context
+          puts JSON.generate(metrics: result.metrics, route: result.route) if @explain
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/cli.rb

@@ -13,6 +13,7 @@ require_relative "cli/commands/mine_skills"
 require_relative "cli/commands/maintain"
 require_relative "cli/commands/stats"
 require_relative "cli/commands/search"
+require_relative "cli/commands/zero_mem"
 require_relative "cli/commands/mcp"
 
 module Llmemory
@@ -60,6 +61,7 @@ module Llmemory
         "mine_skills" => Cli::Commands::MineSkills,
         "maintain" => Cli::Commands::Maintain,
         "search" => Cli::Commands::Search,
+        "zero_mem" => Cli::Commands::ZeroMem,
         "stats" => Cli::Commands::Stats,
         "mcp" => Cli::Commands::Mcp
       }[normalized]
@@ -87,6 +89,7 @@ module Llmemory
           mine-skills USER_ID      Mine reusable skills from episodes (--register to save)
           maintain USER_ID         Run the cognitive maintenance pass (reflect/mine/expire)
           search USER_ID "query"   Search in memory
+          zero-mem SUB ...         Zero-Mem traces, reindex, status, search (experimental)
           stats [USER_ID]          Show statistics
           mcp [serve]              Start MCP server for LLM agents
 

data/lib/llmemory/configuration.rb

@@ -59,7 +59,26 @@ module Llmemory
                   :dashboard_auth,
                   :dashboard_require_auth,
                   :consolidation_policy,
-                  :retrieval_label_volatile
+                  :retrieval_label_volatile,
+                  :zero_mem_index_mode,
+                  :zero_mem_trace_store,
+                  :zero_mem_top_k,
+                  :zero_mem_max_top_k,
+                  :zero_mem_local_span,
+                  :zero_mem_window_size,
+                  :zero_mem_window_overlap,
+                  :zero_mem_episode_gap_seconds,
+                  :zero_mem_entity_extractor,
+                  :zero_mem_embedding_provider,
+                  :zero_mem_require_local_encoders,
+                  :zero_mem_pagerank_damping,
+                  :zero_mem_graph_weight,
+                  :zero_mem_ner_http_url,
+                  :memory_mode,
+                  :zero_mem_ttl_days,
+                  :zero_mem_sidecar_timeout_seconds,
+                  :zero_mem_sidecar_failure_threshold,
+                  :zero_mem_shadow_write
 
     def initialize
       @llm_provider = :openai
@@ -120,6 +139,44 @@ module Llmemory
       @dashboard_require_auth = nil
       @consolidation_policy = nil
       @retrieval_label_volatile = false
+      @zero_mem_index_mode = :sync
+      @zero_mem_trace_store = :memory
+      @zero_mem_top_k = 5
+      @zero_mem_max_top_k = 10
+      @zero_mem_local_span = 2
+      @zero_mem_window_size = 8
+      @zero_mem_window_overlap = 2
+      @zero_mem_episode_gap_seconds = 86_400
+      @zero_mem_entity_extractor = :heuristic
+      @zero_mem_embedding_provider = nil
+      @zero_mem_require_local_encoders = false
+      @zero_mem_pagerank_damping = 0.6
+      @zero_mem_graph_weight = 0.6
+      @zero_mem_ner_http_url = "http://127.0.0.1:8765"
+      @memory_mode = :classic
+      @zero_mem_ttl_days = nil
+      @zero_mem_sidecar_timeout_seconds = 5
+      @zero_mem_sidecar_failure_threshold = 3
+      @zero_mem_shadow_write = false
+    end
+
+    def validate!
+      mode = @memory_mode.to_sym
+      unless ZeroMem::Mode.valid?(mode)
+        raise ConfigurationError, "memory_mode must be :classic, :zero_mem, or :hybrid (got #{@memory_mode.inspect})"
+      end
+
+      rho = zero_mem_graph_weight.to_f
+      gamma = zero_mem_pagerank_damping.to_f
+      raise ConfigurationError, "zero_mem_graph_weight must be in [0, 1]" unless rho.between?(0.0, 1.0)
+      raise ConfigurationError, "zero_mem_pagerank_damping must be in [0, 1]" unless gamma.between?(0.0, 1.0)
+      raise ConfigurationError, "zero_mem_top_k must be positive" unless zero_mem_top_k.to_i.positive?
+      raise ConfigurationError, "zero_mem_max_top_k must be >= zero_mem_top_k" if zero_mem_max_top_k.to_i < zero_mem_top_k.to_i
+
+      extractor = zero_mem_entity_extractor.to_sym
+      unless %i[heuristic http].include?(extractor)
+        raise ConfigurationError, "zero_mem_entity_extractor must be :heuristic or :http"
+      end
     end
 
     def consolidation_policy
@@ -146,6 +203,7 @@ module Llmemory
 
     def configure
       yield configuration
+      configuration.validate!
     end
 
     def reset_configuration!

data/lib/llmemory/instrumentation.rb

@@ -16,10 +16,19 @@ module Llmemory
   #                             output_tokens:, total_tokens:
   #   memory_write.llmemory     memory_type:, user_id:
   #   memory_forget.llmemory    memory_type:, user_id:, count:
-  #   retrieve.llmemory         query_chars:, candidates:, results:
+  #   retrieve.llmemory         query_chars:, candidates:, results:, zero_mem_compliant:
   #   iterative_retrieve.llmemory  hops:, total_results:
   #   reflect.llmemory          window:, insights:
   #   mine_skills.llmemory      window:, auto_register:
+  #   trace_write.llmemory      user_id:, session_id:, trace_id:, sequence:, maintenance_fanout:
+  #   zero_mem_state_update.llmemory  user_id:, state_key:, trace_id:, supersedes_trace_id:
+  #   zero_mem_profile.llmemory       user_id:, query_chars:
+  #   zero_mem_hierarchy_retrieve.llmemory  user_id:, workload:
+  #   zero_mem_retrieve.llmemory      user_id:, evidence_count:, degraded:
+  #   zero_mem_graph_retrieve.llmemory user_id:
+  #   zero_mem_closure.llmemory       user_id:, seeds:
+  #   zero_mem_calibrate.llmemory     user_id:, trace_count:
+  #   encoder_embed.llmemory          user_id:, trace_id:, model:, dimensions:, duration_ms:
   module Instrumentation
     module_function
 

data/lib/llmemory/maintenance/cognitive_pass.rb

@@ -43,7 +43,22 @@ module Llmemory
       end
 
       def run!
-        report = { consolidated: nil, insights: [], mined: [], expired: { episodic: 0, procedural: 0 }, errors: {} }
+        report = {
+          consolidated: nil,
+          insights: [],
+          mined: [],
+          expired: { episodic: 0, procedural: 0 },
+          errors: {},
+          disabled: []
+        }
+
+        if @memory&.zero_mem_strict?
+          report[:disabled] = %i[consolidate reflect mine]
+          report[:consolidated] = false
+          step(report, :zero_mem_repair) { report[:zero_mem] = zero_mem_repair } if @memory.trace_store
+          step(report, :expire) { report[:expired] = expire } if @expire
+          return report
+        end
 
         step(report, :consolidate) { report[:consolidated] = consolidate } if @memory
         step(report, :reflect)     { report[:insights] = reflect } if @reflect
@@ -79,6 +94,19 @@ module Llmemory
         TTLExpiry.run!(@user_id, episodic: episodic, procedural: procedural)
       end
 
+      def zero_mem_repair
+        store = @memory.trace_store
+        repair = ZeroMem::Repair.new(storage: store)
+        sessions = store.list_traces(@user_id).map(&:session_id).uniq
+        sessions.map do |sid|
+          repair.run!(
+            user_id: @user_id,
+            session_id: sid,
+            checkpoint_messages: @memory.messages
+          )
+        end
+      end
+
       def episodic
         @episodic ||= @memory&.episodic || Llmemory::LongTerm::Episodic::Memory.new(user_id: @user_id)
       end

data/lib/llmemory/maintenance/zero_mem_ttl.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Maintenance
+    class ZeroMemTTL
+      def initialize(storage:, ttl_days: nil)
+        @storage = storage
+        @ttl_days = ttl_days || Llmemory.configuration.zero_mem_ttl_days
+      end
+
+      def run!(user_id:, dry_run: false)
+        return { archived: 0, skipped: true } if @ttl_days.nil? || @ttl_days.to_i <= 0
+
+        cutoff = Time.now - (@ttl_days.to_i * 86_400)
+        archived = 0
+        @storage.list_traces(user_id, include_archived: false).each do |trace|
+          next unless trace.occurred_at < cutoff
+
+          archived += 1
+          @storage.archive_trace(user_id, trace.id) unless dry_run
+        end
+        { archived: archived, dry_run: dry_run, cutoff: cutoff.utc.iso8601 }
+      end
+    end
+  end
+end

data/lib/llmemory/maintenance.rb

@@ -5,6 +5,7 @@ require_relative "maintenance/ttl_expiry"
 require_relative "maintenance/cognitive_pass"
 require_relative "maintenance/search_tokens_backfill"
 require_relative "maintenance/policy_prune"
+require_relative "maintenance/zero_mem_ttl"
 
 module Llmemory
   module Maintenance

data/lib/llmemory/mcp/server.rb

@@ -5,6 +5,7 @@ require_relative "authentication"
 require_relative "tools/memory_search"
 require_relative "tools/memory_save"
 require_relative "tools/memory_retrieve"
+require_relative "tools/memory_retrieve_evidence"
 require_relative "tools/memory_timeline"
 require_relative "tools/memory_add_message"
 require_relative "tools/memory_consolidate"
@@ -175,6 +176,7 @@ module Llmemory
           Tools::MemorySearch,
           Tools::MemorySave,
           Tools::MemoryRetrieve,
+          Tools::MemoryRetrieveEvidence,
           Tools::MemoryTimeline,
           Tools::MemoryTimelineContext,
           Tools::MemoryAddMessage,

data/lib/llmemory/mcp/store_helpers.rb

@@ -30,6 +30,22 @@ module Llmemory
       def graph_based?
         Llmemory.configuration.long_term_type.to_sym == :graph_based
       end
+
+      def trace_store_instance
+        @trace_store_instance ||= ZeroMem::Storages.build
+      end
+
+      def build_memory(user_id:, session_id: "default", trace_store: nil, memory_mode: nil)
+        mode = memory_mode || Llmemory.configuration.memory_mode
+        store = trace_store
+        store = trace_store_instance if store.nil? && ZeroMem::Mode.zero_mem_enabled?(mode)
+        Llmemory::Memory.new(
+          user_id: user_id,
+          session_id: session_id,
+          trace_store: store,
+          memory_mode: mode
+        )
+      end
     end
   end
 end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../store_helpers"
+
 module Llmemory
   module MCP
     module Tools
@@ -11,17 +13,28 @@ module Llmemory
             user_id: { type: "string", description: "User identifier" },
             session_id: { type: "string", description: "Session identifier (default: 'default')" },
             role: { type: "string", enum: ["user", "assistant", "system", "tool", "tool_result"], description: "Message role" },
-            content: { type: "string", description: "Message content" }
+            content: { type: "string", description: "Message content" },
+            occurred_at: { type: "string", description: "Optional ISO8601 timestamp for trace ingestion" },
+            boundary_id: { type: "string", description: "Optional boundary identifier (Zero-Mem)" },
+            idempotency_key: { type: "string", description: "Optional idempotency key for trace writes" }
           },
           required: ["user_id", "role", "content"]
         )
 
         class << self
-          def call(user_id:, role:, content:, session_id: nil, server_context: nil)
+          def call(user_id:, role:, content:, session_id: nil, occurred_at: nil, boundary_id: nil,
+                   idempotency_key: nil, server_context: nil)
             session = session_id || "default"
 
-            memory = Llmemory::Memory.new(user_id: user_id, session_id: session)
-            memory.add_message(role: role.to_sym, content: content)
+            memory = StoreHelpers.build_memory(user_id: user_id, session_id: session)
+            parsed_time = occurred_at ? Time.parse(occurred_at.to_s) : nil
+            memory.add_message(
+              role: role.to_sym,
+              content: content,
+              occurred_at: parsed_time,
+              boundary_id: boundary_id,
+              idempotency_key: idempotency_key
+            )
 
             ::MCP::Tool::Response.new([{
               type: "text",

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../store_helpers"
+
 module Llmemory
   module MCP
     module Tools
@@ -20,7 +22,7 @@ module Llmemory
             session = session_id || "default"
             should_clear = clear_session || false
 
-            memory = Llmemory::Memory.new(user_id: user_id, session_id: session)
+            memory = StoreHelpers.build_memory(user_id: user_id, session_id: session)
 
             messages = memory.messages
             if messages.empty?
@@ -33,9 +35,7 @@ module Llmemory
             message_count = messages.size
             memory.consolidate!
 
-            if should_clear
-              memory.clear_session!
-            end
+            memory.clear_session! if should_clear
 
             response_text = "Consolidated #{message_count} messages from session '#{session}' into long-term memory."
             response_text += "\nSession cleared." if should_clear
@@ -44,6 +44,11 @@ module Llmemory
               type: "text",
               text: response_text
             }])
+          rescue Llmemory::GenerativeOperationDisabled => e
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: e.message
+            }], error: true)
           rescue => e
             ::MCP::Tool::Response.new([{
               type: "text",