Reference

client.add(...) -> DocumentRef

📝 Description

Turn text or a supported URL into searchable, evolving memory. Supply a new ID to create a document, or reuse an existing ID to append new information while preserving its history.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

client = Supermemory(
    api_key="<token>",
    environment=SupermemoryEnvironment.DEFAULT,
)

client.add(
    namespace="user_alex",
    content="Supermemory turns unstructured content into evolving memory.",
)

⚙️ Parameters

namespace: str — The isolated namespace. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents.

content: str — The content to process. This may be plaintext or a URL to supported rich content.

id: typing.Optional[str] — An optional caller-defined document ID

supporting_context: typing.Optional[str] — Context used to guide memory extraction within this namespace. Max 1500 characters.

metadata: typing.Optional[typing.Dict[str, MetadataValue]] — Arbitrary metadata attached to the document and derived data

group: typing.Optional[typing.Dict[str, MetadataValue]] — Metadata values that isolate related context within the namespace

date: typing.Optional[str] — When the source content is from, in ISO 8601 format

task_type: typing.Optional[TaskType] — Processing pipeline. "memory" builds durable learned context; "superrag" optimizes the document for retrieval without generating memories.

dreaming: typing.Optional[DreamingMode] — Processing mode. "dynamic" (default) groups related documents so memories form from coherent context. "instant" processes each document independently right away and bills one extra operation per document.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.search(...) -> SearchResponse

📝 Description

Recall the most relevant learned context and source passages from a namespace. Hybrid search combines memories with document chunks by default, with optional query rewriting, reranking, and supporting context attachments.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

client = Supermemory(
    api_key="<token>",
    environment=SupermemoryEnvironment.DEFAULT,
)

client.search(
    namespace="user_alex",
    query="what are the API rate limits",
)

⚙️ Parameters

namespace: str — The isolated namespace to search. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope memories.

query: str — Natural-language question, topic, or phrase to retrieve relevant context for. Replaces the v4 q field.

filter: typing.Optional[FilterExpression] — Type-safe metadata conditions applied before ranking results. Replaces the v4 filters field and unifies both legacy filter formats into one expression type.

search_mode: typing.Optional[SearchMode] — Search surface. "hybrid" combines learned memories with source chunks, "memories" returns learned context, and "chunks" returns source passages.

limit: typing.Optional[int] — Maximum number of results to return

include: typing.Optional[SearchInclude] — Optional context to include alongside each matching result

threshold: typing.Optional[float] — Minimum relevance score from 0 to 1. Raise it for precision (fewer, accurate results) or lower it for broader recall (more results).

rerank: typing.Optional[SearchRequestRerank] — Post-retrieval ranking. "order" improves result ordering; "aggregate" also combines overlapping context into cleaner answers. This is helpful if you want to ensure the most relevant results are returned.

rewrite_query: typing.Optional[bool] — Expand and clarify the query before retrieval to improve recall for conversational or underspecified prompts. This increases the latency by about 400ms.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.profile(...) -> ProfileResponse

📝 Description

Read a continuously maintained understanding of the subject represented by this namespace. Stable facts, evolving context, and selected custom buckets are returned together without requiring a search query.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

client = Supermemory(
    api_key="<token>",
    environment=SupermemoryEnvironment.DEFAULT,
)

client.profile(
    namespace="user_alex",
)

⚙️ Parameters

namespace: str — The isolated namespace to search. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope memories.

filter: typing.Optional[FilterExpression] — Type-safe metadata conditions that limit which memories contribute to the profile

buckets: typing.Optional[typing.List[str]] — Custom buckets to return. Omit to return every effective bucket.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.list(...) -> ListResponse

📝 Description

Browse documents, source chunks, or learned memories through one predictable paginated contract. Choose the collection in the path; the other collection arrays remain empty for a stable response shape. When listing documents, set include.content to include the last published extracted text.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

client = Supermemory(
    api_key="<token>",
    environment=SupermemoryEnvironment.DEFAULT,
)

client.list(
    namespace="user_alex",
    type="documents",
    page=1,
    limit=10,
)

⚙️ Parameters

namespace: str — Namespace containing the resources to list. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope resources.

type: ListType — Resource collection to list: source documents, extracted chunks, or learned memories

page: typing.Optional[int] — One-based page number

limit: typing.Optional[int] — Maximum resources to return per page

sort: typing.Optional[ListSort] — Field used to order results. Position is available only when listing chunks.

order: typing.Optional[SortOrder] — Ascending or descending sort direction

filter: typing.Optional[FilterExpression] — Type-safe metadata conditions applied before pagination

include: typing.Optional[ListRequestInclude] — Optional extras

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Documents

client.documents.delete(...) -> DeleteDocumentsResult

📝 Description

Permanently remove documents and their derived knowledge by document ID or caller-defined ID. Each requested ID is handled independently so successful deletions are preserved when another ID fails.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

client = Supermemory(
    api_key="<token>",
    environment=SupermemoryEnvironment.DEFAULT,
)

client.documents.delete(
    namespace="user_alex",
    ids=[
        "my-doc-123"
    ],
)

⚙️ Parameters

namespace: str — The isolated namespace. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents.

ids: typing.List[str] — Document identifiers to permanently delete from this namespace

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.documents.batch_add(...) -> BatchAddResult

📝 Description

Build a knowledge base efficiently by ingesting up to 600 text or URL documents at once. Existing caller-defined IDs append new information using the same semantics as single-document ingestion.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

client = Supermemory(
    api_key="<token>",
    environment=SupermemoryEnvironment.DEFAULT,
)

client.documents.batch_add(
    namespace="user_alex",
    documents=[
        {
            "content": "Supermemory turns unstructured content into evolving memory."
        }
    ],
)

⚙️ Parameters

namespace: str — The isolated namespace. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents.

documents: typing.List[DocumentInput] — Documents to ingest or append in one request

task_type: typing.Optional[TaskType] — Processing pipeline. "memory" builds durable learned context; "superrag" optimizes the document for retrieval without generating memories.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.documents.get(...) -> Document

📝 Description

Retrieve a document's canonical content, metadata, and processing state by document ID or caller-defined ID. Optionally include its source chunks, derived memories, or both in the same response.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

client = Supermemory(
    api_key="<token>",
    environment=SupermemoryEnvironment.DEFAULT,
)

client.documents.get(
    namespace="user_alex",
    id="my-doc-123",
)

⚙️ Parameters

namespace: str — The isolated namespace. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents.

id: str — The public document ID

include: typing.Optional[typing.Union[DocumentInclude, typing.Sequence[DocumentInclude]]] — Comma-separated child resources to include: chunks, memories, or both.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.documents.update(...) -> DocumentRef

📝 Description

Refresh an existing document without changing its stable ID. Supplied content replaces the canonical content and is reprocessed; omitted fields remain unchanged.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

client = Supermemory(
    api_key="<token>",
    environment=SupermemoryEnvironment.DEFAULT,
)

client.documents.update(
    namespace="user_alex",
    id="my-doc-123",
)

⚙️ Parameters

namespace: str — The isolated namespace. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents.

id: str — The public document ID

content: typing.Optional[str] — The content to process. This may be plaintext or a URL to supported rich content.

supporting_context: typing.Optional[str] — Context used to guide memory extraction within this namespace. Max 1500 characters.

metadata: typing.Optional[typing.Dict[str, MetadataValue]] — Arbitrary metadata attached to the document and derived data

group: typing.Optional[typing.Dict[str, MetadataValue]] — Metadata values that isolate related context within the namespace

date: typing.Optional[str] — When the source content is from, in ISO 8601 format

task_type: typing.Optional[TaskType] — Processing pipeline. "memory" builds durable learned context; "superrag" optimizes the document for retrieval without generating memories.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.documents.upload_file(...) -> DocumentRef

📝 Description

Transform an uploaded file into searchable knowledge and learned memory. The response returns as soon as ingestion is safely queued while extraction and memory formation continue asynchronously.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

client = Supermemory(
    api_key="<token>",
    environment=SupermemoryEnvironment.DEFAULT,
)

client.documents.upload_file(
    namespace="user_alex",
    file="example_file",
)

⚙️ Parameters

namespace: str — The isolated namespace. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents.

file: core.File — File contents to upload

supporting_context: typing.Optional[str] — Context used to guide memory extraction within this namespace. Max 1500 characters.

metadata: typing.Optional[str] — JSON-encoded metadata to attach to the document and its derived memories

group: typing.Optional[str] — JSON-encoded metadata used to keep related context isolated during processing and recall

date: typing.Optional[str] — When the source content is from, in ISO 8601 format

task_type: typing.Optional[TaskType] — Processing pipeline. "memory" builds durable learned context; "superrag" optimizes the document for retrieval without generating memories.

file_type: typing.Optional[FileType] — Explicit source type used when automatic inference is insufficient

mime_type: typing.Optional[str] — Explicit MIME type used when upload metadata is insufficient

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.documents.replace_with_file(...) -> DocumentRef

📝 Description

Replace an existing document with a new file while keeping its stable document ID. Content and caller metadata are overwritten, then the document is reprocessed asynchronously.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

client = Supermemory(
    api_key="<token>",
    environment=SupermemoryEnvironment.DEFAULT,
)

client.documents.replace_with_file(
    namespace="user_alex",
    id="my-doc-123",
    file="example_file",
)