engram 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2d96222b1c43e68da7da579a6b9d1d39f85f5cbe2480be6cd39a19dcf36adc6
-  data.tar.gz: 53bc4261b347e498d20ea4171164b9478c55134067c33715641017b7572c78a7
+  metadata.gz: b3d370df000e9c12a40df932919f0859d9eb7623270ed5aeaa781747f239d865
+  data.tar.gz: 2c49fd3e8126a510f49b711a9ccf9d159ac01b6e540ef2ab168e7e51fa6509f3
 SHA512:
-  metadata.gz: a8001a49d7c280ded764b75e2f62695f3eeaf229e114e5455ee9bfa32f58d0c2a94fd9d70a1b563e246da0efcb570fe5f95ca6ecd61e69ca3cad758a0491abae
-  data.tar.gz: 29d1e339241f3edb54485925f20b78f81740770fc966c8e838cefaef839e191597080249f578f33c8f79c5eb2cc89563b0187cf897b296ab660ff4510a3b0d4d
+  metadata.gz: 161c8e9c199352d663e0ce670f3a6dc76ac98aba0b429566a1c3c96fa8ee5c7db260a449355f449b11dfdb25de4b85f207ca263fcffa6a76248d1269632ecddc
+  data.tar.gz: 1c3867577e6a86128fa4a4036b64cc2790754336c4cc462495284f25f5a7ac63ac56be24694ffb9578d2b50999bde325ca4ced68b6d8e0aed9143234108b0888

data/CHANGELOG.md

@@ -5,6 +5,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-09-15
+
+### Added
+
+- Optional `expires_at` on memories. Expired records are excluded from search and injection while remaining available for inspection and deletion.
+- `engram:expiry` generator for existing Rails apps, with a concurrent index for scoped expiry queries.
+- Scoped `forget_expired` cleanup with batching, dry runs, and a Rails task. Deletion rechecks the deadline so concurrent expiry extensions are preserved.
+
 ## [0.7.0] - 2026-09-13
 
 ### Added

data/README.md

@@ -76,7 +76,7 @@ explicitly version-gated:
 - Core types and facade: `Engram::Memory`, `Engram::Record`, `Engram::Decision`, `Engram::PersistencePolicy`, and `Engram.with_memory`.
 - Store and adapter ports: `Engram::Ports::MemoryStore`, `Engram::Ports::Embedder`, `Engram::Ports::Completion`.
 - Rails integration points: `has_memory`, `Memory#observe_later`, and generator outputs under `engram:` rake tasks.
-- Lifecycle methods in `Engram::Memory`: `add`, `recall`, `inject_into`, `observe`, `observe_later`, `forget`, `forget_stale`, `rebuild_embeddings`, and `memories_from_source`.
+- Lifecycle methods in `Engram::Memory`: `add`, `recall`, `inject_into`, `observe`, `observe_later`, `forget`, `forget_stale`, `forget_expired`, `rebuild_embeddings`, and `memories_from_source`.
 - RubyLLM adapter contract points and evaluator entrypoints (`rake eval`, `rake eval:real`).
 
 ### Backward-compatibility commitments (pre-1.0)
@@ -228,7 +228,7 @@ end
 ### Filtered vector search
 
 Keep the generated B-tree index on `scope`. With an approximate vector index, pgvector
-applies scope and kind filters after the index scan. This can return fewer than `limit`
+applies scope, kind, and expiry filters after the index scan. This can return fewer than `limit`
 memories even when enough matching rows exist.
 
 On pgvector 0.8.0+, HNSW iterative scans can search further:
@@ -553,6 +553,67 @@ Both settings default to nil. Pass nil explicitly to override a configured value
 the cap. `limit: 0` skips embedding and search; `max_bytes: 0` skips recall during injection.
 Invalid values raise `ArgumentError`.
 
+### Memory expiry
+
+Set a deadline for temporary memories:
+
+```ruby
+user.memory.add("Trial access is active", expires_at: 7.days.from_now)
+```
+
+`expires_at` accepts a Time (including Rails time-zone values) or nil. Nil is the default
+and never expires. A memory is expired at `expires_at <= Time.now`. Both built-in stores
+exclude expired records before the search limit, so they no longer participate in recall
+or consolidation. Injection checks expiry again when rendering.
+
+Expiry does not delete rows. `memory.all` still returns them, and `memory.forget(id:)` can
+delete them. A new observation may recreate the same fact from retained source data.
+Custom extractors or `before_persist` can set expiry with `record.with(expires_at: deadline)`;
+Engram does not infer deadlines from conversation text. Store updates replace expiry with
+the supplied record's value, including nil.
+
+New Rails installs include the expiry column and index. For a table created by 0.7.0 or
+earlier, generate and run the upgrade migration:
+
+```sh
+bin/rails generate engram:expiry
+bin/rails db:migrate
+```
+
+The migration adds a nullable datetime column and builds a partial index on scope and
+expiry concurrently. Existing rows keep their data and do not expire. Reads and
+non-expiring writes continue to work before migration; expiring writes raise an error
+instead of losing the deadline. Restart app processes after migrating so ActiveRecord
+refreshes its cached schema. If you use a custom table, adjust the generated migration.
+
+Custom stores must persist `expires_at` and exclude expired records before limiting search
+results. Recall also discards any expired records a custom store returns, but cannot fill
+the gaps left by a store that filters after its limit.
+
+To remove expired rows, preview the count, then run cleanup:
+
+```ruby
+user.memory.forget_expired(dry_run: true)
+# => {matched: 12, deleted: 0, dry_run: true}
+user.memory.forget_expired(batch_size: 500)
+# => {matched: 12, deleted: 12, dry_run: false}
+```
+
+The Rails task requires a scope:
+
+```sh
+DRY_RUN=true BATCH_SIZE=500 bin/rails 'engram:forget_expired[user:42]'
+BATCH_SIZE=500 bin/rails 'engram:forget_expired[user:42]'
+```
+
+Cleanup uses one cutoff for the run and reads only IDs in batches. It rechecks scope and
+expiry when deleting, so a concurrent extension or removal of the deadline is preserved.
+`matched` can exceed `deleted` if records change during the run; dry-run counts are advisory.
+Like `forget(id:)`, this is explicit deletion and bypasses persistence hooks and policies.
+Errors stop the run; completed batches stay deleted and a retry can process the remainder.
+Custom stores need the optional `expired_ids` and `delete_expired` methods for cleanup.
+The `forget_expired.engram` event reports counts without memory content or IDs.
+
 ### Observation and maintenance
 
 Observation uses a scope-and-turn claim before extraction. While a claim lease is live and
@@ -640,6 +701,7 @@ main memory pipeline:
 
 - `add.engram`
 - `forget.engram`
+- `forget_expired.engram`
 - `recall.engram`
 - `inject.engram`
 - `observe.engram`
@@ -785,6 +847,7 @@ gem unpack engram-*.gem --target /tmp/engram-package-check
 - v0.5 (done): embedding provenance and scoped embedding rebuild operations.
 - v0.6 (done): structured provenance, source impact lookup, and grounding reports.
 - v0.7 (done): recall thresholds, injection limits, scoped deletion, and RubyLLM streaming fixes.
+- v0.8 (done): explicit memory expiry, Rails upgrade migration, and scoped cleanup with dry runs.
 - later: additional storage backends and larger real-provider eval benchmarks.
 
 ## License

data/lib/engram/adapters/in_memory_store.rb

@@ -10,23 +10,26 @@ module Engram
       def initialize
         @records = {}
         @sequence = 0
+        @mutex = Mutex.new
       end
 
       def add(record)
         validate_scope!(record.scope)
 
-        record.id = (@sequence += 1)
-        @records[record.id] = record
-        record
+        @mutex.synchronize do
+          record.id = (@sequence += 1)
+          @records[record.id] = record
+          record
+        end
       end
 
       def search(embedding:, scope:, limit:, kinds: nil, embedding_metadata: nil)
         Engram::EmbeddingMetadata.validate_query!(embedding, embedding_metadata)
         allowed_kinds = normalize_kinds(kinds)
+        now = Time.now
 
-        results = @records
-          .values
-          .select { |r| searchable?(r, scope, allowed_kinds) }
+        results = @mutex.synchronize { @records.values }
+          .select { |r| searchable?(r, scope, allowed_kinds) && !r.expired?(at: now) }
           .map { |r| [r, Engram::Math.cosine_similarity(embedding, r.embedding)] }
           .sort_by { |(_, score)| -score }
           .first(limit)
@@ -37,7 +40,7 @@ module Engram
       end
 
       def all(scope:, limit: nil, offset: 0, after_id: nil)
-        records = @records.values.select { |r| r.scope == scope }.sort_by { |record| record.id }
+        records = @mutex.synchronize { @records.values }.select { |r| r.scope == scope }.sort_by { |record| record.id }
         records = records.drop_while { |record| !after_id.nil? && record.id && record.id <= after_id }
         records = records.drop(offset) if offset > 0
         records = records.take(limit) if limit
@@ -45,36 +48,65 @@ module Engram
       end
 
       def existing_ids(scope:, ids:)
-        ids.uniq.select { |id| @records[id]&.scope == scope }
+        @mutex.synchronize { ids.uniq.select { |id| @records[id]&.scope == scope } }
       end
 
       def update(scope:, id:, record:)
-        existing = @records[id]
-        raise Engram::Error, "no memory with id #{id.inspect} in scope #{scope.inspect}" unless existing&.scope == scope
-        raise Engram::Error, "cannot move memory across scopes" unless record.scope == scope
-
-        record.id = id
-        @records[id] = record
+        @mutex.synchronize do
+          existing = @records[id]
+          raise Engram::Error, "no memory with id #{id.inspect} in scope #{scope.inspect}" unless existing&.scope == scope
+          raise Engram::Error, "cannot move memory across scopes" unless record.scope == scope
+
+          record.id = id
+          @records[id] = record
+        end
       end
 
       def delete(scope:, id:)
-        return 0 unless @records[id]&.scope == scope
+        @mutex.synchronize do
+          return 0 unless @records[id]&.scope == scope
 
-        @records.delete(id)
-        1
+          @records.delete(id)
+          1
+        end
       end
 
       def touch(scope:, id:, at: Time.now)
-        record = @records[id]
-        return 0 unless record&.scope == scope
+        @mutex.synchronize do
+          record = @records[id]
+          return 0 unless record&.scope == scope
+
+          record.last_accessed_at = at
+          1
+        end
+      end
 
-        record.last_accessed_at = at
-        1
+      def expired_ids(scope:, at:, limit:, after_id: nil)
+        # IDs follow insertion order; the hash retains it across updates/deletes.
+        @mutex.synchronize do
+          @records.each_value.lazy
+            .select { |record| record.scope == scope && (after_id.nil? || record.id > after_id) && record.expired?(at: at) }
+            .map(&:id).take(limit).force
+        end
+      end
+
+      def delete_expired(scope:, ids:, at:)
+        @mutex.synchronize do
+          ids.uniq.count do |id|
+            record = @records[id]
+            next false unless record&.scope == scope && record.expired?(at: at)
+
+            @records.delete(id)
+            true
+          end
+        end
       end
 
       def clear
-        @records.clear
-        @sequence = 0
+        @mutex.synchronize do
+          @records.clear
+          @sequence = 0
+        end
       end
 
       private

data/lib/engram/adapters/pgvector_store.rb

@@ -18,6 +18,7 @@ module Engram
         validate_scope!(record.scope)
 
         row = model.create!(
+          **expiry_attributes(record),
           content: record.content,
           scope: record.scope,
           kind: record.kind.to_s,
@@ -31,6 +32,10 @@ module Engram
       def search(embedding:, scope:, limit:, kinds: nil, embedding_metadata: nil)
         Engram::EmbeddingMetadata.validate_query!(embedding, embedding_metadata)
         query = model.where(scope: scope)
+        if expiry_column?
+          expiry = model.arel_table[:expires_at]
+          query = query.where(expiry.eq(nil).or(expiry.gt(Time.now)))
+        end
         normalized_kinds = normalize_kinds(kinds)
         query = query.where(kind: normalized_kinds) if normalized_kinds
 
@@ -70,6 +75,7 @@ module Engram
         model.transaction do
           row = model.lock.find_by!(id: id, scope: scope)
           row.update!(
+            **expiry_attributes(record),
             content: record.content,
             kind: record.kind.to_s,
             importance: record.importance,
@@ -90,8 +96,37 @@ module Engram
         model.where(id: id, scope: scope).update_all(last_accessed_at: at)
       end
 
+      def expired_ids(scope:, at:, limit:, after_id: nil)
+        return [] unless expiry_column?
+
+        query = expired_scope(scope, at)
+        query = query.where(model.arel_table[:id].gt(after_id)) unless after_id.nil?
+        query.order(:id).limit(limit).pluck(:id)
+      end
+
+      def delete_expired(scope:, ids:, at:)
+        return 0 if ids.empty? || !expiry_column?
+
+        expired_scope(scope, at).where(id: ids).delete_all
+      end
+
       private
 
+      def expired_scope(scope, at)
+        model.where(scope: scope).where(model.arel_table[:expires_at].lteq(at))
+      end
+
+      def expiry_column?
+        model.column_names.include?("expires_at")
+      end
+
+      def expiry_attributes(record)
+        return {expires_at: record.expires_at} if expiry_column?
+        return {} if record.expires_at.nil?
+
+        raise Engram::Error, "PgvectorStore needs a nullable expires_at datetime column to store expiring memories"
+      end
+
       def validate_scope!(scope)
         raise Engram::Error, "memory scope cannot be nil" if scope.nil?
       end
@@ -124,7 +159,8 @@ module Engram
           importance: row.importance || 1.0,
           metadata: row.metadata || {},
           created_at: row.created_at,
-          last_accessed_at: row.try(:last_accessed_at)
+          last_accessed_at: row.try(:last_accessed_at),
+          expires_at: row.try(:expires_at)
         )
       end
 

data/lib/engram/internal/candidate_integrity.rb

@@ -29,7 +29,8 @@ module Engram
         kind: [Symbol],
         importance: [Integer, Float],
         created_at: [Time],
-        last_accessed_at: [NilClass, Time]
+        last_accessed_at: [NilClass, Time],
+        expires_at: [NilClass, Time]
       }.freeze
 
       Snapshot = Struct.new(:collection, :collection_state, :records)

data/lib/engram/memory.rb

@@ -14,18 +14,17 @@ module Engram
 
     # Persist a memory record of the given kind. Returns nil when the configured
     # persistence policy rejects the record.
-    def add(content, kind: :fact, importance: 1.0, metadata: {})
+    def add(content, kind: :fact, importance: 1.0, metadata: {}, expires_at: nil)
       Engram::Instrumentation.instrument("add", Engram::Instrumentation.payload(scope: scope, store: @store, kind: kind)) do
-        embedding = @embedder.embed(content)
         record = Record.new(
           content: content,
           scope: scope,
-          embedding: embedding,
           kind: kind,
           importance: importance,
-          metadata: metadata
+          metadata: metadata,
+          expires_at: expires_at
         )
-        persist(record)
+        persist(record.with(embedding: @embedder.embed(content)))
       end
     end
 
@@ -119,6 +118,13 @@ module Engram
         .call(scope: scope, older_than: older_than, min_importance: min_importance)
     end
 
+    # Delete expired records without loading their content or embeddings.
+    # Returns matched/deleted counts; dry runs only count eligible records.
+    def forget_expired(batch_size: 100, dry_run: false)
+      UseCases::ForgetExpired.new(store: @store)
+        .call(scope: scope, batch_size: batch_size, dry_run: dry_run)
+    end
+
     # Return the memories in this scope whose provenance references the exact host
     # source. `source_id` and `source_type` must each be non-blank Strings and are
     # matched exactly, without normalization. Source IDs are references, not an

data/lib/engram/ports/memory_store.rb

@@ -12,12 +12,13 @@ module Engram
 
       # Return up to `limit` Records in `scope` nearest to `embedding`,
       # ordered most-relevant first. When `kinds` is provided, only records with
-      # those canonical memory kinds are eligible.
+      # those canonical memory kinds are eligible. Exclude expired records before
+      # ordering and limiting; expires_at <= Time.now is expired, nil never expires.
       def search(embedding:, scope:, limit:, kinds: nil, embedding_metadata: nil)
         raise NotImplementedError, "#{self.class} must implement #search"
       end
 
-      # All Records for a scope (mostly for inspection/tests).
+      # All Records for a scope, including expired records (inspection/maintenance).
       # Supports optional `limit` and `offset` for batching large sweeps.
       # Returned records are sorted in stable `id` order when batching is used.
       # Use `after_id` for keyset pagination.
@@ -49,6 +50,19 @@ module Engram
         raise NotImplementedError, "#{self.class} must implement #delete"
       end
 
+      # Optional expiry maintenance: up to `limit` IDs with expires_at <= at,
+      # ordered by ID, strictly after after_id. Never includes nil expiry.
+      def expired_ids(scope:, at:, limit:, after_id: nil)
+        raise NotImplementedError, "#{self.class} does not implement #expired_ids"
+      end
+
+      # Optional expiry maintenance: delete only the requested IDs in scope that
+      # are still expired at the same cutoff. Recheck expiry atomically at deletion
+      # so a concurrent deadline extension is preserved. Returns the deleted count.
+      def delete_expired(scope:, ids:, at:)
+        raise NotImplementedError, "#{self.class} does not implement #delete_expired"
+      end
+
       # Update the last-accessed timestamp of a memory. Used by recency-aware recall.
       # Returns the number of affected rows: 1 when touched, 0 when the scoped record
       # does not exist.

data/lib/engram/rails/tasks.rake

@@ -3,6 +3,21 @@
 # Loaded by the Railtie in Rails apps (where :environment boots the app and its
 # initializers) and by the gem's own Rakefile (which defines a no-op :environment).
 namespace :engram do
+  desc "Delete expired memories in a scope. Usage: bundle exec rake 'engram:forget_expired[user:1]'"
+  task :forget_expired, [:scope] => :environment do |_, args|
+    scope = args[:scope]
+    raise ArgumentError, "forget_expired requires a scope argument" if scope.to_s.empty?
+
+    dry_run = case ENV.fetch("DRY_RUN", "false").downcase
+    when "true", "1", "yes" then true
+    when "false", "0", "no" then false
+    else raise ArgumentError, "DRY_RUN must be true or false"
+    end
+    batch_size = Integer(ENV.fetch("BATCH_SIZE", "100"))
+    result = Engram::Memory.new(scope: scope).forget_expired(batch_size: batch_size, dry_run: dry_run)
+    puts "matched=#{result[:matched]} deleted=#{result[:deleted]} dry_run=#{result[:dry_run]}"
+  end
+
   desc "Rebuild embeddings in a memory scope. Usage: bundle exec rake 'engram:rebuild_embeddings[user:1]'"
   task :rebuild_embeddings, [:scope] => :environment do |_, args|
     scope = args[:scope]

data/lib/engram/record.rb

@@ -9,15 +9,18 @@ module Engram
   # `semantic` kind is normalized to `fact` for compatibility with pre-1.0 records.
   class Record
     STATE_READERS = %i[
-      id content scope embedding kind importance metadata created_at last_accessed_at
+      id content scope embedding kind importance metadata created_at last_accessed_at expires_at
     ].freeze
 
     attr_accessor :id, :last_accessed_at
     attr_reader :content, :embedding, :scope, :kind, :importance, :metadata,
-      :created_at
+      :created_at, :expires_at
 
     def initialize(content:, scope:, id: nil, embedding: nil, kind: :fact,
-      importance: 1.0, metadata: {}, created_at: nil, last_accessed_at: nil)
+      importance: 1.0, metadata: {}, created_at: nil, last_accessed_at: nil, expires_at: nil)
+      unless expires_at.nil? || expires_at.is_a?(Time)
+        raise ArgumentError, "expires_at must be a Time or nil"
+      end
       @id = id
       @content = content
       @scope = scope
@@ -27,12 +30,17 @@ module Engram
       @metadata = metadata
       @created_at = created_at || Time.now
       @last_accessed_at = last_accessed_at
+      @expires_at = expires_at&.getutc
     end
 
     def with(**attributes)
       self.class.new(**to_h.merge(attributes))
     end
 
+    def expired?(at: Time.now)
+      !expires_at.nil? && expires_at <= at
+    end
+
     # Return structured supporting-source metadata when this record carries a
     # provenance schema understood by the installed Engram version.
     # Legacy, malformed, and future-schema records remain readable and return nil.

data/lib/engram/use_cases/forget_expired.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Engram
+  module UseCases
+    # Deletes expired memories in bounded batches using one cutoff for the whole run.
+    class ForgetExpired
+      def initialize(store:)
+        @store = store
+      end
+
+      def call(scope:, batch_size: 100, dry_run: false, now: Time.now)
+        unless batch_size.is_a?(Integer) && batch_size.positive?
+          raise ArgumentError, "batch_size must be a positive integer"
+        end
+        unless dry_run.equal?(true) || dry_run.equal?(false)
+          raise ArgumentError, "dry_run must be true or false"
+        end
+        unless @store.respond_to?(:expired_ids) && @store.respond_to?(:delete_expired)
+          raise Engram::Error, "forget_expired requires a store implementing expired_ids and delete_expired"
+        end
+
+        counts = {matched: 0, deleted: 0, dry_run: dry_run}
+        payload = Engram::Instrumentation.payload(scope: scope, store: @store, **counts)
+        Engram::Instrumentation.instrument("forget_expired", payload) do
+          after_id = nil
+          loop do
+            ids = @store.expired_ids(scope: scope, at: now, limit: batch_size, after_id: after_id)
+            break if ids.empty?
+            raise Engram::Error, "expired_ids must advance its cursor" if ids.last == after_id
+
+            counts[:matched] += ids.length
+            counts[:deleted] += @store.delete_expired(scope: scope, ids: ids, at: now) unless dry_run
+            payload.merge!(counts)
+            after_id = ids.last
+          end
+          counts
+        end
+      rescue NotImplementedError
+        raise Engram::Error, "forget_expired requires a store implementing expired_ids and delete_expired"
+      end
+    end
+  end
+end

data/lib/engram/use_cases/inject.rb

@@ -31,7 +31,10 @@ module Engram
           suffix = "\n</engram-memories>"
           bytes = prefix.bytesize + suffix.bytesize
           lines = []
+          now = Time.now
           memories.each do |memory|
+            next if memory.expired?(at: now)
+
             line = render_memory(memory)
             added_bytes = line.bytesize + (lines.empty? ? 0 : 1)
             next if max_bytes && bytes + added_bytes > max_bytes

data/lib/engram/use_cases/recall.rb

@@ -57,10 +57,10 @@ module Engram
             kinds: kinds
           )
 
-          candidates = if min_similarity.nil?
-            pool
-          else
-            pool.select { |record| meets_similarity?(record.embedding, embedding, min_similarity) }
+          now = Time.now
+          candidates = pool.select do |record|
+            !record.expired?(at: now) &&
+              (min_similarity.nil? || meets_similarity?(record.embedding, embedding, min_similarity))
           end
           results = (reranking? ? rerank(candidates, embedding) : candidates).first(limit)
           touch(results, scope) if @touch

data/lib/engram/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Engram
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/engram.rb

@@ -31,6 +31,7 @@ require_relative "engram/use_cases/recall"
 require_relative "engram/use_cases/inject"
 require_relative "engram/use_cases/observe"
 require_relative "engram/use_cases/forget"
+require_relative "engram/use_cases/forget_expired"
 require_relative "engram/use_cases/rebuild_embeddings"
 require_relative "engram/use_cases/source_impact"
 require_relative "engram/use_cases/grounding_report"

data/lib/generators/engram/expiry_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Engram
+  module Generators
+    # Adds expiry to a table created by Engram 0.7 or earlier.
+    class ExpiryGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def create_migration_file
+        migration_template "add_expiry_to_engram_memories.rb.tt",
+          "db/migrate/add_expiry_to_engram_memories.rb"
+      end
+
+      def self.next_migration_number(dir)
+        ::ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      private
+
+      def migration_version
+        "#{::ActiveRecord::VERSION::MAJOR}.#{::ActiveRecord::VERSION::MINOR}"
+      end
+    end
+  end
+end

data/lib/generators/engram/templates/add_expiry_to_engram_memories.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class AddExpiryToEngramMemories < ActiveRecord::Migration[<%= migration_version %>]
+  disable_ddl_transaction!
+
+  def change
+    add_column :engram_memories, :expires_at, :datetime
+    add_index :engram_memories, [:scope, :expires_at],
+      name: "index_engram_memories_on_scope_and_expiry",
+      where: "expires_at IS NOT NULL", algorithm: :concurrently
+  end
+end

data/lib/generators/engram/templates/create_engram_memories.rb.tt

@@ -12,11 +12,15 @@ class CreateEngramMemories < ActiveRecord::Migration[<%= migration_version %>]
       t.jsonb :metadata, null: false, default: {}
       t.vector :embedding, limit: <%= dimensions %>
       t.datetime :last_accessed_at
+      t.datetime :expires_at
 
       t.timestamps
     end
 
     add_index :engram_memories, :scope
+    add_index :engram_memories, [:scope, :expires_at],
+      name: "index_engram_memories_on_scope_and_expiry",
+      where: "expires_at IS NOT NULL"
 
     # For larger datasets, choose one approximate vector index after backfilling data.
     # HNSW is a strong default for read-heavy recall workloads with frequent inserts.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: engram
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Alexandr Kholodniak
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-13 00:00:00.000000000 Z
+date: 2026-09-15 00:00:00.000000000 Z
 dependencies: []
 description: |
   Engram gives AI agents durable, long-term memory. It recalls relevant facts about a
@@ -65,6 +65,7 @@ files:
 - lib/engram/reserved_metadata.rb
 - lib/engram/turn_digest.rb
 - lib/engram/use_cases/forget.rb
+- lib/engram/use_cases/forget_expired.rb
 - lib/engram/use_cases/grounding_report.rb
 - lib/engram/use_cases/inject.rb
 - lib/engram/use_cases/observe.rb
@@ -72,7 +73,9 @@ files:
 - lib/engram/use_cases/recall.rb
 - lib/engram/use_cases/source_impact.rb
 - lib/engram/version.rb
+- lib/generators/engram/expiry_generator.rb
 - lib/generators/engram/install_generator.rb
+- lib/generators/engram/templates/add_expiry_to_engram_memories.rb.tt
 - lib/generators/engram/templates/create_engram_memories.rb.tt
 - lib/generators/engram/templates/initializer.rb.tt
 - lib/generators/engram/templates/memory_record.rb.tt