tessl/npm-supermemory

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

—

Pending

Overview

Eval results

Files

Memory Management

Name: tessl/npm-supermemory
Author: tessl

Comprehensive memory operations for creating, retrieving, updating, and deleting memories with rich metadata support and file upload capabilities.

Capabilities

Add Memory

Creates a new memory with content, metadata, and optional container tags for organization.

/**
 * Add a memory with any content type (text, url, file, etc.) and metadata
 * @param params - Memory creation parameters
 * @returns Promise resolving to memory creation response
 */
add(params?: MemoryAddParams): APIPromise<MemoryAddResponse>;

interface MemoryAddParams {
  /** The content to extract and process into a memory */
  content?: string;
  /** Optional custom ID from your database */
  customId?: string;
  /** Key-value metadata for the memory */
  metadata?: { [key: string]: string | number | boolean };
  /** Single container tag for grouping */
  containerTag?: string;
  /** @deprecated Use containerTag instead */
  containerTags?: string[];
}

interface MemoryAddResponse {
  id: string;
  status: string;
}

Usage Examples:

import Supermemory from "supermemory";

const client = new Supermemory({ apiKey: "your-api-key" });

// Add text memory
const textMemory = await client.memories.add({
  content: "Machine learning is a subset of AI",
  metadata: { category: "education", topic: "ai" },
  containerTag: "user_123",
});

// Add URL memory
const urlMemory = await client.memories.add({
  content: "https://example.com/article",
  customId: "article_456",
  metadata: { source: "web", priority: 1 },
});

Get Memory

Retrieves a complete memory object by ID including all content and metadata.

/**
 * Get a memory by ID
 * @param id - Unique memory identifier
 * @returns Promise resolving to complete memory object
 */
get(id: string): APIPromise<MemoryGetResponse>;

interface MemoryGetResponse {
  id: string;
  connectionId: string | null;
  content: string | null;
  createdAt: string;
  customId: string | null;
  metadata: string | number | boolean | { [key: string]: unknown } | Array<unknown> | null;
  ogImage: string | null;
  source: string | null;
  status: MemoryStatus;
  summary: string | null;
  summaryEmbeddingModel: string | null;
  summaryEmbeddingModelNew: string | null;
  summaryEmbeddingNew: number[] | null;
  title: string | null;
  type: MemoryType;
  updatedAt: string;
  containerTags?: string[];
  raw?: null;
  url?: string | null;
}

Usage Example:

const memory = await client.memories.get("memory-id-123");
console.log(memory.title, memory.status, memory.summary);

Update Memory

Updates an existing memory's content, metadata, or container tags.

/**
 * Update a memory with any content type (text, url, file, etc.) and metadata
 * @param id - Memory ID to update
 * @param params - Update parameters
 * @returns Promise resolving to update response
 */
update(id: string, params?: MemoryUpdateParams): APIPromise<MemoryUpdateResponse>;

interface MemoryUpdateParams {
  content?: string;
  customId?: string;
  metadata?: { [key: string]: string | number | boolean };
  containerTag?: string;
  /** @deprecated Use containerTag instead */
  containerTags?: string[];
}

interface MemoryUpdateResponse {
  id: string;
  status: string;
}

Usage Example:

const updated = await client.memories.update("memory-id-123", {
  metadata: { category: "updated", priority: 2 },
  containerTag: "project_456",
});

Delete Memory

Permanently removes a memory by ID.

/**
 * Delete a memory by ID
 * @param id - Memory ID to delete
 * @returns Promise resolving to void
 */
delete(id: string): APIPromise<void>;

Usage Example:

await client.memories.delete("memory-id-123");

List Memories

Retrieves a paginated list of memories with filtering, sorting, and optional content inclusion.

/**
 * Retrieves a paginated list of memories with their metadata and workflow status
 * @param params - List parameters for filtering and pagination
 * @returns Promise resolving to paginated memory list
 */
list(params?: MemoryListParams): APIPromise<MemoryListResponse>;

interface MemoryListParams {
  /** Container tags for filtering */
  containerTags?: string[];
  /** Filter expression for advanced filtering */
  filters?: string;
  /** Include full content in response (increases response size) */
  includeContent?: boolean;
  /** Items per page */
  limit?: string | number;
  /** Sort order */
  order?: "asc" | "desc";
  /** Page number */
  page?: string | number;
  /** Sort field */
  sort?: "createdAt" | "updatedAt";
}

interface MemoryListResponse {
  memories: Memory[];
  pagination: Pagination;
}

interface Memory {
  id: string;
  connectionId: string | null;
  createdAt: string;
  customId: string | null;
  metadata: string | number | boolean | { [key: string]: unknown } | Array<unknown> | null;
  status: MemoryStatus;
  summary: string | null;
  title: string | null;
  type: MemoryType;
  updatedAt: string;
  containerTags?: string[];
  content?: string; // Only included when includeContent=true
}

interface Pagination {
  currentPage: number;
  limit: number;
  totalItems: number;
  totalPages: number;
}

Usage Examples:

// Basic listing
const memories = await client.memories.list({
  limit: 50,
  sort: "createdAt",
  order: "desc",
});

// Filtered listing with content
const filteredMemories = await client.memories.list({
  containerTags: ["user_123", "project_456"],
  includeContent: true,
  filters: "status:done",
});

Upload File

Uploads a file to be processed as a memory with automatic content extraction.

/**
 * Upload a file to be processed
 * @param params - File upload parameters
 * @returns Promise resolving to upload response
 */
uploadFile(params: MemoryUploadFileParams): APIPromise<MemoryUploadFileResponse>;

interface MemoryUploadFileParams {
  /** File to upload (supports multiple input types) */
  file: Uploadable;
  /** Container tags for the uploaded memory */
  containerTags?: string;
}

interface MemoryUploadFileResponse {
  id: string;
  status: string;
}

Usage Examples:

import fs from "fs";
import { toFile } from "supermemory";

// Upload from filesystem
const fileMemory = await client.memories.uploadFile({
  file: fs.createReadStream("./document.pdf"),
  containerTags: "documents",
});

// Upload from Buffer
const bufferMemory = await client.memories.uploadFile({
  file: await toFile(Buffer.from("file content"), "document.txt"),
  containerTags: "text-files",
});

// Upload from web File API
const webFileMemory = await client.memories.uploadFile({
  file: new File(["content"], "document.txt"),
  containerTags: "uploads",
});

Memory Types and Status

type MemoryStatus = 
  | "unknown"     // Initial state
  | "queued"      // Waiting for processing
  | "extracting"  // Content extraction in progress
  | "chunking"    // Breaking content into chunks
  | "embedding"   // Generating embeddings
  | "indexing"    // Adding to search index
  | "done"        // Processing complete
  | "failed";     // Processing failed

type MemoryType = 
  | "text"         // Plain text content
  | "pdf"          // PDF document
  | "tweet"        // Twitter/X post
  | "google_doc"   // Google Docs document
  | "google_slide" // Google Slides presentation
  | "google_sheet" // Google Sheets spreadsheet
  | "image"        // Image file
  | "video"        // Video file
  | "notion_doc"   // Notion document
  | "webpage"      // Web page content
  | "onedrive";    // OneDrive document

Error Handling

Memory operations can throw various errors:

try {
  const memory = await client.memories.add({ content: "test" });
} catch (error) {
  if (error instanceof BadRequestError) {
    console.error("Invalid parameters:", error.message);
  } else if (error instanceof AuthenticationError) {
    console.error("Authentication failed:", error.message);
  } else if (error instanceof RateLimitError) {
    console.error("Rate limit exceeded:", error.message);
  }
}

Install with Tessl CLI