cortexdbai 0.4.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")

# 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}")

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