llmemory 0.2.10 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cc4e7d547ef03649a17696bda31fd75bf9ac2062f70bde092e9e2fd0f084c3e
-  data.tar.gz: 4468f29da8808641c04145637876909e75a077fb3b5186b47b8e488354cb8d5b
+  metadata.gz: 004e6d5f30c9eba38319382257934d0644635fd63555e854043f32d7ec4aa7b0
+  data.tar.gz: 9295714e79963b31a2c23eb6834a4c31b75c2d83a044ecce905726c5ad8a41b1
 SHA512:
-  metadata.gz: 01372cdc24c73fff3ec18862d52a7a7c7cca43de954ab785693e2473a5bd420b3f5354ec816e40c0f80f561d4b9ef0db3bb5e9851bb3c6d3cac2515aebf880a3
-  data.tar.gz: a68cc51d1779de9bc4f21b304670e253c3d254d4a3eb1fb2577ba790aca66acd9587b7eda1f22847fea422fe12f0ac08e60069d717e1892c6a1564cb4c61ad3c
+  metadata.gz: e56b9d1b8a537b1a134be39cc9e0f563eed3f7e20f0cef23bb8dc12aa7881c30512382e027ed5926f507faf09ee2ca691fc2c489fd16bdbf1e1562c7e5e74ca2
+  data.tar.gz: a34a15a7eab1202fe44ebcf85e828c81d99941b1102f88242b8efada40884328a22369dd7860f27449401bd8a123c80cdf02305c9d19b5a0215f1a30ebcd6f31

data/README.md

@@ -153,6 +153,54 @@ 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).
+
+```ruby
+Llmemory.configure do |config|
+  config.consolidation_policy = Llmemory::Consolidation::RuleBasedPolicy.new(
+    drop_predicates: %w[current_job works_at job_title plan_status has_task],
+    drop_categories: %w[work_life]
+  )
+
+  # Optional: prefix volatile memories at retrieval time with "[verify live]"
+  config.retrieval_label_volatile = true
+end
+```
+
+Policy decisions per extracted unit: `:keep` (default), `:drop` (not persisted), or `:volatile` (persisted with a volatile marker in provenance/properties).
+
+To clean **legacy** data consolidated before a policy was enabled:
+
+```bash
+USER_ID=user_123 LONG_TERM_TYPE=graph_based bundle exec rake llmemory:prune_by_policy
+DRY_RUN=1 bundle exec rake llmemory:prune_by_policy
+```
+
 ## Encryption at rest
 
 Optional AES-256-GCM encryption protects persisted memory. Without the key, stored data is unreadable — useful for isolating agents or tenants.

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

@@ -57,7 +57,28 @@ module Llmemory
                   :encryption_key,
                   :shared_memory_stores,
                   :dashboard_auth,
-                  :dashboard_require_auth
+                  :dashboard_require_auth,
+                  :consolidation_policy,
+                  :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
@@ -116,6 +137,50 @@ module Llmemory
       @shared_memory_stores = false
       @dashboard_auth = nil
       @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
+      @consolidation_policy ||= Consolidation::NullPolicy.new
     end
 
     def dashboard_require_auth?
@@ -138,6 +203,7 @@ module Llmemory
 
     def configure
       yield configuration
+      configuration.validate!
     end
 
     def reset_configuration!

data/lib/llmemory/consolidation/filter.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Consolidation
+    module Filter
+      VOLATILE_PROPERTY = "consolidation_volatile"
+      VOLATILE_PROVENANCE_FLAG = "volatile"
+
+      module_function
+
+      def policy
+        Llmemory.configuration.consolidation_policy || NullPolicy.new
+      end
+
+      # @return [Array<Hash>] relations with :volatile key
+      def apply_relations(relations)
+        Array(relations).filter_map do |relation|
+          next unless relation.is_a?(Hash)
+
+          unit = Unit.from_relation(relation)
+          case policy.decide(unit)
+          when :drop
+            next
+          when :volatile
+            relation.merge(volatile: true)
+          else
+            relation.merge(volatile: false)
+          end
+        end
+      end
+
+      # @return [Array<Hash>] item hashes with :volatile key
+      def apply_items(items, classifications = {})
+        Array(items).filter_map do |item|
+          content = item.is_a?(Hash) ? (item["content"] || item[:content]).to_s : item.to_s
+          category = classifications[content] || classifications[content.to_sym]
+          unit = Unit.from_item(item, category: category)
+
+          case policy.decide(unit)
+          when :drop
+            next
+          when :volatile
+            item_hash = item.is_a?(Hash) ? item.dup : {"content" => content}
+            item_hash.merge(volatile: true)
+          else
+            item_hash = item.is_a?(Hash) ? item.dup : {"content" => content}
+            item_hash.merge(volatile: false)
+          end
+        end
+      end
+
+      def volatile_provenance(base_provenance)
+        prov = base_provenance.is_a?(Hash) ? base_provenance.dup : {}
+        prov[:consolidation] = VOLATILE_PROVENANCE_FLAG
+        prov["consolidation"] = VOLATILE_PROVENANCE_FLAG unless prov.key?(:consolidation)
+        prov
+      end
+
+      def volatile_properties(base_properties)
+        props = base_properties.is_a?(Hash) ? base_properties.dup : {}
+        props[VOLATILE_PROPERTY] = true
+        props
+      end
+
+      def volatile_marked?(properties_or_provenance)
+        hash = properties_or_provenance || {}
+        hash[VOLATILE_PROPERTY] == true ||
+          hash["consolidation_volatile"] == true ||
+          hash[:consolidation] == VOLATILE_PROVENANCE_FLAG ||
+          hash["consolidation"] == VOLATILE_PROVENANCE_FLAG
+      end
+    end
+  end
+end

data/lib/llmemory/consolidation/policy.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Consolidation
+    # Base policy: all extracted units are kept in long-term memory.
+    class Policy
+      DECISIONS = %i[keep drop volatile].freeze
+
+      def decide(_unit)
+        :keep
+      end
+    end
+
+    class NullPolicy < Policy
+    end
+  end
+end

data/lib/llmemory/consolidation/rule_based_policy.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Consolidation
+    # Rule-based consolidation policy for agents with authoritative live data sources
+    # (tools, DB snapshots). Drops or marks volatile facts that should not be treated
+    # as stable long-term memory.
+    #
+    # Precedence (first match wins):
+    #   1. drop_if callable
+    #   2. volatile_if callable
+    #   3. drop_predicates (graph relations)
+    #   4. volatile_predicates (graph relations)
+    #   5. drop_categories (file-based items)
+    #   6. volatile_categories (file-based items)
+    #   7. :keep
+    class RuleBasedPolicy < Policy
+      def initialize(
+        drop_predicates: [],
+        volatile_predicates: [],
+        drop_categories: [],
+        volatile_categories: [],
+        drop_if: nil,
+        volatile_if: nil
+      )
+        @drop_predicates = normalize_list(drop_predicates)
+        @volatile_predicates = normalize_list(volatile_predicates)
+        @drop_categories = normalize_list(drop_categories)
+        @volatile_categories = normalize_list(volatile_categories)
+        @drop_if = drop_if
+        @volatile_if = volatile_if
+      end
+
+      def decide(unit)
+        return :drop if callable_true?(@drop_if, unit)
+        return :volatile if callable_true?(@volatile_if, unit)
+
+        case unit.kind
+        when :relation
+          predicate = Unit.normalize_predicate(unit.predicate)
+          return :drop if @drop_predicates.include?(predicate)
+          return :volatile if @volatile_predicates.include?(predicate)
+        when :item
+          category = Unit.normalize_category(unit.category)
+          return :drop if @drop_categories.include?(category)
+          return :volatile if @volatile_categories.include?(category)
+        end
+
+        :keep
+      end
+
+      private
+
+      def normalize_list(values)
+        Array(values).map { |value| value.to_s.strip.downcase.gsub(/\s+/, "_") }.reject(&:empty?)
+      end
+
+      def callable_true?(callable, unit)
+        callable.respond_to?(:call) && callable.call(unit) == true
+      end
+    end
+  end
+end

data/lib/llmemory/consolidation/unit.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Consolidation
+    # Normalized fact unit passed to Consolidation::Policy.
+    # kind: :relation (graph) | :item (file-based)
+    Unit = Data.define(:kind, :subject, :predicate, :object, :content, :category, :importance) do
+      def self.from_relation(relation)
+        new(
+          kind: :relation,
+          subject: normalize_string(relation[:subject] || relation["subject"]),
+          predicate: normalize_predicate(relation[:predicate] || relation["predicate"]),
+          object: normalize_string(relation[:object] || relation["object"]),
+          content: nil,
+          category: nil,
+          importance: nil
+        )
+      end
+
+      def self.from_item(item, category: nil)
+        content = if item.is_a?(Hash)
+          (item["content"] || item[:content]).to_s
+        else
+          item.to_s
+        end
+        importance = if item.is_a?(Hash)
+          item["importance"] || item[:importance]
+        end
+
+        new(
+          kind: :item,
+          subject: nil,
+          predicate: nil,
+          object: nil,
+          content: content,
+          category: normalize_category(category),
+          importance: importance
+        )
+      end
+
+      def self.normalize_predicate(value)
+        normalize_string(value).downcase.gsub(/\s+/, "_")
+      end
+
+      def self.normalize_category(value)
+        normalize_string(value).downcase.gsub(/\s+/, "_")
+      end
+
+      def self.normalize_string(value)
+        value.to_s.strip
+      end
+    end
+  end
+end