cortexdbai 0.10.1

The Long-Term Memory Layer for AI Systems

CortexDB Python SDK

The Long-Term Memory Layer for AI Systems.

CortexDB gives your AI agents persistent, structured memory. Capture experiences, then recall a stratified pack (events, facts, beliefs, episodes, concepts) or get a grounded answer — all scoped to a hierarchical scope path.

This SDK targets the v1 API (/v1/experience, /v1/recall, /v1/answer, …), PASETO auth, and hierarchical scopes. The pre-0.3 remember()/tenant_id client was retired — Cortex is now an alias of V1Client.

Installation

pip install cortexdbai

Quick start

from cortexdb import Cortex

# Local `docker run` with auth disabled (CORTEX_API_KEY unset on the server):
with Cortex("http://localhost:3141") as c:
    c.experience("ws:demo", text="Priya at Acme signed for 200 seats. Q3 close.")
    pack = c.recall("ws:demo", query="How many seats did Acme sign for?")
    print(pack["context_block"])

Hosted / multi-tenant (PASETO bearer + actor)

with Cortex(
    "https://api-v1.cortexdb.ai",
    actor="user:alice",
    bearer="v4.public…",          # PASETO v4 public or JWT (RS256/ES256)
) as c:
    out = c.answer(
        "org:initech/user:alice",
        "What did Alice say about coffee?",
    )
    print(out["answer"])

One-call signup (no prior credentials)

from cortexdb import Cortex

c = Cortex.signup()                      # POST /v1/auth/signup → free-tier PASETO
c.experience(c.actor, text="hello, memory!")
print(c.recall(c.actor, query="what did I say?")["context_block"])

Core operations

# Write — async by default (202); pass wait= for synchronous indexing.
c.experience("ws:demo", text="Deployed payments-service v3.1 to prod.")
c.experience("ws:demo", text="Rolled back auth-gateway.", wait="indexed")

# Large content: wait="captured" returns at the durable accept point (~10ms);
# poll write_status to see indexing progress. After a client timeout,
# found=False or status="failed" both mean re-sending is safe (re-processes).
c.experience("ws:demo", text=big_transcript, idempotency_key="k1", wait="captured")
c.write_status(idempotency_key="k1")  # {found, status, stages_completed, ...}

# Recall — returns a StratifiedPack { context_block, layers, provenance }.
pack = c.recall("ws:demo", query="recent deploys", view="holistic")

# Answer — recall + LLM render with citations.
ans = c.answer("ws:demo", "What changed in payments recently?")

# Forget — GDPR erasure. confirm_all wipes the whole scope.
c.forget("ws:demo", confirm_all=True, cascade="redact_events",
         audit_note="GDPR Article 17 request")

# Layer reads (paginated { items, has_more }).
c.events("ws:demo")
c.facts("ws:demo")
c.beliefs("ws:demo")
c.episodes("ws:demo")
c.understanding("ws:demo")

Async usage

AsyncCortex mirrors every method:

import asyncio
from cortexdb import AsyncCortex

async def main():
    async with AsyncCortex("http://localhost:3141") as c:
        await c.experience("ws:demo", text="async memory works great")
        pack = await c.recall("ws:demo", query="what works?")
        print(pack["context_block"])

asyncio.run(main())

Error handling

from cortexdb import (
    Cortex,
    V1Error,             # base
    V1APIError,          # non-2xx envelope
    V1AuthError,         # 401 / actor mismatch
    V1PolicyDeniedError, # 403 — missing capability
    V1RateLimitError,    # 429 (carries retry_after)
    V1NotConfiguredError,# 503 — feature not configured
    V1ConnectionError,
    V1TimeoutError,
)

with Cortex("http://localhost:3141") as c:
    try:
        c.experience("ws:demo", text="important data")
    except V1RateLimitError as e:
        print(f"rate limited; retry after {e.retry_after}s")
    except V1PolicyDeniedError as e:
        print(f"missing capability: {e}")
    except V1APIError as e:
        print(f"API error [{e.status_code}]: {e}")

Integrations

Framework and provider adapters ship as optional extras of the same cortexdbai package — there are no separate cortexdb-<framework> packages to install. Pick an extra and import from cortexdb.integrations.<submodule>:

pip install cortexdbai[langgraph]      # or crewai, llamaindex, autogen, …

from cortexdb.integrations.langgraph import CortexDBCheckpointer, cortexdb_memory_node

Available extras (pip install cortexdbai[<extra>]):

Extra	Import submodule
autogen	cortexdb.integrations.autogen
beeai	cortexdb.integrations.beeai
camel	cortexdb.integrations.camel
controlflow	cortexdb.integrations.controlflow
crewai	cortexdb.integrations.crewai
dify	cortexdb.integrations.dify
dspy	cortexdb.integrations.dspy
flowise	cortexdb.integrations.flowise
google-adk	cortexdb.integrations.google_adk
hermes	cortexdb.integrations.hermes
instructor	cortexdb.integrations.instructor
langgraph	cortexdb.integrations.langgraph
letta	cortexdb.integrations.letta
llamaindex	cortexdb.integrations.llamaindex
nemo-guardrails	cortexdb.integrations.nemo_guardrails
openai-agents	cortexdb.integrations.openai_agents
prefect	cortexdb.integrations.prefect
pydanticai	cortexdb.integrations.pydanticai
smolagents	cortexdb.integrations.smolagents
temporal	cortexdb.integrations.temporal
langchain	cortexdb.integrations.langchain
ag2	cortexdb.integrations.ag2
agno	cortexdb.integrations.agno
groq	cortexdb.integrations.groq
fireworks	cortexdb.integrations.fireworks
together	cortexdb.integrations.together
deepinfra	cortexdb.integrations.deepinfra
ollama	cortexdb.integrations.ollama
vllm	cortexdb.integrations.vllm

Constructor

Parameter	Type	Default	Description
api_url	str	http://localhost:3141	CortexDB v1 surface URL
actor	str	user:default	Sent as X-Cortex-Actor; must match the token subject when authed
bearer	str | None	None	PASETO v4 public / JWT bearer (omit for auth-disabled dev)
timeout	float	30.0	Request timeout (seconds)

Links

• Documentation
• Issue Tracker

License

Apache-2.0