engram 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9afed525e71087af57cf1297cc80b4547abbe4df9e1077282ba0427cfeb5a708
+  data.tar.gz: 461907e0eafb4bed9442475a0bea0c2830cff62ac55291b7dc3eb9aeb8930b52
+SHA512:
+  metadata.gz: d1fc61bad8a535990c93aa6f12401ffa4a18605357e1782b9e41be4a3d6ddbd9b4a00f805dba904c987db74a65773952cbfad806a60dfbe49a12e3b899cdbb16
+  data.tar.gz: 771b6d7030dd2ae664457c7eba01c7edd1f80f82af5a5566e57c93a97cf9bd1ab34077b638508789e40c7a3128645c0cfc7391fe5fd26d79dec22162696218f8

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-05-25 — idempotency, smarter recall, forgetting
+
+### Added
+- Idempotent observation: `ProcessedTurns` port, `InMemoryProcessedTurns`,
+  `Rails::CacheProcessedTurns`, and a stable `TurnDigest`. A repeated turn is skipped.
+- Recall ranking options: `importance_weight`, `recency_weight`, and `recency_halflife`,
+  blended on top of vector similarity (defaults keep plain similarity search).
+- `touch_on_recall` and `MemoryStore#touch` to update `last_accessed_at` on recall.
+- `UseCases::Forget` and `Memory#forget_stale` to prune memories by age and importance.
+
+## [0.2.0] — extract → consolidate
+
+### Added
+- `Completion` port for structured LLM calls; adapters `RubyLLMCompletion` and `FakeCompletion`.
+- `Extractors::LLMExtractor` — derives durable, user-specific facts from a turn (schema + confidence threshold).
+- `Consolidators::HeuristicConsolidator` (deterministic, dedup) and `Consolidators::LLMConsolidator`
+  (LLM-as-judge, batched ADD / UPDATE / FORGET / NOOP).
+- `UseCases::Observe` orchestrator; `Memory#observe` / `Memory#observe_later`.
+- `Decision` value object; `MemoryStore#update`/`#delete`; record ids.
+- Rails `ObserveJob` for background observation.
+- Consolidation dedup check in the eval harness.
+
+## [0.1.0] — recall + inject foundation
+
+### Added
+- Ports-and-adapters core: `Record`, `MemoryStore`/`Embedder` ports, `Recall`/`Inject` use cases.
+- Built-in adapters: `InMemoryStore`, `NullEmbedder` (zero-config, test-friendly).
+- Optional adapters: `PgvectorStore` (neighbor), `RubyLLMEmbedder`.
+- `Engram::Memory` facade and Rails `has_memory` macro.
+- RubyLLM integration: `Engram.with_memory(chat, memory:)`.
+- Install generator (migration + initializer + model).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandr Kholodniak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,202 @@
+# Engram
+
+Long-term memory for AI agents in Ruby — stored in **your own** Postgres.
+
+Engram lets an agent remember a user across sessions. It recalls the facts relevant to the
+current message and injects them into the prompt, so the model stops asking the same
+questions twice. No external memory-as-a-service: your memories live in your database.
+
+> Status: pre-1.0. Two things are implemented and tested: recall with prompt injection
+> (v0.1), and extracting and consolidating memories from conversations (v0.2). The public
+> API may still change before 1.0.
+
+## Why
+
+LLMs are stateless. Every request starts from zero, so an assistant forgets that the user
+is on the Pro plan, is vegetarian, or already tried clearing the cache. The usual fixes
+fall short: stuffing whole transcripts into the prompt is expensive and noisy, and plain
+RAG retrieves documents, not personal facts. Engram is the memory layer in between.
+
+## Before and after
+
+Without a memory layer, every session starts blank:
+
+```text
+Day 1
+  User:  I'm on the Pro plan, and please keep answers short.
+  Agent: Got it.
+
+Day 5 (new session — the model has forgotten)
+  User:  Why am I being rate limited?
+  Agent: Which plan are you on? Can you share more about your setup?
+```
+
+With engram, the facts from day 1 are recalled and added to the prompt before the model answers:
+
+```ruby
+# Day 1: engram extracts and stores
+#   "User is on the Pro plan", "User prefers short answers"
+current_user.memory.observe(conversation)
+
+# Day 5: engram recalls the relevant facts, then asks the model
+chat = Engram.with_memory(RubyLLM.chat, memory: current_user.memory)
+chat.ask("Why am I being rate limited?")
+```
+
+```text
+  Agent: You're on the Pro plan, which has a per-minute request cap, and you're
+         hitting it. (Kept short, as you prefer.)
+```
+
+## Installation
+
+```ruby
+# Gemfile
+gem "engram"
+```
+
+The core has **zero runtime dependencies**. Optional adapters need:
+
+- `Engram::Adapters::PgvectorStore` → `neighbor` + ActiveRecord + Postgres/pgvector
+- `Engram::Adapters::RubyLLMEmbedder` → `ruby_llm`
+
+## Quick start (plain Ruby)
+
+```ruby
+require "engram"
+
+memory = Engram::Memory.new(scope: "user:42")  # zero-config: in-memory + null embedder
+
+memory.add("Subscription tier is Pro")
+memory.add("Prefers concise answers")
+
+memory.recall("why am I being rate limited?")
+# => [#<Engram::Record content="Subscription tier is Pro" ...>]
+```
+
+## Rails
+
+```bash
+bin/rails generate engram:install   # migration + initializer + model
+bin/rails db:migrate
+```
+
+```ruby
+class User < ApplicationRecord
+  has_memory      # scope defaults to "user:<id>"
+end
+
+current_user.memory.add("Works at Acme Corp")
+current_user.memory.recall("where does the user work?")
+```
+
+## RubyLLM integration
+
+```ruby
+chat = Engram.with_memory(RubyLLM.chat, memory: current_user.memory)
+chat.ask("why am I being rate limited?")
+# recall + inject happen automatically before the model sees the message
+```
+
+## Automatic memory (v0.2)
+
+Instead of adding facts by hand, let engram derive them from a conversation turn. It
+extracts candidate facts, then consolidates them against what's already known —
+add / update / forget / noop.
+
+```ruby
+Engram.configure do |config|
+  config.completion = Engram::Adapters::RubyLLMCompletion.new
+  config.consolidator = :llm   # or :heuristic for deterministic, no-LLM dedup
+end
+
+memory = current_user.memory
+memory.observe([
+  {role: "user", content: "I switched from the Free plan to Pro"}
+])
+# extracts "User is on the Pro plan", and if a "Free plan" memory exists, updates it
+```
+
+In Rails, run it off the request path: `current_user.memory.observe_later(messages)`.
+
+## Tuning and maintenance (v0.3)
+
+Observation is idempotent per turn: observing the same messages twice does nothing the
+second time, so retries do not create duplicate memories or repeat LLM calls. In Rails,
+use a persistent store so this also holds across job retries and processes:
+
+```ruby
+Engram.configure do |c|
+  c.processed_turns = Engram::Rails::CacheProcessedTurns.new
+end
+```
+
+Recall is plain similarity search by default. You can blend in importance and recency:
+
+```ruby
+Engram.configure do |c|
+  c.importance_weight = 0.3
+  c.recency_weight = 0.2
+  c.touch_on_recall = true   # update last_accessed_at when a memory is recalled
+end
+```
+
+Prune memories you no longer need:
+
+```ruby
+# Forget memories untouched for 90 days, but keep anything important
+current_user.memory.forget_stale(older_than: 90 * 24 * 60 * 60, min_importance: 0.7)
+```
+
+## How it works
+
+A loop around your LLM calls. Before a call: recall relevant memories and inject them.
+After a turn (v0.2): extract new facts, consolidate them, and persist. The store
+(Postgres + pgvector) is the only thing that persists between sessions.
+
+## Architecture
+
+Ports-and-adapters. A pure-Ruby core depends on `MemoryStore` and `Embedder` ports;
+pgvector, RubyLLM, and Rails are swappable adapters. This keeps the domain fast to test
+(in-memory + null adapters, no DB or API keys) and lets the v0.2 `Extractor`/`Consolidator`
+slot in without rework.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec          # unit suite (no DB, no network)
+bundle exec standardrb     # lint
+bundle exec rake eval      # recall quality harness (precision@k)
+```
+
+Integration tests exercise the real Postgres + pgvector adapter (tagged `:integration`,
+skipped by default):
+
+```bash
+DATABASE_URL=postgres://postgres:postgres@localhost:5432/engram_test \
+  bundle exec rspec --tag integration
+```
+
+For honest recall numbers, run the eval with a real embedder instead of the test stub.
+`ruby_llm` is not a dependency, so install it separately first:
+
+```bash
+gem install ruby_llm
+ENGRAM_EMBEDDER=ruby_llm OPENAI_API_KEY=... ruby eval/run.rb
+```
+
+On the bundled fixture set, recall@3 is 100% (4/4) with OpenAI's text-embedding-3-small,
+and the consolidation dedup checks pass. The fixture is deliberately small. Treat it as a
+retrieval smoke test, not a benchmark.
+
+## Roadmap
+
+- v0.1 (done): recall + inject foundation, adapters, Rails + RubyLLM integration.
+- v0.2 (done): extract and consolidate (ADD / UPDATE / FORGET), background jobs.
+- v0.3 (done): idempotent observation, importance/recency recall, forgetting and decay.
+- later: memory types per policy, additional storage backends, larger eval benchmarks.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/engram/adapters/fake_completion.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Engram
+  module Adapters
+    # Deterministic Completion for tests. Returns queued responses (already-parsed Hashes)
+    # in order, and records every call so specs can assert on the prompts/schemas sent.
+    class FakeCompletion
+      include Ports::Completion
+
+      attr_reader :calls
+
+      def initialize(responses: [])
+        @responses = responses.dup
+        @calls = []
+      end
+
+      def enqueue(response)
+        @responses << response
+        self
+      end
+
+      def complete(system:, user:, schema:)
+        @calls << {system: system, user: user, schema: schema}
+        if @responses.empty?
+          raise Engram::Error, "FakeCompletion: no scripted response left (call ##{@calls.size})"
+        end
+
+        @responses.shift
+      end
+    end
+  end
+end

data/lib/engram/adapters/in_memory_processed_turns.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Engram
+  module Adapters
+    # In-process ProcessedTurns. The zero-config default; guards against double-processing
+    # within a single process. For cross-process/retry durability in Rails, use a persistent
+    # adapter such as Rails::CacheProcessedTurns.
+    class InMemoryProcessedTurns
+      include Ports::ProcessedTurns
+
+      def initialize
+        @keys = Set.new
+      end
+
+      def seen?(key)
+        @keys.include?(key)
+      end
+
+      def record(key)
+        @keys << key
+        key
+      end
+
+      def clear
+        @keys.clear
+      end
+    end
+  end
+end

data/lib/engram/adapters/in_memory_store.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Engram
+  module Adapters
+    # In-process MemoryStore. Used as the zero-config default and in unit tests.
+    # Search is exact cosine similarity over the stored vectors.
+    class InMemoryStore
+      include Ports::MemoryStore
+
+      def initialize
+        @records = {}
+        @sequence = 0
+      end
+
+      def add(record)
+        record.id ||= (@sequence += 1)
+        @records[record.id] = record
+        record
+      end
+
+      def search(embedding:, scope:, limit:)
+        @records
+          .values
+          .select { |r| r.scope == scope && r.embedding }
+          .map { |r| [r, Engram::Math.cosine_similarity(embedding, r.embedding)] }
+          .sort_by { |(_, score)| -score }
+          .first(limit)
+          .map { |(record, _)| record }
+      end
+
+      def all(scope:)
+        @records.values.select { |r| r.scope == scope }
+      end
+
+      def update(id:, record:)
+        raise Engram::Error, "no memory with id #{id.inspect}" unless @records.key?(id)
+
+        record.id = id
+        @records[id] = record
+      end
+
+      def delete(id:)
+        @records.delete(id)
+      end
+
+      def touch(id:, at: Time.now)
+        record = @records[id]
+        record.last_accessed_at = at if record
+        record
+      end
+
+      def clear
+        @records.clear
+        @sequence = 0
+      end
+    end
+  end
+end

data/lib/engram/adapters/null_embedder.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Engram
+  module Adapters
+    # Deterministic, network-free embedder for tests and the zero-config default.
+    # NOT semantic — equal text yields equal vectors, but unrelated text is not
+    # meaningfully close. Good enough to exercise the pipeline; useless for quality.
+    class NullEmbedder
+      include Ports::Embedder
+
+      def initialize(dimensions: 16)
+        @dimensions = dimensions
+      end
+
+      attr_reader :dimensions
+
+      def embed(text)
+        seed = Digest::SHA256.hexdigest(text.to_s)
+        Array.new(@dimensions) do |i|
+          byte = seed[(i * 2) % seed.length, 2].to_i(16)
+          (byte / 255.0) * 2 - 1 # map 0..255 -> -1.0..1.0
+        end
+      end
+    end
+  end
+end

data/lib/engram/adapters/pgvector_store.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Engram
+  module Adapters
+    # MemoryStore backed by PostgreSQL + pgvector via the `neighbor` gem.
+    #
+    # Requires the host app to provide ActiveRecord, the `neighbor` gem, and an AR model
+    # (default: Engram::MemoryRecord) created by the install generator. These are NOT hard
+    # dependencies of engram; this adapter only references them at call time.
+    class PgvectorStore
+      include Ports::MemoryStore
+
+      def initialize(model: nil)
+        @model = model
+      end
+
+      def add(record)
+        row = model.create!(
+          content: record.content,
+          scope: record.scope,
+          kind: record.kind.to_s,
+          importance: record.importance,
+          metadata: record.metadata,
+          embedding: record.embedding
+        )
+        to_record(row)
+      end
+
+      def search(embedding:, scope:, limit:)
+        model
+          .where(scope: scope)
+          .nearest_neighbors(:embedding, embedding, distance: "cosine")
+          .limit(limit)
+          .map { |row| to_record(row) }
+      end
+
+      def all(scope:)
+        model.where(scope: scope).map { |row| to_record(row) }
+      end
+
+      def update(id:, record:)
+        row = model.find(id)
+        row.update!(
+          content: record.content,
+          kind: record.kind.to_s,
+          importance: record.importance,
+          metadata: record.metadata,
+          embedding: record.embedding
+        )
+        to_record(row)
+      end
+
+      def delete(id:)
+        model.where(id: id).delete_all
+      end
+
+      def touch(id:, at: Time.now)
+        model.where(id: id).update_all(last_accessed_at: at)
+      end
+
+      private
+
+      def model
+        @model ||= resolve_default_model
+      end
+
+      def resolve_default_model
+        unless defined?(Engram::MemoryRecord)
+          raise Engram::Error,
+            "PgvectorStore needs an ActiveRecord model. Run the install generator or pass `model:`."
+        end
+        Engram::MemoryRecord
+      end
+
+      def to_record(row)
+        Engram::Record.new(
+          id: row.id,
+          content: row.content,
+          scope: row.scope,
+          embedding: row.embedding,
+          kind: (row.kind || :semantic).to_sym,
+          importance: row.importance || 1.0,
+          metadata: row.metadata || {},
+          created_at: row.created_at,
+          last_accessed_at: row.try(:last_accessed_at)
+        )
+      end
+    end
+  end
+end

data/lib/engram/adapters/ruby_llm_completion.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Engram
+  module Adapters
+    # Completion backed by RubyLLM structured output. Requires the host app to add the
+    # `ruby_llm` gem and configure credentials. Referenced only at call time.
+    #
+    # NOTE: exercised via integration tests, not the unit suite (which uses FakeCompletion).
+    class RubyLLMCompletion
+      include Ports::Completion
+
+      def initialize(model: nil)
+        @model = model
+      end
+
+      def complete(system:, user:, schema:)
+        ensure_ruby_llm!
+        chat = @model ? RubyLLM.chat(model: @model) : RubyLLM.chat
+        chat.with_instructions(system) if system
+        response = chat.with_schema(schema).ask(user)
+        coerce(response.content)
+      end
+
+      private
+
+      def coerce(content)
+        return content if content.is_a?(Hash)
+
+        require "json"
+        JSON.parse(content)
+      rescue JSON::ParserError => e
+        raise Engram::Error, "RubyLLMCompletion expected structured output: #{e.message}"
+      end
+
+      def ensure_ruby_llm!
+        return if defined?(RubyLLM)
+
+        raise Engram::Error,
+          "RubyLLMCompletion requires the `ruby_llm` gem. Add it to your Gemfile and configure it."
+      end
+    end
+  end
+end

data/lib/engram/adapters/ruby_llm_embedder.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Engram
+  module Adapters
+    # Embedder backed by RubyLLM. Requires the host app to add the `ruby_llm` gem and
+    # configure its credentials. Referenced only at call time, so engram loads without it.
+    class RubyLLMEmbedder
+      include Ports::Embedder
+
+      DEFAULT_MODEL = "text-embedding-3-small"
+      DEFAULT_DIMENSIONS = 1536
+
+      def initialize(model: DEFAULT_MODEL, dimensions: DEFAULT_DIMENSIONS)
+        @model = model
+        @dimensions = dimensions
+      end
+
+      attr_reader :dimensions
+
+      def embed(text)
+        ensure_ruby_llm!
+        RubyLLM.embed(text, model: @model).vectors
+      end
+
+      private
+
+      def ensure_ruby_llm!
+        return if defined?(RubyLLM)
+
+        raise Engram::Error,
+          "RubyLLMEmbedder requires the `ruby_llm` gem. Add it to your Gemfile and configure it."
+      end
+    end
+  end
+end

data/lib/engram/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Engram
+  # Holds the wired adapters and defaults. Out of the box everything works in memory,
+  # so the gem is usable (and testable) with zero infrastructure. In a Rails app the
+  # initializer typically swaps in PgvectorStore + RubyLLMEmbedder + RubyLLMCompletion.
+  class Configuration
+    attr_accessor :store, :embedder, :completion, :default_limit,
+      :consolidator, :extraction_min_confidence, :processed_turns,
+      :importance_weight, :recency_weight, :recency_halflife, :touch_on_recall
+
+    def initialize
+      @store = Adapters::InMemoryStore.new
+      @embedder = Adapters::NullEmbedder.new
+      @completion = nil # required for observe (extract/consolidate); nil until configured
+      @default_limit = 5
+      @consolidator = :heuristic # :heuristic (deterministic) or :llm (LLM-as-judge)
+      @extraction_min_confidence = 0.5
+      @processed_turns = Adapters::InMemoryProcessedTurns.new # idempotency for observe
+
+      # Recall ranking. With both weights at 0.0, recall is plain similarity search.
+      @importance_weight = 0.0
+      @recency_weight = 0.0
+      @recency_halflife = UseCases::Recall::DEFAULT_HALFLIFE
+      @touch_on_recall = false
+    end
+  end
+end

data/lib/engram/consolidators/heuristic_consolidator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Engram
+  module Consolidators
+    # Deterministic, no-LLM consolidation. ADDs a candidate unless a near-duplicate
+    # already exists (then NOOP). It cannot detect contradictions or updates — that is the
+    # LLMConsolidator's job. Useful as the default in tests and as a zero-cost fallback.
+    class HeuristicConsolidator
+      include Ports::Consolidator
+
+      def initialize(store:, similarity_threshold: 0.97)
+        @store = store
+        @similarity_threshold = similarity_threshold
+      end
+
+      def reconcile_all(candidates:, scope:)
+        Array(candidates).map do |candidate|
+          nearest = @store.search(embedding: candidate.embedding, scope: scope, limit: 1).first
+          similarity = nearest ? Engram::Math.cosine_similarity(candidate.embedding, nearest.embedding) : 0.0
+
+          if nearest && similarity >= @similarity_threshold
+            Engram::Decision.new(action: :noop, candidate: candidate,
+              reason: "near-duplicate (sim=#{similarity.round(3)})")
+          else
+            Engram::Decision.new(action: :add, candidate: candidate)
+          end
+        end
+      end
+    end
+  end
+end