Getting started
Quickstart
Retain your first memory and recall it in five minutes.
1. Get an API key
Create a workspace at illumina.sh and mint an API key
from the dashboard. Keys start with sub_live_ and are shown once at creation.
export ILLUMINA_API_KEY=sub_live_...All requests authenticate with a bearer header. See Authentication for scoping and key management.
2. Create a namespace
Memories live in namespaces. Retain does not auto-create one, so create it first:
curl -X PUT "https://api.illumina.sh/v1/default/namespaces/demo" \
-H "Authorization: Bearer $ILLUMINA_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'3. Retain a memory
Write raw text into the namespace. Illumina extracts facts, entities, and relationships asynchronously:
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/memories" \
-H "Authorization: Bearer $ILLUMINA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"items":[{"content":"Ada shipped the payments rewrite in Q3 2025."}]}'Retain is asynchronous
Retain returns an operation_id immediately and extracts facts in the
background. Poll the operation if you need to know
when it lands, or wait a few seconds before your first recall.
4. Recall
Query the namespace. budget controls retrieval effort (low, mid, or
high):
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/memories/recall" \
-H "Authorization: Bearer $ILLUMINA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"who shipped payments?","budget":"mid","max_tokens":2048}'5. Reflect
Ask a higher-level question over everything the namespace knows:
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/reflect" \
-H "Authorization: Bearer $ILLUMINA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"summarize Ada'\''s recent work","budget":"low","max_tokens":512}'The same flow in an SDK
from illumina_client import Illumina
client = Illumina(base_url="https://api.illumina.sh", api_key="sub_live_...")
client.create_namespace(namespace_id="demo")
client.retain(namespace_id="demo", content="Ada shipped the payments rewrite in Q3.")
results = client.recall(namespace_id="demo", query="who shipped payments?")
answer = client.reflect(namespace_id="demo", query="summarize Ada's recent work")import { IlluminaClient } from "@illumina/client";
const client = new IlluminaClient({ baseUrl: "https://api.illumina.sh", apiKey: "sub_live_..." });
await client.createNamespace("demo");
await client.retain("demo", "Ada shipped the payments rewrite in Q3.");
const results = await client.recall("demo", "who shipped payments?");
const answer = await client.reflect("demo", "summarize Ada's recent work");