engram 0.3.0

data/lib/engram/use_cases/forget.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Engram
+  module UseCases
+    # Prune stale memories from a scope. A memory is stale when its last activity
+    # (last_accessed_at, or created_at if never accessed) is older than the cutoff.
+    # `min_importance` keeps important memories even when they are old: only memories with
+    # importance below it are eligible. The default forgets all stale memories.
+    class Forget
+      def initialize(store:)
+        @store = store
+      end
+
+      # Returns the Array<Record> that were forgotten.
+      def call(scope:, older_than:, min_importance: Float::INFINITY, now: Time.now)
+        cutoff = now - older_than
+
+        stale = @store.all(scope: scope).select do |record|
+          timestamp = record.last_accessed_at || record.created_at
+          timestamp && timestamp < cutoff && record.importance.to_f < min_importance
+        end
+
+        stale.each { |record| @store.delete(id: record.id) if record.id }
+        stale
+      end
+    end
+  end
+end

data/lib/engram/use_cases/inject.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Engram
+  module UseCases
+    # Render recalled memories into a prompt as a clearly delimited block.
+    class Inject
+      DEFAULT_HEADER = "# What you remember about the user"
+
+      def initialize(header: DEFAULT_HEADER)
+        @header = header
+      end
+
+      # Returns a new prompt string. If there are no memories, the prompt is unchanged.
+      def call(prompt:, memories:)
+        return prompt if memories.nil? || memories.empty?
+
+        block = memories.map { |m| "- #{m.content}" }.join("\n")
+        "#{prompt}\n\n#{@header}:\n#{block}"
+      end
+    end
+  end
+end

data/lib/engram/use_cases/observe.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Engram
+  module UseCases
+    # Orchestrates a single observed turn: extract candidate facts, consolidate them
+    # against existing memory, and apply the resulting decisions to the store.
+    # Pure and synchronous — async execution is a Rails concern (see ObserveJob).
+    #
+    # When a ProcessedTurns store and an idempotency_key are provided, a turn that was
+    # already processed is skipped (no extraction, no duplicate memories).
+    class Observe
+      def initialize(store:, extractor:, consolidator:, processed_turns: nil)
+        @store = store
+        @extractor = extractor
+        @consolidator = consolidator
+        @processed_turns = processed_turns
+      end
+
+      # Returns the Array<Decision> that were applied (empty if skipped or nothing found).
+      def call(messages:, scope:, idempotency_key: nil)
+        return [] if already_processed?(idempotency_key)
+
+        candidates = @extractor.extract(messages: messages, scope: scope)
+        if candidates.empty?
+          mark_processed(idempotency_key)
+          return []
+        end
+
+        decisions = @consolidator.reconcile_all(candidates: candidates, scope: scope)
+        decisions.each { |decision| apply(decision) }
+        mark_processed(idempotency_key)
+        decisions
+      end
+
+      private
+
+      def already_processed?(key)
+        !!(key && @processed_turns&.seen?(key))
+      end
+
+      def mark_processed(key)
+        @processed_turns.record(key) if key && @processed_turns
+      end
+
+      def apply(decision)
+        case decision.action
+        when :add
+          @store.add(decision.candidate)
+        when :update
+          @store.update(id: decision.target_id, record: decision.candidate) if decision.target_id
+        when :forget
+          @store.delete(id: decision.target_id) if decision.target_id
+        when :noop
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/engram/use_cases/recall.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Engram
+  module UseCases
+    # Embed a query and fetch the most relevant memories for a scope.
+    #
+    # By default this is pure vector similarity (the store's own ordering). When
+    # importance_weight or recency_weight are non-zero, it fetches a larger candidate pool
+    # and re-ranks by a composite score: similarity + importance + recency. With both
+    # weights at zero (the default) behaviour is identical to plain similarity search.
+    class Recall
+      DEFAULT_HALFLIFE = 30 * 24 * 60 * 60 # 30 days, in seconds
+      DEFAULT_POOL_FACTOR = 4
+
+      def initialize(store:, embedder:, importance_weight: 0.0, recency_weight: 0.0,
+        recency_halflife: DEFAULT_HALFLIFE, pool_factor: DEFAULT_POOL_FACTOR, touch: false)
+        @store = store
+        @embedder = embedder
+        @importance_weight = importance_weight.to_f
+        @recency_weight = recency_weight.to_f
+        @recency_halflife = recency_halflife.to_f
+        @pool_factor = pool_factor
+        @touch = touch
+      end
+
+      # Returns Array<Record>, most relevant first.
+      def call(query, scope:, limit: Engram.config.default_limit)
+        raise ArgumentError, "query must be a non-empty string" if query.to_s.strip.empty?
+
+        embedding = @embedder.embed(query)
+        pool_limit = reranking? ? limit * @pool_factor : limit
+        pool = @store.search(embedding: embedding, scope: scope, limit: pool_limit)
+
+        results = (reranking? ? rerank(pool, embedding) : pool).first(limit)
+        touch(results) if @touch
+        results
+      end
+
+      private
+
+      def reranking?
+        !@importance_weight.zero? || !@recency_weight.zero?
+      end
+
+      def rerank(records, query_embedding)
+        now = Time.now
+        records.sort_by do |record|
+          similarity = Engram::Math.cosine_similarity(query_embedding, record.embedding)
+          score = similarity +
+            (@importance_weight * record.importance.to_f) +
+            (@recency_weight * recency(record, now))
+          -score
+        end
+      end
+
+      def recency(record, now)
+        timestamp = record.last_accessed_at || record.created_at
+        return 0.0 unless timestamp
+
+        age = now - timestamp
+        0.5**(age / @recency_halflife)
+      end
+
+      def touch(records)
+        records.each { |record| @store.touch(id: record.id, at: Time.now) if record.id }
+      end
+    end
+  end
+end

data/lib/engram/version.rb

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

data/lib/engram.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "engram/version"
+require_relative "engram/configuration"
+require_relative "engram/math"
+require_relative "engram/record"
+require_relative "engram/decision"
+require_relative "engram/turn_digest"
+
+# Ports (contracts)
+require_relative "engram/ports/memory_store"
+require_relative "engram/ports/embedder"
+require_relative "engram/ports/completion"
+require_relative "engram/ports/extractor"
+require_relative "engram/ports/consolidator"
+require_relative "engram/ports/processed_turns"
+
+# Use cases
+require_relative "engram/use_cases/recall"
+require_relative "engram/use_cases/inject"
+require_relative "engram/use_cases/observe"
+require_relative "engram/use_cases/forget"
+
+# Built-in adapters (pure Ruby, no external deps)
+require_relative "engram/adapters/in_memory_store"
+require_relative "engram/adapters/null_embedder"
+require_relative "engram/adapters/fake_completion"
+require_relative "engram/adapters/in_memory_processed_turns"
+
+# Optional adapters. These reference external libraries (neighbor, ruby_llm) only at
+# call time, so requiring the files here is safe even if those gems are absent.
+require_relative "engram/adapters/pgvector_store"
+require_relative "engram/adapters/ruby_llm_embedder"
+require_relative "engram/adapters/ruby_llm_completion"
+
+# Pipeline stages (v0.2)
+require_relative "engram/extractors/llm_extractor"
+require_relative "engram/consolidators/heuristic_consolidator"
+require_relative "engram/consolidators/llm_consolidator"
+
+require_relative "engram/memory"
+
+# Optional integrations (pure Ruby; reference external libs only at call time)
+require_relative "engram/integrations/ruby_llm"
+
+# Public entrypoint and configuration store.
+module Engram
+  class Error < StandardError; end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # Reset configuration (primarily for tests).
+    def reset!
+      @config = Configuration.new
+    end
+  end
+end
+
+require_relative "engram/railtie" if defined?(Rails::Railtie)

data/lib/generators/engram/install_generator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Engram
+  module Generators
+    # `bin/rails generate engram:install [--dimensions=1536]`
+    # Creates the migration, an initializer, and the AR model.
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      DEFAULT_DIMENSIONS = 1536
+
+      class_option :dimensions, type: :numeric, default: DEFAULT_DIMENSIONS,
+        desc: "Embedding dimensions (match your embedding model)"
+
+      def create_migration_file
+        migration_template "create_engram_memories.rb.tt",
+          "db/migrate/create_engram_memories.rb"
+      end
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/engram.rb"
+      end
+
+      def create_model
+        template "memory_record.rb.tt", "app/models/engram/memory_record.rb"
+      end
+
+      def self.next_migration_number(dir)
+        ::ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      private
+
+      def dimensions
+        options[:dimensions]
+      end
+
+      def migration_version
+        "#{::ActiveRecord::VERSION::MAJOR}.#{::ActiveRecord::VERSION::MINOR}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class CreateEngramMemories < ActiveRecord::Migration[<%= migration_version %>]
+  def change
+    enable_extension "vector" unless extension_enabled?("vector")
+
+    create_table :engram_memories do |t|
+      t.string :scope, null: false
+      t.text :content, null: false
+      t.string :kind, null: false, default: "semantic"
+      t.float :importance, null: false, default: 1.0
+      t.jsonb :metadata, null: false, default: {}
+      t.vector :embedding, limit: <%= dimensions %>
+      t.datetime :last_accessed_at
+
+      t.timestamps
+    end
+
+    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
+  end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+Engram.configure do |config|
+  # Persist memories in your own Postgres via pgvector + neighbor.
+  config.store = Engram::Adapters::PgvectorStore.new
+
+  # Generate embeddings via RubyLLM. Configure RubyLLM separately with your provider keys.
+  config.embedder = Engram::Adapters::RubyLLMEmbedder.new
+
+  # How many memories to recall by default.
+  config.default_limit = 5
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Engram
+  class MemoryRecord < ApplicationRecord
+    self.table_name = "engram_memories"
+
+    has_neighbors :embedding
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: engram
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Alexandr Kholodniak
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-25 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Engram gives AI agents durable, long-term memory. It recalls relevant facts about a
+  user and injects them into the prompt, so an agent appears to remember across sessions.
+  Framework-agnostic core with a ports-and-adapters design; first-class Rails and RubyLLM
+  integration. Your memories live in your own database — no external memory service.
+email:
+- alexandrkholodniak@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/engram.rb
+- lib/engram/adapters/fake_completion.rb
+- lib/engram/adapters/in_memory_processed_turns.rb
+- lib/engram/adapters/in_memory_store.rb
+- lib/engram/adapters/null_embedder.rb
+- lib/engram/adapters/pgvector_store.rb
+- lib/engram/adapters/ruby_llm_completion.rb
+- lib/engram/adapters/ruby_llm_embedder.rb
+- lib/engram/configuration.rb
+- lib/engram/consolidators/heuristic_consolidator.rb
+- lib/engram/consolidators/llm_consolidator.rb
+- lib/engram/decision.rb
+- lib/engram/extractors/llm_extractor.rb
+- lib/engram/integrations/ruby_llm.rb
+- lib/engram/math.rb
+- lib/engram/memory.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/rails/cache_processed_turns.rb
+- lib/engram/rails/has_memory.rb
+- lib/engram/rails/observe_job.rb
+- lib/engram/railtie.rb
+- lib/engram/record.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/recall.rb
+- lib/engram/version.rb
+- lib/generators/engram/install_generator.rb
+- lib/generators/engram/templates/create_engram_memories.rb.tt
+- lib/generators/engram/templates/initializer.rb.tt
+- lib/generators/engram/templates/memory_record.rb.tt
+homepage: https://github.com/kholdrex/engram
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kholdrex/engram
+  source_code_uri: https://github.com/kholdrex/engram
+  changelog_uri: https://github.com/kholdrex/engram/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Long-term memory for AI agents in Ruby — stored in your own Postgres.
+test_files: []