diff --git a/apps/docs/concepts/content-types.mdx b/apps/docs/concepts/content-types.mdx index 939c6d9b..7113fb4e 100644 --- a/apps/docs/concepts/content-types.mdx +++ b/apps/docs/concepts/content-types.mdx @@ -5,7 +5,7 @@ description: "All the content formats Supermemory can ingest and process" icon: "/icons/hugeicons/files-01.svg" --- -Supermemory automatically extracts and indexes content from various formats. There are two entry points: `supermemory.add()` for text and URLs, `supermemory.documents.uploadFile()` for actual files. Both take the target `namespace` as a top-level key. See [Add Memories](/ingestion/add-memories) to learn how to ingest content via the API. +Supermemory automatically extracts and indexes content from various formats. There are two entry points: `supermemory.add()` for text and URLs, `supermemory.documents.uploadFile()` for actual files. Both take the target `namespace` as the first argument. See [Add Memories](/ingestion/add-memories) to learn how to ingest content via the API. ## Text content @@ -31,7 +31,7 @@ await supermemory.add("documentation", { }); ``` -**Extracts:** Article text, headings, metadata. Strips navigation, ads, boilerplate. URL extraction is powered by [Markdowner](https://md.dhr.wtf). +**Extracts:** Article text, headings, metadata. Strips navigation, ads, boilerplate. --- @@ -102,13 +102,13 @@ await supermemory.add("user_123", { **Extracts:** Structure, headings, code blocks with syntax awareness. -Code is chunked using [code-chunk](https://github.com/supermemoryai/code-chunk), which understands AST boundaries to keep functions, classes, and logical blocks intact. See [Super RAG](/concepts/super-rag) for how Supermemory optimizes chunking for each content type. +See [Super RAG](/concepts/super-rag) for how Supermemory optimizes chunking for each content type. --- ## Images -Set `fileType: "image"` and `mimeType` so Supermemory knows exactly how to process it. Both are query parameters, so they sit next to `namespace` rather than inside `body`: +Set `fileType: "image"` and `mimeType` so Supermemory knows exactly how to process it. Both are multipart form fields, sent in the same object as `file` and `metadata`: ```typescript await supermemory.documents.uploadFile("user_123", { @@ -127,7 +127,7 @@ await supermemory.documents.uploadFile("user_123", { ## Audio & video -Video has a dedicated `fileType`; audio is uploaded the same way and detected from the file itself: +Video and audio each have a dedicated `fileType` (`"video"`, `"audio"`); set it with `mimeType` when inference is not enough: ```typescript // Video @@ -142,6 +142,7 @@ await supermemory.documents.uploadFile("user_123", { await supermemory.documents.uploadFile("user_123", { file: fs.createReadStream('call-recording.mp3'), metadata: JSON.stringify({ title: "Customer Call Recording" }), + fileType: "audio", mimeType: "audio/mpeg", }); ``` @@ -215,7 +216,7 @@ await supermemory.add("user_123", { content: "https://example.com/page" }); await supermemory.add("user_123", { content: "User said they prefer email contact" }); ``` -For files, `uploadFile` detects type from the file itself in most cases. `fileType` and `mimeType` only exist to force specific processing when inference is not enough — set them for images and video. +For files, `uploadFile` detects type from the file itself in most cases. `fileType` and `mimeType` only exist to force specific processing when inference is not enough — set them for images, video, and audio. --- @@ -227,7 +228,7 @@ For files, `uploadFile` detects type from the file itself in most cases. `fileTy | Files | 50MB | | URLs | Fetched content up to 10MB | -**Typical processing time:** text is near-instant; PDFs take 1-5s; images 2-10s; video 10s+; webpages 1-3s. Text content is chunked at the sentence level with a 2-sentence overlap between chunks. +**Typical processing time:** text is near-instant; PDFs take 1-5s; images 2-10s; video 10s+; webpages 1-3s. Text content is split on sentence boundaries, with about 200 characters of overlap carried between chunks. For large files, consider chunking or using [connectors](/connectors/overview) for automatic sync. diff --git a/apps/docs/concepts/graph-memory.mdx b/apps/docs/concepts/graph-memory.mdx index 2d70a342..b70cc44f 100644 --- a/apps/docs/concepts/graph-memory.mdx +++ b/apps/docs/concepts/graph-memory.mdx @@ -27,7 +27,7 @@ await supermemory.add("user_123", { dreaming: "instant", // memories land in the graph right away }); -const results = await supermemory.search("user_123", { +const { results } = await supermemory.search("user_123", { query: "where does Alex work?", include: { related: true }, searchMode: "memories", @@ -154,7 +154,7 @@ await supermemory.add("user_123", { content: "Alex mentioned he just started at Stripe", }); -const results = await supermemory.search("user_123", { +const { results } = await supermemory.search("user_123", { query: "where does Alex work?", include: { related: true }, searchMode: "memories", diff --git a/apps/docs/concepts/how-it-works.mdx b/apps/docs/concepts/how-it-works.mdx index cd58d90d..07981632 100644 --- a/apps/docs/concepts/how-it-works.mdx +++ b/apps/docs/concepts/how-it-works.mdx @@ -61,10 +61,10 @@ results = client.search("user_123", query="where does the user want to travel?") ``` ```bash curl -curl -X POST "https://api.supermemory.ai/ns/user_123/document?dreaming=instant" \ +curl -X POST "https://api.supermemory.ai/ns/user_123/document" \ -H "Authorization: Bearer sm_..." \ -H "Content-Type: application/json" \ - -d '{ "content": "The user loves Paris." }' + -d '{ "content": "The user loves Paris.", "dreaming": "instant" }' curl -X POST "https://api.supermemory.ai/ns/user_123/search" \ -H "Authorization: Bearer sm_..." \ @@ -118,7 +118,7 @@ A document with status `done` has its chunks indexed for search. Memories (the g This is when the content is passed through the memory model and merged, arranged and organized for the future. -Pass `dreaming` on [add](/ingestion/add-memories) (a query parameter, so a top-level key in the SDK): +Pass `dreaming` on [add](/ingestion/add-memories) (a field in the JSON body, next to `content` in the SDK): | Mode | Default? | Behavior | When to use | | --- | --- | --- | --- | diff --git a/apps/docs/ingestion/add-memories.mdx b/apps/docs/ingestion/add-memories.mdx index b2e01b72..dde7051e 100644 --- a/apps/docs/ingestion/add-memories.mdx +++ b/apps/docs/ingestion/add-memories.mdx @@ -66,7 +66,7 @@ Every write goes to one `namespace` (what v3/v4 called a container tag). The nam ``` -If an irrecoverable processing error occurs, the document is automatically deleted after 2 minutes. +If an irrecoverable processing error occurs, the document's status becomes `failed`. Send the content again with the same `id` to reprocess it. --- @@ -193,16 +193,16 @@ Scale and Enterprise include [advanced document extraction for PDFs](/concepts/c ## Parameters -`namespace`, `taskType`, and `dreaming` are top-level keys on the SDK call (`taskType` and `dreaming` are query parameters on the HTTP route). Everything else goes in `body`. +`namespace` is the first argument on the SDK call and the URL path on the HTTP route. Every other parameter, including `taskType` and `dreaming`, goes in the request object (the JSON body over HTTP). The route accepts no query parameters; sending one returns `400`. | Parameter | Type | Description | |-----------|------|-------------| | `namespace` | string | **Required.** Group by user/project. Goes in the URL path. Required for user profiles | | `content` | string | **Required.** Any raw content — text, conversations, URLs, HTML | | `id` | string | **Recommended.** Your ID for the content (conversation ID, doc ID). Enables updates and deduplication. The response `id` echoes it back | -| `metadata` | object | Key-value pairs for filtering (strings, numbers, booleans) | +| `metadata` | object | Key-value pairs for filtering (strings, numbers, booleans, or arrays of strings) | | `group` | object | Filter which existing memories are used as context during ingestion. See [Filtered Writes](#filtered-writes) | -| `supportingContext` | string | Context for memory extraction on this namespace. Max 1500 chars. See [Customization](/concepts/customization#entity-context) | +| `supportingContext` | string | Context for memory extraction on this namespace. Max 1500 chars. See [Customization](/concepts/customization#supporting-context) | | `date` | string | ISO 8601 date the content was originally created. Use when backfilling. See [Backfill historical data](/ingestion/batch-ingest-historical-data) | | `dreaming` | `"dynamic" \| "instant"` | Processing mode. Default `"dynamic"`. `"instant"` processes each document on its own and bills one extra operation. See [Processing Modes](#processing-modes) | | `taskType` | `"memory" \| "superrag"` | Pipeline to run. Default `"memory"`. `"superrag"` skips fact extraction and profile updates, doing only chunk/embed/index — at 5x cheaper per token. See [SuperRAG ingestion](/concepts/super-rag#ingesting-as-pure-superrag-tasktype-superrag) | @@ -223,16 +223,16 @@ Scale and Enterprise include [advanced document extraction for PDFs](/concepts/c { content: "# Project Docs\n\n## Features\n- Real-time sync" } ``` - **Namespaces:** + **Namespaces** (first argument; letters, numbers, `-`, `_`, and `:`, up to 100 characters): ```typescript // By user - { namespace: "user_123" } + await supermemory.add("user_123", { content: "..." }); // By project - { namespace: "project_alpha" } + await supermemory.add("project_alpha", { content: "..." }); // Hierarchical - { namespace: "org_456_team_backend" } + await supermemory.add("org_456_team_backend", { content: "..." }); ``` **IDs (Recommended):** @@ -262,8 +262,8 @@ Scale and Enterprise include [advanced document extraction for PDFs](/concepts/c } } ``` - - No nested objects or arrays - - Values: string, number, or boolean only + - No nested objects + - Values: string, number, boolean, or an array of strings **Supporting Context:** ```typescript @@ -363,7 +363,7 @@ The metadata itself is still written to the document, but the memories will only ### How it works When `group` is provided: -- **Profile memories** (static context) are filtered to only those from documents matching the metadata +- **Profile memories** (static context) are filtered by the existing memories' metadata - **Similar memories** used as context during ingestion are filtered the same way - The new document's own metadata is written normally — the filter only affects which **existing** memories are used as context @@ -371,7 +371,7 @@ When `group` is provided: | Key | Type | Description | |-----|------|-------------| -| `group` | `Record` | Key-value pairs to filter existing memories by their source document metadata | +| `group` | `Record` | Key-value pairs to filter existing memories by their own metadata, rather than a live join to source-document metadata | - **Scalar values** (string, number, boolean) match exactly - **Array values** match if **any** value in the array matches (OR logic) @@ -404,7 +404,7 @@ When you add content, Supermemory: Track progress with `GET /ns/{namespace}/document/{id}`: ```typescript const doc = await supermemory.documents.get("user_123", "abc123"); -console.log(doc.system.status); // "queued" | "processing" | "done" +console.log(doc.system.status); // "queued" | "extracting" | "chunking" | "embedding" | "done" | "failed" ``` @@ -444,17 +444,19 @@ console.log(doc.system.status); // "queued" | "processing" | "done" | Status | Error | Cause | |--------|-------|-------| - | 400 | Bad request | Missing required fields, invalid parameters | + | 400 | Bad request | Missing required fields, invalid parameters, unexpected query parameters | | 401 | Unauthorized | Invalid or missing API key | - | 403 | Forbidden | Insufficient permissions | - | 429 | Rate limited | Too many requests or quota exceeded | + | 402 | Payment required | Insufficient balance or document quota | + | 403 | Forbidden | No write access to this namespace | + | 409 | Conflict | A namespace merge is in progress | + | 429 | Rate limited | Too many requests | | 500 | Internal error | Processing failure | ```typescript try { await supermemory.add("user_123", { content: "..." }); } catch (error) { - // Back off on 429, fix the request on 400, retry later on 5xx + // Back off on 429, top up on 402, fix the request on 400, retry later on 5xx console.error("add failed:", error); } ``` diff --git a/apps/docs/ingestion/batch-ingest-historical-data.mdx b/apps/docs/ingestion/batch-ingest-historical-data.mdx index 7bea599f..a859e93b 100644 --- a/apps/docs/ingestion/batch-ingest-historical-data.mdx +++ b/apps/docs/ingestion/batch-ingest-historical-data.mdx @@ -102,7 +102,7 @@ curl -X POST "https://api.supermemory.ai/ns/historical_import/document/batch" \ -Batch results preserve input order. Inspect `success`, `failed`, and every item in `results`; a batch can contain successful and failed items together. +`results` lists accepted documents first, in request order, then failed ones, so match each result by `id`. Inspect `count` (accepted), `failed`, and every item in `results`; a batch can contain successful and failed items together. ## Optional: wait for processing to finish diff --git a/apps/docs/ingestion/document-operations.mdx b/apps/docs/ingestion/document-operations.mdx index 8234b900..428e7c2f 100644 --- a/apps/docs/ingestion/document-operations.mdx +++ b/apps/docs/ingestion/document-operations.mdx @@ -49,7 +49,9 @@ Retrieve paginated documents with filtering. One `list` call serves documents, c "id": "doc_abc123", "title": "Meeting notes", "type": "text", + "summary": "Team sync covering the Q3 roadmap", "metadata": { "source": "slack" }, + "url": null, "system": { "status": "done", "dreamingStatus": "done", @@ -73,16 +75,17 @@ Every response contains `documents`, `chunks`, `memories`, and `pagination`. Onl ### Parameters -`namespace` and `type` are required. Pagination and sorting are query parameters (top-level keys in the SDK); `filter` goes in `body`. +`namespace` and `type` are required. Over HTTP, pagination and sorting are query parameters and `filter` and `include` go in the JSON body; the SDK takes them all in one options object after `namespace` and `type`. Unknown query or body keys return `400`. | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `type` | string | required | `documents`, `chunks`, or `memories` | -| `limit` | number | 10 | Items per page | +| `limit` | number | 10 | Items per page (maximum 100) | | `page` | number | 1 | Page number | -| `sort` | string | `createdAt` | Sort by `createdAt`, `updatedAt`, or `position` | +| `sort` | string | `createdAt` | `createdAt` or `updatedAt` for documents and memories; `createdAt` or `position` for chunks | | `order` | string | `desc` | `desc` (newest) or `asc` (oldest) | | `body.filter` | object | — | Metadata filter. See [Organizing & Filtering](/concepts/filtering) | +| `body.include.forgotten` | boolean | `false` | Memories only: include forgotten or expired rows that remain latest, returned with `isForgotten: true`. Normal forgetting makes a memory non-latest, so it still will not appear in this list | ```typescript @@ -133,8 +136,7 @@ Get a specific document with its processing status. Pass `include` to include it include: ["chunks", "memories"], // optional }); - console.log(doc.system.status); // "queued" | "processing" | "done" | "failed" - console.log(doc.system.dreamingStatus); // "dreaming" | "done" + console.log(doc.system.status); // "queued" | "extracting" | ... | "done" | "failed" console.log(doc.content); ``` @@ -146,8 +148,7 @@ Get a specific document with its processing status. Pass `include` to include it include=["chunks", "memories"], # optional ) - print(doc.system.status) # "queued" | "processing" | "done" | "failed" - print(doc.system.dreaming_status) # "dreaming" | "done" + print(doc.system.status) # "queued" | "extracting" | ... | "done" | "failed" print(doc.content) ``` @@ -161,6 +162,10 @@ Get a specific document with its processing status. Pass `include` to include it The `id` may be the Supermemory document ID or the `id` you supplied at ingestion. It resolves only inside the namespace in the path. + +The current HTTP response also includes `system.dreamingStatus`. TypeScript SDK 5.0.1 and Python SDK 5.0.0 do not expose that field in their generated models; Python's `system.dreaming_status` is not available. Use the raw HTTP response when monitoring memory generation with these versions, or upgrade the TypeScript SDK to 5.0.2 for typed `system.dreamingStatus`. `system.status: "done"` alone does not mean memories are ready. + + ### Processing status | Status | Description | @@ -172,6 +177,8 @@ The `id` may be the Supermemory document ID or the `id` you supplied at ingestio | `done` | Ready for search | | `failed` | Processing failed | +Treat any status other than `done` or `failed` as still in progress. + ### Memory generation status `system.dreamingStatus` tracks memory generation separately from `system.status`. @@ -202,7 +209,7 @@ With the default `dreaming: "dynamic"`, Supermemory batches related documents be ## Update document -Update a document's content or metadata. **Content changes** trigger full reprocessing; **metadata-only changes** (e.g. updating `accepted`, `version`) do not reindex. The body accepts any non-empty subset of `content`, `metadata`, `supportingContext`, `group`, or `date`. +Update a document's content or metadata. **Content changes** trigger full reprocessing; **metadata-only changes** (e.g. updating `accepted`, `version`) do not reindex. The body accepts any non-empty subset of `content`, `metadata`, `supportingContext`, or `date`. Metadata merges key by key. `group` is an ingestion-side setting: it picks which existing memories serve as context while content is processed, so changing it only takes effect when the document is re-ingested. Send it together with `content`. @@ -291,7 +298,7 @@ Permanently remove documents. One call deletes 1 to 100 documents by Supermemory -Inspect both `count` and per-ID `errors`; HTTP success can include partial failures. +Inspect both `count` and per-ID `errors`; HTTP success can include partial failures. Only documents whose `system.status` is `done` or `failed` can be deleted; a document that is still processing is reported in `errors` as `Document is still processing`. Memories derived from a deleted document are forgotten. Deletes are permanent — no recovery. @@ -301,7 +308,7 @@ Deletes are permanent — no recovery. ## Processing queue -There is no separate processing endpoint. List documents and read `system.status` and `system.dreamingStatus` on each item. +There is no separate processing endpoint. List documents and read `system.status` and `system.dreamingStatus` on each item in the HTTP response. The SDK examples below count documents still being indexed; use raw HTTP for memory-generation status with the SDK versions noted above. @@ -310,16 +317,14 @@ There is no separate processing endpoint. List documents and read `system.status limit: 100, }); const processing = documents.filter(d => d.system.status !== "done" && d.system.status !== "failed"); - const dreaming = documents.filter(d => d.system.dreamingStatus === "dreaming"); - console.log(`${processing.length} documents processing, ${dreaming.length} forming memories`); + console.log(`${processing.length} documents processing`); ``` ```python page = client.list("user_123", "documents", limit=100) processing = [d for d in page.documents if d.system.status not in ("done", "failed")] - dreaming = [d for d in page.documents if d.system.dreaming_status == "dreaming"] - print(f"{len(processing)} documents processing, {len(dreaming)} forming memories") + print(f"{len(processing)} documents processing") ``` diff --git a/apps/docs/recall/memory-operations.mdx b/apps/docs/recall/memory-operations.mdx index dc4e6e8e..9cbf3f08 100644 --- a/apps/docs/recall/memory-operations.mdx +++ b/apps/docs/recall/memory-operations.mdx @@ -29,13 +29,14 @@ v5 has no direct memory-create route. Ingest a document instead and Supermemory ```bash - curl -X POST "https://api.supermemory.ai/ns/user_123/document?dreaming=instant" \ + curl -X POST "https://api.supermemory.ai/ns/user_123/document" \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "John prefers dark mode.\nJohn is from Seattle.", "id": "prefs_john", - "metadata": { "source": "user_preference" } + "metadata": { "source": "user_preference" }, + "dreaming": "instant" }' ``` @@ -88,7 +89,7 @@ Soft-delete memories by ID. Forgotten memories are excluded from search results |-------|------|-------------| | `count` | number | Number of memories forgotten; always equals `matches.length` | | `matches` | array | The memories that were forgotten (`{ id, memory }`) | -| `errors` | array | IDs that were missing or not eligible (`{ id, error }`) | +| `errors` | array | IDs that were missing, already forgotten, or in another namespace (`{ id, error }`) | HTTP success does not imply every requested ID changed. Check `errors`. @@ -99,7 +100,7 @@ HTTP success does not imply every requested ID changed. Check `errors`. Forget by meaning. Give a `query` (a prompt or topic) and the service semantically searches the namespace, decides which memories are genuinely about your target, and soft-deletes those — use this for "forget everything about X". -This is a bulk, destructive operation. `dryRun` is required. Call with **`dryRun: true`** first to review what would be forgotten, then apply. The match is semantic, so a too-broad query can select more than you intend. +This is a bulk, destructive operation. `dryRun` is required. Call with **`dryRun: true`** first to review what would be forgotten, then apply. The match is semantic, so a too-broad query can select more than you intend. Each request selects at most 100 memories. After applying a batch, repeat the preview-and-apply workflow to find more; repeated previews alone do not paginate and may return the same matches. @@ -144,7 +145,7 @@ This is a bulk, destructive operation. `dryRun` is required. Call with **`dryRun | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `namespace` | string | yes | Namespace to scope the operation to (URL path) | -| `query` | string | yes | What to forget — a natural-language instruction ("forget everything about Project Titan") or a bare topic ("Project Titan") | +| `query` | string | yes | What to forget — a natural-language instruction ("forget everything about Project Titan") or a bare topic ("Project Titan"). 1 to 2000 characters | | `dryRun` | boolean | yes | `true` returns what *would* be forgotten without changing anything. `false` forgets the memories selected when that request runs | ### Response @@ -161,7 +162,7 @@ Both dry-run and applied requests return the same shape as [Forget Memories](#fo } ``` -The payload does not say which mode was sent, so keep your own record of `dryRun` next to audit logs. +`errors` is always empty for semantic requests. The payload does not say which mode was sent, so keep your own record of `dryRun` next to audit logs. **Exact, bound deletes.** Re-running `forgetMatching` with `dryRun: false` re-runs the semantic match, so the result can drift from the preview if the namespace changed in between. To forget *precisely* what you reviewed, take the `id`s from the `dryRun` preview and send them to `memories.forget` — the delete is then bound to exactly that set. diff --git a/apps/docs/snippets/api-v5-content-management.mdx b/apps/docs/snippets/api-v5-content-management.mdx index ecbf6dc0..e926f97b 100644 --- a/apps/docs/snippets/api-v5-content-management.mdx +++ b/apps/docs/snippets/api-v5-content-management.mdx @@ -31,7 +31,7 @@ GET /ns/{namespace}/memories/{id}?include=related,documents&relatedLimit=10 Returns one memory with `id`, `memory`, `metadata`, `isStatic`, `isInference`, `isLatest`, `isForgotten`, `version`, and `system.createdAt/updatedAt`. A memory from another namespace returns `404`; a forgotten memory, or one past its `forget_after`, is still returned with `isForgotten: true`. -- `include=related` adds `included.related.parents` (earlier versions), `children` (newer versions), and `siblings` (memories connected by `extends` or `derives`). Each list walks outward from the memory until it holds `relatedLimit` items (default `10`, maximum `100`). Forgotten memories and memories in other namespaces are left out. +- `include=related` adds `included.related.parents` (earlier versions), `children` (newer versions), and `siblings` (memories directly connected by `extends` or `derives`). Parents and children reach up to three versions away, nearest first. Each list holds at most `relatedLimit` items (default `10`, maximum `100`). Forgotten memories and memories in other namespaces are left out. - `include=documents` adds `included.document`, the most recently updated source document. With both values, every related memory also carries its own `document`. ### List documents, chunks, or memories @@ -48,9 +48,9 @@ POST /ns/{namespace}/list/{type}?page=1&limit=100&sort=createdAt&order=desc ``` -Set `type` to `documents`, `chunks`, or `memories`. Pagination and sorting move to the query string as plain integers and values; the body takes an optional `filter` and, for memories, `include`. Defaults are `page=1`, `limit=10` (maximum 100), `sort=createdAt`, and `order=desc`. +Set `type` to `documents`, `chunks`, or `memories`. Pagination and sorting move to the query string as plain integers and values; the body takes an optional `filter` and, for memories, `include`. Defaults are `page=1`, `limit=10` (maximum 100), `sort=createdAt`, and `order=desc`. `sort` accepts `createdAt` or `updatedAt` for documents and memories, and `createdAt` or `position` for chunks; any other combination returns `400`. -Memory lists hide forgotten memories and memories past their `forget_after`. Send `"include": {"forgotten": true}` to list them too; they come back with `isForgotten: true`. Document memories (`include=memories` on `GET /ns/{namespace}/document/{id}`) report the same flag. +Memory lists return only the latest version of each memory and hide forgotten memories and memories past their `forget_after`. Sending `"include": {"forgotten": true}` admits forgotten or expired rows only if they remain latest; they come back with `isForgotten: true`. Normal forgetting makes a memory non-latest, so this list does not recover it even with that flag. To search such memories, use search with `include.forgotten`. Document memories (`include=memories` on `GET /ns/{namespace}/document/{id}`) report the same forgotten flag. Every response contains `documents`, `chunks`, `memories`, and `pagination`. Only the selected resource array is populated. Replace legacy `memories` assumptions in document-list callers with `documents`. @@ -68,7 +68,7 @@ DELETE /ns/{namespace}/document ``` -The v5 array accepts 1–100 Supermemory or caller-defined IDs. Inspect both `count` and per-ID `errors`; HTTP success can include partial failures. +The v5 array accepts 1–100 Supermemory or caller-defined IDs. Inspect both `count` and per-ID `errors`; HTTP success can include partial failures. Only documents whose `system.status` is `done` or `failed` are deleted; one that is still processing comes back in `errors` as `Document is still processing`. ### With the SDK diff --git a/apps/docs/snippets/api-v5-document-updates.mdx b/apps/docs/snippets/api-v5-document-updates.mdx index 1c97e95d..a6407f5d 100644 --- a/apps/docs/snippets/api-v5-document-updates.mdx +++ b/apps/docs/snippets/api-v5-document-updates.mdx @@ -6,7 +6,7 @@ v5 makes the difference between adding new information and replacing the canonic | --- | --- | --- | | Add information to a stable caller ID | `POST /ns/{namespace}/document` | Append/diff | | Replace text or URL content | `PATCH /ns/{namespace}/document/{id}` | Replace and reprocess | -| Update only supporting fields | Same `PATCH` without `content` | Canonical content unchanged | +| Update only metadata, context, or date | Same `PATCH` without `content` | Canonical content unchanged | | Replace a source file and its user metadata | `POST /ns/{namespace}/document/file/{id}` | Full replacement and reprocess | | Partially update a file or its supporting fields | `PATCH /ns/{namespace}/document/file/{id}` | Omitted fields remain unchanged | @@ -24,7 +24,7 @@ PATCH /ns/user_1/document/doc_1 ``` -The v5 body accepts any non-empty subset of `content`, `supportingContext`, `metadata`, `group`, or `date`, plus optional `taskType` and `dreaming` (which alone do not count as a change). Supplying `content` makes it the new canonical source; facts supported only by the previous source can disappear after reprocessing. +The v5 body accepts any non-empty subset of `content`, `supportingContext`, `metadata`, or `date`, plus optional `taskType` and `dreaming` (which alone do not count as a change). `group` is an ingestion-side setting: it picks which existing memories serve as context while content is processed, so changing it only takes effect when the document is re-ingested. Send it together with `content`. Supplying `content` makes it the new canonical source; facts supported only by the previous source can disappear after reprocessing. ### Replace a file-backed document @@ -37,7 +37,7 @@ metadata={"revision":2} dreaming=dynamic ``` -POST requires `file` and replaces the canonical source plus user-controlled metadata, grouping, context, and date. Omitted supporting fields are cleared. Use it when the submitted request is the complete new representation of the file-backed document. +POST requires `file` and replaces the canonical source plus caller metadata, including `date`. Omitted metadata and date are cleared. `supportingContext` is stored on the namespace, so omitting it leaves the namespace's existing context unchanged. Use it when the submitted request is the complete new representation of the file-backed document. ### Partially update a file-backed document @@ -49,7 +49,7 @@ metadata={"reviewed":true} dreaming=dynamic ``` -PATCH changes only supplied fields. Include `file` to replace the source while retaining omitted supporting fields, or omit `file` for metadata-, group-, context-, or date-only changes. `metadata` and `group` are JSON-encoded strings; `supportingContext` and `date` are plain strings. +PATCH changes only supplied fields. Include `file` to replace the source while retaining omitted supporting fields, or omit `file` for metadata-, context-, or date-only changes. Like the JSON update, `group` only takes effect when the file is re-ingested, so send it together with `file`. `metadata` and `group` are JSON-encoded strings; `supportingContext` and `date` are plain strings. There is no public v5 `PUT /ns/{namespace}/document/file/{id}` operation. Use POST for a complete replacement and PATCH for a partial update. @@ -90,7 +90,7 @@ The path `id` may be the Supermemory document ID or your caller-defined ID. It i ### Processing and conflicts -Content or file replacement is accepted before downstream processing completes. A document still processing, a namespace conflict, or a conflicting internal file path can return `409`; retry only after the conflicting operation reaches a terminal state. +Content or file replacement is accepted before downstream processing completes. A namespace merge in progress or a conflicting internal file path returns `409`; retry a merge conflict after the merge finishes. ### Verification diff --git a/apps/docs/snippets/api-v5-memory-forgetting.mdx b/apps/docs/snippets/api-v5-memory-forgetting.mdx index 2db8b57f..6f943cd6 100644 --- a/apps/docs/snippets/api-v5-memory-forgetting.mdx +++ b/apps/docs/snippets/api-v5-memory-forgetting.mdx @@ -16,7 +16,7 @@ Content-Type: application/json {"ids":["mem_1","mem_2"]} ``` -Send 1–500 IDs. The response reports successful IDs in `matches` and missing or ineligible IDs in `errors`, so HTTP success does not imply every requested ID changed. +Send 1–500 IDs. The response reports successful IDs in `matches` and missing, already forgotten, or out-of-namespace IDs in `errors`, so HTTP success does not imply every requested ID changed. ### Preview a semantic request @@ -27,7 +27,7 @@ Content-Type: application/json {"query":"outdated home address","dryRun":true} ``` -`dryRun: true` performs selection without changing memory state. `dryRun: false` forgets the memories selected when that request executes. +`dryRun: true` performs selection without changing memory state. `dryRun: false` forgets the memories selected when that request executes. `query` is 1–2000 characters, and each request selects at most 100 memories. After applying a batch, repeat the preview-and-apply workflow to find more; repeated previews alone do not paginate and may return the same matches. ### Avoid selection drift @@ -53,7 +53,7 @@ Use this workflow when a human or policy must approve the exact set. Re-running } ``` -`count` always equals `matches.length`. Both dry-run and applied semantic requests use this shape; the payload alone does not replace your record of which mode was sent. +`count` always equals `matches.length`. Semantic requests always return an empty `errors` array. Both dry-run and applied semantic requests use this shape; the payload alone does not replace your record of which mode was sent. ### With the SDK diff --git a/apps/docs/v5/api-reference/content-management.mdx b/apps/docs/v5/api-reference/content-management.mdx index 6e8fd1f5..37d05a94 100644 --- a/apps/docs/v5/api-reference/content-management.mdx +++ b/apps/docs/v5/api-reference/content-management.mdx @@ -41,4 +41,4 @@ curl -X POST "https://api.supermemory.ai/ns/user_1/list/documents?page=1&limit=5 ``` -Semantic forgetting supports `dryRun: true`, so you can review matches before deleting them. See [document read migration](/migration/api-v5-document-reads) and [memory migration](/migration/api-v5-recall). +Semantic forgetting supports `dryRun: true`, so you can review matches before deleting them. See [document read migration](/migration/api-v5-document-reads) and [memory forgetting migration](/migration/api-v5-memory-forgetting). diff --git a/apps/docs/v5/api-reference/ingest.mdx b/apps/docs/v5/api-reference/ingest.mdx index 6206219c..54e49609 100644 --- a/apps/docs/v5/api-reference/ingest.mdx +++ b/apps/docs/v5/api-reference/ingest.mdx @@ -27,10 +27,10 @@ const { id, status } = await supermemory.add("user_1", { ``` ```bash curl -curl -X POST "https://api.supermemory.ai/ns/user_1/document?dreaming=instant" \ +curl -X POST "https://api.supermemory.ai/ns/user_1/document" \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ - -d '{"content":"The user prefers concise project updates","id":"conv_1","metadata":{"source":"chat"}}' + -d '{"content":"The user prefers concise project updates","id":"conv_1","metadata":{"source":"chat"},"dreaming":"instant"}' ```