Core Concepts

At a glance

Concept	What it is	Where it appears
Memory space	The isolation boundary for one application or tenant.	`space_id` on every call
Scope	A partition inside a space: one end user, agent, or session.	`user_id` / `agent_id` / `session_id`
Record	Storing a memory so its facts become searchable.	`POST /v1/record`
Retrieve	Ranking stored memories against a natural-language query.	`POST /v1/retrieve`
Reason	Synthesizing a single answer across many memories.	`POST /v1/reason`
API key	The credential that identifies your organization.	`Authorization: Bearer`
Credits	The unit every metered operation is billed in.	`GET /v1/usage/me`

Memory space

A space is where the memories for a specific application or context live. Your organization can hold many spaces, and each is fully isolated from the others. You create a space with a name, and that name is its permanent space_id, the identifier every other call takes. Nothing separate is generated, and space_id is not a field you can send on create.

POST /v1/spaces/
{"name": "customer-support-bot"}

# → {"space_id": "customer-support-bot", "name": "customer-support-bot", ...}

Reference: Spaces API

Scope

A space is the coarse boundary. Scope partitions it, so a single space serves many end users without their memories mixing:

POST /v1/record    {"space_id": "support", "user_id": "alice", "content": "..."}
POST /v1/retrieve  {"space_id": "support", "user_id": "alice", "query": "..."}

Do not create a space per end user. Spaces are capped per plan, and memories in different spaces can never be synthesized together, so you would lose exactly the cross-user view you built a memory layer for. One space plus user_id is the pattern. Scoping is strict: a scoped search returns only memories written under that same scope, never another user’s, and never unscoped ones. Consolidated memories are built per user, so a synthesis cannot mix two users’ facts. Reference: Scoping

Record

Storing a memory is not a plain insert. The content is analyzed, its durable facts are extracted, and the result is embedded and indexed for semantic search.

client.record(
    space_id="customer-support-bot",
    content="Alice works at Google and specializes in distributed systems",
)

Reference: Memories API

Retrieve

Retrieve finds memories by meaning rather than keyword overlap, and returns them ranked by relevance with their entities and event time attached.

results = client.retrieve(
    space_id="customer-support-bot",
    query="What is Alice's expertise?",
)

Reference: Retrieve API

Reason

Reason runs an agentic pass over the space, connecting related facts and weighing recency, and returns one synthesized answer instead of a ranked list.

answer = client.reason(
    space_id="customer-support-bot",
    query="What have we learned about Alice's career?",
)

	Retrieve	Reason
Returns	A ranked list of memories	A single synthesized answer
Cost	Lower	Higher, it reasons across the space
Use when	You want to inject context into a prompt	You want a conclusion, not the evidence

Reference: Reason API

API key

Every request carries Authorization: Bearer <key>. Keys are created and revoked from the dashboard under API keys, or through the API Keys endpoints. The full key is shown once at creation; afterwards only its prefix is visible. Reference: Authentication

Tenant isolation

Each organization’s memories live in a dedicated database schema, with no shared tables. A space_id belonging to one organization is both meaningless and inaccessible to another. The boundary is enforced twice: as an authorization check at the gateway, and again at the database layer.

Getting Started

API Essentials

Memory (data plane)

LLM Proxy (drop-in)

Account (control plane)

SDKs & MCP

Integrations

Guides

Changelog

At a glance

Memory space

Scope

Record

Retrieve

Reason

API key

Tenant isolation

Next steps

API overview

Python SDK

​At a glance

​Memory space

​Scope

​Record

​Retrieve

​Reason

​API key

​Tenant isolation

​Next steps

API overview

Python SDK

At a glance

Memory space

Scope

Record

Retrieve

Reason

API key

Tenant isolation

Next steps