Reason

Most memory APIs stop at retrieval: they hand back a ranked list and leave the reasoning to you. Reason goes a step further. It runs an agentic pass across the memories in a space, connecting related facts, weighing recency, and resolving what matters, then returns one synthesized answer.

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

Reason over a space

POST /v1/reason
Authorization: Bearer anona_live_YOUR_KEY
Content-Type: application/json

{
  "space_id": "customer-support-bot",
  "query": "What have we learned about Alice's career?"
}

Parameter	Type	Required	Description
`space_id`	string	Yes	Which space to synthesize from.
`query`	string	Yes	What you want to learn.

Response 200 OK

{
  "status": "complete",
  "insights": "Alice has progressed from junior to senior engineer over 6 years, specializing in distributed systems. She has taken on mentorship responsibilities recently.",
  "usage": {
    "input_tokens": 340,
    "output_tokens": 58
  }
}

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

client.reason() returns the synthesized string directly, or None when nothing was found.

How it works

Reason is read-only and never writes new memories. Internally it runs a multi-step pass: retrieving relevant facts, expanding context through linked entities, and cross-referencing related memories. Answer quality improves as more relevant memories accumulate in the space.

Error responses

Status	Code	Cause
400	`bad_request`	Missing `query` or `space_id`.
401	`unauthorized`	Missing or invalid API key.
403	`forbidden`	The space is not owned by your organization.
404	`not_found`	The space does not exist.
429	`rate_limited`	Credit quota or rate limit exceeded.

See the full error reference.

Next steps

Retrieve API

Query memories for specific information.

Chat

OpenAI-compatible chat with memory built in.

API Essentials

Memory (data plane)

LLM Proxy (drop-in)

Account (control plane)

Reason over a space

How it works

Error responses

Next steps

Retrieve API

Chat

​Reason over a space

​How it works

​Error responses

​Next steps

Retrieve API

Chat

Reason over a space

How it works

Error responses

Next steps