---
canonical_url: "https://docs.composio.dev/toolkits/supermemory"
markdown_url: "https://docs.composio.dev/toolkits/supermemory.md"
product: "platform"
version: null
last_updated: null
---

# Supermemory

Supermemory is a memory and context API for ingesting, organizing, searching, and recalling information across applications.

- **Category:** artificial intelligence
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 11
- **Triggers:** 0
- **Slug:** `SUPERMEMORY`
- **Version:** 20260821_00

## Tools

### Add Document

**Slug:** `SUPERMEMORY_ADD_DOCUMENT`

Ingest text or a public URL as a Supermemory document and return its document ID and initial processing status.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | Yes | Plain text or a public URL to ingest. |
| `dreaming` | string ("instant" | "dynamic") | No | Processing mode; instant processes this document alone and may consume an extra operation. |
| `metadata` | object | No | Flat metadata values: strings, numbers, booleans, or string arrays. Nested objects are not supported. |
| `custom_id` | string | No | Caller-defined stable document ID for deduplication or lookup. |
| `task_type` | string ("memory" | "superrag") | No | Use memory for the full context layer or superrag for managed document retrieval. |
| `container_tag` | string | No | Container tag used to isolate this document's memories. Letters, numbers, underscores, colons, and hyphens only. |
| `entity_context` | string | No | Context about the container entity that should guide memory extraction (maximum 1500 characters). |
| `filter_by_metadata` | object | No | Flat metadata filter limiting existing memories used as ingestion context. Values may be strings, numbers, booleans, or string arrays. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Add Documents

**Slug:** `SUPERMEMORY_ADD_DOCUMENTS`

Add 1 to 600 documents in one request, with explicit per-document metadata and processing options. HTTP 200 may contain partial failures; callers must inspect failed, success, and every result rather than treating 200 as complete batch success. The API does not guarantee atomicity or result ordering.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `dreaming` | string ("instant" | "dynamic") | No | Processing mode applied to the whole batch: dynamic groups related documents; instant processes documents independently and bills one extra operation per document. |
| `documents` | array | Yes | One to 600 documents to ingest. Set each document's optional processing fields explicitly when its behavior must differ from provider defaults. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Document

**Slug:** `SUPERMEMORY_DELETE_DOCUMENT`

Permanently delete one document by ID. This does not remove the document's container-tag settings record.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `document_id` | string | Yes | Supermemory document ID to permanently delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Account Status

**Slug:** `SUPERMEMORY_GET_ACCOUNT_STATUS`

Return the connected Supermemory organization's plan, credit balance, high-level usage, and reset date.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Document

**Slug:** `SUPERMEMORY_GET_DOCUMENT`

Get one document's content, metadata, source details, and processing status by document ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `document_id` | string | Yes | Supermemory document ID returned by Add Document or List Documents. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Document Chunks

**Slug:** `SUPERMEMORY_GET_DOCUMENT_CHUNKS`

Return the ordered extracted chunks for one processed document.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `document_id` | string | Yes | Processed Supermemory document ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Profile

**Slug:** `SUPERMEMORY_GET_PROFILE`

Retrieve the static, dynamic, or bucketed profile learned for one container tag, optionally with matching search results.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | No | Optional query that also returns matching profile search results. |
| `buckets` | array | No | Specific profile bucket keys to return when buckets are included. |
| `filters` | object | No | Root metadata filter. Choose AND or OR, never both; operands may be conditions or one nested AND/OR group containing conditions. Deeper groups are unsupported. |
| `include` | array | No | Profile sections to return: static, dynamic, or buckets. Omit this field to return all available sections. |
| `threshold` | number | No | Minimum score from 0 to 1 for optional search results. |
| `container_tag` | string | Yes | Container tag whose learned profile should be returned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Documents

**Slug:** `SUPERMEMORY_LIST_DOCUMENTS`

List documents, optionally filtered by containers, metadata, or filepath, one page at a time.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sort` | string ("createdAt" | "updatedAt") | No | Timestamp field used for sorting. |
| `limit` | integer | No | Maximum documents to return in this page (1-1100). |
| `order` | string ("asc" | "desc") | No | Sort direction. |
| `filters` | object | No | Root metadata filter. Choose AND or OR, never both; operands may be conditions or one nested AND/OR group containing conditions. Deeper groups are unsupported. |
| `filepath` | string | No | Exact filepath, or a directory prefix ending in /, used to filter documents. |
| `next_cursor` | string | No | Opaque cursor returned by the previous call; omit for the first page. |
| `container_tags` | array | No | Only return documents in any of these container tags. |
| `include_content` | boolean | No | Include full document content. Leave false unless content is needed because responses can become large. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Memories

**Slug:** `SUPERMEMORY_LIST_MEMORIES`

List extracted memory entries for one or more container tags, one page at a time.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sort` | string ("createdAt" | "updatedAt") | No | Timestamp field used for sorting. |
| `limit` | integer | No | Maximum memories to return in this page (1-1100). |
| `order` | string ("asc" | "desc") | No | Sort direction. |
| `filters` | object | No | Root metadata filter. Choose AND or OR, never both; operands may be conditions or one nested AND/OR group containing conditions. Deeper groups are unsupported. |
| `next_cursor` | string | No | Opaque cursor returned by the previous call; omit for the first page. |
| `container_tags` | array | Yes | One or more container tags whose memory entries should be returned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search Memory

**Slug:** `SUPERMEMORY_SEARCH_CONTEXT`

Semantically search Supermemory memories, document chunks, or both, with optional container and metadata filters.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum results to return (1-100); this endpoint has no continuation token. |
| `query` | string | Yes | Natural-language search query. |
| `rerank` | boolean | No | Rerank matches for improved relevance. |
| `filters` | object | No | Root metadata filter. Choose AND or OR, never both; operands may be conditions or one nested AND/OR group containing conditions. Deeper groups are unsupported. |
| `include` | object | No | Optional associated content to include: documents, summaries, related memories, and forgotten memories. |
| `aggregate` | boolean | No | Synthesize information across matches; intended to be used with reranking. |
| `threshold` | number | No | Minimum relevance threshold from 0 to 1; higher values return fewer, stricter matches. |
| `search_mode` | string ("memories" | "hybrid" | "documents") | No | Search memories, document chunks, or both. |
| `rewrite_query` | boolean | No | Rewrite the query for retrieval at additional latency. |
| `container_tags` | array | No | Restrict search to memories under these container tags. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Document

**Slug:** `SUPERMEMORY_UPDATE_DOCUMENT`

Update the content, metadata, container, or processing configuration of one existing document. When metadata is supplied, it completely replaces the document's metadata, so omitted metadata keys are removed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | No | Replacement text or public URL to process. |
| `metadata` | object | No | Complete replacement metadata object; omitted keys are removed. |
| `custom_id` | string | No | Replacement caller-defined document ID. |
| `task_type` | string ("memory" | "superrag") | No | Replacement processing task type. |
| `document_id` | string | Yes | Supermemory document ID returned by Add Document or List Documents. |
| `container_tag` | string | No | Replacement container tag, up to 100 characters. Use only letters, numbers, underscores, colons, and hyphens. |
| `filter_by_metadata` | object | No | Replacement flat metadata filter for contextual memories. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |