Device Memory API

REST API reference for device-memory endpoints

Device memory reuses the existing store_memory and search endpoints. Pass snapshot instead of collection_id — they are mutually exclusive.

All endpoints require authentication via X-API-Key header (or Authorization: Bearer <token>).

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

Python

from nebula import Nebula

client = Nebula(api_key="YOUR_API_KEY")
snapshot = client.export_snapshot(collection_id="YOUR_COLLECTION_ID")

---

Store Memory

The existing /v1/memories endpoint accepts a snapshot field instead of collection_id. When a snapshot is provided, Nebula processes the content statelessly and returns an updated snapshot instead of a memory_id.

POST /v1/memories

Field	Type	Required	Description
snapshot	object	Yes	Your current snapshot (mutually exclusive with collection_id)
raw_text	string	Yes	Content to store
metadata	object	No	Arbitrary metadata

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

Python

from nebula import Memory

result = client.store_memory(
    Memory(
        snapshot=snapshot,
        content="Had a meeting with Alice about the Q2 roadmap",
    )
)

snapshot = result.snapshot

---

Search

The existing /v1/memories/search endpoint accepts a snapshot 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	Your full snapshot (mutually exclusive with collection_ids)
query	string	Yes	Natural language search query

Returns the same MemoryResponse format as standard search (semantics, procedures, episodes, sources).

Python

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

for fact in results.semantics:
    print(f"{fact['subject']} -> {fact['predicate']} -> {fact['value']}")

---

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	The full snapshot to import

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

Python

ephemeral_id = client.import_snapshot(snapshot=snapshot)