supermemory 0.1.0

data/lib/supermemory/client.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+require "json"
+
+module Supermemory
+  class Client
+    RETRYABLE_STATUS_CODES = [408, 409, 429, 500, 502, 503, 504].freeze
+    INITIAL_RETRY_DELAY = 0.5
+    MAX_RETRY_DELAY = 8.0
+
+    attr_reader :api_key, :base_url, :timeout, :max_retries
+
+    # @param api_key [String, nil] API key (defaults to SUPERMEMORY_API_KEY env var)
+    # @param base_url [String, nil] Base URL (defaults to https://api.supermemory.ai)
+    # @param timeout [Integer] Request timeout in seconds (default: 60)
+    # @param max_retries [Integer] Max retry attempts (default: 2)
+    # @param extra_headers [Hash] Additional headers to send with every request
+    def initialize(api_key: nil, base_url: nil, timeout: nil, max_retries: nil, extra_headers: {})
+      config = Supermemory.configuration
+      @api_key = api_key || config.api_key
+      @base_url = base_url || config.base_url
+      @timeout = timeout || config.timeout
+      @max_retries = max_retries || config.max_retries
+      @extra_headers = extra_headers.merge(config.extra_headers)
+
+      unless @api_key
+        raise Supermemory::Error.new("API key is required. Set via Supermemory.configure or pass api_key:")
+      end
+    end
+
+    # Top-level convenience: add a document
+    # @param content [String] Text, URL, or file content
+    # @param options [Hash] Additional parameters (container_tag, custom_id, metadata, entity_context)
+    # @return [Hash] { "id" => "...", "status" => "..." }
+    def add(content:, **options)
+      documents.add(content: content, **options)
+    end
+
+    # Top-level convenience: get user profile
+    # @param container_tag [String] User/project identifier
+    # @param q [String, nil] Optional search query
+    # @param threshold [Float, nil] Score threshold for search results
+    # @return [Hash]
+    def profile(container_tag:, q: nil, threshold: nil)
+      body = { container_tag: container_tag }
+      body[:q] = q if q
+      body[:threshold] = threshold if threshold
+      post("/v4/profile", body)
+    end
+
+    # @return [Supermemory::Resources::Documents]
+    def documents
+      @documents ||= Resources::Documents.new(self)
+    end
+
+    # @return [Supermemory::Resources::Search]
+    def search
+      @search ||= Resources::Search.new(self)
+    end
+
+    # @return [Supermemory::Resources::Memories]
+    def memories
+      @memories ||= Resources::Memories.new(self)
+    end
+
+    # @return [Supermemory::Resources::Settings]
+    def settings
+      @settings ||= Resources::Settings.new(self)
+    end
+
+    # @return [Supermemory::Resources::Connections]
+    def connections
+      @connections ||= Resources::Connections.new(self)
+    end
+
+    # Low-level HTTP methods
+
+    # @param path [String]
+    # @param params [Hash, nil]
+    # @return [Hash, nil]
+    def get(path, params = nil)
+      request(:get, path, params: params)
+    end
+
+    # @param path [String]
+    # @param body [Hash, nil]
+    # @return [Hash, nil]
+    def post(path, body = nil)
+      request(:post, path, body: body)
+    end
+
+    # @param path [String]
+    # @param body [Hash, nil]
+    # @return [Hash, nil]
+    def patch(path, body = nil)
+      request(:patch, path, body: body)
+    end
+
+    # @param path [String]
+    # @param body [Hash, nil]
+    # @return [Hash, nil]
+    def delete(path, body = nil)
+      request(:delete, path, body: body)
+    end
+
+    # @param path [String]
+    # @param body [Hash]
+    # @return [Hash, nil]
+    def multipart_post(path, body)
+      request(:post, path, body: body, multipart: true)
+    end
+
+    private
+
+    def request(method, path, body: nil, params: nil, multipart: false)
+      attempts = 0
+
+      begin
+        response = connection(multipart: multipart).run_request(method, path, nil, nil) do |req|
+          req.params = params if params
+          if multipart
+            body.each { |k, v| req.body[k] = v }
+          elsif body
+            req.body = body.to_json
+          end
+        end
+
+        handle_response(response)
+      rescue Faraday::TimeoutError => e
+        raise Supermemory::APITimeoutError.new("Request timed out: #{e.message}")
+      rescue Faraday::ConnectionFailed => e
+        raise Supermemory::APIConnectionError.new("Connection failed: #{e.message}")
+      rescue Supermemory::APIError => e
+        attempts += 1
+        if attempts <= @max_retries && retryable?(e.status)
+          sleep(retry_delay(attempts))
+          retry
+        end
+        raise
+      end
+    end
+
+    def handle_response(response)
+      status = response.status
+      body = parse_body(response.body)
+      headers = response.headers
+
+      return body if status >= 200 && status < 300
+
+      error_class = ERROR_MAP[status] || (status >= 500 ? InternalServerError : APIError)
+      message = body.is_a?(Hash) ? (body["error"] || body["message"] || body.to_s) : body.to_s
+      raise error_class.new(message, status: status, body: body, headers: headers)
+    end
+
+    def parse_body(body)
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    def connection(multipart: false)
+      @connections_cache ||= {}
+      cache_key = multipart ? :multipart : :json
+      @connections_cache[cache_key] ||= Faraday.new(url: @base_url) do |f|
+        f.options.timeout = @timeout
+        f.options.open_timeout = 5
+        if multipart
+          f.request :multipart
+        else
+          f.headers["Content-Type"] = "application/json"
+        end
+        f.headers["Authorization"] = "Bearer #{@api_key}"
+        @extra_headers.each { |k, v| f.headers[k.to_s] = v.to_s }
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def retryable?(status)
+      RETRYABLE_STATUS_CODES.include?(status)
+    end
+
+    def retry_delay(attempt)
+      delay = INITIAL_RETRY_DELAY * (2**(attempt - 1))
+      delay = [delay, MAX_RETRY_DELAY].min
+      jitter = delay * 0.25 * ((rand * 2) - 1)
+      delay + jitter
+    end
+  end
+end

data/lib/supermemory/configuration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Supermemory
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout, :max_retries, :extra_headers
+
+    def initialize
+      @api_key = ENV.fetch("SUPERMEMORY_API_KEY", nil)
+      @base_url = ENV.fetch("SUPERMEMORY_BASE_URL", "https://api.supermemory.ai")
+      @timeout = 60
+      @max_retries = 2
+      @extra_headers = {}
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

data/lib/supermemory/errors.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Supermemory
+  class Error < StandardError; end
+
+  class APIError < Error
+    attr_reader :status, :body, :headers
+
+    def initialize(message = nil, status: nil, body: nil, headers: nil)
+      @status = status
+      @body = body
+      @headers = headers
+      super(message || default_message)
+    end
+
+    private
+
+    def default_message
+      "API error (status: #{status})"
+    end
+  end
+
+  class BadRequestError < APIError
+    def initialize(message = nil, **kwargs)
+      super(message, status: 400, **kwargs)
+    end
+  end
+
+  class AuthenticationError < APIError
+    def initialize(message = nil, **kwargs)
+      super(message, status: 401, **kwargs)
+    end
+  end
+
+  class PermissionDeniedError < APIError
+    def initialize(message = nil, **kwargs)
+      super(message, status: 403, **kwargs)
+    end
+  end
+
+  class NotFoundError < APIError
+    def initialize(message = nil, **kwargs)
+      super(message, status: 404, **kwargs)
+    end
+  end
+
+  class ConflictError < APIError
+    def initialize(message = nil, **kwargs)
+      super(message, status: 409, **kwargs)
+    end
+  end
+
+  class UnprocessableEntityError < APIError
+    def initialize(message = nil, **kwargs)
+      super(message, status: 422, **kwargs)
+    end
+  end
+
+  class RateLimitError < APIError
+    def initialize(message = nil, **kwargs)
+      super(message, status: 429, **kwargs)
+    end
+  end
+
+  class InternalServerError < APIError
+    def initialize(message = nil, **kwargs)
+      super(message, status: 500, **kwargs)
+    end
+  end
+
+  class APIConnectionError < Error; end
+  class APITimeoutError < APIConnectionError; end
+
+  # @private
+  ERROR_MAP = {
+    400 => BadRequestError,
+    401 => AuthenticationError,
+    403 => PermissionDeniedError,
+    404 => NotFoundError,
+    409 => ConflictError,
+    422 => UnprocessableEntityError,
+    429 => RateLimitError
+  }.freeze
+end

data/lib/supermemory/integrations/graph_agent.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "supermemory"
+
+module Supermemory
+  module Integrations
+    # Integration with graph-agent (https://github.com/ai-firstly/graph-agent).
+    #
+    # Provides reusable node functions and a pre-built memory-augmented graph
+    # for adding persistent memory to graph-agent workflows.
+    #
+    # @example Basic usage with pre-built nodes
+    #   require "supermemory/integrations/graph_agent"
+    #
+    #   nodes = Supermemory::Integrations::GraphAgent::Nodes.new(
+    #     api_key: ENV["SUPERMEMORY_API_KEY"]
+    #   )
+    #
+    #   graph = GraphAgent::Graph::StateGraph.new(
+    #     Supermemory::Integrations::GraphAgent.memory_schema
+    #   )
+    #   graph.add_node("recall", nodes.method(:recall_memories))
+    #   graph.add_node("store", nodes.method(:store_memory))
+    module GraphAgent
+      # Build a state schema with memory fields
+      # @param extra_fields [Hash] Additional field definitions to merge
+      # @return [Hash] Schema hash compatible with GraphAgent::Graph::StateGraph
+      def self.memory_schema(extra_fields: {})
+        {
+          messages: { type: Array, reducer: ->(a, b) { a + Array(b) }, default: [] },
+          memories: { type: Array, reducer: ->(a, b) { a + Array(b) }, default: [] },
+          memory_context: { type: String, default: "" },
+          user_id: { type: String, default: "" }
+        }.merge(extra_fields)
+      end
+
+      # Pre-built node functions for memory operations
+      class Nodes
+        attr_reader :client
+
+        # @param api_key [String] Supermemory API key
+        # @param base_url [String, nil] Custom API endpoint
+        def initialize(api_key:, base_url: nil)
+          @client = Supermemory::Client.new(api_key: api_key, base_url: base_url)
+        end
+
+        # Node: Recall memories based on the last user message.
+        # Fetches user profile and relevant memories, stores them in state.
+        #
+        # @param state [Hash] Current graph state (must contain :messages and :user_id)
+        # @param _config [Hash] Graph config (unused but accepted for arity compatibility)
+        # @return [Hash] State update with :memories and :memory_context
+        def recall_memories(state, _config = nil)
+          user_id = state[:user_id]
+          return { memories: [], memory_context: "" } unless user_id && !user_id.empty?
+
+          query = extract_last_user_message(state[:messages])
+          return { memories: [], memory_context: "" } unless query
+
+          result = @client.profile(container_tag: user_id, q: query)
+
+          static_facts = result.dig("profile", "static") || []
+          dynamic_context = result.dig("profile", "dynamic") || []
+          search_results = result.dig("searchResults", "results") || []
+
+          memories = search_results.map { |r| r["memory"] || r["chunk"] }.compact
+
+          context = build_context(static_facts, dynamic_context, memories)
+
+          { memories: search_results, memory_context: context }
+        rescue => e
+          warn "[Supermemory::GraphAgent] Failed to recall memories: #{e.message}"
+          { memories: [], memory_context: "" }
+        end
+
+        # Node: Store the latest conversation exchange as a memory.
+        #
+        # @param state [Hash] Current graph state
+        # @param _config [Hash] Graph config
+        # @return [Hash] Empty state update
+        def store_memory(state, _config = nil)
+          user_id = state[:user_id]
+          return {} unless user_id && !user_id.empty?
+
+          messages = state[:messages] || []
+          user_msg = extract_last_user_message(messages)
+          assistant_msg = extract_last_assistant_message(messages)
+
+          content = if user_msg && assistant_msg
+                      "User: #{user_msg}\nAssistant: #{assistant_msg}"
+                    elsif user_msg
+                      "User: #{user_msg}"
+                    end
+
+          if content
+            @client.add(content: content, container_tag: user_id)
+          end
+
+          {}
+        rescue => e
+          warn "[Supermemory::GraphAgent] Failed to store memory: #{e.message}"
+          {}
+        end
+
+        # Node: Search memories with a specific query.
+        #
+        # @param state [Hash] Current graph state (expects :query or last user message)
+        # @param _config [Hash] Graph config
+        # @return [Hash] State update with :memories
+        def search_memories(state, _config = nil)
+          user_id = state[:user_id]
+          query = state[:query] || extract_last_user_message(state[:messages])
+          return { memories: [] } unless user_id && query
+
+          result = @client.search.memories(
+            q: query,
+            container_tag: user_id,
+            search_mode: "hybrid",
+            limit: 5
+          )
+
+          { memories: result["results"] || [] }
+        rescue => e
+          warn "[Supermemory::GraphAgent] Failed to search memories: #{e.message}"
+          { memories: [] }
+        end
+
+        # Node: Add a specific piece of content to memory.
+        #
+        # @param state [Hash] Current graph state (expects :memory_content)
+        # @param _config [Hash] Graph config
+        # @return [Hash] Empty state update
+        def add_memory(state, _config = nil)
+          user_id = state[:user_id]
+          content = state[:memory_content]
+          return {} unless user_id && content
+
+          metadata = state[:memory_metadata] || {}
+          @client.add(content: content, container_tag: user_id, metadata: metadata)
+
+          {}
+        rescue => e
+          warn "[Supermemory::GraphAgent] Failed to add memory: #{e.message}"
+          {}
+        end
+
+        private
+
+        def extract_last_user_message(messages)
+          msg = Array(messages).reverse.find { |m| m[:role] == "user" || m["role"] == "user" }
+          msg[:content] || msg["content"] if msg
+        end
+
+        def extract_last_assistant_message(messages)
+          msg = Array(messages).reverse.find { |m| m[:role] == "assistant" || m["role"] == "assistant" }
+          msg[:content] || msg["content"] if msg
+        end
+
+        def build_context(static_facts, dynamic_context, memories)
+          parts = []
+          parts << "User Background:\n#{static_facts.map { |f| "- #{f}" }.join("\n")}" if static_facts.any?
+          parts << "Recent Context:\n#{dynamic_context.map { |c| "- #{c}" }.join("\n")}" if dynamic_context.any?
+          parts << "Relevant Memories:\n#{memories.map { |m| "- #{m}" }.join("\n")}" if memories.any?
+          parts.join("\n\n")
+        end
+      end
+
+      # Build a complete memory-augmented graph
+      #
+      # @param api_key [String] Supermemory API key
+      # @param llm_node [Proc] A callable that takes (state, config) and returns
+      #   a state update with at least a new message in :messages
+      # @param should_store [Proc, nil] Optional callable (state) -> Boolean
+      #   to conditionally skip memory storage
+      # @param extra_schema [Hash] Additional schema fields
+      # @param base_url [String, nil] Custom API endpoint
+      # @return [Object] Compiled graph (call .invoke or .stream)
+      #
+      # @example
+      #   llm_node = ->(state, _config) {
+      #     context = state[:memory_context]
+      #     # ... call your LLM with context ...
+      #     { messages: [{ role: "assistant", content: response }] }
+      #   }
+      #
+      #   app = Supermemory::Integrations::GraphAgent.build_memory_graph(
+      #     api_key: ENV["SUPERMEMORY_API_KEY"],
+      #     llm_node: llm_node
+      #   )
+      #
+      #   result = app.invoke(
+      #     { messages: [{ role: "user", content: "Hi!" }], user_id: "user-123" }
+      #   )
+      def self.build_memory_graph(api_key:, llm_node:, should_store: nil, extra_schema: {}, base_url: nil)
+        require "graph_agent"
+
+        nodes = Nodes.new(api_key: api_key, base_url: base_url)
+        schema = memory_schema(extra_fields: extra_schema)
+        graph = ::GraphAgent::Graph::StateGraph.new(schema)
+
+        graph.add_node("recall", nodes.method(:recall_memories))
+        graph.add_node("generate", llm_node)
+        graph.add_node("store", nodes.method(:store_memory))
+
+        graph.add_edge(::GraphAgent::START, "recall")
+        graph.add_edge("recall", "generate")
+
+        if should_store
+          graph.add_conditional_edges("generate", lambda { |state|
+            should_store.call(state) ? "store" : ::GraphAgent::END_NODE.to_s
+          })
+        else
+          graph.add_edge("generate", "store")
+        end
+
+        graph.add_edge("store", ::GraphAgent::END_NODE)
+
+        graph.compile
+      end
+    end
+  end
+end