Supermemory Python SDK

Supermemory is the official Python library for the Supermemory REST API, an AI memory layer that lets applications store, search, and retrieve long-term context for LLM-powered products. Generated with Stainless from Supermemory’s OpenAPI spec, the package wraps every documented endpoint — search, memories, documents, connections, and settings — behind a single typed client, so callers get autocomplete and validation instead of hand-rolled HTTP calls.

Both a synchronous Supermemory client and an AsyncSupermemory client ship from the same codebase with identical method surfaces, and the async client can swap its transport to aiohttp for higher-concurrency workloads. Request parameters are typed as TypedDicts and responses as Pydantic models, with built-in retry/backoff, configurable timeouts, and raw/streaming response accessors for cases where the parsed model isn’t enough.

What You Get

• A synchronous Supermemory client and an AsyncSupermemory client with matching method surfaces across search, memories, documents, connections, and settings resources
• Fully typed requests (TypedDict params) and responses (Pydantic models) generated from Supermemory’s OpenAPI spec, with editor autocomplete and static type checking
• Built-in retries with exponential backoff, per-request timeout overrides, and RequestOptions for customizing individual calls
• .with_raw_response and .with_streaming_response wrappers for accessing raw HTTP headers or streaming bodies without leaving the typed client
• Optional aiohttp transport backend (pip install supermemory[aiohttp]) for improved async concurrency over the default httpx client

Common Use Cases

• Storing conversational or document context into Supermemory so an LLM application can retrieve it as long-term memory in later sessions
• Running semantic search over previously ingested memories or documents via client.search.documents / client.search.memories
• Bulk-importing documents through documents.batch_add when backfilling an existing knowledge base
• Managing per-user memory containers with container_tag scoping so multi-tenant apps keep each user’s context isolated
• Building async ingestion pipelines with AsyncSupermemory and the aiohttp backend for higher-throughput write workloads

Under The Hood

Architecture The SDK is a Stainless-generated OpenAPI client with a clean three-layer split: a transport layer (_base_client.py’s SyncAPIClient/AsyncAPIClient, plus _streaming.py and _files.py) that owns retry/backoff, timeout handling, and request building; a resource layer (resources/search.py, resources/memories.py, resources/documents.py, resources/connections.py, resources/settings.py) of thin classes that call self._get/self._post and wrap results in to_raw_response_wrapper/to_streamed_response_wrapper; and a types layer (types/*.py) of per-endpoint Pydantic response models and TypedDict request params. The top-level Supermemory/AsyncSupermemory classes in _client.py compose the resources as cached_propertys, so changing the base client’s request/retry behavior cascades uniformly to every resource without resource-specific overrides.

Tech Stack Python 3.9+ targeting both sync and async usage, built on httpx (>=0.23,<1) for HTTP transport with an optional httpx_aiohttp-backed aiohttp transport for the async client, pydantic (>=1.9,<3) for response models, typing-extensions, anyio, distro, and sniffio for platform/runtime detection. Packaged with hatchling plus hatch-fancy-pypi-readme for the PyPI-rendered README, and managed via rye for dependency pinning.

Code Quality The repo carries a substantial tests/ suite mirroring each resource (api_resources/test_search.py, test_memories.py, test_documents.py, test_connections.py, test_settings.py) plus lower-level coverage for streaming, file uploads, response parsing, and param transforms, all built on respx to mock the underlying httpx transport and pytest-asyncio/pytest-xdist for parallel async test runs. Typing is strict: pyright runs in strict mode and mypy is configured with disallow_untyped_defs, disallow_any_generics, and strict_equality, backed by ruff for linting/formatting and GitHub Actions CI. xfail_strict and filterwarnings = ['error'] in pytest.ini_options mean the suite fails loudly rather than silently passing on warnings.

API Design The client follows the now-common Stainless SDK ergonomics pattern: a single constructor (Supermemory(api_key=...)), resource-scoped method calls (client.search.documents(...), client.memories.update_memory(...)), identical sync/async surfaces, and escape hatches (with_raw_response, with_streaming_response, undocumented-endpoint helpers) for cases the typed surface doesn’t cover. It’s a well-executed, consistent implementation of a widely-used generated-SDK pattern rather than a novel API design.