Skip to content

reference.md

Latest commit

 

History

History
2975 lines (2036 loc) · 46.7 KB

reference.md

File metadata and controls

2975 lines (2036 loc) · 46.7 KB
Raw

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.

🔌 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, matching search's include

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.

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.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.

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.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.

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.

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",
)

⚙️ 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

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.

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.

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.update_file(...) -> DocumentRef

📝 Description

Refresh only the file-backed fields you provide. Supplying a file replaces the canonical content; omitted metadata and processing context remain unchanged.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.documents.update_file(
    namespace="user_alex",
    id="my-doc-123",
    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.

id: str — The public document ID

file: typing.Optional[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.

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.

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.

Profiles

client.profiles.get_buckets(...) -> ProfileBuckets

📝 Description

Inspect the profile taxonomy active in this namespace. The response combines organization-wide buckets with namespace-owned additions as a concise name-to-description map.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.profiles.get_buckets(
    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.

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

client.profiles.set_buckets(...) -> ProfileBuckets

📝 Description

Teach Supermemory new ways to organize this namespace's profile, or refine how existing namespace-owned buckets are classified. Omitted buckets remain unchanged and organization-wide buckets stay protected.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.profiles.set_buckets(
    namespace="user_alex",
    buckets={
        "interests": "Topics the subject actively follows"
    },
)

⚙️ 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.

buckets: typing.Dict[str, str] — Namespace-owned bucket names mapped to descriptions that guide memory classification. Existing names are updated; new names are added.

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

client.profiles.delete_buckets(...) -> ProfileBuckets

📝 Description

Remove profile categories created specifically for this namespace. Unknown names are safely ignored, while organization-wide buckets remain protected.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.profiles.delete_buckets(
    namespace="user_alex",
    buckets=[
        "interests"
    ],
)

⚙️ 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.

buckets: typing.List[str] — Namespace-owned bucket names to delete. Organization-level buckets are protected and cannot be removed here.

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

Memories

client.memories.forget(...) -> ForgetResult

📝 Description

Remove exact memories from normal recall while preserving their audit history. Each ID is handled independently and any missing or ineligible memory is reported without rolling back successful changes.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.memories.forget(
    namespace="user_alex",
    ids=[
        "mem_abc123"
    ],
)

⚙️ Parameters

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

ids: typing.List[str] — Memory identifiers to remove from normal recall

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

client.memories.forget_matching(...) -> ForgetResult

📝 Description

Describe what should be forgotten in natural language, then preview or apply the matching set. Use dry-run results with the exact-ID endpoint when you need a reviewable, drift-free workflow.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.memories.forget_matching(
    namespace="user_alex",
    query="everything about the old pricing plans",
    dry_run=True,
)

⚙️ Parameters

namespace: str — Namespace containing the memories to forget. 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 description of the memories that should be forgotten

dry_run: bool — When true, preview matching memories without changing their recall state

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

client.memories.get(...) -> MemoryDetails

📝 Description

Retrieve one memory by ID. Optionally include its version history and connected memories (each list walks outward up to relatedLimit, nearest first) and its source document.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.memories.get(
    namespace="user_alex",
    id="mem_abc123",
)

⚙️ Parameters

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

id: str — Memory identifier

include: typing.Optional[typing.Union[MemoryInclude, typing.Sequence[MemoryInclude]]] — Comma-separated extras. related: the memory's version history and connected memories. documents: the source document, also attached to each related memory when both are requested.

related_limit: typing.Optional[int] — Maximum parents, children and siblings to return, applied to each list separately. Each list walks outward from the memory, nearest first, until it reaches this many.

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

Connectors

client.connectors.list_all(...) -> ConnectorList

📝 Description

List connectors across every namespace this key can read. Use it for admin views that span users or projects.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.connectors.list_all()

⚙️ Parameters

provider: typing.Optional[ConnectorProvider] — Only return connectors for this provider

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

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

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

client.connectors.list(...) -> ConnectorList

📝 Description

List the connectors that sync into this namespace.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.connectors.list(
    namespace="user_alex",
)

⚙️ Parameters

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

provider: typing.Optional[ConnectorProvider] — Only return connectors for this provider

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

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

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

client.connectors.create(...) -> ConnectorSetupResult

📝 Description

Connect an external source to this namespace. OAuth providers return an authorization url to send the user to; providers that authenticate with config start syncing right away.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.connectors.create(
    namespace="user_alex",
    request={
        "provider": "notion"
    },
)

⚙️ Parameters

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

request: ConnectorSetup

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

client.connectors.get(...) -> Connector

📝 Description

Read one connector. Add include=syncs to include its recent sync runs and the items that failed. include=picker needs an admin with write access, since the link changes what syncs.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.connectors.get(
    namespace="user_alex",
    id="PTzGiUYei7pgzg5buzZHgA",
)

⚙️ Parameters

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

id: str — Connector identifier returned when the connector was created

include: typing.Optional[typing.Union[ConnectorInclude, typing.Sequence[ConnectorInclude]]] — Comma-separated extras. syncs: the 10 most recent sync runs with their failed items. picker: a one-time hosted picker URL.

return_url: typing.Optional[str] — Where the hosted picker sends the user when they finish

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

client.connectors.delete(...) -> ConnectorDeleted

📝 Description

Disconnect a connector and stop its webhooks. Its imported documents are deleted too unless deleteDocuments is false.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.connectors.delete(
    namespace="user_alex",
    id="PTzGiUYei7pgzg5buzZHgA",
)

⚙️ Parameters

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

id: str — Connector identifier returned when the connector was created

delete_documents: typing.Optional[bool] — Also delete documents this connector imported. Defaults to true.

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

client.connectors.update(...) -> Connector

📝 Description

Change what a connector syncs. A new selection replaces the old one and starts a sync.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.connectors.update(
    namespace="user_alex",
    id="PTzGiUYei7pgzg5buzZHgA",
)

⚙️ Parameters

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

id: str — Connector identifier returned when the connector was created

selection: typing.Optional[ConnectorSelection] — What to sync, as ids grouped by kind. GitHub takes repos, Gmail takes labels, Google Drive takes files and folders. Replaces the current selection.

document_limit: typing.Optional[int] — Maximum documents this connector imports

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

client.connectors.sync(...) -> ConnectorSyncStarted

📝 Description

Start a sync now. Returns 409 while a sync for this connector is already running.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.connectors.sync(
    namespace="user_alex",
    id="PTzGiUYei7pgzg5buzZHgA",
)

⚙️ Parameters

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

id: str — Connector identifier returned when the connector was created

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

Namespaces

client.namespaces.list(...) -> NamespaceList

📝 Description

Discover every namespace available to the caller, including its purpose, document volume, memory count, and lifecycle timestamps.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.namespaces.list()

⚙️ Parameters

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

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

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

client.namespaces.get(...) -> NamespaceDetails

📝 Description

Read the supporting context that helps Supermemory understand content and form better memories inside this namespace.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.namespaces.get(
    namespace="user_alex",
)

⚙️ Parameters

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

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

client.namespaces.delete(...) -> NamespaceDeleted

📝 Description

Retire a namespace by permanently deleting its content, or preserve that knowledge by moving everything into another namespace first. Moves are queued and complete asynchronously.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.namespaces.delete(
    namespace="user_alex",
    move_to="project_archive",
)

⚙️ Parameters

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

move_to: typing.Optional[str] — Destination namespace that should receive this namespace's content before deletion. Omit to permanently delete the content.

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

client.namespaces.update(...) -> NamespaceDetails

📝 Description

Shape how Supermemory understands an existing namespace by updating the background context used during ingestion and memory formation.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.namespaces.update(
    namespace="user_alex",
)

⚙️ Parameters

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

supporting_context: typing.Optional[str] — Background that guides how Supermemory interprets documents and forms memories. Max 1500 characters. Set null to clear it.

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

Organization

client.organization.get() -> Organization

📝 Description

Read the shared background that guides memory formation across the organization, together with the number of active namespaces.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.organization.get()

⚙️ Parameters

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

client.organization.update(...) -> Organization

📝 Description

Give Supermemory organization-wide background that improves how content is interpreted across every namespace. Send null to remove the existing context.

🔌 Usage

from supermemory import Supermemory
from supermemory.environment import SupermemoryEnvironment

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

client.organization.update(
    organizational_context=None,
)

⚙️ Parameters

organizational_context: typing.Optional[str] — Shared background that guides memory formation across every namespace. Set null to clear it.

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