mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-11-04 07:30:17 +00:00
f3001517d1
## Why The document operations guide did not describe how to retrieve extracted text from a v5 document list, and the migration guide incorrectly said the list `include` object was for memories only. ## What changed - Document `include.content`, its `false` default, and a cURL request for uploaded files in the same section pattern as the surrounding guide. - Explain that list content is the last published extracted text, including the behavior before first publication and during failed replacement. - Correct the v5 migration and reference overview copy. ```mermaid flowchart LR A[Document operations guide] --> B[include.content request] B --> C[Published extracted text in list response] ``` ## Validation - Compared the guide and migration snippet with adjacent v5 docs for format and terminology. - `git diff --check` — passed. - `python3 -m json.tool apps/docs/docs.json` — passed. Related API PR: https://github.com/supermemoryai/mono/pull/3606 The written docs should publish with or after the API change. The generated v5 reference reads the deployed OpenAPI source, so it updates when that source is available and the docs site refreshes.
125 lines
6.5 KiB
Text
125 lines
6.5 KiB
Text
v5 retrieves, lists, and removes content within one explicit namespace.
|
||
|
||
### Retrieve a document and its derived context
|
||
|
||
<CodeGroup>
|
||
```bash Legacy
|
||
GET /v3/documents/{id}
|
||
GET /v3/documents/{id}/chunks
|
||
```
|
||
|
||
```bash v5
|
||
GET /ns/{namespace}/document/{id}?include=chunks,memories
|
||
```
|
||
</CodeGroup>
|
||
|
||
Pass `include` as a comma-separated list to return chunks, memories, or both. Keys you omit are absent; requested keys with no results are empty arrays. Lifecycle fields move under `system`:
|
||
|
||
```json
|
||
{"system":{"status":"done","dreamingStatus":"dreaming","createdAt":"...","updatedAt":"..."}}
|
||
```
|
||
|
||
`system.status` is one of `unknown`, `queued`, `extracting`, `chunking`, `embedding`, `indexing`, `done`, or `failed`.
|
||
|
||
`system.dreamingStatus` tracks memory generation separately. It is `dreaming` while memories for the latest content are queued, being generated, or waiting for a retry, and `done` once they are generated or when the document needed none. Under the default `dreaming: "dynamic"`, `status` can reach `done` minutes before `dreamingStatus` does, so wait on `dreamingStatus` when the next step reads memories or profiles. Legacy `GET /v3/documents/{id}` returned it as a top-level `dreamingStatus`; v5 nests it under `system` on document reads and on document list items.
|
||
|
||
### Retrieve a memory and its history
|
||
|
||
```bash v5
|
||
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 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
|
||
|
||
<CodeGroup>
|
||
```bash Legacy
|
||
POST /v3/documents/list
|
||
POST /v4/memories/list
|
||
```
|
||
|
||
```bash v5
|
||
POST /ns/{namespace}/list/{type}?page=1&limit=100&sort=createdAt&order=desc
|
||
{}
|
||
```
|
||
</CodeGroup>
|
||
|
||
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 `include` object. 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`.
|
||
|
||
Document lists omit `content` by default. Send `{"include":{"content":true}}` to return the last published extracted text, including text from uploaded files. `content` is `null` before the first extraction publishes. During a replacement, previous text remains until new text publishes and also remains if extraction fails. Including content can make responses large.
|
||
|
||
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`.
|
||
|
||
### Delete documents
|
||
|
||
<CodeGroup>
|
||
```bash Legacy
|
||
DELETE /v3/documents/{id}
|
||
DELETE /v3/documents/bulk
|
||
```
|
||
|
||
```bash v5
|
||
DELETE /ns/{namespace}/document
|
||
{"ids":["doc_1","external_id_2"]}
|
||
```
|
||
</CodeGroup>
|
||
|
||
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
|
||
|
||
<CodeGroup>
|
||
```ts Legacy
|
||
const doc = await client.documents.get("doc_1")
|
||
const page = await client.documents.list({ containerTags: ["user_1"] })
|
||
const processing = await client.documents.listProcessing()
|
||
await client.documents.delete("doc_1")
|
||
```
|
||
|
||
```ts v5
|
||
const doc = await supermemory.documents.get("user_1", "doc_1", {
|
||
include: ["chunks", "memories"],
|
||
})
|
||
|
||
const { documents, pagination } = await supermemory.list("user_1", "documents", {
|
||
page: 1,
|
||
limit: 100,
|
||
sort: "createdAt",
|
||
order: "desc",
|
||
})
|
||
|
||
const { memories } = await supermemory.list("user_1", "memories")
|
||
|
||
const { count, errors } = await supermemory.documents.delete("user_1", {
|
||
ids: ["doc_1", "external_id_2"],
|
||
})
|
||
```
|
||
</CodeGroup>
|
||
|
||
There is no separate processing list. Read `system.status` and `system.dreamingStatus` on each item returned by `supermemory.list(namespace, "documents")`. Chunks come from `supermemory.list(namespace, "chunks")` or `documents.get` with `include: ["chunks"]`.
|
||
|
||
### Forget memories
|
||
|
||
| Legacy intent | v5 operation |
|
||
| --- | --- |
|
||
| Forget exact IDs | `DELETE /ns/{namespace}/memories` with `{ "ids": [...] }` |
|
||
| Find memories by meaning | `DELETE /ns/{namespace}/memories/semantic` with `{ "query": "...", "dryRun": true }` |
|
||
|
||
Both return `{ count, matches, errors }`. For drift-free semantic deletion, preview with `dryRun: true`, review the IDs, then submit them to the exact-ID endpoint.
|
||
|
||
See [memory forgetting](/migration/api-v5-memory-forgetting) for the complete dry-run, approval, response, and audit workflow.
|
||
|
||
### Verification
|
||
|
||
- Assert requested empty includes are `[]`, while omitted includes are absent.
|
||
- Move readers of the legacy top-level `dreamingStatus` to `system.dreamingStatus`, and gate memory or profile reads on it rather than on `system.status`.
|
||
- Paginate each resource type until `currentPage >= totalPages`; unselected arrays stay empty.
|
||
- Verify chunk rows contain their parent `documentId`.
|
||
- Exercise partial document-delete failures and semantic dry runs.
|
||
- Verify IDs cannot read, list, or delete content outside their namespace.
|