llmemory 0.2.9 → 0.2.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1758a40a096cf694812a669cb4c92ee6010954b68f733acf8d31083cd8ccaf21
-  data.tar.gz: 9f7c8a4d63c2f71325ef6dc5134fa5895655e1d2fadfe93b64ebbcc2e68224f6
+  metadata.gz: c52d2f218d44057a93d247a535d06a4f4d0877d3ff67fdc48bf9011886ac9199
+  data.tar.gz: 1934ecd2e82c9518cbb9806c297c172fa5d3c2baa2c676da81943646309cf4bc
 SHA512:
-  metadata.gz: f8ef12d0d2294ebc7eca0d1ad4760f92c288fb54c02c41ce88b88c16d8fd459d77364ab3f29388801daaaf4cf1c42d4e972dacfbda69c8433c13dc7ff4f4e5c0
-  data.tar.gz: 7b6bbe90b6b251f11cbc2692eb4f63d3dc57699dbadda16001d171b836a28fd4ac871e1e94742e81bd2b80efff890c13142934c7a210dee790331bad78ef1c37
+  metadata.gz: 5879fda1878fe865b8e9391f36270cbb85b74b41461a06f66e2c86f3c33475fb383f98ae6dc06391764ad9ec65055b97b146908d3b96d39cff39e4971aeb134b
+  data.tar.gz: e7f3f99792aa601b49b6c96f3d960acbf4969b5df6b7341aa8074a46e87ab6a96245752a758902300a8c40b7b2683d5bcc4ba8d0517b978169526647a3d4e64c

data/README.md

@@ -153,6 +153,31 @@ Llmemory.configure do |config|
 end
 ```
 
+## 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/llmemory/configuration.rb

@@ -57,7 +57,9 @@ module Llmemory
                   :encryption_key,
                   :shared_memory_stores,
                   :dashboard_auth,
-                  :dashboard_require_auth
+                  :dashboard_require_auth,
+                  :consolidation_policy,
+                  :retrieval_label_volatile
 
     def initialize
       @llm_provider = :openai
@@ -116,6 +118,12 @@ module Llmemory
       @shared_memory_stores = false
       @dashboard_auth = nil
       @dashboard_require_auth = nil
+      @consolidation_policy = nil
+      @retrieval_label_volatile = false
+    end
+
+    def consolidation_policy
+      @consolidation_policy ||= Consolidation::NullPolicy.new
     end
 
     def dashboard_require_auth?

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

data/lib/llmemory/consolidation.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "consolidation/unit"
+require_relative "consolidation/policy"
+require_relative "consolidation/rule_based_policy"
+require_relative "consolidation/filter"
+
+module Llmemory
+  module Consolidation
+  end
+end

data/lib/llmemory/long_term/file_based/memory.rb

@@ -6,6 +6,7 @@ require_relative "category"
 require_relative "storage"
 require_relative "../../noise_filter"
 require_relative "../../memory_module"
+require_relative "../../consolidation/filter"
 
 module Llmemory
   module LongTerm
@@ -28,19 +29,26 @@ module Llmemory
           resource_id = save_resource(text)
           append_to_daily_log(text) if Llmemory.configuration.daily_logs_enabled && @storage.respond_to?(:save_daily_log_entry)
           items = @extractor.extract_items(text)
-          contents = items.map do |item|
-            item.is_a?(Hash) ? (item["content"] || item[:content]).to_s : item.to_s
-          end
-          classifications = @extractor.classify_items(contents)
+          classifications = @extractor.classify_items(
+            items.map { |item| item.is_a?(Hash) ? (item["content"] || item[:content]).to_s : item.to_s }
+          )
+          items = Consolidation::Filter.apply_items(items, classifications)
           updates_by_category = {}
 
           items.each do |item|
             content = item.is_a?(Hash) ? (item["content"] || item[:content]) : item.to_s
             importance = (item["importance"] || item[:importance] || 0.7).to_f
             cat = classifications[content] || @extractor.classify_item(content)
+            volatile = item[:volatile] == true
             updates_by_category[cat] ||= []
             updates_by_category[cat] << content.to_s
-            save_item(category: cat, item: item, source_resource_id: resource_id, importance: importance)
+            save_item(
+              category: cat,
+              item: item,
+              source_resource_id: resource_id,
+              importance: importance,
+              volatile: volatile
+            )
           end
 
           updates_by_category.each do |category, new_memories|
@@ -70,13 +78,15 @@ module Llmemory
           end
 
           items.first(top_k).each do |i|
+            prov = i[:provenance] || i["provenance"]
             out << {
               id: i[:id] || i["id"],
               text: i[:content] || i["content"],
               timestamp: i[:created_at] || i["created_at"],
               score: 1.0,
               importance: (i[:importance] || i["importance"] || 1.0).to_f,
-              evergreen: i[:evergreen] || i["evergreen"]
+              evergreen: i[:evergreen] || i["evergreen"],
+              volatile: Consolidation::Filter.volatile_marked?(prov)
             }
           end
           resources.first([top_k - out.size, 0].max).each do |r|
@@ -152,11 +162,12 @@ module Llmemory
           @storage.save_resource(@user_id, text)
         end
 
-        def save_item(category:, item:, source_resource_id:, importance: 0.7)
+        def save_item(category:, item:, source_resource_id:, importance: 0.7, volatile: false)
           content = item.is_a?(Hash) ? item["content"] || item[:content] : item.to_s
           provenance = Llmemory::Provenance.from_resource(
             source_resource_id, method: "fact_extraction", confidence: importance
           )
+          provenance = Consolidation::Filter.volatile_provenance(provenance) if volatile
           @storage.save_item(@user_id, category: category, content: content, source_resource_id: source_resource_id, importance: importance, provenance: provenance)
         end
 

data/lib/llmemory/long_term/graph_based/memory.rb

@@ -8,6 +8,7 @@ require_relative "conflict_resolver"
 require_relative "storage"
 require_relative "../../noise_filter"
 require_relative "../../memory_module"
+require_relative "../../consolidation/filter"
 
 module Llmemory
   module LongTerm
@@ -32,6 +33,7 @@ module Llmemory
           return true if text.strip.empty?
 
           entities, relations = extract_graph(text)
+          relations = Consolidation::Filter.apply_relations(relations)
           return true if entities.empty? && relations.empty?
 
           provenance = Llmemory::Provenance.from_text_fingerprint(text, method: "entity_relation_extraction")
@@ -54,7 +56,8 @@ module Llmemory
               text: r[:text],
               timestamp: r[:created_at] || r[:timestamp],
               score: r[:score] || 1.0,
-              importance: r[:importance]
+              importance: r[:importance],
+              volatile: r[:volatile]
             }
           end
         end
@@ -147,8 +150,12 @@ module Llmemory
             object = (r[:object] || r["object"]).to_s.strip
             next if subject.empty? || predicate.empty? || object.empty?
 
-            subject_id = name_to_id[subject] || @kg.add_node(entity_type: "concept", name: subject, properties: { "provenance" => provenance })
-            object_id = name_to_id[object] || @kg.add_node(entity_type: "concept", name: object, properties: { "provenance" => provenance })
+            volatile = r[:volatile] == true
+            relation_provenance = volatile ? Consolidation::Filter.volatile_provenance(provenance) : provenance
+            edge_properties = volatile ? Consolidation::Filter.volatile_properties("provenance" => relation_provenance) : {"provenance" => relation_provenance}
+
+            subject_id = name_to_id[subject] || @kg.add_node(entity_type: "concept", name: subject, properties: { "provenance" => relation_provenance })
+            object_id = name_to_id[object] || @kg.add_node(entity_type: "concept", name: object, properties: { "provenance" => relation_provenance })
 
             existing = @kg.find_edges(
               subject: subject_id,
@@ -164,13 +171,13 @@ module Llmemory
               subject_id: subject_id,
               predicate: predicate,
               target_id: object_id,
-              properties: { "provenance" => provenance },
+              properties: edge_properties,
               created_at: Time.now,
               archived_at: nil
             )
             archived_ids = @conflict_resolver.resolve(edge)
             remove_edge_embeddings(archived_ids)
-            edge_id = @kg.add_edge(subject: subject_id, predicate: predicate, object: object_id, properties: { "provenance" => provenance })
+            edge_id = @kg.add_edge(subject: subject_id, predicate: predicate, object: object_id, properties: edge_properties)
 
             edge_text = "#{subject} #{predicate} #{object}"
             embedding = @vector_store.respond_to?(:embed) ? @vector_store.embed(edge_text) : nil
@@ -197,7 +204,13 @@ module Llmemory
             next unless active_edge?(id)
 
             meta = v[:metadata] || v["metadata"] || {}
-            { id: id, text: meta["text"] || meta[:text] || id.to_s, score: v[:score] || v["score"] || 1.0, created_at: meta["created_at"] || meta[:created_at] }
+            {
+              id: id,
+              text: meta["text"] || meta[:text] || id.to_s,
+              score: v[:score] || v["score"] || 1.0,
+              created_at: meta["created_at"] || meta[:created_at],
+              volatile: volatile_candidate?(edge_properties(id))
+            }
           end
 
           node_ids = out.flat_map { |r| extract_node_ids_from_text(r[:text]) }.compact.uniq
@@ -209,7 +222,7 @@ module Llmemory
               subj = @kg.find_node_by_id(e.subject_id)
               obj = @kg.find_node_by_id(e.target_id)
               edge_text = "#{subj&.name} #{e.predicate} #{obj&.name}"
-              out << { id: e.id, text: edge_text, score: 0.85, created_at: e.created_at } unless out.any? { |o| o[:text] == edge_text }
+              out << { id: e.id, text: edge_text, score: 0.85, created_at: e.created_at, volatile: volatile_candidate?(e.properties) } unless out.any? { |o| o[:text] == edge_text }
             end
           end
 
@@ -222,7 +235,7 @@ module Llmemory
               obj = @kg.find_node_by_id(e.target_id)
               next unless subj && obj
               edge_text = "#{subj.name} #{e.predicate} #{obj.name}"
-              out << { id: e.id, text: edge_text, score: 0.7, created_at: e.created_at }
+              out << { id: e.id, text: edge_text, score: 0.7, created_at: e.created_at, volatile: volatile_candidate?(e.properties) }
             end
           end
 
@@ -278,6 +291,16 @@ module Llmemory
           @kg.find_edges(subject: nil, predicate: nil, object: nil, include_archived: false)
             .any? { |edge| edge.id.to_s == edge_id.to_s }
         end
+
+        def volatile_candidate?(properties_or_provenance)
+          Consolidation::Filter.volatile_marked?(properties_or_provenance)
+        end
+
+        def edge_properties(edge_id)
+          @kg.find_edges(subject: nil, predicate: nil, object: nil, include_archived: false)
+            .find { |edge| edge.id.to_s == edge_id.to_s }
+            &.properties
+        end
       end
     end
   end

data/lib/llmemory/maintenance/policy_prune.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "../consolidation/unit"
+require_relative "../consolidation/filter"
+
+module Llmemory
+  module Maintenance
+    # Archives long-term facts that the current consolidation policy would drop.
+    # Useful for cleaning legacy data consolidated before a policy was configured.
+    class PolicyPrune
+      Result = Struct.new(:graph_edges, :file_items, :dry_run, keyword_init: true) do
+        def total
+          graph_edges + file_items
+        end
+
+        def to_h
+          { graph_edges: graph_edges, file_items: file_items, dry_run: dry_run, total: total }
+        end
+      end
+
+      def initialize(dry_run: false, policy: nil)
+        @dry_run = dry_run
+        @policy = policy || Llmemory.configuration.consolidation_policy
+      end
+
+      def run(memory:)
+        case memory
+        when LongTerm::GraphBased::Memory
+          Result.new(graph_edges: prune_graph(memory), file_items: 0, dry_run: @dry_run)
+        when LongTerm::FileBased::Memory
+          Result.new(graph_edges: 0, file_items: prune_file(memory), dry_run: @dry_run)
+        else
+          raise ArgumentError, "Unsupported memory type: #{memory.class}"
+        end
+      end
+
+      private
+
+      def prune_graph(memory)
+        storage = memory.instance_variable_get(:@graph_storage)
+        kg = memory.instance_variable_get(:@kg)
+        user_id = memory.user_id
+        return 0 unless storage.respond_to?(:list_edges)
+
+        removed = 0
+        storage.list_edges(user_id).each do |edge|
+          next if edge.archived?
+
+          subject = kg.find_node_by_id(edge.subject_id)
+          object = kg.find_node_by_id(edge.target_id)
+          unit = Consolidation::Unit.from_relation(
+            subject: subject&.name,
+            predicate: edge.predicate,
+            object: object&.name
+          )
+          next unless @policy.decide(unit) == :drop
+
+          removed += 1
+          next if @dry_run
+
+          memory.forget(ids: [edge.id], reason: "consolidation_policy_prune")
+        end
+        removed
+      end
+
+      def prune_file(memory)
+        storage = memory.instance_variable_get(:@storage)
+        user_id = memory.user_id
+        removed = 0
+
+        storage.get_all_items(user_id).each do |item|
+          unit = Consolidation::Unit.from_item(item, category: item[:category] || item["category"])
+          next unless @policy.decide(unit) == :drop
+
+          item_id = item[:id] || item["id"]
+          removed += 1
+          next if @dry_run
+
+          memory.forget(ids: [item_id], reason: "consolidation_policy_prune")
+        end
+        removed
+      end
+    end
+  end
+end

data/lib/llmemory/maintenance/search_tokens_backfill.rb

@@ -71,6 +71,10 @@ module Llmemory
       end
 
       def load_active_record_models!
+        require_relative "../long_term/file_based/storages/active_record_storage"
+        require_relative "../long_term/episodic/storages/active_record_storage"
+        require_relative "../long_term/procedural/storages/active_record_storage"
+
         LongTerm::FileBased::Storages::ActiveRecordStorage.load_models!
         LongTerm::Episodic::Storages::ActiveRecordStorage.load_models!
         LongTerm::Procedural::Storages::ActiveRecordStorage.load_models!

data/lib/llmemory/maintenance.rb

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

data/lib/llmemory/retrieval/context_assembler.rb

@@ -14,13 +14,15 @@ module Llmemory
 
         ranked_memories.each do |memory|
           text = memory[:text] || memory["text"] || ""
+          text = label_volatile(text) if volatile_memory?(memory)
           memory_tokens = count_tokens(text)
           break if token_count + memory_tokens > max_tokens
 
           selected << {
             text: text,
             timestamp: memory[:timestamp] || memory["timestamp"],
-            confidence: memory[:temporal_score] || memory[:score] || memory["score"]
+            confidence: memory[:temporal_score] || memory[:score] || memory["score"],
+            volatile: volatile_memory?(memory)
           }
           token_count += memory_tokens
         end
@@ -48,6 +50,20 @@ module Llmemory
         lines << "=== END MEMORIES ==="
         lines.join("\n")
       end
+
+      def volatile_memory?(memory)
+        memory[:volatile] == true || memory["volatile"] == true
+      end
+
+      def label_volatile_enabled?
+        Llmemory.configuration.retrieval_label_volatile
+      end
+
+      def label_volatile(text)
+        return text unless label_volatile_enabled?
+
+        "[verify live] #{text}"
+      end
     end
   end
 end

data/lib/llmemory/version.rb

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

data/lib/llmemory.rb

@@ -3,6 +3,7 @@
 require_relative "llmemory/version"
 require_relative "llmemory/configuration"
 require_relative "llmemory/provenance"
+require_relative "llmemory/consolidation"
 require_relative "llmemory/tokenizer"
 require_relative "llmemory/instrumentation"
 require_relative "llmemory/memory_module"

data/lib/tasks/llmemory.rake

@@ -3,9 +3,9 @@
 namespace :llmemory do
   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_deps = Rake::Task.task_defined?(:environment) ? [:environment] : []
+  task :backfill_search_tokens, [:user_id] do |_t, args|
+    Rake::Task[:environment].invoke if Rake::Task.task_defined?(:environment)
 
-  task :backfill_search_tokens, [:user_id] => task_deps do |_t, args|
     require "llmemory"
     require_relative "../llmemory/maintenance/search_tokens_backfill"
 
@@ -36,4 +36,34 @@ namespace :llmemory do
          "(total=#{summary[:total]})"
     puts "Dry run — no rows written." if dry_run
   end
+
+  desc "Archive long-term facts that the current consolidation policy would drop. " \
+       "Env: DRY_RUN=1 (count only), USER_ID=..., LONG_TERM_TYPE=graph_based|file_based"
+  task :prune_by_policy do
+    Rake::Task[:environment].invoke if Rake::Task.task_defined?(:environment)
+
+    require "llmemory"
+    require_relative "../llmemory/maintenance/policy_prune"
+
+    dry_run = ENV["DRY_RUN"].to_s == "1"
+    user_id = ENV["USER_ID"].presence || "default"
+    long_term_type = (ENV["LONG_TERM_TYPE"].presence || Llmemory.configuration.long_term_type).to_s
+
+    memory = case long_term_type
+    when "graph_based"
+      Llmemory::LongTerm::GraphBased::Memory.new(user_id: user_id)
+    when "file_based"
+      Llmemory::LongTerm::FileBased::Memory.new(user_id: user_id)
+    else
+      abort "Unsupported LONG_TERM_TYPE=#{long_term_type.inspect}"
+    end
+
+    prune = Llmemory::Maintenance::PolicyPrune.new(dry_run: dry_run)
+    result = prune.run(memory: memory)
+
+    puts "Policy prune for user_id=#{user_id} type=#{long_term_type}" \
+         "#{dry_run ? " [DRY RUN]" : ""}"
+    puts "Archived: graph_edges=#{result.graph_edges} file_items=#{result.file_items} " \
+         "(total=#{result.total})"
+  end
 end

data/lib/tasks/release.rake

@@ -14,7 +14,8 @@ module Release
 
   def build_changelog_entry(version, date, notes_body)
     body = notes_body.strip
-    body = body.sub(/\A#+\s*[^\n]*\n+/, "") # drop optional leading markdown title
+    # Drop an optional top-level title only (# / ##), keep ### section headers.
+    body = body.sub(/\A(?:#|##)\s+[^\n]*\n+/, "")
 
     <<~ENTRY
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llmemory
 version: !ruby/object:Gem::Version
-  version: 0.2.9
+  version: 0.2.11
 platform: ruby
 authors:
 - llmemory
@@ -149,6 +149,11 @@ files:
 - lib/llmemory/cli/commands/users.rb
 - lib/llmemory/cli/commands/working.rb
 - lib/llmemory/configuration.rb
+- lib/llmemory/consolidation.rb
+- lib/llmemory/consolidation/filter.rb
+- lib/llmemory/consolidation/policy.rb
+- lib/llmemory/consolidation/rule_based_policy.rb
+- lib/llmemory/consolidation/unit.rb
 - lib/llmemory/crypto/cipher.rb
 - lib/llmemory/crypto/field_helpers.rb
 - lib/llmemory/dashboard.rb
@@ -216,6 +221,7 @@ files:
 - lib/llmemory/maintenance.rb
 - lib/llmemory/maintenance/cognitive_pass.rb
 - lib/llmemory/maintenance/consolidator.rb
+- lib/llmemory/maintenance/policy_prune.rb
 - lib/llmemory/maintenance/reindexer.rb
 - lib/llmemory/maintenance/runner.rb
 - lib/llmemory/maintenance/search_tokens_backfill.rb