spurline-dashboard 0.3.0

data/lib/spurline/memory/embedder/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Memory
+    module Embedder
+      class Base
+        def embed(_text)
+          raise NotImplementedError, "#{self.class.name} must implement #embed"
+        end
+
+        def dimensions
+          raise NotImplementedError, "#{self.class.name} must implement #dimensions"
+        end
+      end
+    end
+  end
+end

data/lib/spurline/memory/embedder/open_ai.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Memory
+    module Embedder
+      class OpenAI < Base
+        DEFAULT_MODEL = "text-embedding-3-small"
+        DIMENSIONS = 1536
+
+        def initialize(api_key: nil, model: nil)
+          @api_key = resolve_api_key(api_key)
+          @model = model || DEFAULT_MODEL
+        end
+
+        def embed(text)
+          # ASYNC-READY: Embedding requests are blocking in v1 and run at this seam.
+          response = build_client.embeddings(parameters: { model: @model, input: text.to_s })
+          embedding = response.dig("data", 0, "embedding")
+
+          if embedding.is_a?(Array) && embedding.all? { |value| value.is_a?(Numeric) }
+            embedding
+          else
+            raise Spurline::EmbedderError,
+              "OpenAI embedding response did not include a valid embedding vector"
+          end
+        rescue Spurline::EmbedderError
+          raise
+        rescue StandardError => e
+          raise Spurline::EmbedderError, "OpenAI embedding failed: #{e.message}"
+        end
+
+        def dimensions
+          DIMENSIONS
+        end
+
+        private
+
+        def resolve_api_key(explicit_key)
+          candidates = [
+            explicit_key,
+            ENV.fetch("OPENAI_API_KEY", nil),
+            Spurline.credentials["openai_api_key"],
+          ]
+          key = candidates.find { |value| present_string?(value) }
+          return key if key
+
+          raise Spurline::ConfigurationError,
+            "Missing OpenAI API key for embedding model :openai. " \
+            "Set OPENAI_API_KEY, add openai_api_key to Spurline.credentials, " \
+            "or pass api_key:."
+        end
+
+        def present_string?(value)
+          return false if value.nil?
+          return !value.strip.empty? if value.respond_to?(:strip)
+
+          true
+        end
+
+        def build_client
+          require "openai"
+          ::OpenAI::Client.new(access_token: @api_key)
+        rescue LoadError
+          raise Spurline::EmbedderError,
+            "The 'openai' gem is required for embedding_model :openai"
+        end
+      end
+    end
+  end
+end

data/lib/spurline/memory/episode.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Spurline
+  module Memory
+    # Immutable value object representing one structured event in an agent session.
+    class Episode
+      attr_reader :id, :type, :content, :metadata, :timestamp, :turn_number, :parent_episode_id
+
+      def initialize(
+        type:,
+        content:,
+        metadata: {},
+        timestamp: Time.now,
+        turn_number: nil,
+        parent_episode_id: nil,
+        id: SecureRandom.uuid
+      )
+        @id = id.to_s
+        @type = type.to_sym
+        @content = content
+        @metadata = (metadata || {}).dup.freeze
+        @timestamp = timestamp
+        @turn_number = turn_number
+        @parent_episode_id = parent_episode_id
+        freeze
+      end
+
+      def to_h
+        {
+          id: id,
+          type: type,
+          content: content,
+          metadata: metadata,
+          timestamp: timestamp,
+          turn_number: turn_number,
+          parent_episode_id: parent_episode_id,
+        }
+      end
+
+      def self.from_h(data)
+        hash = data.transform_keys(&:to_sym)
+        new(
+          id: hash[:id],
+          type: hash.fetch(:type),
+          content: hash[:content],
+          metadata: hash[:metadata] || {},
+          timestamp: hash[:timestamp] || Time.now,
+          turn_number: hash[:turn_number],
+          parent_episode_id: hash[:parent_episode_id]
+        )
+      end
+    end
+  end
+end

data/lib/spurline/memory/episodic_store.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Memory
+    # Structured per-session trace for replay and explainability.
+    class EpisodicStore
+      attr_reader :enabled
+
+      def initialize(enabled: true, episodes: [])
+        @enabled = enabled
+        @episodes = Array(episodes).map { |episode| coerce_episode(episode) }
+      end
+
+      def record(type:, content:, metadata: {}, turn_number: nil, parent_episode_id: nil, timestamp: Time.now)
+        return nil unless enabled
+
+        episode = Episode.new(
+          type: type,
+          content: content,
+          metadata: metadata,
+          timestamp: timestamp,
+          turn_number: turn_number,
+          parent_episode_id: parent_episode_id
+        )
+        @episodes << episode
+        episode
+      end
+
+      def all
+        @episodes.dup
+      end
+
+      def count
+        @episodes.length
+      end
+
+      def empty?
+        @episodes.empty?
+      end
+
+      def clear!
+        @episodes.clear
+      end
+
+      def for_turn(turn_number)
+        @episodes.select { |episode| episode.turn_number == turn_number }
+      end
+
+      def tool_calls
+        by_type(:tool_call)
+      end
+
+      def decisions
+        by_type(:decision)
+      end
+
+      def external_data
+        by_type(:external_data)
+      end
+
+      def user_messages
+        by_type(:user_message)
+      end
+
+      def assistant_responses
+        by_type(:assistant_response)
+      end
+
+      def find(id)
+        @episodes.find { |episode| episode.id == id }
+      end
+
+      def serialize
+        @episodes.map(&:to_h)
+      end
+
+      def restore(serialized_episodes)
+        @episodes = Array(serialized_episodes).map { |episode| coerce_episode(episode) }
+        self
+      end
+
+      def explain
+        return "No episodes recorded." if @episodes.empty?
+
+        @episodes.sort_by(&:timestamp).map do |episode|
+          turn_label = episode.turn_number ? "Turn #{episode.turn_number}" : "Turn ?"
+          "#{turn_label} | #{episode_label(episode)}#{episode_parent_label(episode)}"
+        end.join("\n")
+      end
+
+      private
+
+      def by_type(type)
+        target = type.to_sym
+        @episodes.select { |episode| episode.type == target }
+      end
+
+      def coerce_episode(episode)
+        return episode if episode.is_a?(Episode)
+
+        Episode.from_h(episode)
+      end
+
+      def episode_label(episode)
+        case episode.type
+        when :user_message
+          "User message: #{summarize(episode.content)}"
+        when :decision
+          decision = episode.metadata[:decision] || episode.metadata["decision"] || "decision"
+          "Decision (#{decision}): #{summarize(episode.content)}"
+        when :tool_call
+          tool_name = episode.metadata[:tool_name] || episode.metadata["tool_name"] || "unknown_tool"
+          "Tool call #{tool_name}: #{summarize(episode.content)}"
+        when :external_data
+          source = episode.metadata[:source] || episode.metadata["source"] || "external"
+          "External data (#{source}): #{summarize(episode.content)}"
+        when :assistant_response
+          "Assistant response: #{summarize(episode.content)}"
+        else
+          "#{episode.type}: #{summarize(episode.content)}"
+        end
+      end
+
+      def episode_parent_label(episode)
+        return "" unless episode.parent_episode_id
+
+        " [after #{episode.parent_episode_id}]"
+      end
+
+      def summarize(content)
+        text = case content
+               when Spurline::Security::Content
+                 content.text
+               when String
+                 content
+               else
+                 content.inspect
+               end
+
+        cleaned = text.to_s.gsub(/\s+/, " ").strip
+        return cleaned if cleaned.length <= 120
+
+        "#{cleaned[0, 117]}..."
+      end
+    end
+  end
+end

data/lib/spurline/memory/long_term/CLAUDE.md

@@ -0,0 +1,11 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+### Feb 21, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #3664 | 8:45 PM | 🔵 | Spurline Milestone 1 implementation status audit completed | ~598 |
+</claude-mem-context>

data/lib/spurline/memory/long_term/base.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Memory
+    module LongTerm
+      class Base
+        def store(content:, metadata: {})
+          raise NotImplementedError, "#{self.class.name} must implement #store"
+        end
+
+        # Returns an array of Security::Content objects at :operator trust.
+        def retrieve(query:, limit: 5)
+          raise NotImplementedError, "#{self.class.name} must implement #retrieve"
+        end
+
+        def clear!
+          raise NotImplementedError, "#{self.class.name} must implement #clear!"
+        end
+      end
+    end
+  end
+end

data/lib/spurline/memory/long_term/postgres.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Spurline
+  module Memory
+    module LongTerm
+      class Postgres < Base
+        TABLE_NAME = "spurline_memories"
+
+        def initialize(connection_string:, embedder:)
+          @connection_string = connection_string
+          @embedder = embedder
+          @connection = nil
+        end
+
+        def store(content:, metadata: {})
+          embedding = @embedder.embed(content)
+          session_id = metadata[:session_id] || metadata["session_id"]
+          sql = <<~SQL
+            INSERT INTO #{TABLE_NAME} (session_id, content, embedding, metadata)
+            VALUES ($1, $2, $3::vector, $4::jsonb)
+          SQL
+          params = [
+            session_id,
+            content,
+            vector_literal(embedding),
+            JSON.generate(metadata),
+          ]
+
+          # ASYNC-READY: Database writes are synchronous in v1 at this boundary.
+          connection.exec_params(sql, params)
+        rescue StandardError => e
+          raise Spurline::LongTermMemoryError, "Failed storing long-term memory: #{e.message}"
+        end
+
+        def retrieve(query:, limit: 5)
+          query_embedding = @embedder.embed(query)
+          sql = <<~SQL
+            SELECT content, metadata
+            FROM #{TABLE_NAME}
+            ORDER BY embedding <-> $1::vector
+            LIMIT $2
+          SQL
+          params = [vector_literal(query_embedding), limit]
+          # ASYNC-READY: Database reads are synchronous in v1 at this boundary.
+          result = connection.exec_params(sql, params)
+
+          result.map do |row|
+            Security::Content.new(
+              text: row["content"],
+              trust: :operator,
+              source: "memory:long_term"
+            )
+          end
+        rescue StandardError => e
+          raise Spurline::LongTermMemoryError, "Failed retrieving long-term memory: #{e.message}"
+        end
+
+        def clear!
+          connection.exec("DELETE FROM #{TABLE_NAME}")
+        rescue StandardError => e
+          raise Spurline::LongTermMemoryError, "Failed clearing long-term memory: #{e.message}"
+        end
+
+        def create_table!
+          dim = @embedder.dimensions
+
+          connection.exec("CREATE EXTENSION IF NOT EXISTS vector")
+          connection.exec(<<~SQL)
+            CREATE TABLE IF NOT EXISTS #{TABLE_NAME} (
+              id BIGSERIAL PRIMARY KEY,
+              session_id TEXT,
+              content TEXT NOT NULL,
+              embedding vector(#{dim}) NOT NULL,
+              metadata JSONB DEFAULT '{}',
+              created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+          SQL
+          connection.exec(<<~SQL)
+            CREATE INDEX IF NOT EXISTS idx_#{TABLE_NAME}_session_id
+            ON #{TABLE_NAME} (session_id)
+          SQL
+        rescue StandardError => e
+          raise Spurline::LongTermMemoryError, "Failed creating long-term memory schema: #{e.message}"
+        end
+
+        private
+
+        def vector_literal(embedding)
+          "[#{embedding.join(",")}]"
+        end
+
+        def connection
+          @connection ||= begin
+            require "pg"
+            PG.connect(@connection_string)
+          rescue LoadError
+            raise Spurline::LongTermMemoryError,
+              "The 'pg' gem is required for long-term memory adapter :postgres"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spurline/memory/manager.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Memory
+    # Orchestrates short-term and long-term memory stores.
+    class Manager
+      attr_reader :short_term, :long_term, :episodic
+
+      def initialize(config: {})
+        window = config.fetch(:short_term, {}).fetch(:window, ShortTerm::DEFAULT_WINDOW)
+        @short_term = ShortTerm.new(window: window)
+        @long_term = build_long_term_store(config.fetch(:long_term, nil))
+        @episodic = build_episodic_store(config.fetch(:episodic, nil))
+      end
+
+      def add_turn(turn)
+        evicted_before = short_term.last_evicted
+        short_term.add_turn(turn)
+
+        evicted_turn = short_term.last_evicted
+        if long_term && evicted_turn && !evicted_turn.equal?(evicted_before)
+          persist_to_long_term!(evicted_turn)
+        end
+      end
+
+      def recent_turns(n = nil)
+        short_term.recent(n)
+      end
+
+      def turn_count
+        short_term.size
+      end
+
+      def recall(query:, limit: 5)
+        return [] unless long_term
+
+        long_term.retrieve(query: query, limit: limit)
+      end
+
+      def clear!
+        short_term.clear!
+        long_term&.clear!
+        episodic&.clear!
+      end
+
+      # Whether any turns have been evicted from the window.
+      # Useful for determining if summarization should kick in.
+      def window_overflowed?
+        !short_term.last_evicted.nil?
+      end
+
+      def record_episode(type:, content:, metadata: {}, turn_number: nil, parent_episode_id: nil, timestamp: Time.now)
+        return nil unless episodic
+
+        episodic.record(
+          type: type,
+          content: content,
+          metadata: metadata,
+          turn_number: turn_number,
+          parent_episode_id: parent_episode_id,
+          timestamp: timestamp
+        )
+      end
+
+      def restore_episodes(serialized_episodes)
+        return unless episodic
+
+        episodic.restore(serialized_episodes)
+      end
+
+      private
+
+      def build_long_term_store(config)
+        return nil unless config
+
+        adapter = config[:adapter]
+        case adapter
+        when :postgres
+          embedder = build_embedder(config)
+          LongTerm::Postgres.new(connection_string: config[:connection_string], embedder: embedder)
+        when nil
+          nil
+        else
+          return adapter if adapter.respond_to?(:store) && adapter.respond_to?(:retrieve)
+
+          raise Spurline::ConfigurationError,
+            "Unknown long-term memory adapter: #{adapter.inspect}."
+        end
+      end
+
+      def build_embedder(config)
+        model = config[:embedding_model] || config[:embedder]
+
+        case model
+        when :openai
+          Embedder::OpenAI.new
+        when nil
+          raise Spurline::ConfigurationError,
+            "Long-term memory requires an embedding_model. " \
+            "Example: memory :long_term, adapter: :postgres, embedding_model: :openai"
+        else
+          return model if model.respond_to?(:embed) && model.respond_to?(:dimensions)
+
+          raise Spurline::ConfigurationError,
+            "Unknown embedding model: #{model.inspect}."
+        end
+      end
+
+      def persist_to_long_term!(turn)
+        text_parts = []
+        text_parts << extract_text(turn.input) if turn.input
+        text_parts << extract_text(turn.output) if turn.output
+        content_text = text_parts.join("\n")
+        return if content_text.strip.empty?
+
+        long_term.store(content: content_text, metadata: { turn_number: turn.number })
+      end
+
+      def build_episodic_store(config)
+        enabled = case config
+                  when nil
+                    true
+                  when true, false
+                    config
+                  when Hash
+                    config.fetch(:enabled, true)
+                  else
+                    !!config
+                  end
+
+        episodes = config.is_a?(Hash) ? config.fetch(:episodes, []) : []
+        EpisodicStore.new(enabled: enabled, episodes: episodes)
+      end
+
+      def extract_text(value)
+        case value
+        when Security::Content
+          value.text
+        when String
+          value
+        else
+          value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/spurline/memory/short_term.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Memory
+    # Sliding window of recent turns. Holds Turn objects with their Content
+    # (input/output) carrying inherited trust levels.
+    #
+    # When the window overflows, oldest turns are evicted. The last evicted
+    # turn is available via #last_evicted for potential summarization.
+    class ShortTerm
+      DEFAULT_WINDOW = 20
+
+      attr_reader :window_size, :last_evicted
+
+      def initialize(window: DEFAULT_WINDOW)
+        @window_size = window
+        @turns = []
+        @last_evicted = nil
+      end
+
+      def add_turn(turn)
+        @turns << turn
+        trim!
+      end
+
+      # Returns recent turns as an array, most recent last.
+      def recent(n = nil)
+        n ? @turns.last(n) : @turns.dup
+      end
+
+      def size
+        @turns.length
+      end
+
+      def full?
+        @turns.length >= @window_size
+      end
+
+      def empty?
+        @turns.empty?
+      end
+
+      def clear!
+        @turns.clear
+        @last_evicted = nil
+      end
+
+      private
+
+      def trim!
+        while @turns.length > window_size
+          @last_evicted = @turns.shift
+        end
+      end
+    end
+  end
+end