engram 0.3.0 → 0.5.0

data/lib/engram.rb

@@ -3,9 +3,16 @@
 require_relative "engram/version"
 require_relative "engram/configuration"
 require_relative "engram/math"
+require_relative "engram/reserved_metadata"
+require_relative "engram/embedding_metadata"
+require_relative "engram/provenance"
+require_relative "engram/memory_kind"
 require_relative "engram/record"
 require_relative "engram/decision"
 require_relative "engram/turn_digest"
+require_relative "engram/persistence_policy"
+require_relative "engram/instrumentation"
+require_relative "engram/persistence"
 
 # Ports (contracts)
 require_relative "engram/ports/memory_store"
@@ -20,6 +27,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/rebuild_embeddings"
 
 # Built-in adapters (pure Ruby, no external deps)
 require_relative "engram/adapters/in_memory_store"
@@ -47,6 +55,9 @@ require_relative "engram/integrations/ruby_llm"
 module Engram
   class Error < StandardError; end
 
+  # Raised when a live claim suppresses an observation that has not completed.
+  class ObservationInProgressError < Error; end
+
   class << self
     def config
       @config ||= Configuration.new

data/lib/generators/engram/install_generator.rb

@@ -17,6 +17,10 @@ module Engram
       class_option :dimensions, type: :numeric, default: DEFAULT_DIMENSIONS,
         desc: "Embedding dimensions (match your embedding model)"
 
+      def validate_dimensions
+        validate_dimensions!
+      end
+
       def create_migration_file
         migration_template "create_engram_memories.rb.tt",
           "db/migrate/create_engram_memories.rb"
@@ -40,6 +44,12 @@ module Engram
         options[:dimensions]
       end
 
+      def validate_dimensions!
+        return if dimensions.is_a?(Integer) && dimensions.positive?
+
+        raise ArgumentError, "dimensions must be a positive integer that matches your embedding model"
+      end
+
       def migration_version
         "#{::ActiveRecord::VERSION::MAJOR}.#{::ActiveRecord::VERSION::MINOR}"
       end

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

@@ -7,7 +7,7 @@ class CreateEngramMemories < ActiveRecord::Migration[<%= migration_version %>]
     create_table :engram_memories do |t|
       t.string :scope, null: false
       t.text :content, null: false
-      t.string :kind, null: false, default: "semantic"
+      t.string :kind, null: false, default: "fact"
       t.float :importance, null: false, default: 1.0
       t.jsonb :metadata, null: false, default: {}
       t.vector :embedding, limit: <%= dimensions %>
@@ -18,7 +18,14 @@ class CreateEngramMemories < ActiveRecord::Migration[<%= migration_version %>]
 
     add_index :engram_memories, :scope
 
-    # For larger datasets, add an approximate index (requires data present first):
-    # add_index :engram_memories, :embedding, using: :hnsw, opclass: :vector_cosine_ops
+    # For larger datasets, choose one approximate vector index after backfilling data.
+    # HNSW is a strong default for read-heavy recall workloads with frequent inserts.
+    # IVFFlat can be smaller/faster to build, but should be created after enough representative data exists.
+    #
+    # HNSW:
+    #   add_index :engram_memories, :embedding, using: :hnsw, opclass: :vector_cosine_ops
+    # IVFFlat:
+    #   add_index :engram_memories, :embedding, using: :ivfflat, opclass: :vector_cosine_ops
+    # See the Engram README for production index guidance.
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: engram
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Alexandr Kholodniak
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-25 00:00:00.000000000 Z
+date: 2026-07-16 00:00:00.000000000 Z
 dependencies: []
 description: |
   Engram gives AI agents durable, long-term memory. It recalls relevant facts about a
@@ -36,25 +36,34 @@ files:
 - lib/engram/consolidators/heuristic_consolidator.rb
 - lib/engram/consolidators/llm_consolidator.rb
 - lib/engram/decision.rb
+- lib/engram/embedding_metadata.rb
 - lib/engram/extractors/llm_extractor.rb
+- lib/engram/instrumentation.rb
 - lib/engram/integrations/ruby_llm.rb
 - lib/engram/math.rb
 - lib/engram/memory.rb
+- lib/engram/memory_kind.rb
+- lib/engram/persistence.rb
+- lib/engram/persistence_policy.rb
 - lib/engram/ports/completion.rb
 - lib/engram/ports/consolidator.rb
 - lib/engram/ports/embedder.rb
 - lib/engram/ports/extractor.rb
 - lib/engram/ports/memory_store.rb
 - lib/engram/ports/processed_turns.rb
+- lib/engram/provenance.rb
 - lib/engram/rails/cache_processed_turns.rb
 - lib/engram/rails/has_memory.rb
 - lib/engram/rails/observe_job.rb
+- lib/engram/rails/tasks.rake
 - lib/engram/railtie.rb
 - lib/engram/record.rb
+- lib/engram/reserved_metadata.rb
 - lib/engram/turn_digest.rb
 - lib/engram/use_cases/forget.rb
 - lib/engram/use_cases/inject.rb
 - lib/engram/use_cases/observe.rb
+- lib/engram/use_cases/rebuild_embeddings.rb
 - lib/engram/use_cases/recall.rb
 - lib/engram/version.rb
 - lib/generators/engram/install_generator.rb
@@ -66,8 +75,9 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/kholdrex/engram
-  source_code_uri: https://github.com/kholdrex/engram
+  source_code_uri: https://github.com/kholdrex/engram/tree/main
   changelog_uri: https://github.com/kholdrex/engram/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/kholdrex/engram/issues
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -84,7 +94,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Long-term memory for AI agents in Ruby — stored in your own Postgres.