supermemory 0.1.0

data/lib/supermemory/integrations/langchain.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "json"
+
+begin
+  require "langchain"
+rescue LoadError
+  raise LoadError.new("The langchainrb gem is required for Supermemory::Integrations::Langchain. " \
+                      "Add `gem 'langchainrb'` to your Gemfile.")
+end
+
+module Supermemory
+  module Integrations
+    # Integration with langchainrb (https://github.com/patterns-ai-core/langchainrb).
+    #
+    # Provides:
+    # 1. SupermemoryTool - A Langchain tool for memory operations via function calling
+    # 2. SupermemoryMemory - A memory class for conversation-aware agents
+    #
+    # @example Using as a tool with Langchain::Assistant
+    #   tool = Supermemory::Integrations::Langchain::SupermemoryTool.new(
+    #     api_key: ENV["SUPERMEMORY_API_KEY"],
+    #     container_tag: "user-123"
+    #   )
+    #
+    #   assistant = Langchain::Assistant.new(
+    #     llm: Langchain::LLM::OpenAI.new(api_key: ENV["OPENAI_API_KEY"]),
+    #     tools: [tool],
+    #     instructions: "You are a helpful assistant with memory."
+    #   )
+    #
+    #   assistant.add_message_and_run!(content: "Remember I like Ruby")
+    module Langchain
+      # Langchain tool for Supermemory memory operations.
+      # Extends Langchain::ToolDefinition to work with Langchain::Assistant.
+      class SupermemoryTool
+        extend ::Langchain::ToolDefinition
+
+        define_function :search_memory,
+                        description: "SupermemoryTool: Search the user's long-term memory. " \
+                                     "Use to recall stored facts, preferences, or context." do
+          property :query, type: "string",
+                           description: "The question or topic to search for in memory", required: true
+          property :limit, type: "integer",
+                           description: "Maximum number of memories to return (default: 5)"
+          property :search_mode, type: "string",
+                                 description: "Search mode: 'memories', 'hybrid', or 'documents'",
+                                 enum: %w[memories hybrid documents]
+        end
+
+        define_function :add_memory,
+                        description: "SupermemoryTool: Save information to long-term memory. " \
+                                     "Use when the user shares preferences or facts worth remembering." do
+          property :content, type: "string",
+                             description: "The information to save as a memory", required: true
+          property :metadata, type: "object",
+                              description: "Optional metadata to attach to the memory"
+        end
+
+        define_function :get_profile,
+                        description: "SupermemoryTool: Get user profile with long-term facts and context. " \
+                                     "Use to understand the user's background." do
+          property :query, type: "string",
+                           description: "Optional query to also search for relevant memories alongside the profile"
+        end
+
+        define_function :forget_memory,
+                        description: "SupermemoryTool: Remove a specific memory from the user's long-term memory. " \
+                                     "Use this when the user asks to forget or delete specific information." do
+          property :content, type: "string",
+                             description: "The exact content of the memory to forget", required: true
+          property :reason, type: "string",
+                            description: "Optional reason for forgetting this memory"
+        end
+
+        # @param api_key [String] Supermemory API key
+        # @param container_tag [String] Container tag for scoping memories to a user/project
+        # @param base_url [String, nil] Custom API endpoint
+        def initialize(api_key:, container_tag:, base_url: nil)
+          @client = Supermemory::Client.new(api_key: api_key, base_url: base_url)
+          @container_tag = container_tag
+        end
+
+        attr_reader :client, :container_tag
+
+        def search_memory(query:, limit: 5, search_mode: "hybrid")
+          result = @client.search.memories(
+            q: query,
+            container_tag: @container_tag,
+            search_mode: search_mode,
+            limit: limit
+          )
+
+          memories = (result["results"] || []).map do |r|
+            r["memory"] || r["chunk"] || ""
+          end.compact
+
+          tool_response(content: memories.any? ? memories.join("\n---\n") : "No relevant memories found.")
+        end
+
+        def add_memory(content:, metadata: nil)
+          result = @client.add(
+            content: content,
+            container_tag: @container_tag,
+            metadata: metadata
+          )
+          tool_response(content: "Memory saved (ID: #{result["id"]})")
+        end
+
+        def get_profile(query: nil)
+          result = @client.profile(container_tag: @container_tag, q: query)
+
+          static = result.dig("profile", "static") || []
+          dynamic = result.dig("profile", "dynamic") || []
+
+          parts = []
+          parts << "Background: #{static.join("; ")}" if static.any?
+          parts << "Recent context: #{dynamic.join("; ")}" if dynamic.any?
+
+          if query && result["searchResults"]
+            search_results = result.dig("searchResults", "results") || []
+            memories = search_results.map { |r| r["memory"] || r["chunk"] }.compact
+            parts << "Related: #{memories.join("; ")}" if memories.any?
+          end
+
+          tool_response(content: parts.any? ? parts.join("\n") : "No profile information available yet.")
+        end
+
+        def forget_memory(content:, reason: nil)
+          result = @client.memories.forget(
+            container_tag: @container_tag,
+            content: content,
+            reason: reason
+          )
+          tool_response(content: result["forgotten"] ? "Memory forgotten." : "Memory not found.")
+        end
+
+        private
+
+        def tool_response(content: nil, image_url: nil)
+          ::Langchain::ToolResponse.new(content: content, image_url: image_url)
+        end
+      end
+
+      # Helper class for injecting memory context into Langchain conversations.
+      # Use this for automatic memory retrieval/storage without explicit tool calling.
+      #
+      # @example
+      #   memory = Supermemory::Integrations::Langchain::SupermemoryMemory.new(
+      #     api_key: ENV["SUPERMEMORY_API_KEY"],
+      #     container_tag: "user-123"
+      #   )
+      #
+      #   # Get context for injection into system prompt
+      #   context = memory.context(query: "user preferences")
+      #
+      #   # Store a conversation exchange
+      #   memory.store(user_message: "I prefer dark mode", assistant_message: "Noted!")
+      class SupermemoryMemory
+        attr_reader :client, :container_tag
+
+        # @param api_key [String] Supermemory API key
+        # @param container_tag [String] Container tag for scoping
+        # @param base_url [String, nil] Custom API endpoint
+        def initialize(api_key:, container_tag:, base_url: nil)
+          @client = Supermemory::Client.new(api_key: api_key, base_url: base_url)
+          @container_tag = container_tag
+        end
+
+        # Retrieve memory context for a query
+        # @param query [String, nil] Search query
+        # @return [String] Formatted memory context
+        def context(query: nil)
+          result = @client.profile(container_tag: @container_tag, q: query)
+          format_context(result)
+        rescue => e
+          warn "[Supermemory::Langchain] Failed to fetch context: #{e.message}"
+          ""
+        end
+
+        # Store a conversation exchange
+        # @param user_message [String] User's message
+        # @param assistant_message [String, nil] Assistant's response
+        # @param metadata [Hash, nil] Optional metadata
+        def store(user_message:, assistant_message: nil, metadata: nil)
+          content = if assistant_message
+                      "User: #{user_message}\nAssistant: #{assistant_message}"
+                    else
+                      user_message
+                    end
+
+          @client.add(content: content, container_tag: @container_tag, metadata: metadata)
+        rescue => e
+          warn "[Supermemory::Langchain] Failed to store memory: #{e.message}"
+        end
+
+        # Search memories
+        # @param query [String] Search query
+        # @param limit [Integer] Max results
+        # @return [Array<Hash>]
+        def search(query:, limit: 5)
+          result = @client.search.memories(
+            q: query,
+            container_tag: @container_tag,
+            search_mode: "hybrid",
+            limit: limit
+          )
+          result["results"] || []
+        rescue => e
+          warn "[Supermemory::Langchain] Failed to search: #{e.message}"
+          []
+        end
+
+        private
+
+        def format_context(result)
+          static = result.dig("profile", "static") || []
+          dynamic = result.dig("profile", "dynamic") || []
+          search_results = result.dig("searchResults", "results") || []
+
+          parts = []
+          parts << "User Background:\n#{static.join("\n")}" if static.any?
+          parts << "Recent Context:\n#{dynamic.join("\n")}" if dynamic.any?
+
+          if search_results.any?
+            memories = search_results.map { |r| r["memory"] || r["chunk"] }.compact
+            parts << "Relevant Memories:\n#{memories.join("\n")}" if memories.any?
+          end
+
+          parts.join("\n\n")
+        end
+      end
+    end
+  end
+end

data/lib/supermemory/integrations/openai.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+require "json"
+require "supermemory"
+
+module Supermemory
+  module Integrations
+    # Integration with the ruby-openai gem (https://github.com/alexrudall/ruby-openai).
+    #
+    # Provides two approaches:
+    # 1. SupermemoryTools - Function calling tools for explicit memory operations
+    # 2. with_supermemory - Wrapper that auto-injects memories into system prompts
+    module OpenAI
+      # Tool definitions for OpenAI function calling
+      class SupermemoryTools
+        SEARCH_MEMORIES_TOOL = {
+          type: "function",
+          function: {
+            name: "searchMemories",
+            description: "Search through user memories for relevant information. " \
+                         "Use this when the user asks a question that might be answered by their stored memories.",
+            parameters: {
+              type: "object",
+              properties: {
+                information_to_get: {
+                  type: "string",
+                  description: "What information to search for in the user's memories"
+                },
+                limit: {
+                  type: "integer",
+                  description: "Maximum number of memories to return (default: 10)"
+                }
+              },
+              required: ["information_to_get"]
+            }
+          }
+        }.freeze
+
+        ADD_MEMORY_TOOL = {
+          type: "function",
+          function: {
+            name: "addMemory",
+            description: "Save important information to the user's long-term memory. " \
+                         "Use when the user shares preferences, facts, or information worth remembering.",
+            parameters: {
+              type: "object",
+              properties: {
+                memory: {
+                  type: "string",
+                  description: "The information to save as a memory"
+                }
+              },
+              required: ["memory"]
+            }
+          }
+        }.freeze
+
+        attr_reader :api_key, :config
+
+        # @param api_key [String] Supermemory API key
+        # @param config [Hash] Configuration options
+        # @option config [String] :container_tag Container tag for scoping memories
+        # @option config [String] :base_url Custom API endpoint
+        def initialize(api_key:, config: {})
+          @api_key = api_key
+          @config = config
+          @client = Supermemory::Client.new(
+            api_key: api_key,
+            base_url: config[:base_url]
+          )
+        end
+
+        # Get tool definitions for OpenAI function calling
+        # @return [Array<Hash>]
+        def get_tool_definitions
+          [SEARCH_MEMORIES_TOOL, ADD_MEMORY_TOOL]
+        end
+
+        # Search memories
+        # @param information_to_get [String] Query string
+        # @param limit [Integer] Max results
+        # @param include_full_docs [Boolean]
+        # @return [Hash]
+        def search_memories(information_to_get:, limit: 10, include_full_docs: false)
+          params = { q: information_to_get, limit: limit }
+          params[:container_tag] = config[:container_tag] if config[:container_tag]
+
+          if include_full_docs
+            @client.search.documents(q: information_to_get, limit: limit,
+                                     include_full_docs: true)
+          else
+            @client.search.memories(**params)
+          end
+        end
+
+        # Add a memory
+        # @param memory [String] Content to remember
+        # @return [Hash]
+        def add_memory(memory:)
+          options = {}
+          options[:container_tag] = config[:container_tag] if config[:container_tag]
+          @client.add(content: memory, **options)
+        end
+
+        # Execute a single tool call from an OpenAI response
+        # @param tool_call [Hash] Tool call from OpenAI response
+        # @return [Hash] { tool_call_id:, role: "tool", name:, content: }
+        def execute_tool_call(tool_call)
+          function_name = tool_call.dig("function", "name")
+          arguments = JSON.parse(tool_call.dig("function", "arguments"), symbolize_names: true)
+
+          result = case function_name
+                   when "searchMemories"
+                     search_memories(
+                       information_to_get: arguments[:information_to_get],
+                       limit: arguments[:limit] || 10
+                     )
+                   when "addMemory"
+                     add_memory(memory: arguments[:memory])
+                   else
+                     { error: "Unknown tool: #{function_name}" }
+                   end
+
+          {
+            tool_call_id: tool_call["id"],
+            role: "tool",
+            name: function_name,
+            content: result.to_json
+          }
+        end
+      end
+
+      # Execute memory tool calls from an OpenAI response
+      # @param api_key [String] Supermemory API key
+      # @param tool_calls [Array<Hash>] Tool calls from OpenAI response
+      # @param config [Hash] Configuration options
+      # @return [Array<Hash>] Tool result messages
+      def self.execute_memory_tool_calls(api_key:, tool_calls:, config: {})
+        tools = SupermemoryTools.new(api_key: api_key, config: config)
+        memory_tool_names = %w[searchMemories addMemory]
+
+        tool_calls.select { |tc| memory_tool_names.include?(tc.dig("function", "name")) }
+                  .map { |tc| tools.execute_tool_call(tc) }
+      end
+
+      # Wrap an OpenAI client to automatically inject memories into system prompts
+      #
+      # @param openai_client [OpenAI::Client] A ruby-openai client instance
+      # @param user_id [String] User identifier (used as container_tag)
+      # @param options [Hash] Configuration
+      # @option options [String] :mode "profile", "query", or "full" (default: "full")
+      # @option options [String] :add_memory "always" or "never" (default: "always")
+      # @option options [Boolean] :verbose Enable debug logging (default: false)
+      # @option options [String] :base_url Custom API endpoint
+      # @return [WrappedClient]
+      def self.with_supermemory(openai_client, user_id, options = {})
+        WrappedClient.new(openai_client, user_id, options)
+      end
+
+      # A wrapper around OpenAI::Client that auto-injects memories
+      class WrappedClient
+        attr_reader :openai_client
+
+        def initialize(openai_client, user_id, options = {})
+          @openai_client = openai_client
+          @user_id = user_id
+          @mode = options.fetch(:mode, "full")
+          @add_memory = options.fetch(:add_memory, "always")
+          @verbose = options.fetch(:verbose, false)
+          @supermemory = Supermemory::Client.new(
+            api_key: options[:api_key] || ENV.fetch("SUPERMEMORY_API_KEY", nil),
+            base_url: options[:base_url]
+          )
+        end
+
+        # Intercept chat calls to inject memory context
+        # @param parameters [Hash] OpenAI chat parameters
+        # @return [Hash] OpenAI response
+        def chat(parameters:)
+          messages = parameters[:messages] || parameters["messages"] || []
+          user_message = find_last_user_message(messages)
+
+          if user_message
+            context = fetch_memory_context(user_message)
+            parameters = inject_context(parameters, context) if context
+          end
+
+          response = @openai_client.chat(parameters: parameters)
+
+          if @add_memory == "always" && user_message
+            store_conversation(user_message, response)
+          end
+
+          response
+        end
+
+        # Delegate all other methods to the wrapped client
+        def method_missing(method, ...)
+          @openai_client.send(method, ...)
+        end
+
+        def respond_to_missing?(method, include_private = false)
+          @openai_client.respond_to?(method, include_private) || super
+        end
+
+        private
+
+        def find_last_user_message(messages)
+          user_msgs = messages.select { |m| m[:role] == "user" || m["role"] == "user" }
+          msg = user_msgs.last
+          msg[:content] || msg["content"] if msg
+        end
+
+        def fetch_memory_context(query)
+          case @mode
+          when "profile"
+            result = @supermemory.profile(container_tag: @user_id)
+            format_profile(result)
+          when "query"
+            result = @supermemory.search.memories(q: query, container_tag: @user_id, limit: 5)
+            format_search_results(result)
+          when "full"
+            result = @supermemory.profile(container_tag: @user_id, q: query)
+            format_full(result)
+          end
+        rescue => e
+          warn "[Supermemory] Failed to fetch context: #{e.message}" if @verbose
+          nil
+        end
+
+        def inject_context(parameters, context)
+          parameters = parameters.dup
+          messages = (parameters[:messages] || parameters["messages"]).dup
+
+          system_idx = messages.index { |m| (m[:role] || m["role"]) == "system" }
+          if system_idx
+            msg = messages[system_idx].dup
+            content = msg[:content] || msg["content"]
+            msg_key = msg.key?(:content) ? :content : "content"
+            msg[msg_key] = "#{content}\n\n#{context}"
+            messages[system_idx] = msg
+          else
+            messages.unshift({ role: "system", content: context })
+          end
+
+          key = parameters.key?(:messages) ? :messages : "messages"
+          parameters[key] = messages
+          parameters
+        end
+
+        def store_conversation(user_message, response)
+          assistant_content = response.dig("choices", 0, "message", "content")
+          return unless assistant_content
+
+          @supermemory.add(
+            content: "User: #{user_message}\nAssistant: #{assistant_content}",
+            container_tag: @user_id
+          )
+        rescue => e
+          warn "[Supermemory] Failed to store conversation: #{e.message}" if @verbose
+        end
+
+        def format_profile(result)
+          static = result.dig("profile", "static") || []
+          dynamic = result.dig("profile", "dynamic") || []
+          parts = []
+          parts << "User Background:\n#{static.join("\n")}" if static.any?
+          parts << "Recent Context:\n#{dynamic.join("\n")}" if dynamic.any?
+          parts.any? ? "[User Memory Context]\n#{parts.join("\n\n")}" : nil
+        end
+
+        def format_search_results(result)
+          results = result["results"] || []
+          return nil if results.empty?
+
+          memories = results.map { |r| r["memory"] || r["chunk"] }.compact
+          "[Relevant Memories]\n#{memories.join("\n")}"
+        end
+
+        def format_full(result)
+          profile_text = format_profile(result)
+          search = result.dig("searchResults", "results") || []
+          memory_text = if search.any?
+                          memories = search.map { |r| r["memory"] || r["chunk"] }.compact
+                          "Relevant Memories:\n#{memories.join("\n")}" if memories.any?
+                        end
+
+          parts = [profile_text, memory_text].compact
+          parts.any? ? "[User Memory Context]\n#{parts.join("\n\n")}" : nil
+        end
+      end
+    end
+  end
+end

data/lib/supermemory/resources/base.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Supermemory
+  module Resources
+    class Base
+      # @return [Supermemory::Client]
+      attr_reader :client
+
+      # @param client [Supermemory::Client]
+      def initialize(client)
+        @client = client
+      end
+    end
+  end
+end

data/lib/supermemory/resources/connections.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Supermemory
+  module Resources
+    class Connections < Base
+      PROVIDERS = %w[notion google-drive onedrive gmail github web-crawler s3].freeze
+
+      # Create a connection (returns OAuth auth URL)
+      # @param provider [String] Provider name
+      # @param container_tags [Array<String>, nil]
+      # @param document_limit [Integer, nil]
+      # @param metadata [Hash, nil]
+      # @param redirect_url [String, nil]
+      # @return [Hash] { "id" => "...", "authLink" => "...", "expiresIn" => "..." }
+      def create(provider, container_tags: nil, document_limit: nil, metadata: nil, redirect_url: nil)
+        body = {}
+        body[:containerTags] = container_tags if container_tags
+        body[:documentLimit] = document_limit if document_limit
+        body[:metadata] = metadata if metadata
+        body[:redirectUrl] = redirect_url if redirect_url
+        client.post("/v3/connections/#{provider}", body)
+      end
+
+      # List connections
+      # @param container_tags [Array<String>, nil]
+      # @return [Array<Hash>]
+      def list(container_tags: nil)
+        body = {}
+        body[:containerTags] = container_tags if container_tags
+        client.post("/v3/connections/list", body)
+      end
+
+      # Configure a connection (e.g., GitHub resources)
+      # @param connection_id [String]
+      # @param resources [Array<Hash>]
+      # @return [Hash] { "message" => "...", "success" => true/false }
+      def configure(connection_id, resources:)
+        client.post("/v3/connections/#{connection_id}/configure", { resources: resources })
+      end
+
+      # Get connection by ID
+      # @param connection_id [String]
+      # @return [Hash]
+      def get_by_id(connection_id)
+        client.get("/v3/connections/#{connection_id}")
+      end
+
+      # Get connection by provider and tags
+      # @param provider [String]
+      # @param container_tags [Array<String>]
+      # @return [Hash]
+      def get_by_tag(provider, container_tags:)
+        client.post("/v3/connections/#{provider}/connection", { containerTags: container_tags })
+      end
+
+      # Delete connection by ID
+      # @param connection_id [String]
+      # @return [Hash]
+      def delete_by_id(connection_id)
+        client.delete("/v3/connections/#{connection_id}")
+      end
+
+      # Delete connection by provider
+      # @param provider [String]
+      # @param container_tags [Array<String>]
+      # @return [Hash]
+      def delete_by_provider(provider, container_tags:)
+        client.delete("/v3/connections/#{provider}", { containerTags: container_tags })
+      end
+
+      # Trigger manual import/sync
+      # @param provider [String]
+      # @param container_tags [Array<String>, nil]
+      # @return [String]
+      def import(provider, container_tags: nil)
+        body = {}
+        body[:containerTags] = container_tags if container_tags
+        client.post("/v3/connections/#{provider}/import", body)
+      end
+
+      # List documents for a connection
+      # @param provider [String]
+      # @param container_tags [Array<String>, nil]
+      # @return [Array<Hash>]
+      def list_documents(provider, container_tags: nil)
+        body = {}
+        body[:containerTags] = container_tags if container_tags
+        client.post("/v3/connections/#{provider}/documents", body)
+      end
+
+      # Get available resources for a connection
+      # @param connection_id [String]
+      # @param page [Integer, nil]
+      # @param per_page [Integer, nil]
+      # @return [Hash] { "resources" => [...], "total_count" => ... }
+      def resources(connection_id, page: nil, per_page: nil)
+        params = {}
+        params[:page] = page if page
+        params[:per_page] = per_page if per_page
+        client.get("/v3/connections/#{connection_id}/resources", params)
+      end
+    end
+  end
+end