engram 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3d370df000e9c12a40df932919f0859d9eb7623270ed5aeaa781747f239d865
-  data.tar.gz: 2c49fd3e8126a510f49b711a9ccf9d159ac01b6e540ef2ab168e7e51fa6509f3
+  metadata.gz: 50765b71eaace1c3abc16581e67c2466bf992fa023b082fe29d4b2c889cfb9d9
+  data.tar.gz: c439b5c3f34b9c91b8e1b7099b015c9b05eda5db93edc66de2bd913370c19303
 SHA512:
-  metadata.gz: 161c8e9c199352d663e0ce670f3a6dc76ac98aba0b429566a1c3c96fa8ee5c7db260a449355f449b11dfdb25de4b85f207ca263fcffa6a76248d1269632ecddc
-  data.tar.gz: 1c3867577e6a86128fa4a4036b64cc2790754336c4cc462495284f25f5a7ac63ac56be24694ffb9578d2b50999bde325ca4ced68b6d8e0aed9143234108b0888
+  metadata.gz: e862092cd85d8501d437d18a9c31dfe039809196c927c685235ee42bc32be629df3fda5b3f3934fdc92c6f2a64e110eb30aecd1b2e8889178a1c97a2295e5564
+  data.tar.gz: fddf7838f9396078287d58d67f25cb1b182c355c21b32b2937b4715e8ed63541305927c8b48b070dee426e3f3196330572a11c02cf7f17a94ed76b2d1f7985dd

data/CHANGELOG.md

@@ -5,6 +5,42 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-12
+
+### Added
+
+- `Memory#update(id:, ...)` changes the given attributes of a memory in the current scope,
+  keeping its id and timestamps. It returns the stored record, `nil` when `before_persist` or
+  the policy rejects the edit, and raises `Engram::MemoryNotFoundError` for an unknown id.
+  Content changes re-embed the memory and remove its provenance. Emits `update.engram`.
+- `Memory#all(limit:, after_id:)` reads one page of memories in id order, and
+  `Memory#each_memory(batch_size:)` iterates a scope in batches. `all` without arguments is
+  unchanged.
+- `Memory#forget_all(batch_size:, dry_run:)` and the `engram:forget_all[scope]` task delete
+  every memory in a scope in batches and return matched/deleted counts. Emits
+  `forget_all.engram`. The README describes the full erasure steps and an export example.
+- Optional `MemoryStore#delete_many(scope:, ids:)`, implemented by the built-in stores; custom
+  stores without it fall back to `delete`.
+- Optional `MemoryStore#find(scope:, id:)`. The in-memory and pgvector stores implement it;
+  custom stores without it fall back to scanning `all`.
+
+### Fixed
+
+- `InMemoryStore#update` keeps the stored `created_at` and `last_accessed_at`, matching the
+  pgvector store.
+- `Memory#add` no longer sends content to the embedder before `before_persist` and the
+  persistence policy run. Rejected text is not embedded, and redacted text is embedded once,
+  after redaction.
+- `has_memory` raises `Engram::Error` for an owner that is not persisted (new or destroyed)
+  instead of deriving its scope from an unsaved or reused id.
+- The install generator configures the embedder with the requested `--dimensions` so the
+  initializer matches the migration.
+
+### Changed
+
+- On `Memory#add`, `before_persist` hooks now receive a record without an embedding. Hooks
+  that read or transform `record.embedding` on this path must handle `nil`.
+
 ## [0.8.0] - 2026-09-15
 
 ### 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`, `forget_expired`, `rebuild_embeddings`, and `memories_from_source`.
+- Lifecycle methods in `Engram::Memory`: `add`, `update`, `all`, `each_memory`, `recall`, `inject_into`, `observe`, `observe_later`, `forget`, `forget_all`, `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)
@@ -140,6 +140,9 @@ current_user.memory.add("Works at Acme Corp", kind: :fact)
 current_user.memory.recall("where does the user work?")
 ```
 
+The default scope needs a persisted record; calling `memory` on a new or destroyed owner
+raises `Engram::Error`. Pass `has_memory scope: -> { ... }` to use a different key.
+
 Run automatic observation off the request path:
 
 ```ruby
@@ -388,6 +391,11 @@ Engram.configure do |config|
 end
 ```
 
+`Memory#add` runs `before_persist` and the policy before computing the embedding, so rejected
+or redacted text is never sent to the embedder, and hooks receive a record without an
+embedding. `observe` is different: the conversation goes to the completion provider, and
+extracted facts are embedded for consolidation before hooks and policy run.
+
 Write-content filtering and transformation are not deletion authorization. A consolidation
 `forget` decision still validates scope, target existence, candidate integrity, and provenance, but it does not run
 `before_persist` or the policy's `call` method; this allows secret, transient, and redacted
@@ -396,6 +404,47 @@ implementing `allow_destructive?(record)` and returning exactly `true` or `false
 that only implement `call` affect writes but do not prevent deletion. The built-in policy uses
 this separate hook to retain its ungrounded-provenance protection.
 
+### Listing memories
+
+`memory.all` returns every memory in the scope, including expired ones. For large scopes, read
+one page at a time or iterate in batches:
+
+```ruby
+page = memory.all(limit: 50)
+next_page = memory.all(limit: 50, after_id: page.last.id)
+
+memory.each_memory(batch_size: 500) { |record| export(record) }
+```
+
+Both return memories in id order. A custom store whose `all` does not accept `limit:` and
+`after_id:` is read in a single call.
+
+### Correcting memories
+
+```ruby
+memory.update(id: record.id, content: "Lives in Berlin")
+memory.update(id: record.id, importance: 0.2, expires_at: nil)
+```
+
+`update` changes only the attributes you pass (`content`, `kind`, `importance`, `metadata`,
+`expires_at`) and keeps the id, `created_at`, and `last_accessed_at`. `metadata:` replaces the
+application metadata; `{}` clears it, and the reserved `_engram` key is not accepted.
+`expires_at: nil` removes the expiry. Other attributes do not accept `nil`.
+
+The edit goes through `before_persist` and the persistence policy like a new memory, and a
+policy that implements `allow_destructive?` must also allow replacing the original record.
+Expired memories can be updated too. `update` returns the stored record, `nil` if the hook or policy rejects it (the stored memory is
+left unchanged), and raises `Engram::MemoryNotFoundError` if the id is not in this scope.
+The embedding is recomputed when the content changes, or generated if the stored memory has
+no embedding.
+
+Changing the content removes the record's provenance, because the old sources no longer
+support the new text. Other edits keep it.
+
+`update` reads the record, applies the changes, and writes it back without conflict
+detection. If `observe`, an embedding rebuild, or another `update` writes the same memory at
+the same time, one of the changes can be lost.
+
 ### Extraction provenance
 
 Custom extractors remain compatible when they return an array of plain `Engram::Record`
@@ -614,6 +663,47 @@ Errors stop the run; completed batches stay deleted and a retry can process the
 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.
 
+### Erasing or exporting a user's memory
+
+To delete everything Engram stores for one owner, preview the count, then run it:
+
+```ruby
+user.memory.forget_all(dry_run: true)
+# => {matched: 87, deleted: 0, dry_run: true}
+user.memory.forget_all(batch_size: 500)
+# => {matched: 87, deleted: 87, dry_run: false}
+```
+
+```sh
+DRY_RUN=true bin/rails 'engram:forget_all[user:42]'
+bin/rails 'engram:forget_all[user:42]'
+```
+
+`forget_all` deletes expired memories too and, like `forget(id:)`, bypasses hooks and policies.
+It only removes rows in the memory store. Before running it for an erasure request:
+
+1. Stop new `observe` and `observe_later` calls for the owner, and let queued `ObserveJob`s
+   finish or remove them. Otherwise they can write new memories during or after the erasure.
+2. Run `forget_all`. Memories added while it runs may or may not be deleted, so check
+   `memory.all` afterwards.
+3. Delete conversation transcripts and other source data your app keeps; Engram does not
+   store them. Processed-turn markers in the cache expire on their own and hold no content.
+
+To export, iterate in batches and write the fields you need:
+
+```ruby
+File.open("memories.jsonl", "w") do |file|
+  user.memory.each_memory(batch_size: 500) do |record|
+    file.puts({id: record.id, kind: record.kind, content: record.content,
+      created_at: record.created_at, expires_at: record.expires_at}.to_json)
+  end
+end
+```
+
+Custom stores can implement the optional `delete_many(scope:, ids:)` to delete a batch in one
+call; without it, `forget_all` deletes one id at a time. The `forget_all.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
@@ -700,8 +790,10 @@ When ActiveSupport is loaded, Engram emits `ActiveSupport::Notifications` events
 main memory pipeline:
 
 - `add.engram`
+- `update.engram`
 - `forget.engram`
 - `forget_expired.engram`
+- `forget_all.engram`
 - `recall.engram`
 - `inject.engram`
 - `observe.engram`
@@ -848,6 +940,7 @@ gem unpack engram-*.gem --target /tmp/engram-package-check
 - 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.
+- v0.9 (done): memory correction, paged listing and batched iteration, and scope erasure.
 - later: additional storage backends and larger real-provider eval benchmarks.
 
 ## License

data/lib/engram/adapters/in_memory_store.rb

@@ -51,14 +51,20 @@ module Engram
         @mutex.synchronize { ids.uniq.select { |id| @records[id]&.scope == scope } }
       end
 
+      def find(scope:, id:)
+        @mutex.synchronize do
+          record = @records[id]
+          record if record&.scope == scope
+        end
+      end
+
       def update(scope:, 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
+          @records[id] = record.with(id: id, created_at: existing.created_at, last_accessed_at: existing.last_accessed_at)
         end
       end
 
@@ -90,6 +96,17 @@ module Engram
         end
       end
 
+      def delete_many(scope:, ids:)
+        @mutex.synchronize do
+          ids.uniq.count do |id|
+            next false unless @records[id]&.scope == scope
+
+            @records.delete(id)
+            true
+          end
+        end
+      end
+
       def delete_expired(scope:, ids:, at:)
         @mutex.synchronize do
           ids.uniq.count do |id|

data/lib/engram/adapters/pgvector_store.rb

@@ -69,6 +69,11 @@ module Engram
         end
       end
 
+      def find(scope:, id:)
+        row = model.find_by(scope: scope, id: id)
+        to_record(row) if row
+      end
+
       def update(scope:, id:, record:)
         raise Engram::Error, "cannot move memory across scopes" unless record.scope == scope
 
@@ -104,6 +109,12 @@ module Engram
         query.order(:id).limit(limit).pluck(:id)
       end
 
+      def delete_many(scope:, ids:)
+        return 0 if ids.empty?
+
+        model.where(scope: scope, id: ids).delete_all
+      end
+
       def delete_expired(scope:, ids:, at:)
         return 0 if ids.empty? || !expiry_column?
 

data/lib/engram/memory.rb

@@ -4,6 +4,9 @@ module Engram
   # The friendly facade. Bound to one `scope` (an owner), it wires the configured store
   # and embedder into the use cases. This is what `user.memory` returns in Rails.
   class Memory
+    UNSET = Object.new.freeze
+    private_constant :UNSET
+
     attr_reader :scope
 
     def initialize(scope:, store: Engram.config.store, embedder: Engram.config.embedder)
@@ -16,18 +19,24 @@ module Engram
     # persistence policy rejects the record.
     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
-        record = Record.new(
+        persist(Record.new(
           content: content,
           scope: scope,
           kind: kind,
           importance: importance,
           metadata: metadata,
           expires_at: expires_at
-        )
-        persist(record.with(embedding: @embedder.embed(content)))
+        ))
       end
     end
 
+    # Correct supplied attributes of a memory in this scope. Omitted fields are kept.
+    def update(id:, content: UNSET, kind: UNSET, importance: UNSET, metadata: UNSET, expires_at: UNSET)
+      attributes = {content: content, kind: kind, importance: importance, metadata: metadata, expires_at: expires_at}
+        .reject { |_, value| value.equal?(UNSET) }
+      UseCases::Update.new(store: @store, embedder: @embedder).call(scope: scope, id: id, attributes: attributes)
+    end
+
     # Return the most relevant memories for a query.
     def recall(query, limit: Engram.config.default_limit, kinds: nil,
       min_similarity: Engram.config.recall_min_similarity)
@@ -84,15 +93,35 @@ module Engram
       end
     end
 
-    def all
-      @store.all(scope: scope)
+    # Memories in this scope, including expired ones. Pass limit and after_id (the last id of
+    # the previous page) to read one page in id order.
+    def all(limit: nil, after_id: nil)
+      return @store.all(scope: scope) if limit.nil? && after_id.nil?
+      if !limit.nil? && !(limit.is_a?(Integer) && limit.positive?)
+        raise ArgumentError, "limit must be a positive integer"
+      end
+      if !after_id.nil? && !valid_id?(after_id)
+        raise ArgumentError, "after_id must be an Integer or a non-empty String"
+      end
+
+      @store.all(scope: scope, limit: limit, after_id: after_id)
+    end
+
+    # Yield every memory in this scope in id order, loading batch_size records at a time.
+    # Returns an Enumerator without a block.
+    def each_memory(batch_size: 100, &block)
+      unless batch_size.is_a?(Integer) && batch_size.positive?
+        raise ArgumentError, "batch_size must be a positive integer"
+      end
+      return enum_for(:each_memory, batch_size: batch_size) unless block
+
+      UseCases::EachMemory.new(store: @store).call(scope: scope, batch_size: batch_size, &block)
     end
 
     # Delete one memory in this scope. Returns 1 when deleted, or 0 when missing.
     # Explicit deletion bypasses extraction, consolidation, and persistence hooks.
     def forget(id:)
-      valid_id = id.instance_of?(Integer) || (id.instance_of?(String) && id.valid_encoding? && !id.strip.empty?)
-      raise ArgumentError, "id must be an Integer or a non-empty String" unless valid_id
+      raise ArgumentError, "id must be an Integer or a non-empty String" unless valid_id?(id)
 
       payload = Engram::Instrumentation.payload(scope: scope, store: @store)
       Engram::Instrumentation.instrument("forget", payload) do
@@ -100,6 +129,12 @@ module Engram
       end
     end
 
+    # Delete every memory in this scope in batches. Returns matched and deleted counts.
+    # Bypasses extraction, consolidation, and persistence hooks, like #forget.
+    def forget_all(batch_size: 100, dry_run: false)
+      UseCases::ForgetAll.new(store: @store).call(scope: scope, batch_size: batch_size, dry_run: dry_run)
+    end
+
     # Recompute embeddings (and embedding metadata) for memories in the scope.
     # When `stale_only` is true, only records whose current metadata does not match the
     # active embedder are rebuilt.
@@ -142,6 +177,10 @@ module Engram
 
     private
 
+    def valid_id?(id)
+      id.instance_of?(Integer) || (id.instance_of?(String) && id.valid_encoding? && !id.strip.empty?)
+    end
+
     def persist(record)
       Persistence.new(store: @store, embedder: @embedder).add(record)
     end

data/lib/engram/persistence.rb

@@ -48,20 +48,30 @@ module Engram
     # Applies all write transformations without mutating the store. Input is validated
     # before callbacks can remove or replace provenance, and final output is validated too.
     def prepare(record)
-      original_provenance = validate_provenance!(record)
       original_content = record.content
+      record = transform(record)
+      # Embed only after hooks and policy so rejected or redacted text never reaches the embedder.
+      if record && (record.embedding.nil? || record.content != original_content)
+        record = record.with(embedding: @embedder.embed(record.content))
+      end
+      record = Engram::EmbeddingMetadata.attach(record, embedder: @embedder) if record
+      validate_provenance!(record) if record
+      record
+    end
+
+    # Runs before_persist and the policy without embedding. Memory#update passes a block
+    # that runs after each step to check the result and drop invalidated provenance.
+    def transform(record)
+      original_provenance = validate_provenance!(record)
       record = @before_persist.call(record) if @before_persist
       if record
         transformed_provenance = validate_provenance!(record)
         validate_provenance_trust!(original_provenance, transformed_provenance) if @before_persist
       end
+      record = yield(record) if record && block_given?
       record = @persistence_policy.call(record) if record && @persistence_policy
       validate_provenance!(record) if record
-      if record && record.content != original_content
-        record = record.with(embedding: @embedder.embed(record.content))
-      end
-      record = Engram::EmbeddingMetadata.attach(record, embedder: @embedder) if record
-      validate_provenance!(record) if record
+      record = yield(record) if record && block_given?
       record
     end
 

data/lib/engram/ports/extractor.rb

@@ -2,13 +2,12 @@
 
 module Engram
   module Ports
-    # PLACEHOLDER (v0.2). Contract for deriving candidate facts from a conversation turn.
-    # Declared now so the differentiator (extract -> consolidate) slots in without
-    # reworking the core. Not implemented in v0.1.
+    # Contract for deriving candidate facts from a conversation turn.
+    # Implementation: Extractors::LLMExtractor.
     module Extractor
       # Given conversation messages, return an Array whose members are Record or Extraction values.
       def extract(messages:, scope:)
-        raise NotImplementedError, "Extractor arrives in v0.2"
+        raise NotImplementedError, "#{self.class} must implement #extract"
       end
     end
   end

data/lib/engram/ports/memory_store.rb

@@ -26,6 +26,12 @@ module Engram
         raise NotImplementedError, "#{self.class} must implement #all"
       end
 
+      # Optional scoped lookup, including expired records, without touching access time.
+      # Returns a Record or nil. Legacy adapters can fall back to #all.
+      def find(scope:, id:)
+        raise NotImplementedError, "#{self.class} does not implement #find"
+      end
+
       # Optional performance capability: return the subset of requested ids that
       # exists in `scope`, preserving each requested value's representation rather
       # than returning a store-native cast of it. Return at most one requested
@@ -50,6 +56,12 @@ module Engram
         raise NotImplementedError, "#{self.class} must implement #delete"
       end
 
+      # Optional bulk deletion: delete the requested IDs that exist in scope and return the
+      # deleted count. Callers fall back to #delete for adapters without it.
+      def delete_many(scope:, ids:)
+        raise NotImplementedError, "#{self.class} does not implement #delete_many"
+      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)

data/lib/engram/rails/has_memory.rb

@@ -22,6 +22,11 @@ module Engram
             if scope_proc
               instance_exec(&scope_proc)
             else
+              unless persisted?
+                raise Engram::Error,
+                  "#{self.class.name} must be saved before using memory, or pass a scope to has_memory"
+              end
+
               "#{self.class.name.underscore}:#{id}"
             end
           Engram::Memory.new(scope: key)

data/lib/engram/rails/tasks.rake

@@ -18,6 +18,21 @@ namespace :engram do
     puts "matched=#{result[:matched]} deleted=#{result[:deleted]} dry_run=#{result[:dry_run]}"
   end
 
+  desc "Delete every memory in a scope. Usage: bundle exec rake 'engram:forget_all[user:1]'"
+  task :forget_all, [:scope] => :environment do |_, args|
+    scope = args[:scope]
+    raise ArgumentError, "forget_all 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_all(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/use_cases/each_memory.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Engram
+  module UseCases
+    # Yields every memory in a scope in id order, loading at most batch_size records at a time.
+    # Stores whose #all does not accept limit/after_id are read in one call.
+    class EachMemory
+      def initialize(store:)
+        @store = store
+      end
+
+      def call(scope:, batch_size: 100, &block)
+        unless batch_size.is_a?(Integer) && batch_size.positive?
+          raise ArgumentError, "batch_size must be a positive integer"
+        end
+        unless keyset_supported?
+          sort_by_id(@store.all(scope: scope)).each(&block)
+          return nil
+        end
+
+        after_id = nil
+        loop do
+          batch = @store.all(scope: scope, limit: batch_size, after_id: after_id)
+          break if batch.empty?
+          unless batch.size <= batch_size && advances?(batch.map(&:id), after_id)
+            raise Engram::Error, "store #all must return pages that advance by id"
+          end
+
+          batch.each(&block)
+          after_id = batch.last.id
+        end
+        nil
+      end
+
+      private
+
+      def advances?(ids, after_id)
+        ids = [after_id, *ids] unless after_id.nil?
+        ids.none?(&:nil?) && ids.each_cons(2).all? { |previous, current| previous < current }
+      rescue ArgumentError, NoMethodError
+        false
+      end
+
+      def sort_by_id(records)
+        records.sort_by(&:id)
+      rescue ArgumentError, NoMethodError
+        raise Engram::Error, "store #all returned ids that cannot be ordered"
+      end
+
+      def keyset_supported?
+        keywords = @store.method(:all).parameters.filter_map { |kind, name| name if %i[key keyreq].include?(kind) }
+        keywords.include?(:limit) && keywords.include?(:after_id)
+      end
+    end
+  end
+end

data/lib/engram/use_cases/forget_all.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Engram
+  module UseCases
+    # Deletes every memory in a scope in id-ordered batches. Like Memory#forget, it bypasses
+    # extraction, consolidation, and persistence hooks.
+    class ForgetAll
+      def initialize(store:)
+        @store = store
+      end
+
+      def call(scope:, batch_size: 100, dry_run: false)
+        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
+
+        counts = {matched: 0, deleted: 0, dry_run: dry_run}
+        payload = Engram::Instrumentation.payload(scope: scope, store: @store, **counts)
+        Engram::Instrumentation.instrument("forget_all", payload) do
+          ids = []
+          flush = lambda do
+            counts[:matched] += ids.size
+            payload.merge!(counts)
+            unless dry_run
+              delete(scope, ids) do |deleted|
+                counts[:deleted] += deleted
+                payload.merge!(counts)
+              end
+            end
+            ids = []
+          end
+          EachMemory.new(store: @store).call(scope: scope, batch_size: batch_size) do |record|
+            ids << record.id
+            flush.call if ids.size == batch_size
+          end
+          flush.call unless ids.empty?
+          counts
+        end
+      end
+
+      private
+
+      def delete(scope, ids)
+        if @store.respond_to?(:delete_many)
+          begin
+            return yield @store.delete_many(scope: scope, ids: ids)
+          rescue NotImplementedError
+            # Optional capability: legacy adapters may inherit the default stub.
+          end
+        end
+
+        ids.each { |id| yield @store.delete(scope: scope, id: id).to_i }
+      end
+    end
+  end
+end

data/lib/engram/use_cases/update.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Engram
+  module UseCases
+    # Scoped read/merge/write correction. Concurrent writers require host coordination.
+    class Update
+      def initialize(store:, embedder:)
+        @store = store
+        @embedder = embedder
+      end
+
+      def call(scope:, id:, attributes:)
+        attributes = validate_attributes!(id, attributes)
+        payload = Engram::Instrumentation.payload(scope: scope, store: @store,
+          fields: attributes.keys.map(&:to_s), content_changed: false, reembedded: false)
+        Engram::Instrumentation.instrument("update", payload) do
+          original = find(scope, id)
+          unless original && Engram::Internal::Scope.record_matches?(original, scope)
+            payload[:outcome] = "missing"
+            raise Engram::MemoryNotFoundError, "no memory in this scope"
+          end
+
+          # Validate before any edit can remove inherited evidence.
+          Engram::Provenance.canonical_payload_for_persistence(original.metadata)
+          original = detach(plain_times(original))
+          original = original.with(metadata: Engram::Provenance.canonical_metadata_for_persistence(original.metadata))
+          persistence = Engram::Persistence.new(store: @store, embedder: @embedder)
+          unless persistence.allowed?(detach(original))
+            payload[:outcome] = "rejected"
+            next nil
+          end
+
+          candidate = merge(original, attributes)
+          candidate = invalidate_provenance(candidate, original)
+          payload[:content_changed] = candidate.content != original.content
+          evidence = provenance(candidate)
+          candidate = persistence.transform(candidate) do |transformed|
+            validate_transformation!(transformed, original, scope)
+            unless provenance(transformed) == evidence
+              raise Engram::Error, "update transformations cannot change provenance trust"
+            end
+            transformed = invalidate_provenance(transformed, original)
+            evidence = provenance(transformed)
+            payload[:content_changed] = transformed.content != original.content
+            transformed
+          end
+          unless candidate
+            payload[:outcome] = "rejected"
+            next nil
+          end
+
+          payload[:content_changed] = candidate.content != original.content
+          candidate = replace_reserved_field(candidate, "embedding")
+          if payload[:content_changed] || original.embedding.nil?
+            candidate = candidate.with(embedding: @embedder.embed(candidate.content))
+            payload[:reembedded] = true
+            candidate = Engram::EmbeddingMetadata.attach(candidate, embedder: @embedder)
+          else
+            candidate = replace_reserved_field(candidate, "embedding", source: original)
+              .with(embedding: original.embedding)
+          end
+          candidate = candidate.with(created_at: original.created_at, last_accessed_at: original.last_accessed_at)
+          stored = persistence.update_prepared(scope: scope, id: id, record: candidate)
+          payload[:outcome] = "updated"
+          stored
+        end
+      end
+
+      private
+
+      def validate_attributes!(id, attributes)
+        valid_id = id.instance_of?(Integer) || (id.instance_of?(String) && id.valid_encoding? && !id.strip.empty?)
+        raise ArgumentError, "id must be an Integer or a non-empty String" unless valid_id
+        raise ArgumentError, "at least one attribute must be supplied" if attributes.empty?
+
+        attributes = attributes.dup
+        attributes.each do |field, value|
+          valid = case field
+          when :content
+            value.is_a?(String) && value.valid_encoding? && !value.strip.empty?
+          when :kind
+            attributes[field] = Engram::MemoryKind.normalize(value)
+            true
+          when :importance
+            (value.is_a?(Integer) || value.is_a?(Float)) && value.finite?
+          when :metadata
+            value.is_a?(Hash) && !reserved_metadata?(value)
+          when :expires_at
+            value.nil? || value.is_a?(Time)
+          else
+            false
+          end
+          raise ArgumentError, "invalid #{field}" unless valid
+        end
+        attributes
+      end
+
+      def reserved_metadata?(metadata)
+        Engram::Internal::CoreHash.each_pair(metadata) do |key, _|
+          return true if key.equal?(:_engram)
+          return true if key.is_a?(String) && String.instance_method(:==).bind_call(key, "_engram")
+        end
+        false
+      end
+
+      def find(scope, id)
+        if @store.respond_to?(:find)
+          begin
+            return @store.find(scope: scope, id: id)
+          rescue NotImplementedError
+            # Optional capability: legacy adapters may inherit the default stub.
+          end
+        end
+        @store.all(scope: scope).find { |record| record.id == id }
+      end
+
+      def detach(record)
+        Engram::Internal::CandidateIntegrity.new.detach(record)
+      rescue Engram::Internal::CandidateIntegrity::Error => error
+        raise Engram::Error, error.message
+      end
+
+      # Rails stores return ActiveSupport::TimeWithZone; candidates accept only plain Time.
+      def plain_times(record)
+        record.with(
+          created_at: plain_time(record.created_at),
+          last_accessed_at: plain_time(record.last_accessed_at),
+          expires_at: plain_time(record.expires_at)
+        )
+      end
+
+      def plain_time(value)
+        (value.nil? || value.instance_of?(Time)) ? value : Time.at(value.to_r).utc
+      end
+
+      def merge(original, attributes)
+        if attributes.key?(:metadata)
+          metadata = Hash.instance_method(:transform_values).bind_call(attributes[:metadata]) { |value| value }
+          ["_engram", :_engram].each do |key|
+            metadata[key] = original.metadata[key] if original.metadata.key?(key)
+          end
+          attributes = attributes.merge(metadata: metadata)
+        end
+        detach(original.with(**attributes))
+      end
+
+      def provenance(record)
+        Engram::Provenance.canonical_integrity_representation_for_persistence(record.metadata)
+      end
+
+      def invalidate_provenance(record, original)
+        return record if record.content == original.content
+
+        replace_reserved_field(record, "provenance")
+      end
+
+      # Keep unrelated reserved siblings and preserve the stored embedding schema
+      # exactly when reusing its vector, including legacy symbol-key aliases.
+      def replace_reserved_field(record, field, source: nil)
+        metadata = record.metadata.dup
+        ["_engram", :_engram].each do |key|
+          reserved = metadata[key]&.dup || {}
+          reserved.delete(field)
+          reserved.delete(field.to_sym)
+          inherited = source&.metadata&.fetch(key, {}) || {}
+          [field, field.to_sym].each do |alias_key|
+            reserved[alias_key] = inherited[alias_key] if inherited.key?(alias_key)
+          end
+          metadata[key] = reserved if metadata.key?(key) || !reserved.empty?
+        end
+        record.with(metadata: metadata)
+      end
+
+      def validate_transformation!(record, original, scope)
+        unless Engram::Internal::Scope.record_matches?(record, scope) && record.id == original.id
+          raise Engram::Error, "update transformations cannot change memory identity or scope"
+        end
+        validate_attributes!(record.id,
+          content: record.content, kind: record.kind, importance: record.importance, expires_at: record.expires_at)
+      rescue ArgumentError => error
+        raise Engram::Error, error.message
+      end
+    end
+  end
+end

data/lib/engram/version.rb

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

data/lib/engram.rb

@@ -31,6 +31,9 @@ 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/update"
+require_relative "engram/use_cases/each_memory"
+require_relative "engram/use_cases/forget_all"
 require_relative "engram/use_cases/forget_expired"
 require_relative "engram/use_cases/rebuild_embeddings"
 require_relative "engram/use_cases/source_impact"
@@ -65,6 +68,9 @@ module Engram
   # Raised when a live claim suppresses an observation that has not completed.
   class ObservationInProgressError < Error; end
 
+  # Raised when a correction targets a memory absent from the caller's scope.
+  class MemoryNotFoundError < Error; end
+
   class << self
     def config
       @config ||= Configuration.new

data/lib/generators/engram/install_generator.rb

@@ -44,6 +44,12 @@ module Engram
         options[:dimensions]
       end
 
+      def embedder_arguments
+        return "" if dimensions == DEFAULT_DIMENSIONS
+
+        "(dimensions: #{dimensions})"
+      end
+
       def validate_dimensions!
         return if dimensions.is_a?(Integer) && dimensions.positive?
 

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

@@ -5,7 +5,8 @@ Engram.configure do |config|
   config.store = Engram::Adapters::PgvectorStore.new
 
   # Generate embeddings via RubyLLM. Configure RubyLLM separately with your provider keys.
-  config.embedder = Engram::Adapters::RubyLLMEmbedder.new
+  # The embedder must return <%= dimensions %>-dimensional vectors to match the migration.
+  config.embedder = Engram::Adapters::RubyLLMEmbedder.new<%= embedder_arguments %>
 
   # How many memories to recall by default.
   config.default_limit = 5

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: engram
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Alexandr Kholodniak
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-15 00:00:00.000000000 Z
+date: 2026-10-11 00:00:00.000000000 Z
 dependencies: []
 description: |
   Engram gives AI agents durable, long-term memory. It recalls relevant facts about a
@@ -64,7 +64,9 @@ files:
 - lib/engram/record.rb
 - lib/engram/reserved_metadata.rb
 - lib/engram/turn_digest.rb
+- lib/engram/use_cases/each_memory.rb
 - lib/engram/use_cases/forget.rb
+- lib/engram/use_cases/forget_all.rb
 - lib/engram/use_cases/forget_expired.rb
 - lib/engram/use_cases/grounding_report.rb
 - lib/engram/use_cases/inject.rb
@@ -72,6 +74,7 @@ files:
 - lib/engram/use_cases/rebuild_embeddings.rb
 - lib/engram/use_cases/recall.rb
 - lib/engram/use_cases/source_impact.rb
+- lib/engram/use_cases/update.rb
 - lib/engram/version.rb
 - lib/generators/engram/expiry_generator.rb
 - lib/generators/engram/install_generator.rb