tessl/npm-supermemory

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

—

Pending

Overview

Eval results

Files

Supermemory

Name: tessl/npm-supermemory
Author: tessl

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>;

Install with Tessl CLI

npx tessl i tessl/npm-supermemory

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 1 month ago
Describes: pkg:npm/supermemory@3.0.x
Publish Source: CLI
Badge