Python Quickstart

Get from zero to a working stratified pack in under 5 minutes with the Python SDK.

Your own server instead of the cloud?

This page uses CortexDB Cloud. Against your own server, construct the client with api_url="http://localhost:3141", actor="user:local" and a scope such as SCOPE = "org:demo/user:local" (a dev server started with CORTEX_INSECURE_NO_AUTH=1 needs no token; on a keyed server pass bearer="<your CORTEX_API_KEY>"), and jump to step 4.

1. Install

pip install cortexdbai

Package	Name
PyPI package	`cortexdbai`
Python import	`cortexdb.v1`

Requires Python 3.10+. The HTTP dependencies (requests, httpx) are installed automatically with the package.

2. Get a token

Sign up at cortexdb.ai/signup/free (free, no card), then open your dashboard and choose Create an API token. The dashboard shows your actor and your default scope next to it.

export CORTEXDB_TOKEN='<your token>'   # PASETO v4 bearer, valid 90 days

import os
TOKEN = os.environ["CORTEXDB_TOKEN"]
ACTOR = "user:acct_42"                 # your actor, from the dashboard
SCOPE = "org:acct_42/user:acct_42"     # your default scope, from the dashboard

The token reaches only your own account (org:acct_42 and the tenants under it). Create a new one from the dashboard at any time; an operator running their own identity provider mints tokens the same way with POST /v1/auth/tokens.

3. Open a client

from cortexdb.v1 import V1Client

client = V1Client(
    api_url="https://api.cortexdb.ai",
    actor=ACTOR,
    bearer=TOKEN,
)

print(client.whoami()["effective_capabilities"])

api_url defaults to http://localhost:3141 (a locally running server). Pass the cloud URL explicitly, as above, when using CortexDB Cloud.

4. Capture an experience

result = client.experience(
    scope=SCOPE,
    text="Just got off a call with Priya at Acme. They upgraded to 200 seats.",
    role="user",
    observed_at="2026-05-16T10:42:00Z",
    idempotency_key="alice-chat-001",
)
print(result["event_id"])  # "evt_01HX..."
print(result["status"])    # "captured"

Pass role= and the SDK builds the right envelope; modality defaults to conversation. You may also pass an optional modality= label.

Returns 202 Accepted as soon as the WAL append succeeds. Pass wait="indexed" to block until BM25 + HNSW indexes have the event (30 s ceiling). wait is sent as ?wait=indexed and works from every SDK and from raw REST; for longer waits use GET /v1/lifecycle/stream?event_id=evt_… (see Lifecycle).

5. Recall a stratified pack

pack = client.recall(
    scope=SCOPE,
    view="holistic",
    query="What did we decide about Acme's renewal?",
    include=["events", "beliefs", "facts", "episodes"],
    budgets={"max_tokens": 4000},
    diagnostics="none",   # cloud tokens don't hold diagnostics.read
)

print(pack.get("context_block", ""))
for fact in pack["layers"].get("facts", []):
    print(fact["predicate"], "=", fact["object"]["value"])

Cloud token capabilities. diagnostics="summary"/"full" require the diagnostics.read capability, which a CortexDB Cloud token doesn't include — pass diagnostics="none" on the cloud.

Views. Cloud tokens hold scope.read.local, scope.read.holistic, and scope.read.descend, so view="holistic" works out of the box. The accepted recall views are raw, granular (alias local), holistic, descend, lineage, structured — local is accepted and normalizes to granular.

6. Recall + LLM in one call

answer = client.answer(
    scope=SCOPE,
    question="Did Acme renew?",
    view="holistic",
    temporal={"natural": "last 30 days"},
    diagnostics="none",
)

print(answer["answer"])
for c in answer["citations"]:
    print(f"  {c['marker']} → {c['layer']}:{c['id']}")

answer() is natural-language Q&A with full citations back to the events that supported the answer — build your UI around this.

7. Inspect why a belief exists

Facts populate within ~5–30 s of a write (LLM-extracted; requires enrichment configured — on a bare self-hosted instance the Facts/Beliefs layers stay empty, see Self-hosting defaults). Beliefs and Understanding are synthesized async (minutes+). Use client.facts(scope=…) as a smoke-test that extraction is running.

beliefs = client.beliefs(scope=SCOPE)
if beliefs["items"]:
    top = beliefs["items"][0]
    trail = client.belief_why(top["id"])   # belief items key their id as `id`, not `belief_id`
    print(trail["narrative"])

What's next

The Experience Envelope — full shape, content kinds, directives
The Five Memory Layers — when to read which layer
Scopes · Bi-temporal queries · Lifecycle
Python SDK reference

Async variant

from cortexdb.v1 import AsyncV1Client

async with AsyncV1Client(
    api_url="https://api.cortexdb.ai",
    actor=ACTOR,
    bearer=TOKEN,
) as client:
    pack = await client.recall(scope=SCOPE, view="holistic", diagnostics="none")

Python Quickstart

On this page