supermemory 0.1.0

data/lib/supermemory/resources/documents.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Supermemory
+  module Resources
+    class Documents < Base
+      # Add a document
+      # @param content [String] Text, URL, PDF, image, or video content
+      # @param container_tag [String, nil] Container tag (max 100 chars)
+      # @param custom_id [String, nil] Custom identifier (max 100 chars)
+      # @param entity_context [String, nil] Context to guide memory extraction (max 1500 chars)
+      # @param metadata [Hash, nil] Key-value metadata
+      # @return [Hash] { "id" => "...", "status" => "..." }
+      def add(content:, container_tag: nil, custom_id: nil, entity_context: nil, metadata: nil)
+        body = { content: content }
+        body[:containerTag] = container_tag if container_tag
+        body[:customId] = custom_id if custom_id
+        body[:entityContext] = entity_context if entity_context
+        body[:metadata] = metadata if metadata
+        client.post("/v3/documents", body)
+      end
+
+      # Batch add documents
+      # @param documents [Array<Hash>, Array<String>] Array of document objects or content strings
+      # @param container_tag [String, nil] Applied to all documents
+      # @param metadata [Hash, nil] Applied to all documents
+      # @return [Array<Hash>] Array of { "id" => "...", "status" => "..." }
+      def batch_add(documents:, container_tag: nil, metadata: nil)
+        body = { documents: documents }
+        body[:containerTag] = container_tag if container_tag
+        body[:metadata] = metadata if metadata
+        client.post("/v3/documents/batch", body)
+      end
+
+      # Get a document by ID
+      # @param id [String] Document ID
+      # @return [Hash] Full document object
+      def get(id)
+        client.get("/v3/documents/#{id}")
+      end
+
+      # Update a document
+      # @param id [String] Document ID
+      # @param options [Hash] Fields to update (content, container_tag, custom_id, metadata)
+      # @return [Hash] { "id" => "...", "status" => "..." }
+      def update(id, **options)
+        body = {}
+        body[:content] = options[:content] if options.key?(:content)
+        body[:containerTag] = options[:container_tag] if options.key?(:container_tag)
+        body[:customId] = options[:custom_id] if options.key?(:custom_id)
+        body[:metadata] = options[:metadata] if options.key?(:metadata)
+        client.patch("/v3/documents/#{id}", body)
+      end
+
+      # Delete a document
+      # @param id [String] Document ID
+      # @return [nil]
+      def delete(id)
+        client.delete("/v3/documents/#{id}")
+        nil
+      end
+
+      # List documents
+      # @param filters [Hash, nil] Filter expression ({ "AND" => [...] } or { "OR" => [...] })
+      # @param include_content [Boolean] Include document content in response
+      # @param limit [Integer, nil] Results per page
+      # @param page [Integer, nil] Page number
+      # @param sort [String, nil] Sort field ("createdAt" or "updatedAt")
+      # @param order [String, nil] Sort order ("asc" or "desc")
+      # @return [Hash] { "memories" => [...], "pagination" => { ... } }
+      def list(filters: nil, include_content: false, limit: nil, page: nil, sort: nil, order: nil)
+        body = {}
+        body[:filters] = filters if filters
+        body[:includeContent] = include_content if include_content
+        body[:limit] = limit if limit
+        body[:page] = page if page
+        body[:sort] = sort if sort
+        body[:order] = order if order
+        client.post("/v3/documents/list", body)
+      end
+
+      # Bulk delete documents
+      # @param ids [Array<String>, nil] Document IDs to delete (max 100)
+      # @param container_tags [Array<String>, nil] Delete all docs in these containers
+      # @return [Hash] { "deletedCount" => ..., "success" => true/false }
+      def delete_bulk(ids: nil, container_tags: nil)
+        body = {}
+        body[:ids] = ids if ids
+        body[:containerTags] = container_tags if container_tags
+        client.delete("/v3/documents/bulk", body)
+      end
+
+      # List documents currently processing
+      # @return [Hash] { "documents" => [...], "totalCount" => ... }
+      def list_processing
+        client.get("/v3/documents/processing")
+      end
+
+      # Upload a file
+      # @param file [Faraday::Multipart::FilePart, IO] File to upload
+      # @param file_type [String, nil] Override file type detection
+      # @param mime_type [String, nil] Required for image/video file types
+      # @param metadata [Hash, nil] Metadata as a hash (will be JSON-encoded)
+      # @param container_tag [String, nil] Container tag
+      # @return [Hash] { "id" => "...", "status" => "..." }
+      def upload_file(file:, file_type: nil, mime_type: nil, metadata: nil, container_tag: nil)
+        body = { file: file }
+        body[:fileType] = file_type if file_type
+        body[:mimeType] = mime_type if mime_type
+        body[:metadata] = metadata.to_json if metadata
+        body[:containerTags] = container_tag if container_tag
+        client.multipart_post("/v3/documents/file", body)
+      end
+    end
+  end
+end

data/lib/supermemory/resources/memories.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Supermemory
+  module Resources
+    class Memories < Base
+      # Forget (soft-delete) a memory
+      # @param container_tag [String] Scope identifier
+      # @param id [String, nil] Memory ID (use id or content)
+      # @param content [String, nil] Exact content match (alternative to id)
+      # @param reason [String, nil] Optional reason for forgetting
+      # @return [Hash] { "id" => "...", "forgotten" => true/false }
+      def forget(container_tag:, id: nil, content: nil, reason: nil)
+        body = { containerTag: container_tag }
+        body[:id] = id if id
+        body[:content] = content if content
+        body[:reason] = reason if reason
+        client.delete("/v4/memories", body)
+      end
+
+      # Update a memory (creates a new version)
+      # @param container_tag [String] Scope identifier
+      # @param new_content [String] Replacement content
+      # @param id [String, nil] Target memory ID
+      # @param content [String, nil] Exact content match for lookup
+      # @param metadata [Hash, nil] Metadata for the new version
+      # @return [Hash] { "id" => "...", "memory" => "...", "version" => ... }
+      def update_memory(container_tag:, new_content:, id: nil, content: nil, metadata: nil)
+        body = { containerTag: container_tag, newContent: new_content }
+        body[:id] = id if id
+        body[:content] = content if content
+        body[:metadata] = metadata if metadata
+        client.patch("/v4/memories", body)
+      end
+    end
+  end
+end

data/lib/supermemory/resources/search.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Supermemory
+  module Resources
+    class Search < Base
+      # Search documents (v3 API)
+      # @param q [String] Search query
+      # @param chunk_threshold [Float, nil] 0 (most results) to 1 (most precise)
+      # @param doc_id [String, nil] Limit search to a specific document
+      # @param filters [Hash, nil] Filter expression
+      # @param include_full_docs [Boolean] Include full document content
+      # @param include_summary [Boolean] Include document summaries
+      # @param limit [Integer, nil] Max results
+      # @param only_matching_chunks [Boolean] Skip surrounding context chunks
+      # @param rerank [Boolean] Rerank results by relevance
+      # @param rewrite_query [Boolean] LLM query rewrite (~400ms extra latency)
+      # @return [Hash] { "results" => [...], "timing" => ..., "total" => ... }
+      def documents(q:, chunk_threshold: nil, doc_id: nil, filters: nil,
+                    include_full_docs: false, include_summary: false,
+                    limit: nil, only_matching_chunks: false,
+                    rerank: false, rewrite_query: false)
+        body = { q: q }
+        body[:chunkThreshold] = chunk_threshold if chunk_threshold
+        body[:docId] = doc_id if doc_id
+        body[:filters] = filters if filters
+        body[:includeFullDocs] = include_full_docs if include_full_docs
+        body[:includeSummary] = include_summary if include_summary
+        body[:limit] = limit if limit
+        body[:onlyMatchingChunks] = only_matching_chunks if only_matching_chunks
+        body[:rerank] = rerank if rerank
+        body[:rewriteQuery] = rewrite_query if rewrite_query
+        client.post("/v3/search", body)
+      end
+
+      # Alias for documents search
+      # @see #documents
+      def execute(**params)
+        documents(**params)
+      end
+
+      # Search memories (v4 API - lower latency, conversational use)
+      # @param q [String] Search query
+      # @param container_tag [String, nil] Scope to a container
+      # @param filters [Hash, nil] Filter expression
+      # @param include [Hash, nil] Control included fields
+      # @param limit [Integer, nil] Max results
+      # @param rerank [Boolean] Rerank results
+      # @param rewrite_query [Boolean] LLM query rewrite
+      # @param search_mode [String, nil] "memories", "hybrid", or "documents"
+      # @param threshold [Float, nil] Score threshold (0 to 1)
+      # @return [Hash] { "results" => [...], "timing" => ..., "total" => ... }
+      def memories(q:, container_tag: nil, filters: nil, include: nil,
+                   limit: nil, rerank: false, rewrite_query: false,
+                   search_mode: nil, threshold: nil)
+        body = { q: q }
+        body[:containerTag] = container_tag if container_tag
+        body[:filters] = filters if filters
+        body[:include] = include if include
+        body[:limit] = limit if limit
+        body[:rerank] = rerank if rerank
+        body[:rewriteQuery] = rewrite_query if rewrite_query
+        body[:searchMode] = search_mode if search_mode
+        body[:threshold] = threshold if threshold
+        client.post("/v4/search", body)
+      end
+    end
+  end
+end

data/lib/supermemory/resources/settings.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Supermemory
+  module Resources
+    class Settings < Base
+      # Get current settings
+      # @return [Hash]
+      def get
+        client.get("/v3/settings")
+      end
+
+      # Update settings
+      # @param options [Hash] Settings to update
+      # @option options [Integer, nil] :chunk_size
+      # @option options [String, nil] :filter_prompt
+      # @option options [Boolean, nil] :should_llm_filter
+      # @option options [String, nil] :github_client_id
+      # @option options [String, nil] :github_client_secret
+      # @option options [Boolean, nil] :github_custom_key_enabled
+      # @option options [String, nil] :google_drive_client_id
+      # @option options [String, nil] :google_drive_client_secret
+      # @option options [Boolean, nil] :google_drive_custom_key_enabled
+      # @option options [String, nil] :notion_client_id
+      # @option options [String, nil] :notion_client_secret
+      # @option options [Boolean, nil] :notion_custom_key_enabled
+      # @option options [String, nil] :onedrive_client_id
+      # @option options [String, nil] :onedrive_client_secret
+      # @option options [Boolean, nil] :onedrive_custom_key_enabled
+      # @return [Hash]
+      def update(**options)
+        body = {}
+        SETTINGS_KEY_MAP.each do |ruby_key, api_key|
+          body[api_key] = options[ruby_key] if options.key?(ruby_key)
+        end
+        client.patch("/v3/settings", body)
+      end
+
+      SETTINGS_KEY_MAP = {
+        chunk_size: :chunkSize,
+        filter_prompt: :filterPrompt,
+        should_llm_filter: :shouldLLMFilter,
+        exclude_items: :excludeItems,
+        include_items: :includeItems,
+        github_client_id: :githubClientId,
+        github_client_secret: :githubClientSecret,
+        github_custom_key_enabled: :githubCustomKeyEnabled,
+        google_drive_client_id: :googleDriveClientId,
+        google_drive_client_secret: :googleDriveClientSecret,
+        google_drive_custom_key_enabled: :googleDriveCustomKeyEnabled,
+        notion_client_id: :notionClientId,
+        notion_client_secret: :notionClientSecret,
+        notion_custom_key_enabled: :notionCustomKeyEnabled,
+        onedrive_client_id: :onedriveClientId,
+        onedrive_client_secret: :onedriveClientSecret,
+        onedrive_custom_key_enabled: :onedriveCustomKeyEnabled
+      }.freeze
+    end
+  end
+end

data/lib/supermemory/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Supermemory
+  VERSION = '0.1.0'
+end

data/lib/supermemory.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "supermemory/version"
+require_relative "supermemory/errors"
+require_relative "supermemory/configuration"
+require_relative "supermemory/client"
+require_relative "supermemory/resources/base"
+require_relative "supermemory/resources/documents"
+require_relative "supermemory/resources/search"
+require_relative "supermemory/resources/memories"
+require_relative "supermemory/resources/settings"
+require_relative "supermemory/resources/connections"
+
+module Supermemory
+  class << self
+    # Create a new client instance
+    # @param options [Hash] Client options (api_key:, base_url:, timeout:, max_retries:)
+    # @return [Supermemory::Client]
+    def new(**options)
+      Client.new(**options)
+    end
+  end
+end

metadata

@@ -0,0 +1,173 @@
+--- !ruby/object:Gem::Specification
+name: supermemory
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Supermemory
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Official Ruby SDK for Supermemory. Add persistent memory to AI applications
+  with document management, semantic search, user profiling, and integrations with
+  ruby-openai, graph-agent, and langchainrb.
+email:
+- support@supermemory.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/supermemory.rb
+- lib/supermemory/client.rb
+- lib/supermemory/configuration.rb
+- lib/supermemory/errors.rb
+- lib/supermemory/integrations/graph_agent.rb
+- lib/supermemory/integrations/langchain.rb
+- lib/supermemory/integrations/openai.rb
+- lib/supermemory/resources/base.rb
+- lib/supermemory/resources/connections.rb
+- lib/supermemory/resources/documents.rb
+- lib/supermemory/resources/memories.rb
+- lib/supermemory/resources/search.rb
+- lib/supermemory/resources/settings.rb
+- lib/supermemory/version.rb
+homepage: https://github.com/supermemoryai/ruby-sdk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/supermemoryai/ruby-sdk
+  source_code_uri: https://github.com/supermemoryai/ruby-sdk
+  changelog_uri: https://github.com/supermemoryai/ruby-sdk/blob/main/CHANGELOG.md
+  documentation_uri: https://supermemory.ai/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby SDK for the Supermemory API - Memory API for the AI era
+test_files: []