engram 0.3.0

data/lib/engram/consolidators/llm_consolidator.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Engram
+  module Consolidators
+    # LLM-as-judge consolidation. For each candidate it gathers the nearest existing
+    # memories (vector pre-filter) and asks the model, in a single batched call, what to
+    # do: add / update / forget / noop.
+    class LLMConsolidator
+      include Ports::Consolidator
+
+      SYSTEM = <<~PROMPT
+        You maintain a user's long-term memory. For each candidate fact, decide how it
+        relates to the existing memories provided:
+          - "add":    genuinely new information
+          - "update": supersedes a specific existing memory (e.g. a changed preference)
+          - "forget": an existing memory is now contradicted or obsolete
+          - "noop":   already known, or not worth storing
+        Use "update"/"forget" only with the id of an existing memory shown for that candidate.
+        Return one decision per candidate, referencing it by its index.
+      PROMPT
+
+      SCHEMA = {
+        type: "object",
+        properties: {
+          decisions: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                index: {type: "integer"},
+                action: {type: "string", enum: %w[add update forget noop]},
+                target_id: {type: %w[integer string null]},
+                reason: {type: "string"}
+              },
+              required: %w[index action]
+            }
+          }
+        },
+        required: %w[decisions]
+      }.freeze
+
+      def initialize(store:, completion:, neighbors: 5)
+        @store = store
+        @completion = completion
+        @neighbors = neighbors
+      end
+
+      def reconcile_all(candidates:, scope:)
+        candidates = Array(candidates)
+        return [] if candidates.empty?
+
+        result = @completion.complete(
+          system: SYSTEM,
+          user: JSON.generate(payload(candidates, scope)),
+          schema: SCHEMA
+        )
+        map_decisions(decisions(result), candidates)
+      end
+
+      private
+
+      def payload(candidates, scope)
+        items = candidates.each_with_index.map do |candidate, index|
+          existing = @store.search(embedding: candidate.embedding, scope: scope, limit: @neighbors)
+          {
+            index: index,
+            candidate: candidate.content,
+            existing: existing.map { |r| {id: r.id, content: r.content} }
+          }
+        end
+        {candidates: items}
+      end
+
+      def decisions(result)
+        return [] unless result.is_a?(Hash)
+
+        result["decisions"] || result[:decisions] || []
+      end
+
+      def map_decisions(raw, candidates)
+        raw.filter_map do |decision|
+          decision = decision.transform_keys(&:to_s)
+          index = decision["index"]
+          next unless index && candidates[index]
+
+          Engram::Decision.new(
+            action: (decision["action"] || "noop").to_sym,
+            candidate: candidates[index],
+            target_id: decision["target_id"],
+            reason: decision["reason"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/engram/decision.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Engram
+  # The outcome of consolidating one candidate fact against existing memory.
+  #
+  #   action     - :add | :update | :forget | :noop
+  #   candidate  - the Record produced by extraction
+  #   target_id  - id of the existing memory to update/forget (nil for add/noop)
+  #   reason     - optional human-readable rationale (useful for audit/eval)
+  class Decision
+    ACTIONS = %i[add update forget noop].freeze
+
+    attr_reader :action, :candidate, :target_id, :reason
+
+    def initialize(action:, candidate:, target_id: nil, reason: nil)
+      action = action.to_sym
+      unless ACTIONS.include?(action)
+        raise ArgumentError, "unknown action #{action.inspect}; expected one of #{ACTIONS.inspect}"
+      end
+
+      @action = action
+      @candidate = candidate
+      @target_id = target_id
+      @reason = reason
+    end
+  end
+end

data/lib/engram/extractors/llm_extractor.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Engram
+  module Extractors
+    # Derives durable, user-specific facts from a conversation turn via an LLM.
+    class LLMExtractor
+      include Ports::Extractor
+
+      SYSTEM = <<~PROMPT
+        You extract durable, user-specific facts worth remembering across future sessions.
+        Rules:
+        - Only stable facts about the user (preferences, attributes, decisions, history).
+        - Ignore ephemeral chit-chat, questions, and the assistant's own messages.
+        - Normalize each fact to a terse third-person statement (e.g. "User is on the Pro plan").
+        - Set confidence in [0,1]; importance in [0,1].
+        Return an empty list if there is nothing worth remembering.
+      PROMPT
+
+      SCHEMA = {
+        type: "object",
+        properties: {
+          facts: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                content: {type: "string"},
+                kind: {type: "string", enum: %w[semantic episodic preference]},
+                importance: {type: "number"},
+                confidence: {type: "number"}
+              },
+              required: %w[content]
+            }
+          }
+        },
+        required: %w[facts]
+      }.freeze
+
+      def initialize(completion:, embedder:, min_confidence: 0.5)
+        @completion = completion
+        @embedder = embedder
+        @min_confidence = min_confidence
+      end
+
+      def extract(messages:, scope:)
+        result = @completion.complete(system: SYSTEM, user: transcript(messages), schema: SCHEMA)
+        facts(result).filter_map do |fact|
+          fact = fact.transform_keys(&:to_s)
+          content = fact["content"].to_s.strip
+          next if content.empty?
+          next if (fact["confidence"] || 1.0).to_f < @min_confidence
+
+          Engram::Record.new(
+            content: content,
+            scope: scope,
+            kind: (fact["kind"] || "semantic").to_sym,
+            importance: (fact["importance"] || 1.0).to_f,
+            embedding: @embedder.embed(content)
+          )
+        end
+      end
+
+      private
+
+      def facts(result)
+        return [] unless result.is_a?(Hash)
+
+        result["facts"] || result[:facts] || []
+      end
+
+      def transcript(messages)
+        Array(messages).map { |m| line(m) }.join("\n")
+      end
+
+      def line(message)
+        if message.is_a?(Hash)
+          role = message[:role] || message["role"] || "user"
+          "#{role}: #{message[:content] || message["content"]}"
+        else
+          "user: #{message}"
+        end
+      end
+    end
+  end
+end

data/lib/engram/integrations/ruby_llm.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Engram
+  module Integrations
+    module RubyLLM
+      # Wraps a RubyLLM chat so every `ask` is preceded by recall + inject.
+      # Experimental in v0.1 — surface may change as the RubyLLM integration matures.
+      #
+      #   chat = Engram.with_memory(RubyLLM.chat, memory: current_user.memory)
+      #   chat.ask("why am I rate limited?")  # recall + inject happen automatically
+      class MemoryChat
+        def initialize(chat, memory:, limit: Engram.config.default_limit)
+          @chat = chat
+          @memory = memory
+          @limit = limit
+        end
+
+        def ask(message, **opts)
+          augmented = @memory.inject_into(message.to_s, query: message.to_s, limit: @limit)
+          @chat.ask(augmented, **opts)
+        end
+
+        def method_missing(name, *args, **kwargs, &block)
+          return super unless @chat.respond_to?(name)
+
+          @chat.public_send(name, *args, **kwargs, &block)
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          @chat.respond_to?(name, include_private) || super
+        end
+      end
+    end
+  end
+
+  # Convenience entrypoint.
+  def self.with_memory(chat, memory:, limit: config.default_limit)
+    Integrations::RubyLLM::MemoryChat.new(chat, memory: memory, limit: limit)
+  end
+end

data/lib/engram/math.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Engram
+  # Small vector helpers shared by adapters and consolidators.
+  module Math
+    module_function
+
+    def cosine_similarity(a, b)
+      return 0.0 if a.nil? || b.nil? || a.empty? || b.empty? || a.length != b.length
+
+      dot = 0.0
+      norm_a = 0.0
+      norm_b = 0.0
+      a.each_index do |i|
+        dot += a[i] * b[i]
+        norm_a += a[i]**2
+        norm_b += b[i]**2
+      end
+      denom = ::Math.sqrt(norm_a) * ::Math.sqrt(norm_b)
+      denom.zero? ? 0.0 : dot / denom
+    end
+  end
+end

data/lib/engram/memory.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+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
+    attr_reader :scope
+
+    def initialize(scope:, store: Engram.config.store, embedder: Engram.config.embedder)
+      @scope = scope
+      @store = store
+      @embedder = embedder
+    end
+
+    # Persist a fact. (In v0.2 this is mostly done for you via extract/consolidate.)
+    def add(content, kind: :semantic, importance: 1.0, metadata: {})
+      record = Record.new(
+        content: content,
+        scope: scope,
+        embedding: @embedder.embed(content),
+        kind: kind,
+        importance: importance,
+        metadata: metadata
+      )
+      @store.add(record)
+    end
+
+    # Return the most relevant memories for a query.
+    def recall(query, limit: Engram.config.default_limit)
+      UseCases::Recall.new(
+        store: @store,
+        embedder: @embedder,
+        importance_weight: Engram.config.importance_weight,
+        recency_weight: Engram.config.recency_weight,
+        recency_halflife: Engram.config.recency_halflife,
+        touch: Engram.config.touch_on_recall
+      ).call(query, scope: scope, limit: limit)
+    end
+
+    # Recall, then inject into a prompt string.
+    def inject_into(prompt, query:, limit: Engram.config.default_limit)
+      memories = recall(query, limit: limit)
+      UseCases::Inject.new.call(prompt: prompt, memories: memories)
+    end
+
+    # Derive memories from a conversation turn and consolidate them (v0.2).
+    # `messages` is an Array of {role:, content:} hashes (or plain strings).
+    # Returns the Array<Decision> applied. Requires a configured Completion.
+    def observe(messages, completion: Engram.config.completion)
+      if completion.nil?
+        raise Engram::Error, "observe requires a Completion. Set Engram.config.completion."
+      end
+
+      UseCases::Observe.new(
+        store: @store,
+        extractor: build_extractor(completion),
+        consolidator: build_consolidator(completion),
+        processed_turns: Engram.config.processed_turns
+      ).call(
+        messages: messages,
+        scope: scope,
+        idempotency_key: TurnDigest.digest(scope: scope, messages: messages)
+      )
+    end
+
+    # Enqueue observation as a background job (Rails only).
+    def observe_later(messages)
+      unless defined?(Engram::ObserveJob)
+        raise Engram::Error, "observe_later needs ActiveJob (Rails). Use #observe outside Rails."
+      end
+
+      Engram::ObserveJob.perform_later(scope, messages)
+    end
+
+    def all
+      @store.all(scope: scope)
+    end
+
+    # Prune stale memories. `older_than` is a duration in seconds; `min_importance` keeps
+    # memories at or above that importance even when old. Returns the forgotten records.
+    def forget_stale(older_than:, min_importance: Float::INFINITY)
+      UseCases::Forget.new(store: @store)
+        .call(scope: scope, older_than: older_than, min_importance: min_importance)
+    end
+
+    private
+
+    def build_extractor(completion)
+      Extractors::LLMExtractor.new(
+        completion: completion,
+        embedder: @embedder,
+        min_confidence: Engram.config.extraction_min_confidence
+      )
+    end
+
+    def build_consolidator(completion)
+      case Engram.config.consolidator
+      when :llm
+        Consolidators::LLMConsolidator.new(store: @store, completion: completion)
+      else
+        Consolidators::HeuristicConsolidator.new(store: @store)
+      end
+    end
+  end
+end

data/lib/engram/ports/completion.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Engram
+  module Ports
+    # Contract for structured LLM calls used by extraction and consolidation.
+    # Implementations: Adapters::RubyLLMCompletion (real), Adapters::FakeCompletion (tests).
+    module Completion
+      # Run a completion and return parsed structured data conforming to `schema`
+      # (a JSON-schema-ish Hash). `system` and `user` are prompt strings.
+      def complete(system:, user:, schema:)
+        raise NotImplementedError, "#{self.class} must implement #complete"
+      end
+    end
+  end
+end

data/lib/engram/ports/consolidator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Engram
+  module Ports
+    # Contract for reconciling candidate facts against existing memories: decide
+    # ADD / UPDATE / FORGET / NOOP per candidate. This is what separates "memory" from a
+    # dumb pile of embeddings.
+    # Implementations: Consolidators::HeuristicConsolidator, Consolidators::LLMConsolidator.
+    module Consolidator
+      # Given Array<Record> candidates and a scope, return Array<Decision> (one per
+      # candidate that should result in an action).
+      def reconcile_all(candidates:, scope:)
+        raise NotImplementedError, "#{self.class} must implement #reconcile_all"
+      end
+    end
+  end
+end

data/lib/engram/ports/embedder.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Engram
+  module Ports
+    # Contract for turning text into a vector embedding.
+    # Implementations: Adapters::NullEmbedder, Adapters::RubyLLMEmbedder.
+    module Embedder
+      # Return an Array<Float> embedding for `text`.
+      def embed(text)
+        raise NotImplementedError, "#{self.class} must implement #embed"
+      end
+
+      # Dimensionality of the produced vectors.
+      def dimensions
+        raise NotImplementedError, "#{self.class} must implement #dimensions"
+      end
+    end
+  end
+end

data/lib/engram/ports/extractor.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+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.
+    module Extractor
+      # Given conversation messages, return Array<Record> of candidate memories.
+      def extract(messages:, scope:)
+        raise NotImplementedError, "Extractor arrives in v0.2"
+      end
+    end
+  end
+end

data/lib/engram/ports/memory_store.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Engram
+  module Ports
+    # Contract for a place memories are persisted and searched.
+    # Implementations: Adapters::InMemoryStore, Adapters::PgvectorStore.
+    module MemoryStore
+      # Persist a Record. Returns the stored Record.
+      def add(record)
+        raise NotImplementedError, "#{self.class} must implement #add"
+      end
+
+      # Return up to `limit` Records in `scope` nearest to `embedding`,
+      # ordered most-relevant first.
+      def search(embedding:, scope:, limit:)
+        raise NotImplementedError, "#{self.class} must implement #search"
+      end
+
+      # All Records for a scope (mostly for inspection/tests).
+      def all(scope:)
+        raise NotImplementedError, "#{self.class} must implement #all"
+      end
+
+      # Replace the content/embedding of an existing memory. Used by consolidation
+      # (UPDATE). Returns the updated Record.
+      def update(id:, record:)
+        raise NotImplementedError, "#{self.class} must implement #update"
+      end
+
+      # Remove a memory by id. Used by consolidation (FORGET).
+      def delete(id:)
+        raise NotImplementedError, "#{self.class} must implement #delete"
+      end
+
+      # Update the last-accessed timestamp of a memory. Used by recency-aware recall.
+      def touch(id:, at: Time.now)
+        raise NotImplementedError, "#{self.class} must implement #touch"
+      end
+    end
+  end
+end

data/lib/engram/ports/processed_turns.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Engram
+  module Ports
+    # Contract for remembering which turns have already been observed, so observation is
+    # idempotent across retries and accidental double-calls.
+    # Implementations: Adapters::InMemoryProcessedTurns, Rails::CacheProcessedTurns.
+    module ProcessedTurns
+      # Has this idempotency key already been processed?
+      def seen?(key)
+        raise NotImplementedError, "#{self.class} must implement #seen?"
+      end
+
+      # Mark this idempotency key as processed.
+      def record(key)
+        raise NotImplementedError, "#{self.class} must implement #record"
+      end
+    end
+  end
+end

data/lib/engram/rails/cache_processed_turns.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Engram
+  module Rails
+    # ProcessedTurns backed by Rails.cache. Idempotency survives across processes and job
+    # retries when a shared cache (e.g. Solid Cache) is configured.
+    class CacheProcessedTurns
+      include Engram::Ports::ProcessedTurns
+
+      def initialize(namespace: "engram:processed_turns", ttl: 86_400)
+        @namespace = namespace
+        @ttl = ttl
+      end
+
+      def seen?(key)
+        ::Rails.cache.exist?(cache_key(key))
+      end
+
+      def record(key)
+        ::Rails.cache.write(cache_key(key), true, expires_in: @ttl)
+        key
+      end
+
+      private
+
+      def cache_key(key)
+        "#{@namespace}:#{key}"
+      end
+    end
+  end
+end

data/lib/engram/rails/has_memory.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Engram
+  module Rails
+    # Class-level macro added to ActiveRecord models.
+    #
+    #   class User < ApplicationRecord
+    #     has_memory                      # scope => "user:<id>"
+    #   end
+    #
+    #   class Account < ApplicationRecord
+    #     has_memory scope: ->{ "team:#{team_id}" }
+    #   end
+    #
+    # `user.memory` returns an Engram::Memory bound to that owner.
+    module HasMemory
+      def has_memory(scope: nil)
+        scope_proc = scope
+
+        define_method(:memory) do
+          key =
+            if scope_proc
+              instance_exec(&scope_proc)
+            else
+              "#{self.class.name.underscore}:#{id}"
+            end
+          Engram::Memory.new(scope: key)
+        end
+      end
+    end
+  end
+end

data/lib/engram/rails/observe_job.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Engram
+  # Background observation: runs extract → consolidate off the request path.
+  # Defined only when ActiveJob is available (loaded via the Railtie).
+  class ObserveJob < ActiveJob::Base
+    def perform(scope, messages)
+      Engram::Memory.new(scope: scope).observe(messages)
+    end
+  end
+end

data/lib/engram/railtie.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require_relative "rails/cache_processed_turns"
+
+module Engram
+  # Wires engram into Rails: the `has_memory` macro on ActiveRecord models and the
+  # background ObserveJob on ActiveJob. Loaded only when Rails is present (see lib/engram.rb).
+  class Railtie < ::Rails::Railtie
+    initializer "engram.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        require "engram/rails/has_memory"
+        extend Engram::Rails::HasMemory
+      end
+    end
+
+    initializer "engram.active_job" do
+      ActiveSupport.on_load(:active_job) do
+        require "engram/rails/observe_job"
+      end
+    end
+  end
+end

data/lib/engram/record.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Engram
+  # A single unit of memory.
+  #
+  # `id` is assigned by the store on persistence (nil until then); consolidation uses it
+  # to target UPDATE/FORGET. `scope` namespaces memories to an owner (e.g. "user:42").
+  # `kind` is a memory type (semantic / episodic / preference).
+  class Record
+    attr_accessor :id, :last_accessed_at
+    attr_reader :content, :embedding, :scope, :kind, :importance, :metadata,
+      :created_at
+
+    def initialize(content:, scope:, id: nil, embedding: nil, kind: :semantic,
+      importance: 1.0, metadata: {}, created_at: nil, last_accessed_at: nil)
+      @id = id
+      @content = content
+      @scope = scope
+      @embedding = embedding
+      @kind = kind
+      @importance = importance
+      @metadata = metadata
+      @created_at = created_at || Time.now
+      @last_accessed_at = last_accessed_at
+    end
+
+    def to_h
+      {
+        id: id, content: content, scope: scope, embedding: embedding, kind: kind,
+        importance: importance, metadata: metadata,
+        created_at: created_at, last_accessed_at: last_accessed_at
+      }
+    end
+  end
+end

data/lib/engram/turn_digest.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Engram
+  # Produces a stable digest for a conversation turn (scope + messages). Used as an
+  # idempotency key so the same turn is not observed twice.
+  module TurnDigest
+    module_function
+
+    def digest(scope:, messages:)
+      normalized = Array(messages).map { |message| normalize(message) }
+      Digest::SHA256.hexdigest(JSON.generate(scope: scope, messages: normalized))
+    end
+
+    def normalize(message)
+      if message.is_a?(Hash)
+        {
+          role: (message[:role] || message["role"] || "user").to_s,
+          content: (message[:content] || message["content"]).to_s
+        }
+      else
+        {role: "user", content: message.to_s}
+      end
+    end
+  end
+end