Device Memory API

Device memory reuses the existing memories.create and memories.search endpoints. Pass snapshot or snapshot_ref instead of collection_id — they are mutually exclusive.

All endpoints require authentication via the Authorization: Bearer <token> header.

Export Snapshot

Export a collection’s full graph state as a portable snapshot.

POST /v1/device-memory/snapshot/export

Field	Type	Required	Description
`collection_id`	string	Yes	UUID of the collection to export
`destination`	object	No	Signed URL destination for customer-owned snapshot storage

from nebula import Nebula

client = Nebula(api_key="YOUR_API_KEY")
snapshot = client.snapshots.export(collection_id="YOUR_COLLECTION_ID").results

from nebula import AsyncNebula

async with AsyncNebula(api_key="YOUR_API_KEY") as client:
    snapshot = (
        await client.snapshots.export(collection_id="YOUR_COLLECTION_ID")
    ).results

import Nebula from '@nebula-ai/sdk';

const client = new Nebula({ apiKey: 'YOUR_API_KEY' });
const { results: snapshot } = await client.snapshots.export({
  collection_id: 'YOUR_COLLECTION_ID',
});

curl -X POST "https://api.zeroset.com/v1/device-memory/snapshot/export" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"collection_id": "YOUR_COLLECTION_ID"}'

To export directly to customer-owned object storage, pass a signed URL destination:

curl -X POST "https://api.zeroset.com/v1/device-memory/snapshot/export" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "collection_id": "YOUR_COLLECTION_ID",
    "destination": {
      "type": "signed_url",
      "collection_id": "YOUR_COLLECTION_ID",
      "put_url": "https://storage.example.com/signed-put-url"
    }
  }'

Store Memory

The existing /v1/memories endpoint accepts a snapshot or snapshot_ref field instead of collection_id. When a snapshot source is provided, Nebula processes the content statelessly and returns an updated snapshot or writes the updated snapshot to your signed URL.

POST /v1/memories

Field	Type	Required	Description
`snapshot`	object	Yes, unless using `snapshot_ref`	Your current snapshot (mutually exclusive with `collection_id` and `snapshot_ref`)
`snapshot_ref`	object	Yes, unless using `snapshot`	Signed URL reference for customer-owned snapshot storage
`raw_text`	string	Yes	Content to store
`metadata`	object	No	Arbitrary metadata

Returns { "snapshot": <updated_snapshot> } when using device memory mode.

result = client.memories.create(
    snapshot=snapshot,
    raw_text="Had a meeting with Alice about the Q2 roadmap",
).results

snapshot = result.snapshot

async with AsyncNebula(api_key="YOUR_API_KEY") as client:
    result = (
        await client.memories.create(
            snapshot=snapshot,
            raw_text="Had a meeting with Alice about the Q2 roadmap",
        )
    ).results
    snapshot = result.snapshot

const { results } = await client.memories.create({
  snapshot,
  raw_text: 'Had a meeting with Alice about the Q2 roadmap',
});

snapshot = results.snapshot;

curl -X POST "https://api.zeroset.com/v1/memories" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "snapshot": { "...your snapshot..." },
    "raw_text": "Had a meeting with Alice about the Q2 roadmap"
  }'

With customer-owned snapshot storage, provide a signed URL reference:

curl -X POST "https://api.zeroset.com/v1/memories" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "snapshot_ref": {
      "type": "signed_url",
      "collection_id": "YOUR_COLLECTION_ID",
      "get_url": "https://storage.example.com/signed-get-url",
      "put_url": "https://storage.example.com/signed-put-url"
    },
    "raw_text": "Had a meeting with Alice about the Q2 roadmap"
  }'

Search

The existing /v1/memories/search endpoint accepts a snapshot or snapshot_ref field instead of collection_ids. Nebula scores your snapshot statelessly and returns results. Nothing is persisted.

POST /v1/memories/search

Field	Type	Required	Description
`snapshot`	object	Yes, unless using `snapshot_ref`	Your full snapshot (mutually exclusive with `collection_ids` and `snapshot_ref`)
`snapshot_ref`	object	Yes, unless using `snapshot`	Signed URL reference for customer-owned snapshot storage
`query`	string	Yes	Natural language search query

Returns a graph-shaped SnapshotSearchResult: entities (each with id, name, category, description, score) and relationships (each with id, subject_id, object_id, predicate, description, weight). This is distinct from the standard MemoryResponse returned by collection-based search.

results = client.memories.search(
    query="What do I know about Alice?",
    snapshot=snapshot,
).results

for entity in results.entities or []:
    print(f"{entity.name} ({entity.category}): {entity.description}")
for rel in results.relationships or []:
    print(f"{rel.subject_id} -[{rel.predicate}]-> {rel.object_id}")

results = (
    await client.memories.search(
        query="What do I know about Alice?",
        snapshot=snapshot,
    )
).results

const { results } = await client.memories.search({
  query: 'What do I know about Alice?',
  snapshot,
});

for (const entity of results.entities ?? []) {
  console.log(`${entity.name} (${entity.category}): ${entity.description}`);
}
for (const rel of results.relationships ?? []) {
  console.log(`${rel.subject_id} -[${rel.predicate}]-> ${rel.object_id}`);
}

curl -X POST "https://api.zeroset.com/v1/memories/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "snapshot": { "...your snapshot..." },
    "query": "What do I know about Alice?"
  }'

Search can also load the snapshot through a signed URL:

curl -X POST "https://api.zeroset.com/v1/memories/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "snapshot_ref": {
      "type": "signed_url",
      "collection_id": "YOUR_COLLECTION_ID",
      "get_url": "https://storage.example.com/signed-get-url"
    },
    "query": "What do I know about Alice?"
  }'

Import Snapshot

Import a snapshot into an ephemeral server-side collection. Useful for debugging or running server-side operations against a client-owned snapshot.

POST /v1/device-memory/snapshot/import

Field	Type	Required	Description
`snapshot`	object	Yes, unless using `snapshot_ref`	The full snapshot to import
`snapshot_ref`	object	Yes, unless using `snapshot`	Signed URL reference for customer-owned snapshot storage

Returns { "ephemeral_collection_id": "<uuid>" }.

ephemeral_id = client.snapshots.import_(snapshot=snapshot).results.ephemeral_collection_id

ephemeral_id = (
    await client.snapshots.import_(snapshot=snapshot)
).results.ephemeral_collection_id

const { results } = await client.snapshots.import({ snapshot });
const ephemeralId = results.ephemeral_collection_id;

curl -X POST "https://api.zeroset.com/v1/device-memory/snapshot/import" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"snapshot": { "...your snapshot..." }}'

Customer-Owned Snapshot Objects

Use snapshot_ref when snapshots are too large to send inline or when your application stores snapshots in customer-owned object storage.

{
  "type": "signed_url",
  "collection_id": "YOUR_COLLECTION_ID",
  "get_url": "https://storage.example.com/signed-get-url",
  "put_url": "https://storage.example.com/signed-put-url",
  "get_headers": {},
  "put_headers": {}
}

Field	Required	Description
`type`	No	Must be `signed_url`; defaults to `signed_url`
`collection_id`	Yes	Collection UUID Nebula authorizes before using the URL
`get_url`	For reads	Short-lived signed URL Nebula can GET
`put_url`	For writes	Short-lived signed URL Nebula can PUT
`get_headers`	No	Additional headers for the GET request
`put_headers`	No	Additional headers for the PUT request

Signed URLs must use public HTTPS destinations. Nebula rejects private, loopback, and link-local hosts, does not follow redirects, and caps snapshot download size.

Get Started

Core Guides

Advanced Guides

Device Memory

Integration

Device Memory API

Export Snapshot

Store Memory

Search

Import Snapshot

Customer-Owned Snapshot Objects

​Export Snapshot

​Store Memory

​Search

​Import Snapshot

​Customer-Owned Snapshot Objects

Export Snapshot

Store Memory

Search

Import Snapshot

Customer-Owned Snapshot Objects