Nebula stores what your agents learn so they can retrieve it later. Five nouns carry the whole model.

The hierarchy

Resources belong to this hierarchy:

Organization → Account → Workspace → Collection → Memory

Your verified credential selects the organization. URLs name the resource: /v2/workspaces discovers accessible workspaces, /v2/workspaces/{workspace_id}/collections lists or creates collections, and /v2/collections/{collection_id}/memories reads or stores memories. The server resolves the collection's workspace and checks your current access. SDK constructors need only an API key.

Organization — the billing and ownership boundary.

Account — a tenant inside an organization.

Workspace — an isolated environment. Workspaces are read-only over the public API: list them with workspaces.list, fetch one with workspaces.get. A workspace is active or suspended; calls against a suspended workspace fail with workspace_suspended.

Collection — the unit you create and delete, and the boundary that search runs inside. A collection has a collection_id you choose, a name, and optional metadata.

Memory — the thing you store. A memory has a memory_id you choose, a kind, and content. See Memories.

Two things worth knowing early

Identifiers are UUIDs, and the clients generate them. collection_id, memory_id and retrieval_id are format: uuid on the wire — a human-readable slug is rejected. The TypeScript and Python clients generate one when you omit it, so the common path is to let them.

Pass your own UUID when you want the write to be idempotent: the same id with the same content is safe to retry, which matters because the store path is asynchronous. Note that path parameters are plain strings up to 128 characters — only the create/store/search bodies constrain the format.

Writes are asynchronous. memory.store, memory.delete and collections.delete return 202 with an operation rather than the finished resource. A memory is not searchable the moment the call returns — it becomes searchable when its operation reports search_ready.

Reads (workspaces.*, collections.get, collections.list, memory.get, memory.list, memory.search) are synchronous.