supermemory

supermemory is the official TypeScript client for the Supermemory API, a hosted “memory” layer that AI applications call to store, search, and retrieve long-term context — documents, conversations, and discrete memories — instead of re-implementing retrieval infrastructure themselves. The SDK is generated by Speakeasy directly from Supermemory’s OpenAPI specification, so every resource (documents, memories, connections, container tags, conversations, profiles, settings) is exposed as a fully typed method with Zod-validated request and response schemas.

Beyond basic CRUD, it wraps the more operational parts of running a memory API in production: configurable per-call or global retry strategies with backoff, a pluggable HTTPClient built on the native Fetch API with request/response lifecycle hooks, streaming file uploads for large documents, and a typed error hierarchy (SupermemoryError and its subclasses) so failures can be handled as values rather than generic exceptions. Every SDK method also ships as a tree-shakeable standalone function, letting bundle-size-sensitive apps (browser, edge, serverless) import only the operations they use.

What You Get

• A single Supermemory client class with resource-scoped namespaces (documents, memories, connections, containerTags, conversations, profiles, settings) mirroring the API’s domain model
• Zod-validated, fully typed request/response models generated straight from the OpenAPI spec, with a typed SupermemoryError hierarchy for known failure modes
• Tree-shakeable standalone functions (import { add } from "supermemory/core.js") for bundle-size-sensitive browser, edge, and serverless deployments
• Configurable retry strategies (per-call or SDK-wide) with exponential backoff for flaky network conditions
• A pluggable HTTPClient built on native Fetch with beforeRequest/requestError hooks for proxies, custom headers, and logging
• Streaming file upload support so large documents don’t have to be buffered fully into memory

Common Use Cases

• Giving an LLM application persistent, searchable long-term memory across sessions
• Ingesting documents, conversations, or connected third-party data (e.g. Notion, Google Drive) into a unified searchable memory store
• Building RAG-style retrieval pipelines that call search/documents.search instead of maintaining a custom vector store integration
• Syncing and re-importing data from external connections on a schedule via connections.import
• Managing per-user or per-tenant memory scoping with container tags

Under The Hood

Architecture The SDK is a thin Supermemory facade (src/sdk/sdk.ts) extending a shared ClientSDK base (src/lib/sdks.ts) that lazily instantiates resource-scoped sub-clients — Documents, Memories, Connections, ContainerTags, Conversations, Profiles, Settings — via getters on first access. Each sub-client delegates to standalone functions in src/funcs/ (e.g. add.ts, documents-batch-add.ts) that build the actual HTTP request, encode it, and validate the response against Zod schemas in src/models/operations and src/models/errors. Shared concerns — retry backoff (src/lib/retries.ts), request/response hooks (src/hooks/hooks.ts), and low-level Fetch wrapping (src/lib/http.ts) — live in a common layer every resource function pulls from, so changing that core HTTP/retry abstraction would ripple through every generated operation.

Tech Stack Written entirely in TypeScript, distributed ESM-only via a granular exports map (./core.js, ./models, ./funcs/*) for tree-shaking, and built with tsgo (TypeScript’s native-preview compiler). Its only runtime dependency is zod (^3.25 || ^4.0) for schema validation; HTTP calls go through the native Fetch API rather than a wrapped client library like axios. Linting uses oxlint with several strict rules disabled for generated code. CI is entirely Speakeasy-driven (sdk_generation.yaml, publish-npm.yml) — generation and publishing, not a hand-authored test/build pipeline.

Code Quality Every source file carries a “Code generated by Speakeasy — DO NOT EDIT” banner, and no unit test files exist anywhere in the repository; correctness depends on Speakeasy’s generation pipeline and the upstream OpenAPI spec rather than repo-level tests. Error handling is nonetheless explicit and typed: a SupermemoryError base class with specific subclasses (ErrorResponse, ConnectionError, RequestTimeoutError, ResponseValidationError, etc.), and standalone functions return a Result<Value, Error> rather than throwing, keeping error paths part of normal control flow. Naming is mechanical and consistent (kebab-case files, camelCase methods matching OpenAPI operationIds).

API Design The client mirrors the API’s own domain model through resource namespaces (supermemory.documents, supermemory.memories, supermemory.connections), which keeps discovery intuitive for anyone who has read the Supermemory API docs. It layers in genuinely useful production ergonomics on top of the generated core — per-call or SDK-wide retry configuration, a pluggable HTTPClient with lifecycle hooks, streaming file uploads, and tree-shakeable standalone functions for bundle-conscious environments — all standard Speakeasy SDK conventions rather than novel design, but well-executed and consistent.