Supermemory Python SDK
The official Python library for the Supermemory v5 API, with sync and async clients built on httpx.
Upgrading from 3.x? v5 moves to the namespace-first v5 API. See MIGRATION.md.
Installation
pip install supermemory
Usage
from supermemory import Supermemory
client = Supermemory() # reads SUPERMEMORY_API_KEY; or Supermemory(api_key="...")
client.add("user_alex", content="Alex prefers morning meetings.", id="pref-1")
response = client.search("user_alex", query="when does alex like to meet?", limit=5)
for result in response.results:
print(result)
Every content operation is scoped to a namespace (a user ID, project ID, or anything you want to isolate memories by), passed as the first argument.
Async
import asyncio
from supermemory import AsyncSupermemory
async_client = AsyncSupermemory()
async def main() -> None:
profile, results = await asyncio.gather(
async_client.profile("user_alex"),
async_client.search("user_alex", query="upcoming meetings"),
)
asyncio.run(main())
Install supermemory[aiohttp] to use aiohttp as the async transport.
API surface
| Call | Endpoint |
|---|---|
client.add(namespace, content=...) |
POST /ns/{namespace}/document |
client.search(namespace, query=...) |
POST /ns/{namespace}/search |
client.profile(namespace) |
POST /ns/{namespace}/profile |
client.list(namespace, "documents" | "chunks" | "memories") |
POST /ns/{namespace}/list/{type} |
client.documents.{get, update, delete, batch_add, upload_file, replace_with_file, update_file} |
/ns/{namespace}/document… |
client.memories.{forget, forget_matching} |
/ns/{namespace}/memories… |
client.profiles.{get_buckets, set_buckets, delete_buckets} |
/ns/{namespace}/profile/buckets |
client.connectors.{list_all, list, create, get, update, delete, sync} |
/connectors, /ns/{namespace}/connectors… |
client.namespaces.{list, get, update, delete} |
/ns, /ns/{namespace} |
client.organization.{get, update} |
/organization |
Full parameter reference: reference.md.
Filtering
Filters are plain dicts (typed as FilterExpressionParams), combinable with and / or:
response = client.search(
"user_alex",
query="launch plans",
filter={
"operator": "and",
"operands": [
{"field": "source", "operator": "eq", "value": "slack"},
{"field": "priority", "operator": "gte", "value": 3},
],
},
)
The same filter shape works for client.list(...) and client.profile(...).
Listing
page = client.list("user_alex", "documents", page=1, limit=50, sort="createdAt", order="desc")
for document in page.documents or []:
print(document.id, document.title)
print(page.pagination)
File uploads
with open("notes.pdf", "rb") as f:
client.documents.upload_file("user_alex", file=f)
Errors
Same exception classes as 3.x. Non-2xx responses raise a subclass of supermemory.APIStatusError with status_code, body, message, request, and response. Network failures raise APIConnectionError (APITimeoutError for timeouts):
import supermemory
from supermemory import Supermemory
client = Supermemory()
try:
client.documents.get("user_alex", "missing-id")
except supermemory.NotFoundError:
...
except supermemory.RateLimitError as e:
print(e.response.headers.get("retry-after"))
except supermemory.APIStatusError as e:
print(e.status_code, e.body)
except supermemory.APIConnectionError:
...
| Status | Error |
|---|---|
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 409 | ConflictError |
| 422 | UnprocessableEntityError |
| 429 | RateLimitError |
| >=500 | InternalServerError |
Retries, timeouts, and per-request options
Connection errors, 408, 429, and 5xx responses are retried twice with exponential backoff, and requests time out after 60 seconds (5 seconds to connect). All of these can be set on the client, or for one request with with_options:
import httpx
client = Supermemory(max_retries=5, timeout=20.0, default_headers={"X-App": "my-app"})
client.with_options(max_retries=0, timeout=httpx.Timeout(5.0)).search("user_alex", query="...")
Every method also takes extra_headers, extra_query, extra_body, and timeout:
client.search("user_alex", query="...", extra_headers={"X-Trace": "1"}, timeout=5)
The client reads SUPERMEMORY_API_KEY, SUPERMEMORY_BASE_URL, and SUPERMEMORY_CUSTOM_HEADERS from the environment.
Raw responses
response = client.with_raw_response.search("user_alex", query="...")
print(response.headers.get("x-request-id"))
results = response.parse() # SearchResponse
Response models have .to_dict() and .to_json().
Development
The SDK is generated from the live v5 OpenAPI spec with Fern's open-source Python generator, run locally in Docker. No hosted codegen service is involved. Don't edit src/supermemory by hand; CI fails if it doesn't match a fresh generation.
| To change | Edit |
|---|---|
| Method names, grouping, parameter names, hidden endpoints | fern/overlay.yaml (x-fern-sdk-group-name, x-fern-sdk-method-name, x-fern-parameter-name, x-fern-ignore) |
Type names (Document, Memory, Connector, …) |
fern/schemas.yaml |
| Generator options | fern/generators.yml |
| Client conventions (options, errors, per-call options) | custom/supermemory/_compat.py |
| Small fixes to Fern's generated core | custom/patches/*.patch |
scripts/generate fetches the spec, names its schemas, runs Fern, then layers custom/ on top.
scripts/generate # fetch /v5/openapi and regenerate (needs Docker, bun, uv)
SKIP_FETCH=1 scripts/generate # regenerate from the committed fern/openapi.json
uv run --group dev pytest # offline tests, including every snippet in README.md and MIGRATION.md
SUPERMEMORY_LIVE_API_KEY=... uv run --group dev pytest tests/live # against the real API
Runnable examples are in examples/.
Releases
- When the API deploy sends
openapi-updated(or on the daily backstop run), Generate SDK regenerates. If the SDK changed, it bumps the version and opens a PR with the tests already run. - Merging a PR that changes the version in
pyproject.tomlpublishes it to PyPI and creates a GitHub release. - To cut a specific version, run Generate SDK manually with
versionset.
1 maintainer
Metadata
1 maintainer
Release files for supermemory 5.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| supermemory-5.0.0.tar.gz | 290.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| supermemory-5.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 538.8 kB
Release files / supermemory-5.0.0.tar.gz
| Download URL | supermemory-5.0.0.tar.gz |
|---|---|
| Size | 290.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5475e49cc16ae01deab3c16f57704f88af66660295d75332223bad6caddd87cd
|
|
BLAKE2b-256 checksum How to use checksums |
131884a54e44f8b02b0c3ce50fe8329f2935a350de0ac7a0b751cbae732d9ed5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / supermemory-5.0.0-py3-none-any.whl
| Download URL | supermemory-5.0.0-py3-none-any.whl |
|---|---|
| Size | 248.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9422f0b2904793778dc388735776068213f9a9d478bbf0d42e714d7a2c3563d8
|
|
BLAKE2b-256 checksum How to use checksums |
0c3b48a1b659a5c9d8f0c575be34d02e275dc07f4aaed3c3134a55d1e6795b2c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
