CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-supermemory

The official TypeScript library for the Supermemory API providing memory management, search, settings, and connection capabilities.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Supermemory

Supermemory is the official TypeScript library for the Supermemory API, providing comprehensive memory management, search functionality, organization settings, and third-party integrations. Built with Stainless from OpenAPI specifications, it offers a modern, type-safe client for interacting with the Supermemory REST API.

Package Information

  • Package Name: supermemory
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install supermemory

Core Imports

import Supermemory from "supermemory";

For CommonJS:

const Supermemory = require("supermemory");

Named imports for utilities:

import { toFile, APIError, APIPromise } from "supermemory";

Basic Usage

import Supermemory from "supermemory";

const client = new Supermemory({
  apiKey: process.env.SUPERMEMORY_API_KEY, // or provide directly
});

// Add a memory
const memory = await client.memories.add({
  content: "Machine learning fundamentals",
  metadata: { category: "education", topic: "ai" },
});

// Search memories
const results = await client.search.documents({
  q: "machine learning concepts",
  limit: 10,
});

// Get organization settings
const settings = await client.settings.get();

Architecture

Supermemory is organized around four main resource groups:

  • Client Core: Main Supermemory class with authentication, configuration, and HTTP methods
  • Memory Management: Create, read, update, delete memories with rich metadata and file upload support
  • Search Engine: Advanced semantic search across documents and memories with filtering and ranking
  • Settings Management: Organization-level configuration for integrations and filtering
  • Connection Management: Third-party service integrations (Notion, Google Drive, OneDrive)

The library provides comprehensive error handling, automatic retries with exponential backoff, request/response logging, and enhanced Promise objects with raw response access.

Capabilities

Client Configuration

Core client instantiation and configuration options for authentication, timeouts, and customization.

class Supermemory {
  constructor(options?: ClientOptions);
  withOptions(options: Partial<ClientOptions>): Supermemory;
}

interface ClientOptions {
  apiKey?: string;
  baseURL?: string;
  timeout?: number;
  maxRetries?: number;
  logLevel?: LogLevel;
  logger?: Logger;
  fetchOptions?: RequestInit;
  fetch?: Fetch;
  defaultHeaders?: HeadersLike;
  defaultQuery?: Record<string, string | undefined>;
}

Memory Management

Comprehensive memory operations including creation, retrieval, updates, deletion, and file uploads.

interface Memories {
  add(params?: MemoryAddParams): APIPromise<MemoryAddResponse>;
  get(id: string): APIPromise<MemoryGetResponse>;
  update(id: string, params?: MemoryUpdateParams): APIPromise<MemoryUpdateResponse>;
  delete(id: string): APIPromise<void>;
  list(params?: MemoryListParams): APIPromise<MemoryListResponse>;
  uploadFile(params: MemoryUploadFileParams): APIPromise<MemoryUploadFileResponse>;
}

Memory Management

Search Operations

Advanced search functionality for finding memories and documents with semantic understanding and filtering.

interface Search {
  documents(params: SearchDocumentsParams): APIPromise<SearchDocumentsResponse>;
  execute(params: SearchExecuteParams): APIPromise<SearchExecuteResponse>;
  memories(params: SearchMemoriesParams): APIPromise<SearchMemoriesResponse>;
}

Search Operations

Settings Management

Organization-level settings configuration for integrations, filtering, and customization.

interface Settings {
  get(): APIPromise<SettingGetResponse>;
  update(params?: SettingUpdateParams): APIPromise<SettingUpdateResponse>;
}

Settings Management

Connection Management

Third-party service integrations for automated content synchronization and document importing.

interface Connections {
  create(provider: ConnectionProvider, params?: ConnectionCreateParams): APIPromise<ConnectionCreateResponse>;
  list(params?: ConnectionListParams): APIPromise<ConnectionListResponse>;
  getByID(connectionID: string): APIPromise<ConnectionGetByIDResponse>;
  getByTags(provider: ConnectionProvider, params: ConnectionGetByTagsParams): APIPromise<ConnectionGetByTagsResponse>;
  deleteByID(connectionID: string): APIPromise<ConnectionDeleteByIDResponse>;
  deleteByProvider(provider: ConnectionProvider, params: ConnectionDeleteByProviderParams): APIPromise<ConnectionDeleteByProviderResponse>;
  import(provider: ConnectionProvider, params?: ConnectionImportParams): APIPromise<string>;
  listDocuments(provider: ConnectionProvider, params?: ConnectionListDocumentsParams): APIPromise<ConnectionListDocumentsResponse>;
}

Connection Management

Core Types

type LogLevel = "debug" | "info" | "warn" | "error" | "off";

type ConnectionProvider = "notion" | "google-drive" | "onedrive";

type MemoryStatus = "unknown" | "queued" | "extracting" | "chunking" | "embedding" | "indexing" | "done" | "failed";

type MemoryType = "text" | "pdf" | "tweet" | "google_doc" | "google_slide" | "google_sheet" | "image" | "video" | "notion_doc" | "webpage" | "onedrive";

interface APIPromise<T> extends Promise<T> {
  asResponse(): Promise<Response>;
  withResponse(): Promise<{ data: T; response: Response }>;
}

interface RequestOptions {
  timeout?: number;
  maxRetries?: number;
  headers?: HeadersLike;
  query?: Record<string, unknown>;
  fetchOptions?: RequestInit;
  signal?: AbortSignal;
  idempotencyKey?: string;
}

Error Handling

class SupermemoryError extends Error {}

class APIError extends SupermemoryError {
  readonly status: number;
  readonly headers: Headers;
  readonly error: object;
}

class APIConnectionError extends APIError {}
class APIConnectionTimeoutError extends APIConnectionError {}
class APIUserAbortError extends APIError {}
class BadRequestError extends APIError {} // 400
class AuthenticationError extends APIError {} // 401
class PermissionDeniedError extends APIError {} // 403
class NotFoundError extends APIError {} // 404
class ConflictError extends APIError {} // 409
class UnprocessableEntityError extends APIError {} // 422
class RateLimitError extends APIError {} // 429
class InternalServerError extends APIError {} // 5xx

File Upload Utilities

type Uploadable = File | Response | ReadStream | Buffer | Uint8Array | ArrayBuffer | DataView | FormData | URLSearchParams;

/**
 * Converts various input types to uploadable file format
 * @param value - Input data (Buffer, Uint8Array, etc.) or PromiseLike
 * @param name - Optional filename for the upload
 * @param options - Optional FilePropertyBag with properties like lastModified
 * @returns Promise resolving to File object
 */
function toFile(
  value: ToFileInput | PromiseLike<ToFileInput>,
  name?: string | null,
  options?: FilePropertyBag
): Promise<File>;

type ToFileInput = 
  | FileLike          // File-like objects with name, lastModified properties
  | ResponseLike      // Response objects with url and blob() method
  | BlobLikePart      // string | ArrayBuffer | ArrayBufferView | BlobLike | DataView
  | AsyncIterable<BlobLikePart>;
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/supermemory@3.0.x
Publish Source
CLI
Badge
tessl/npm-supermemory badge