Skip to main content
On v3 or v4? Run npx supermemory@latest migrate, or read the full v5 migration guide.

​
Migration details

v5 retrieves, lists, and removes content within one explicit namespace.

​
Retrieve a document and its derived context

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

v5
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=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

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

The v5 array accepts 1–100 Supermemory or caller-defined IDs. Inspect both count and per-ID errors; HTTP success can include partial failures.

​
With the SDK

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

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