Skip to main content

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.

PyPI version Python License

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

import os
from cortexdb import Cortex

# Authenticated local Docker instance (set CORTEX_API_KEY on the server too):
with Cortex("http://localhost:3141", bearer=os.environ["CORTEX_API_KEY"]) as c:
    c.experience(
        "ws:demo",
        text="Priya at Acme signed for 200 seats. Q3 close.",
        wait="indexed",
    )
    pack = c.recall("ws:demo", query="How many seats did Acme sign for?")
    print(pack["context_block"])

Hosted / multi-tenant (PASETO bearer + actor)

The client acts as its token's subject: X-Cortex-Actor is the token's sub unless you pass actor (actor=None sends no header, as a token whose subject the server maps itself needs).

with Cortex(
    "https://api-v1.cortexdb.ai",
    bearer="v4.public…",          # PASETO v4 public or JWT (RS256/ES256); acts as its sub
) 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!", wait="indexed")
print(c.recall(c.actor, query="what did I say?")["context_block"])

Core operations

# Write — async by default (202); use wait="indexed" for read-your-writes.
c.experience("ws:demo", text="Deployed payments-service v3.1 to prod.", wait="indexed")
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, its
# `resend` says what to do: "no" means stored, and a write that failed indexing
# (status="failed") is stored too: never re-send it, at any age or under any
# key (a new key would store it twice); the operator re-includes it in place.
# "if_sent_within_24h" means no receipt: re-send if you sent it within a day.
c.experience("ws:demo", text=big_transcript, idempotency_key="k1", wait="captured")
c.write_status(idempotency_key="k1")  # {found, status, stages_completed, resend, note}

# Preserve exact source structure for citations, replay, and artifact building.
from cortexdb import sha256_fingerprint

text = "Customer approved the renewal."
fingerprint = sha256_fingerprint(text)
c.experience(
    "ws:demo",
    text=text,
    modality="conversation",
    source={
        "schema_version": 2,
        "source_id": "crm:thread:42",
        "modality": "conversation",
        "content_kind": "message",
        "source_fingerprint": fingerprint,
        "fragments": [{
            "fragment_id": "message-7",
            "locator": {
                "kind": "conversation",
                "session_id": "thread-42",
                "turn_index": 7,
            },
            "content_fingerprint": fingerprint,
        }],
    },
)

# Losslessly split a larger logical text source at UTF-8 boundaries. The
# response includes every fragment event ID; no existing one-event API changes.
source_write = c.experience_source_text(
    "ws:demo",
    handbook_text,
    source_id="document:employee-handbook",
    locator_path=["employee-handbook", "body"],
)
assert len(source_write["event_ids"]) == source_write["fragment_count"]
# The server retains replay keys for 24 hours. For longer jobs, persist each
# `on_fragment` checkpoint and pass it back through `completed_fragments`.

# 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",
         reason="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 has every method Cortex has, under the same name, with the same parameters; each is a coroutine (streams and pages are async iterators):

import asyncio
import os
from cortexdb import AsyncCortex

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

asyncio.run(main())

Error handling

Every refusal raises the class of its error_code, from cortexdb.errors (one per code: WAIT_TIMEOUT raises errors.WaitTimeoutError), which subclasses the class of its HTTP status family: V1BadRequestError (400, and V1ValidationError for 422), V1AuthError (401), V1PaymentRequiredError (402), V1PolicyDeniedError (403), V1NotFoundError (404), V1ConflictError (409, and V1PreconditionFailedError for 412), V1GoneError (410), V1PayloadTooLargeError (413), V1RateLimitError (429), V1ServerTimeoutError (408 and 504), V1ServerError (5xx) and V1UnavailableError (503, with V1NotConfiguredError for a server missing a provider). All of them are V1APIErrors, with status, error_code, message, request_id, retriable (sending the same request again can succeed), details, headers and retry_after (the Retry-After header in seconds); each per-code class reads its documented details keys as properties (err.waiting_on, err.limit, …). A code this SDK does not know yet raises its family's class.

import os
import time

from cortexdb import Cortex, V1APIError, V1PolicyDeniedError, V1UnavailableError, errors

with Cortex("http://localhost:3141", bearer=os.environ["CORTEX_API_KEY"]) as c:
    try:
        c.experience("ws:demo", text="important data", wait="indexed")
    except errors.WaitTimeoutError as e:        # captured; the barrier ran out
        print(f"still {e.waiting_on} after {e.waited_ms} ms")
    except V1UnavailableError as e:              # any 503
        if e.retriable:
            time.sleep(e.retry_after or 1)
    except V1PolicyDeniedError as e:             # any 403
        print(f"refused: {e.error_code} {e.details}")
    except V1APIError as e:                      # anything else the server refused
        print(f"API error [{e.status} {e.error_code}]: {e.message}")

V1ConnectionError and V1TimeoutError (the client's own timeout) are the transport's; V1InvalidRequestError is a request the SDK refused before sending it, with the code the server would answer. A value a route always refuses (an extra_scopes list past 40, a malformed break-glass header, a mint the server never accepts) raises ValueError before anything is sent.

What's new in 0.14.0 for CortexDB 0.15.0

cortexdbai 0.14.0 is the client side of CortexDB 0.15.0's governed memory formation. Each item needs a server that lists its capability (capabilities()): a server before 0.15.0 answers 404 for a route it does not serve, which reads like a missing record.

  • How a memory was made (derivation_provenance_v1): include=["derivation"] on the fact and belief reads, derivation_decisions, and the status route's extraction block (below).
  • Derivation policies (derivation_policy_v1): derive_record for change sets, derivation_policy, derivation_templates, derivation_taxonomy, derivation_policy_test (a draft tested on a sample of events, writing nothing), subject settings (derivation_settings, put_derivation_settings, delete_derivation_settings), policy texts (derivation_texts, erase_derivation_texts) and audit_list(action=...) (below).
  • The change feed (derivation_feed_v1): derivation_feed, feed_iter, and the hash an erasure names events by (feed_erased_id_hash, erased_matches; pip install cortexdbai[blake3] computes it natively).
  • Write-back stamps (derived_by_v1): derived_by= on typed triples and on create_belief, and derivation_status(scope, derived_by=[...]).
  • Importers: mode= on import_mem0, import_zep, import_letta and import_openai; dropped_derived_by(job).
  • Corrections (corrections_v1): correct and its shorthands reject, replace, pin and confirm, corrections, correction, undo_correction and memory_about; resolve_conflict takes loser= and answers correction_ids (below).
  • Review before commit (derivation_review_v1): review, review_decide and its shorthands approve and reject_held, and the held items memory_about lists (below).
  • Re-derivation (derivation_rederive_v1): rederive(scope, mode), a regate or a reextract, a dry run unless dry_run=False, of the unsynced rows unless it names event_ids; rederive_job, rederive_wait and rederive_cancel follow the job, and derivation_report(scope, since=, until=, csv=) answers what was derived over a period, counts and ids only.
  • Outside workers: feed_consumers (the feed's consumers, from format 11), declared episodes (declare_episode, delete_episode, declared_episodes_v1), the reference worker cortexdb.workers.DerivationWorker (with FileCursor and MemoryCursor; below) and cortexdb.memory_tool.CortexMemoryTool, a Claude memory tool backed by a scope (pip install cortexdbai[anthropic]; below).
  • The read-time use rule (derivation_use_rules_v1): session= on recall, recall_stream, answer and compose (Reading across scopes).
  • Typed errors for DERIVATION_POLICY_INVALID, DERIVATION_POLICY_WIDENS, DERIVATION_MODEL_NOT_ALLOWED, DERIVATION_TEXT_INVALID, POLICY_TEST_TOO_LARGE, DERIVED_BY_INVALID, FEED_CURSOR_INVALID, CORRECTION_CONFLICT, CORRECTION_TARGET_UNKNOWN, WRITER_NOT_ALLOWED, REVIEW_ITEM_DECIDED, the re-derivation codes (REDERIVE_ESTIMATE_REQUIRED, REDERIVE_ESTIMATE_STALE, REDERIVE_BUDGET_EXHAUSTED, DERIVATION_JOB_ACTIVE, REEXTRACT_NOT_ALLOWED) and the console's FORMAT_ARMED_ONE_WAY and ONE_WAY_CONFIRMATION_REQUIRED.

What's new in 0.13.1 for CortexDB 0.14.1

  • Long change-set evaluations are waited for. A staging, a preview or an activation whose evaluation runs past the server's own wait answers 202 with Retry-After; each change-set method sends the same call again until the answer comes, for at most wait seconds (120 by default, CHANGESET_WAIT_SECONDS; changeset_apply's bounds its three steps together), then raises V1EvaluationPendingError. wait=0 returns the raw 202 as an EvaluationPending. The preview waited 60 s by default.
  • A version downgrade names what it drops: INVALID_ACCESS_RECORD (a change set without convert) or INVALID_SCOPE_TREE (a legacy registry write), reason == "version_downgrade", with path and dropped.
  • A tenant binding's dry run answers operator_plane {registers_root, in_band, mode, break_glass_required}.
  • Lifetime ceilings are the server's settings: lifetime_ceiling() gives the defaults, now 90 days for a person (a week for an agent, 30 days for a service, a day for a chain token), admin_metrics()["auth"] ["lifetime_ceilings"] the server's own, and check_mint leaves a chain token's lifetime to the server. InvalidBodyError and InvalidTokenClaimError read lifetime_s and ceiling_s.

What's new in 0.13.0 for CortexDB 0.14.0

cortexdbai 0.13.0 covers the whole v1 API of CortexDB 0.14.0 (COVERAGE.md: every route and the method that calls it), on both clients under the same names.

  • Every route has a method, on Cortex and AsyncCortex alike: the access API (access_check, access_explain, the lookups, access_limits), AuthZEN 1.0, change sets (changeset_apply and its steps), the access watch and notices, applications, the directory, SCIM (client.scim), restores, source containers (rehome, watermarks, account resolution), rollups and publish, person, party and tenant erasures with receipts and proofs, the read-free forget, the operator's access routes, and the routes older releases left out (lifecycle, vocabularies, imports, export, keyed blobs, the cohort lanes, audit, retention, the code plane, the native memory host's).
  • Typed models for every request and response (cortexdb.v1.models, TypedDicts generated from the server's OpenAPI contract).
  • A typed exception per error code (cortexdb.errors), under one class per HTTP status family, with retriable, details (named properties for each documented key) and retry_after.
  • Consistency tokens: consistency=True on writes and reads, consistency=<token> or at_least=<token> to demand one, and ConsistencyTokens to carry them per root.
  • The new read and write fields: extra_scopes (up to 40), coverage, beliefs="merged", mounts="default", purpose, session; provenance, intent, subject and the envelope's other fields; streams as StreamEvent iterators; a declared belief's idempotency_key.
  • Paging and by-id reads: every listing pages with pages() (events newest first by their le1. cursor, the scope list, the layers); scope= on the by-id layer reads (a scope that does not hold the row is 404); include_vectors=True returns embeddings; the timeline takes as_of.
  • Auth: the actor follows the token, mint_token's chain fields with mint_agent_token and mint_app_token, break-glass (client.break_glass) and the subject-token shadow (with_options(subject_token=...)).

Its breaking changes are below. Each feature has a section under Shared memory with an example the SDK's live tests run against a 0.14.0 server.

Breaking changes in 0.13.0

Upgrading from cortexdbai 0.12: every call keeps its name, its positional parameters and every keyword it took; these behave differently.

  • Errors are typed per code. Every refusal raises the class of its error_code (cortexdb.errors), a subclass of its HTTP status family's class. A code this SDK does not know raises its family's class (a 503 is a V1UnavailableError), no longer a bare V1APIError: an except V1APIError keeps catching everything, but a type(err) is V1APIError check no longer matches. V1NotConfiguredError is now a V1UnavailableError, and V1InvalidRequestError a V1BadRequestError. For a body without retriable, retriable is the code's documented default instead of False.
  • The actor follows the token. A client built with a token bearer and no actor sends the token's sub as X-Cortex-Actor (0.12 sent user:default, which the server refuses with 401 ACTOR_MISMATCH for any other subject), and no header for a token whose subject an issuer maps. The operator key and no bearer still send user:default; pass actor to choose.
  • view is the server's. recall, recall_stream, answer and compose send view only when you pass it (0.12 sent "holistic"). The server reads holistic as before, but granular at an org tree's shared scope (team, org, group, compartment), where holistic is 422 VIEW_NOT_ALLOWED_AT_SCOPE.
  • Local refusals. A request the server always refuses fails before it is sent, with ValueError: an extra_scopes list past 40, a malformed break-glass header, a mint whose chain fields break mint_chain_v1's rules, more than 1,024 provenance ids.
  • Server 0.14.0 refuses what 0.13.x served (its own release notes list them): forget and erasure selectors are strict (422 INVALID_BODY, an unknown selector field or one the cascade would not apply, field_not_applied), every mint names its tenant root (scope, tenant or scopes; only the trusted operator mints deployment-wide, and only for a service: or system: subject), mints are held to their lifetime ceilings, a token that carries scopes must confine every capability it uses, and a tenant in deny refuses the operator key's data reads without break-glass. A header that does not parse is 400 INVALID_HEADER (a malformed break-glass header was BREAK_GLASS_INVALID, which has no class any more).

Shared memory (CortexDB 0.14.0)

CortexDB 0.14.0 adds org trees with real access control, and the routes that run them: change sets to register an org's records, an access API that says who may read what and why, AuthZEN for policy enforcement points, a watch of every access change, notices, consistency tokens, applications, a directory of people, SCIM, rollups, publish, and person and tenant erasures. Every method below exists on Cortex (V1Client) and, with await, on AsyncCortex (AsyncV1Client), under the same name.

The examples run, in order, against a fresh server (the SDK's live tests run each of them). Start one with the operator key, the minter, and demo as the deployment's tenant, so a token minted without tenant belongs to org:demo:

CORTEX_API_KEY=demo-operator-key CORTEX_V1_MINTER_ENABLE=1 \
CORTEX_V1_AUDIENCE=cortexdb:tenant:demo ./cortexdb
import os

from cortexdb import Cortex

URL = os.environ.get("CORTEX_URL", "http://localhost:3141")
ROOT = os.environ.get("CORTEX_DEMO_ROOT", "org:demo")
ENG = f"{ROOT}/team:eng"

# The deployment's operator key. `actor=None` sends no X-Cortex-Actor: the key
# then acts as itself.
operator = Cortex(URL, bearer=os.environ.get("CORTEX_API_KEY", "demo-operator-key"), actor=None)

Change sets: registering an org tree

An org's records (its org, teams, sets, people's private regions, sources …) are written in change sets: staged, previewed (who gains and loses what), then activated in one step. A compiler stages them under its own principal; here the operator key acts as service:compiler. scope_record, member and set_member build the version-2 records; a record holds no names (those live in the directory, below).

from cortexdb.v1 import changeset_part, member, put_record, scope_record, set_member

compiler = operator.with_options(actor="service:compiler")
owner = member("service:compiler", "owner")
records = [
    scope_record(ROOT, members=[owner, member("user:ada", "owner"), member("service:scim-okta", "owner")],
                 kind="org"),
    scope_record(f"{ROOT}/set:eng", members=[owner], kind="set", parent=ROOT,
                 set={"entries": [{"actor": "user:alice"}, {"actor": "user:bob"}]}),
    scope_record(ENG, members=[owner, set_member(f"{ROOT}/set:eng", "writer")],
                 kind="team", parent=ROOT, audience="members"),
    scope_record(f"{ROOT}/user:alice", members=[member("user:alice", "owner"), owner],
                 kind="person", parent=ENG, private=True, self_principal="user:alice"),
]
# Stage, preview and activate in one call ...
applied = compiler.changeset_apply(ROOT, "org-compile-1", records, reason="first compile")
print(applied["activated"]["state"])                 # activated

# ... or step by step, reading the preview before approving it.
sales = scope_record(f"{ROOT}/team:sales", members=[owner, member("user:carol", "writer")],
                     kind="team", parent=ROOT)
compiler.changeset_stage(ROOT, "sales-1", [changeset_part(0, [put_record(sales["path"], sales)])])
preview = compiler.changeset_preview("sales-1", ROOT, people=True)
print(preview["summary"]["people_gaining"], preview["widens"])
status = compiler.changeset_activate("sales-1", ROOT, preview["preview_hash"])
print(status["state"], status["consistency_token"][:4])  # activated ct1.

A refusal raises its typed error: PREVIEW_CHANGED (the registry moved since the preview), ACCESS_ASSERTION_FAILED (a widening breaks one of the tenant's policy cases), CHANGESET_STALE (a record changed after staging), ACCESS_LIMIT_REACHED, and since 0.14.1 INVALID_ACCESS_RECORD with reason == "version_downgrade" for a put that would make a version-2 record a version-1 one (err.dropped lists the stored record's version-2 fields the put leaves out: state them, or stage with convert=True). changeset_get and changeset_discard read and drop a staged change set.

A large evaluation can run past the server's own wait (20 s by default): from 0.14.1 a staging, a preview or an activation then answers 202 with Retry-After, and each method sends the same call again until the answer comes, for at most wait seconds in all (CHANGESET_WAIT_SECONDS, 120, by default; changeset_apply's wait bounds its three steps together). Past it the method raises V1EvaluationPendingError, and the same call sent again joins the evaluation. wait=0 returns the first answer as it came, a 202 as an EvaluationPending (its body, status and retry_after).

Under a tenant whose operator mode is deny, the operator key's activation of a change set that registers a record, names a service: principal or widens who reads a private region is an in-band path. Its preview says so (in_band, and in_band_parts names each record and why), and the activation takes a break-glass client, else 403 BREAK_GLASS_REQUIRED: compiler.break_glass("support", "SUP-1142").changeset_activate(id, ROOT, preview["preview_hash"]). Each private region it widens is told first (503 NOTICE_UNAVAILABLE, nothing activated, when that notice cannot commit), and a registry change in between is 503 REGISTRY_STALE, which a retry decides again. Staging, the preview and a discard need no header.

The access API

access_check answers whether a principal chain may read, write or administer a scope, or read one memory, with the deciding path of every link; access_explain says why, atom by atom. Without chain, it decides for the caller's own token; another chain may be asked about by an Owner of the scope or the trusted operator. access_lookup_scopes lists what a chain may read under a prefix, access_lookup_principals who may read a scope, and access_limits the limits the deployment enforces (read them; never hard-code them).

check = operator.access_check(ENG, role="writer", chain={"sub": "user:alice"})
print(check["allowed"], check["delivered_role"])     # True writer
denied = operator.access_check(ENG, chain={"sub": "user:mallory"})
print(denied["denied_by"], denied["links"]["person"]["reason"])  # person not_a_member

why = operator.access_explain(ENG, chain={"sub": "user:alice"})
print(why["home"]["links"]["person"]["via"][0]["record"])        # org:demo/team:eng

for page in operator.pages(operator.access_lookup_scopes, ROOT, chain={"sub": "user:alice"}):
    for item in page["items"]:
        print(item["scope"], item["role"])           # org:demo/team:eng writer
readers = operator.access_lookup_principals(ENG)
print(sorted(i.get("principal") or i.get("set") for i in readers["items"]))

limits = {limit["name"]: limit["value"] for limit in operator.access_limits(ROOT)["limits"]}
print(limits["apps"], limits["scope_path_segments"])  # 8 32

AuthZEN 1.0

A third-party policy enforcement point asks the same questions through AuthZEN 1.0: authzen_evaluation (actions summary, read, write, own) and authzen_search_resource, with the PDP's metadata at authzen_configuration().

print(operator.authzen_evaluation("user:alice", "write", ENG))     # {'decision': True}
print(operator.authzen_evaluation("user:mallory", "read", ENG))
# {'context': {'denied_by': 'person'}, 'decision': False}
found = operator.authzen_search_resource("user:alice", "read", ROOT, limit=10)
print([r["id"] for r in found["results"]])
print(operator.authzen_configuration()["access_evaluation_endpoint"])

Watch and notices

access_watch follows a root's access changes (registry changes with their consistency tokens, change-set events, notices, assertion breaks and restores) from a position, within a 7-day window; wait_ms long-polls. A person reads the notices that name them (who read what of theirs, under a grant or a break-glass read) with access_notices and acknowledges them with access_notices_ack.

start = operator.access_watch(ROOT)                  # the current position, no history
ops = scope_record(f"{ROOT}/team:ops", members=[owner], kind="team", parent=ROOT)
compiler.changeset_apply(ROOT, "ops-1", [ops])
page = operator.access_watch(ROOT, after=start["position"], wait_ms=2000)
print(sorted({item["type"] for item in page["items"]}))  # ['changeset', 'registry']

alice = Cortex(URL, bearer=operator.mint_token(subject="user:alice", scope=ROOT)["token"])
notices = alice.access_notices(ROOT)
if notices["items"]:
    alice.access_notices_ack(ROOT, seqs=[n["seq"] for n in notices["items"]])

Consistency tokens

Every write and read can carry a consistency token: a lower bound, so a later read that demands it sees at least what that response saw or wrote, on any node. Pass consistency=True to a write (or a read) for a token, then consistency=<token> to a read, or at_least=<token> to a GET read. A ConsistencyTokens tracker does it for you, per scope root.

from cortexdb.v1 import ConsistencyTokens

receipt = alice.experience(ENG, text="Shipped payments v3.1 today", consistency=True)
pack = alice.recall(ENG, query="what shipped?", consistency=receipt["consistency_token"])
events = alice.events(ENG, at_least=pack["consistency_token"])

tokens = ConsistencyTokens()
session = alice.with_options(consistency=tokens)
session.experience(ENG, text="Rolled back auth-gateway", wait="captured")
pack = session.recall(ENG, query="what was rolled back?")  # waits for that write
print(sorted(tokens.as_dict()))                      # ['org:demo']

A demand the node cannot reach in time answers 408 WAIT_TIMEOUT (details.waiting_on: registry, indexer or access_view); a token of another root, or one this deployment never issued, 422 CONSISTENCY_TOKEN_INVALID.

Applications

An application record (<root>/app:<id>) names what an application writes and what its chains read by default: mounts, which mounts="default" on a read adds (each admitted by an apps entry of the record it mounts). A tenant holds at most limits.apps of them (access_limits). The record holds no name: app_put refuses display_name, and the application's name is the directory's name entry of its path (directory_put(f"{ROOT}/app:notes", ROOT, display_name="Notes")).

ada = Cortex(URL, bearer=operator.mint_token(subject="user:ada", scope=ROOT)["token"])
app = ada.app_put("notes", ROOT, kinds=["note", "decision"])
print(app["path"], app["home"])     # org:demo/app:notes org:demo/app:notes/user:{person}
print(ada.app_get("notes", ROOT)["kinds"])

The directory

Each tenant's people, with their names, emails and source accounts, and the name entries of its scopes and sets. Records hold no names: a scope's display name is its entry here. Writes can be conditional on the version last read.

operator.directory_put("user:alice", ROOT, display_name="Alice Moreau", emails=["Alice@Demo.Example"],
                       accounts=[{"system": "slack:T1", "account": "UALICE"}])
operator.directory_put(ENG, ROOT, display_name="Engineering")    # a scope's name entry
entry = operator.directory_get("user:alice", ROOT)
print(entry["emails"], entry["version"])                         # ['alice@demo.example'] 1
# A put replaces the whole entry; if_version makes it conditional on the version read.
operator.directory_put("user:alice", ROOT, display_name="Alice M.", emails=entry["emails"],
                       accounts=entry["accounts"], if_version=entry["version"])
print([e["id"] for e in operator.directory_search(ROOT, "ali")["items"]])
resolved = operator.access_resolve_accounts(ROOT, [("slack:T1", "UALICE"), ("slack:T1", "UNKNOWN")])
print([a["id"] for a in resolved["accounts"]])                    # ['user:alice', None]

A stale version is 412 DIRECTORY_VERSION_CHANGED; an account another principal holds 409 DIRECTORY_ACCOUNT_TAKEN. A deactivated entry (status="deactivated") refuses every credential of the person, 401 SUBJECT_UNMAPPED, until it is active again.

SCIM

An identity provider provisions the tenant's people and groups through SCIM 2.0, with a bearer for service:scim-<client> that is an Owner of the tenant root. client.scim sends its requests the way a provider does, without X-Cortex-Actor; scim_user, scim_group and scim_op build the resources.

from cortexdb.v1 import scim_group, scim_op, scim_user

idp = Cortex(URL, bearer=operator.mint_token(subject="service:scim-okta", scope=ROOT,
                                              ttl_seconds=30 * 86400)["token"])
faye = idp.scim.create_user(scim_user("faye@demo.example", external_id="00u-faye", display_name="Faye Ng"))
group = idp.scim.create_group(scim_group("Platform", [faye["id"]]))
print(idp.scim.list_users(filter='userName eq "faye@demo.example"')["totalResults"])  # 1
print(idp.scim.resource_type("User")["endpoint"])                # /Users
idp.scim.patch_user(faye["id"], [scim_op("replace", value={"active": False})])  # her tokens stop
idp.scim.patch_user(faye["id"], [scim_op("replace", value={"active": True})])   # and work again
idp.scim.delete_group(group["id"])
idp.scim.delete_user(faye["id"])

SCIM's error bodies raise the SDK's typed errors, with the CortexDB code as error_code and SCIM's scimType as scim_type.

Restores

A copy restored with its access state lost (cortexdb restore-check --access-state lost) holds every root it restored pending: requests that do not repair it answer 503 ACCESS_RESTORE_PENDING (not retriable), until each of the root's access sources re-sends its state (change sets staged with resync=True, the last one resync=True and activated) and acknowledges with access_restore_ack, or the trusted operator overrides with admin_access_restore. access_records pages a root's registry records, what a source diffs its own state against, with the root's consistency token (at_least= waits for one). access_texts_erase(root, path) erases the free texts a record names (reasons, a hold's matter, a policy case's notes) from every voter's files; the record keeps its references.

from cortexdb.v1 import V1APIError

records = operator.access_records(ROOT)
print(len(records["items"]) > 0, records["revision_changed"])     # True False
print(operator.access_records(ROOT, at_least=records["consistency_token"])["items"] != [])  # True
print(compiler.access_texts_erase(ROOT, ENG)["erased"] >= 0)     # True
try:
    operator.access_restore_ack(ROOT)
except V1APIError as error:
    print(error.error_code)                                       # RESTORE_NOT_PENDING

Source containers

A connector writes each item into its permission unit's container (<tenant>/source:<system>/container:<key>), registered through change sets. When an item's sharing changes it moves the item's live events with access_rehome (nothing is erased); after each sync it stores the source's watermark (access_watermark_put), which reads report in coverage.

from datetime import datetime, timedelta, timezone

slack_owner = member("service:slack", "owner")
source = f"{ROOT}/source:slack"
general, launch = f"{source}/container:general", f"{source}/container:launch"
compiler.changeset_apply(ROOT, "slack-1", [
    scope_record(source, members=[slack_owner], kind="source", parent=ROOT),
    scope_record(f"{ROOT}/set:slack-members", members=[slack_owner], kind="set", parent=ROOT,
                 set={"entries": [{"actor": "user:alice"}]}),
    scope_record(general, members=[slack_owner, set_member(f"{ROOT}/set:slack-members", "reader")],
                 kind="container", parent=source),
    scope_record(launch, members=[slack_owner, set_member(f"{ROOT}/set:slack-members", "reader")],
                 kind="container", parent=source, private=True),
])
slack = Cortex(URL, bearer=operator.mint_token(subject="service:slack", scope=ROOT)["token"])
synced = (datetime.now(timezone.utc) - timedelta(seconds=5)).strftime("%Y-%m-%dT%H:%M:%SZ")
print(slack.access_watermark_put(source, synced)["changed"])      # True
message = slack.experience(general, text="Launch moves to Friday", wait="indexed")
print(slack.access_rehome(launch, [message["event_id"]])["moved"])  # 1
print([w["source"] for w in alice.access_watermarks(launch)["watermarks"]])

Rollups and publish

A unit with an aud:roll compartment gets rollups: typed totals per month and synthesis items, built by the shard leader and served to a reader only when it reads every input (dominance), so its head reads them and others do not. A person widens a memory only by publishing a copy of it into a home they write; erasing the original erases the copy.

import time

roll = f"{ENG}/aud:roll"
compiler.changeset_apply(ROOT, "eng-rollup-1", [
    scope_record(roll, members=[owner], kind="compartment", parent=ENG, audience="rollup"),
    scope_record(f"{ENG}/attrs:unit", kind="attrs", parent=ENG, attrs={"heads": [{"actor": "user:ada"}]}),
])
alice.experience(ENG, text="Decided: ship the new pricing page", wait="indexed")
for _ in range(60):                       # a unit is built the first time it is read
    rolled = ada.rollups(roll)
    if rolled["items"]:
        break
    time.sleep(1)
print(rolled["items"][0]["kind"], ada.rollup_totals(roll)["totals"]["events"] > 0)

note = alice.experience(f"{ROOT}/user:alice", text="Proposal: weekly design reviews", wait="indexed")
copy = alice.publish(ENG, f"{ROOT}/user:alice", event_id=note["event_id"], wait="indexed")
print(copy["published_from"]["event_id"] == note["event_id"])     # True

Only a person's own chain publishes, through an application the person drives too (app with client: "person"): an agent's act, a run, a service, an app without client and the operator key are 403 PUBLISH_PERSON_REQUIRED. consistency=True returns a token at the target's root. Publishing a norm (intent="procedure", rule, …) needs a sign-in within 10 minutes (401 FRESH_AUTH_REQUIRED, its RFC 9470 challenge in the error's headers).

Reading across scopes

A read names its home scope and up to 40 extra_scopes under the same tenant root, and searches them all as one read set; coverage=True reports what it searched, what of its read set the caller may read, and each gap with its reason (a scope left out by a bound, a deadline, a source's watermark, a scope the caller may not read …), so a response never reads as complete when it is not. beliefs="merged" rebuilds the beliefs of every scope read into one set, and mounts="default" adds an application chain's mounts (a token minted with app). purpose declares what the read is for ([a-z0-9_-]{1,64}), which an access path's when: {purpose} condition reads; a read refused only for want of the purpose its one path names raises errors.PolicyDeniedError with reason == "purpose_required" and purpose the one it needs. session (derivation_use_rules_v1, CortexDB 0.15.0) names the conversation session the read is made in (1 to 256 bytes with no control character): where a read-time use rule is in force, memory captured in another session or before the rule's window is withheld, and warnings says use_rule_withheld: <n> events from earlier sessions. Send session only when the server lists derivation_use_rules_v1: one before 0.15.0 refuses it on recall and recall_stream (422 INVALID_BODY) and ignores it on answer and compose, so nothing is withheld there. recall, recall_stream, answer and compose take the same fields, and access_check and access_explain take purpose.

pack = alice.recall(ENG, query="when does the launch move?", extra_scopes=[general, launch],
                    coverage=True)
print(sorted(pack["coverage"]["searched"]["scopes"]))
# ['org:demo/source:slack/container:general', 'org:demo/source:slack/container:launch',
#  'org:demo/team:eng']
print({event["scope"] for event in pack["layers"]["events"]} >= {launch})   # True
answer = alice.answer(ENG, "When does the launch move?", extra_scopes=[general, launch],
                      beliefs="merged", coverage=True, purpose="planning")
print([citation["id"] for citation in answer["citations"]][:1])

A scope outside the root, or a list past the bound, is 422 INVALID_EXTRA_SCOPES; mounts without an application in the token 422 INVALID_MOUNTS (details.reason no_app).

Streams

recall_stream and answer_stream yield StreamEvents (event, data, id) as the server sends them: a recall's plan, each layer, its context_block and done (with the consistency token); an answer's tokens, citations and done. lifecycle_stream follows the write lifecycle (captured, indexed …) of a scope, an event or a job. An error event raises its typed error. On AsyncCortex they are async iterators.

names = [event.event for event in alice.recall_stream(ENG, query="what shipped?")]
print(names[0], names[-1])                                        # plan done
text = "".join(event.data["text"] for event in alice.answer_stream(ENG, "What shipped?")
               if event.event == "token")
print(bool(text))                                                 # True

Writes that cite their sources

A write that summarizes or derives from other memories names them in provenance (at most 1,024 event ids in the same root): the stored event keeps them, and reads and erasures follow them. intent, subject, observed_actor, directives and context are the envelope's other fields.

notes = alice.experience(ENG, text="Raw notes: the gateway timed out twice", wait="indexed")
summary = alice.experience(ENG, text="Summary: gateway timeouts after the deploy", wait="indexed",
                           provenance=[notes["event_id"]], intent="decision")
stored = alice.event(summary["event_id"], scope=ENG)
print(stored["provenance"] == [notes["event_id"]], stored["context"]["intent"])  # True decision

An id that names no event of the root is 422 PROVENANCE_UNKNOWN (details.cited), an erased one 409 PROVENANCE_ERASED, one in another root 422 CROSS_ROOT_PROVENANCE.

The read-free forget

A deletion worker forgets by keys it already holds, so the server reads nothing first: idempotency_keys (the keys the writes were sent with; for another principal's write, (key, caller)), and capture_keys (a label the writer put on every event of one capture). forget_preview counts the same selector. It takes Owner at the scope; the default derived_only cascade removes the selected events with what was derived from them. What a legal hold keeps is matched, not deleted: matched counts it (at most requested), and events_under_legal_hold and derived_under_legal_hold count it apart, in neither deleted nor estimated_deleted.

home = f"{ROOT}/user:alice"
alice.experience(home, text="A draft I will take back", idempotency_key="draft-1", wait="indexed")
preview = alice.forget_preview(home, idempotency_keys=["draft-1"])
print(preview["requested"], preview["matched"], preview["events_under_legal_hold"])  # 1 1 0
gone = alice.forget(home, idempotency_keys=["draft-1"], from_preview_id=preview["preview_id"])
print(gone["deleted"]["events"])                                  # 1

for part in ("first", "second"):
    alice.experience(home, text=f"call 42, {part} passage", labels=["cap:call-42"], wait="indexed")
print(alice.forget(home, capture_keys=["cap:call-42"])["deleted"]["events"])   # 2

Erasures

erase deletes the rows themselves (not only what was derived), frees the writes' idempotency keys and leaves a durable receipt that erasure_verify proves store by store; erasure_wait polls a job (with residual=True, until its bytes left the log on every voter). The trusted operator also erases an outside party by address (subject_email: the events writers labelled party:<address>, in every scope of the tenant), a person (erase_person: their region, their application and capture homes, their own messages in the tenant's groups, then their directory entry) and a whole tenant (erase_tenant, a dry run unless dry_run=False and confirm=True). A legal hold keeps what it names.

slack.experience(general, text="Pat from Initech asked for a quote", wait="indexed",
                 labels=["party:pat@initech.example"])
preview = operator.erasure_preview(ROOT, subject_email="pat@initech.example")
print(preview["estimated_affected"]["events"])                    # 1
job = operator.erase(ROOT, subject_email="pat@initech.example", confirm=True,
                     from_preview_id=preview["preview_id"])
receipt = operator.erasure_receipt(job["erasure_id"])
print(receipt["receipt"]["kind"], receipt["sha256_verified"])     # party True
print(operator.erasure_verify(job["erasure_id"])["checks_ok"])    # True

leaver = operator.erase_person(ROOT, "user:bob", confirm=True, reason="leaver")
print(operator.erasure_wait(leaver["erasure_id"])["status"])      # completed
plan = operator.erase_tenant(ROOT)                                # counts only
print(plan["dry_run"], plan["counts"]["records"] > 0)             # True True

Operator routes

The trusted operator reads and sets each tenant's operator mode (operator_data_reads: allow, audit, which tells the people whose memories an operator read touched, or deny, which takes break-glass) beside the deployment's own (deployment_mode, what a tenant that clears its mode falls back to), reads the access report's counters, rebinds a root's records from the static key's tenant, and reads the node's health, readiness and metrics.

settings = operator.admin_tenant_settings(ROOT)
print(settings["operator_data_reads"], settings["deployment_mode"])
# {'mode': 'allow', 'source': 'deployment'} allow
operator.admin_set_tenant_settings(ROOT, operator_data_reads="audit")
report = operator.admin_access_report(ROOT)
print(report["scope"], len(report["checks"]) > 0)                 # org:demo True
operator.admin_set_tenant_settings(ROOT, operator_data_reads=None)  # the deployment's mode again
print(operator.ready()["ready"], "disk" in operator.admin_metrics())  # True True

Tokens and principal chains

A client acts as its token's subject. mint_token mints a PASETO token for a principal; its chain fields say who is acting for whom: act (an agent acting for the subject; it writes only with a run), app and client (an application, and whether a person or an agent drives it), run and run_start, and taint tags. mint_agent_token and mint_app_token mint the two common chains. A token with a chain field lives at most a day by default (CHAIN_TOKEN_MAX_TTL_SECONDS), and an agent chain token names its caps with scopes that confine each; the SDK refuses before sending what the server always refuses (check_mint, a ValueError). Other tokens live at most their kind's ceiling, by default lifetime_ceiling(subject): 90 days for a person (a week on a 0.14.0 server), a week for an agent, 30 days for a service. Since 0.14.1 each ceiling is a server setting (CORTEX_MINT_MAX_LIFETIME_PERSON, _AGENT, _SERVICE, _CHAIN): admin_metrics()["auth"]["lifetime_ceilings"] reports the server's, and a mint over one is 422 INVALID_BODY ttl_too_long with ceiling_s. with_token derives a client that uses another token over the same connections.

from cortexdb.v1 import lifetime_ceiling

erin = Cortex(URL, bearer=operator.mint_token(subject="user:erin", scope=ROOT)["token"])
print(erin.actor, lifetime_ceiling("user:erin"))                 # user:erin 7776000

home = f"{ROOT}/user:alice"
planner = alice.with_token(alice.mint_agent_token(
    "user:alice", "agent:planner", run="weekly-plan-1", ttl_seconds=600,
    caps=["scope.write", "scope.read.local"], scopes=[f"scope.write:{home}!", f"scope.read.local:{home}!"]))
planner.experience(home, text="Drafted the weekly plan", wait="indexed")
chain = planner.whoami()["chain"]
print(chain["act"], chain["run"])                                # agent:planner weekly-plan-1

# The application's own principal mints a person's token for it.
notes = alice.with_token(operator.with_options(actor="service:notes").mint_app_token(
    "user:alice", "service:notes", scope=ROOT))
print(notes.whoami()["chain"]["app"])                            # service:notes

act naming an AI employee is 422 INVALID_BODY (act_not_delegable: an AI employee's token has the employee as sub and no act); a token over its ceiling 422 INVALID_BODY ttl_too_long at the mint and 401 INVALID_TOKEN_CLAIM (lifetime_over_ceiling) once presented. Each caps entry is one capability: a pattern such as scope.* is 422 INVALID_BODY with field == "caps", entry the entry and reason == "wildcard_not_allowed" ("invalid" for an entry that does not parse).

Break-glass and the subject-token shadow

A tenant's operator mode (admin_set_tenant_settings) decides what the operator key may do with the tenant's data: allow, audit (served and counted), or deny, where reads of stored rows, private regions and the in-band paths answer 403 BREAK_GLASS_REQUIRED unless the request carries X-Cortex-Break-Glass. break_glass(reason, ticket, note) derives a client that sends it: every request is audited with the reason and ticket, and a read of a private region tells its person first. The header is checked here as the server checks it. with_options(subject_token=...) sends the person's own token beside the key (X-Cortex-Subject-Token): the server evaluates each decision for that token too and counts the differences in the access report, without changing any response.

from cortexdb import errors

operator.admin_set_tenant_settings(ROOT, operator_data_reads="deny")
try:
    operator.events(f"{ROOT}/user:alice")
except errors.BreakGlassRequiredError as refused:
    print(refused.error_code, refused.mode)                      # BREAK_GLASS_REQUIRED deny
glass = operator.break_glass("support", "SUP-1142", "alice asked for help with her notes")
print(len(glass.events(f"{ROOT}/user:alice")["items"]) > 0)       # True: served and audited
print(alice.access_notices(ROOT)["items"][-1]["cause"])          # break_glass
glass.admin_set_tenant_settings(ROOT, operator_data_reads=None)  # lowering from deny takes it too

shadowed = operator.with_options(subject_token=alice.bearer)
shadowed.recall(ENG, query="what shipped?")
checks = {c["check"]: c["requests"] for c in operator.admin_access_report(ROOT)["checks"]}
print(checks["subject_shadow"] > 0)                              # True

How a memory was made (CortexDB 0.15.0)

A server that lists derivation_provenance_v1 says how each fact and belief was made, and what became of each event's derivation. Nothing here serves text the extractor read or wrote: models, versions, rule ids and counts only.

  • include=["derivation"] on facts, fact, facts_timeline, beliefs and belief_why adds one derivation object per row: verdict ("accepted" for a fact the enrichment plane wrote, "declared" for a write-back, None for a row with no stamp, written before 0.15.0 or as a typed triple), the extraction model and entity_model, prompt_version, gate_version, policy_hash ("dp1:none": no derivation policy), and rule, topic, derived_by, pinned, confirmed and unsynced. A belief's is computed from its supporting facts. A server without the capability ignores the parameter; derivation_of(row) is then None.
  • derivation_decisions(scope, event_id): the event's outcome (learned, nothing_admitted, held_only, pending, skipped with its reason, or failed with retrying), the models, prompt version and policy, and rejected counted by rule id. A reader of the event only: anything else is 404 NOT_FOUND, as on a server before 0.15.0, which has no such route, so check capabilities() first: the two 404s read alike.
  • derivation_status(scope) gains extraction: the scope's events by recorded outcome, what the enrichment scanner has yet to derive (pending), and its own caught_up (the top-level caught_up stays the layer builds').
  • A write that names a directive nothing reads (consolidate_into, confidence_floor, ttl_for_belief_layer, embed, async) is told so in its ack's warnings, as directive_not_enforced:<name>; unenforced_directives(ack) reads the names from an ack, a bulk results item or an import job. A change set whose companion put leaves enrich out keeps the stored value, and enrich_kept(answer) reads what a staging answer or a preview page says it kept.
from cortexdb.v1 import derivation_of, unenforced_directives

note = alice.experience(ENG, text="The gateway moves to Frankfurt in March", wait="indexed",
                        directives={"embed": "lazy"})
print(unenforced_directives(note))                               # ['embed']: accepted, not enforced
decision = alice.derivation_decisions(ENG, note["event_id"])
print(decision["outcome"], decision.get("reason"))               # skipped enrich_off (no enrichment here)
for fact in alice.facts(ENG, include=["derivation"])["items"]:
    print(fact["predicate"], (derivation_of(fact) or {}).get("model"))
print(alice.derivation_status(ENG)["extraction"]["caught_up"])   # True

Govern what CortexDB learns (CortexDB 0.15.0)

A server that lists derivation_policy_v1 lets an organization decide what CortexDB learns from its memories; derivation_feed_v1 and derived_by_v1 let its own workers learn the rest and write it back. Check capabilities() first: a server before 0.15.0 answers 404 for a route it does not serve, which reads like a missing record (derivation_settings answers 404 for a scope without settings too), and no method asks on its own. Every route here answers X-Cortex-Stability: experimental. Policies, settings and texts need a shard armed for apply format 11 (a 0.15.0 data directory arms it at its first boot); below it they answer 503 FORMAT_UPGRADE_PENDING, while the policy read serves the empty policy with format_armed: 10.

Derivation policies

A policy is a registry record at <scope>/attrs:derive, written by a change set that holds derive records and nothing else; derive_record(scope, body) (also client.derive_record) builds the put for changeset_part. A body names the taxonomy's topics and detectors (derivation_taxonomy()), may start from a template (derivation_templates()), and may write its instructions, examples and custom topics' descriptions inline: the change set stores each as a policy text. Every page of its preview carries a derivation section, each governed scope's policy hash before and after, which the approval binds. derivation_policy(scope) reads the effective policy: what every derive record on the scope's path and org chart and the subject's settings make of it, where each rule was set, its hash (dp1:none without a policy) and format_armed; include_texts=True adds the texts' content, for an Owner who administers derivation. A refused body raises errors.DerivationPolicyInvalidError (path, field, reason), DerivationPolicyWidensError (rule, value, ancestor: a policy only tightens its ancestors'), DerivationModelNotAllowedError (model, allowed) or DerivationTextInvalidError (reason, index: an example says synthetic: True or cites the events it was copied from).

from cortexdb.v1 import changeset_part, derivation, derive_record

print(derivation.DERIVATION_POLICY_V1 in operator.capabilities())   # True
print(sorted(t["id"] for t in operator.derivation_templates()["templates"])[:2])
# ['consumer@1', 'enterprise@1']
print("payment_data" in {g["id"] for g in operator.derivation_taxonomy()["groups"]})  # True

body = {"v": 1, "mode": "automatic", "topics": {"deny": ["payment_data", "government_ids", "secrets"]},
        "instructions": [{"text": "Keep what helps the team plan its releases."}],
        "examples": [{"input": "Payments v3.1 ships Friday", "memories": ["Payments v3.1 ships on Friday"],
                      "synthetic": True}]}
compiler.changeset_stage(ROOT, "derive-eng-1", [changeset_part(0, [derive_record(ENG, body)])],
                         reason="what the team's memory keeps")
preview = compiler.changeset_preview("derive-eng-1", ROOT)
change = preview["derivation"]["effective"][0]
print(change["scope"], change["before"])                         # org:demo/team:eng dp1:none
compiler.changeset_activate("derive-eng-1", ROOT, preview["preview_hash"])
policy = alice.derivation_policy(ENG)
print(policy["policy_hash"] == change["after"], policy["format_armed"])   # True 11
print("topics.deny" in {rule["rule"] for rule in policy["restrictions"]})  # True

Testing a draft

derivation_policy_test(scope, policy=body) runs extraction and the gate over a sample of the scope's events under a draft, in place of the scope's own derive record (the ancestors' restrictions still apply), and answers each candidate's verdict, rule and topic beside the policy in force; changeset="<id>" tests what one of your staged change sets would leave instead. It writes nothing, but its model calls are real: max_cost_usd (1 by default) is refused up front when the server's estimate is above it, reserved of the tenant's daily budget of tests and dry runs, and the run stops once its calls spent it (the events left are not_run). sample is the newest N events (50 by default, at most 200) or a list of event ids. The answer names rejected candidates with their text: keep it no longer than you need it. A test needs enrichment on, an Owner of the scope who administers derivation and may call the model (llm.invoke), and a Reader of every sample event; errors.PolicyTestTooLargeError carries the estimate (estimate_usd), an unpriced model (reason == "unpriced_model") or the day's budget (reason == "daily_budget", remaining_usd). The method raises its HTTP timeout to cover the sample, and never sends a test twice.

from cortexdb.v1 import errors

draft = dict(body, topics={"deny": ["payment_data", "government_ids", "secrets", "gdpr_art9"]})
try:
    result = compiler.derivation_policy_test(ENG, policy=draft, sample=20, max_cost_usd=0.50)
except errors.PolicyTestTooLargeError as refused:
    print("estimated at", refused.estimate_usd)        # raise max_cost_usd, or sample fewer
else:
    print(result["summary"]["rejected"], result["diff"], result["cost"]["usd"])
    for event in result["events"]:
        for candidate in event.get("candidates", []):
            if candidate["verdict"] != candidate.get("active"):
                print(event["event_id"], candidate["rule"], candidate.get("active_rule"))

Subject settings

An application, or its user, sets restrictions and consents for one scope with no change set: a stricter mode, deny_topics, deny_predicates, consents that lift a deny_unless_consent topic until they end, limit_spi, objection and the read-time rule's attributes. put_derivation_settings replaces the whole record: a field it leaves out is removed, so a change reads the record (derivation_settings), changes it and writes it back; settings_fields(answer) gives the fields a put takes (without the v, by and at the server sets). A looser mode raises DerivationPolicyWidensError; delete_derivation_settings erases the record. A consent given, changed or withdrawn writes an audit row (audit_list(action="derivation_consent")) that holds a hash of the consents, never the consents.

from cortexdb.v1 import settings_fields

home = f"{ROOT}/user:alice"
put = alice.put_derivation_settings(home, mode="explicit", deny_predicates=["diet"],
                                    consents={"health": {"purpose": "health coaching"}})
print(put["settings"]["mode"], put["policy_hash"].startswith("dp1:"))    # explicit True
fields = settings_fields(alice.derivation_settings(home))   # read, change, write back
fields["deny_topics"] = ["political_opinion"]
again = alice.put_derivation_settings(home, **fields)
print(again["settings"]["deny_predicates"], again["revision"] > put["revision"])  # ['diet'] True
print(alice.delete_derivation_settings(home)["erased"])                  # True

Policy texts

A policy's instructions, examples and topic descriptions are policy texts, which may hold personal data. derivation_texts(scope) lists those created at or under a scope, without their content (pages with pages()), for an Owner who administers derivation; erase_derivation_texts(scope, ids, reason=) erases some, and each policy that named one keeps the id and gets a new hash. The reason can name a person, so it is kept nowhere: the audit row (action="derivation_text_erase") and the erasure's receipt hold its peppered hash. An example also goes with any event it cites.

texts = compiler.derivation_texts(ROOT)["items"]
print(sorted(text["role"] for text in texts))                    # ['example', 'instruction']
example = next(text for text in texts if text["role"] == "example")
erased = compiler.erase_derivation_texts(ROOT, [example["id"]], reason="no longer needed")
print(erased["erased"], erased["policies_affected"])             # 1 ['org:demo/team:eng/attrs:derive']
print(alice.derivation_policy(ENG)["policy_hash"] == erased["new_policy_hashes"][0])  # True

The change feed

A worker outside CortexDB reads a scope's events, and the erasures that touch them, with derivation_feed(scope, consumer, cursor=, limit=, descend=, since=), a page at a time, or with feed_iter(...), an iterator of the items (an async iterator on AsyncCortex) that follows each page's next_cursor, stops at has_more: False, and with follow=True waits poll_seconds and asks again. Its cursor is where to resume without skipping an item not yet handled: save it once an item's writes commit. The cursor is opaque and bound to the root and the consumer (FEED_CURSOR_INVALID otherwise); delivery is at least once. An erased, expired or redacted item names its events only by hash, never by id: feed_erased_id_hash(event_id) is the lowercase hex of BLAKE3 over cortexdb/feed/erased-id/v1 and the id's 16 UUID bytes (evt_0196f2a0c1d27b3e9a4f5d6c7b8a9e02 hashes to 284c5e5cb197e678093a790ca6ccf3d7ec1822b71b811b3d42672d49e4fca18e), computed by the blake3 package when it is installed (pip install cortexdbai[blake3]) and in pure Python otherwise, and erased_matches(item, held_ids) picks the ids a worker holds that an item names.

from cortexdb.v1 import erased_matches

home = f"{ROOT}/user:alice"
draft = alice.experience(home, text="A draft the worker copies", wait="indexed")
worker = alice.feed_iter(home, "notes-worker")
held = {}                                                       # the worker's copies, by event id
for item in worker:
    if item["type"] == "event":
        held[item["event"]["id"]] = item["event"]["content"]
print(draft["event_id"] in held, worker.has_more)               # True False
alice.forget(home, memory_ids=[draft["event_id"]])
for item in alice.feed_iter(home, "notes-worker", cursor=worker.cursor):
    for gone in erased_matches(item, held):                     # by hash: the id is never sent
        del held[gone]
print(draft["event_id"] in held)                                # False

The reference worker

cortexdb.workers.DerivationWorker is a whole worker: subclass it with a name, a version, derive(event) (what to write back: Triple objects) and purge(event_ids) (delete your own copies), and call run(). It reads the feed as its consumer, writes each event's results back in bulk with provenance: [event.id], its derived_by stamp and a deterministic idempotency key (a page delivered again replays), keeps each derived event's hash beside its id, matches the erasure items' event_id_hashes against them and calls purge with the ids they name, saves the cursor only after the page's writes committed (FileCursor(path) keeps it with the hashes, atomically; MemoryCursor() in memory), backs off on 503 honouring Retry-After, and stops with WorkerStoppedError on FORMAT_UPGRADE_PENDING and ENRICHMENT_SCOPE_NOT_ALLOWED. run(follow=True) keeps polling. It never derives from its own write-backs, which the feed serves too.

from cortexdb.workers import DerivationWorker, MemoryCursor, Triple

class LevelWorker(DerivationWorker):
    name, version = "acme-level", "1.0.0"

    def derive(self, event):
        if "source:assessment" not in event.labels:
            return []
        band = event.text.split("band=")[-1].strip()
        return [Triple(subject="alice", predicate="level", object=band)]

    def purge(self, event_ids):
        print("purged", len(event_ids))

home = f"{ROOT}/user:alice"
test = alice.experience(home, text="assessment band=advanced", labels=["source:assessment"],
                        wait="indexed")
worker = LevelWorker(alice, scope=home, cursor=MemoryCursor())
print(worker.run().writes)                                       # 1
alice.forget(home, memory_ids=[test["event_id"]])
worker.run()                                                     # purged 1

Declared episodes and the feed's consumers

declare_episode(scope, name, summary, events, started_at=, ended_at=, actors_involved=, derived_by=, idempotency_key=) stores a worker's episode over 1 to 1,024 events it read as a replicated record (declared_episodes_v1, format 11): every replica serves it beside the built episodes with declared: True, a rebuild spares it, and it is erased with any event it names. delete_episode(scope, id) erases one (a built episode answers 404). A server before 0.15.0 answers declare_episode 405 (it serves that path for listing only) and delete_episode 404. From format 11 a feed request that names a consumer records the consumer's mark, and feed_consumers(scope) (an Owner with derivation.administer.scope, or the operator; pages with pages()) lists the consumers whose marks reach the scope: principal, scope, delivered_through, last_read_at, idle after 7 days without a read, and when an unread mark is purged. An erasure's receipt and proof name the consumers that may hold a copy of what it took (feed_consumers_of(answer), each line's event_id_hashes in the feed's form), and the proof checks the governed records (verify_check(proof, GOVERNED_RECORDS_CHECK)).

from cortexdb.v1.derivation import GOVERNED_RECORDS_CHECK, feed_consumers_of, verify_check

first = alice.experience(home, text="The checkout service failed at nine", wait="indexed")
second = alice.experience(home, text="The checkout service was restored at ten", wait="indexed")
episode = alice.declare_episode(home, "Checkout outage", "The checkout service failed for an hour.",
                                [first["event_id"], second["event_id"]],
                                derived_by="acme-sessionizer@2.1.0", idempotency_key="outage-1")
print(episode["declared"], episode["id"].startswith("ep_"))      # True True
print(alice.delete_episode(home, episode["id"]))                 # {'deleted': True}
names = {c["consumer"] for c in operator.feed_consumers(ROOT)["consumers"]}
print("acme-level" in names)                                     # True
job = operator.erase(home, memory_ids=[first["event_id"]], audit_note="readme")
receipt = operator.erasure_receipt(job["erasure_id"], scope=home)
print("acme-level" in {line["consumer"] for line in feed_consumers_of(receipt)})  # True
proof = operator.erasure_verify(job["erasure_id"], scope=home)
print(verify_check(proof, GOVERNED_RECORDS_CHECK)["ok"])              # True

Write-backs and imports

A worker stamps what it writes back with derived_by ({"name", "version"} or "name@version") on a typed triple (experience(..., triple=...), a bulk item) or a declared belief (create_belief); the stamp is part of the write's identity, and the fact or belief serves it under include=["derivation"]. derivation_status(scope, derived_by=[names]) reports each name's latest version and the rows written under older ones, which the worker writes again. A label of the write's own that starts derived_by: raises errors.DerivedByInvalidError (reason == "reserved_label"). The importers take mode: raw (the default) derives the rows again, keep keeps them as the memories the source extracted, and Zep's keep_triples writes its edges as typed triples. A row's id keys it, so an export sent again replays, and every row is stamped import:<provider>@1. A server before 0.15.0 ignores mode. dropped_derived_by(job) names the stamps an import of exported lines did not keep.

from cortexdb.v1 import dropped_derived_by

release = {"subject": {"type": "literal", "datatype": "string", "value": "payments"},
           "predicate": "release_day",
           "object": {"type": "literal", "datatype": "string", "value": "Friday"}}
alice.experience(ENG, triple=release, derived_by="release-notes@1.0.0", wait="indexed")
report = alice.derivation_status(ENG, derived_by=["release-notes"])["derived_by"][0]
print(report["latest"], report["current"], report["unsynced"])   # 1.0.0 1 0
job = alice.import_mem0(f"{ROOT}/user:alice", [{"id": "mem0-42", "memory": "Prefers aisle seats"}],
                        mode="keep")
print(job["accepted"], dropped_derived_by(job))                   # 1 []

Correct a memory (CortexDB 0.15.0)

A server that lists corrections_v1 lets a scope's Writers, the end user's own token included, correct what CortexDB holds about them, on every replica and durably: a derived_only forget can be derived again, a correction is not. A correction names a claim (subject, predicate, value and polarity), never a fact: the target is a fact id, which the server resolves to its claim, or a claim mapping {"subject", "predicate", "object", "negated"}. Check capabilities() first (a server before 0.15.0 answers 404); corrections need a shard armed for apply format 11, memory_about format 10.

  • reject(scope, target, bind=) deletes the claim's facts and suppresses it, so no re-enrichment, re-derivation or replay brings it back: bind="claim" (the default) still lets a later event state it again, "subject_predicate" and "subject" never. A typed triple is the customer's own statement, so rejecting one erases its event.
  • replace(scope, target, value, valid_from=) writes the new value as a typed triple, closes the old facts (they stay in facts_timeline), pins the new claim and suppresses the old.
  • pin(scope, target) keeps extracted facts from superseding the claim's; confirm(scope, target, valid=) raises its authority. correct(scope, action, target, ...) is the general form.
  • corrections(scope, action=, origin=, subject=, predicate=) lists the corrections of a scope (pages with pages()), correction(scope, id) reads one with the facts it changed, and undo_correction(scope, id) reverses it (its author, an Owner or the trusted operator).
  • memory_about(scope) is what is known about the scope's subject, each fact and belief with its sources, and the scope's corrections: the per-subject export for access requests, readable with the person's own token. Its include is ("corrections", "held") by default, so the answer also holds the scope's corrections and its open candidates held for review (derivation_review_v1, below): everything known about the subject. include=() asks for neither, the server's own default; the TypeScript SDK's memoryAbout() sends the same.

Pass an idempotency_key: the same call sent again answers the first attempt (replayed: True), which is how a WAL_OUTCOME_UNKNOWN is retried. A refusal raises errors.CorrectionConflictError (an open correction of the same claim and action, or a pin beside a reject; existing), errors.CorrectionTargetUnknownError (no live fact states the claim; claim), IdempotencyConflictError or NotFoundError. A conflict's resolution (resolve_conflict) is proposed as corrections too, and answers their correction_ids; loser="wrong" beside a pick rejects the losers instead of closing them.

home = f"{ROOT}/user:alice"
lived = {"subject": {"type": "literal", "datatype": "string", "value": "alice"}, "predicate": "lives_in",
         "object": {"type": "literal", "datatype": "string", "value": "Boston"}}
alice.experience(home, triple=lived, wait="indexed")
fact = next(f for f in alice.facts(home)["items"] if f["predicate"] == "lives_in")
fixed = alice.replace(home, fact["id"], "Denver", idempotency_key="alice-moved")
print(fixed["state"], fixed["replacement"]["claim"]["object"])   # applied Denver
print([(c["action"], c["claim"]["object"]) for c in alice.corrections(home)["items"]])
# [('replace', 'Boston')]
about = alice.memory_about(home)
print(fixed["correction_id"] in {c["correction_id"] for c in about["corrections"]})  # True
print(alice.undo_correction(home, fixed["correction_id"])["state"])                 # undone

Review before commit (CortexDB 0.15.0)

A derivation policy can hold a candidate memory for a reviewer instead of storing it: a topic or predicate its review rules hold, the review mode, a writer rule's refusal, or a confidence below the policy's threshold. A held candidate is in no store, recall or answer until a reviewer approves it; one nobody decides lapses after the policy's review.lapse_days (30 by default). Check capabilities() for DERIVATION_REVIEW_V1 first: a server before 0.15.0 answers 404 for these routes, which reads like a missing record. They need a shard armed for apply format 11 (errors.FormatUpgradePendingError below it), and every answer carries X-Cortex-Stability: experimental.

  • review(scope, topic=, rule=, descend=, state=, cursor=, limit=) lists the open candidates held at exactly scope, oldest first (descend=True adds the scopes under it the caller may read with scope.read.descend). Each item has its held_id (hld_…), event_id, the candidate (kind, subject, predicate, object or text, quote, topic, confidence), the rule that held it, held_at, lapse_at and source (the text around the quote, or None once its event is no longer here to quote). open counts every item the filters select; limit is 1 to 200 (50 by default), and pages() follows next_cursor.
  • review_decide(scope, decisions) decides 1 to 100 candidates, each {"held_id", "decision": "approve" | "reject", "bind"?, "reason"?}; approve(scope, held_id, reason=) and reject_held(scope, held_id, bind=, reason=) decide one. An approval makes the candidate a fact of its event, the same on every replica (fact_id; pending: True while the server still makes it). A rejection erases the candidate and leaves a correction (origin: "review", correction_id; corrections(scope, origin="review") lists them) that keeps its claim suppressed: bind="claim" (the default) for this claim, from its event and every event captured up to the decision, "subject_predicate" for every value of its subject and predicate, past and future. (reject corrects a fact CortexDB already holds.)
  • Each decision answers on its own, in order: a refused one is a result with error_code (NOT_FOUND, REVIEW_ITEM_DECIDED with details["decision_id"], PROVENANCE_ERASED, or a retriable storage code: send that one again), not an exception, and the others ran. What the route always refuses (no decisions or more than 100, a bind on an approval, bind="subject", a malformed held_id) raises ValueError before anything is sent.
  • A reviewer is a Writer of the scope, or a principal the policy's review.reviewers names, with Reader on the scope; deciding needs scope.write. Each decision writes an audit row (audit_list(action="review_decision")) that holds a hash of its result, never its words.
  • memory_about(scope) (include=("corrections", "held") by default) lists the scope's open candidates as items of kind: "held", with their held_id, rule and lapse_at, and counts["held"].
from cortexdb.v1 import DERIVATION_REVIEW_V1

clinic = "org:acme/clinic:north"   # reviewer: a client of a Writer there, or of a reviewer its policy names
if DERIVATION_REVIEW_V1 in reviewer.capabilities():     # a server before 0.15.0 answers 404
    for page in reviewer.pages(reviewer.review, clinic, topic="health"):
        for item in page["items"]:
            print(item["held_id"], item["rule"], item["candidate"], item["lapse_at"])
    approved = reviewer.approve(clinic, "hld_0196f2a1c3d47e8f9a0b1c2d3e4f5a6b", reason="confirmed with patient")
    print(approved["results"][0].get("fact_id") or approved["results"][0].get("error_code"))
    rejected = reviewer.reject_held(clinic, "hld_0197a2b3c4d5e6f708192a3b4c5d6e7f", bind="subject_predicate")
    print(rejected["results"][0].get("correction_id") or rejected["results"][0].get("error_code"))

A Claude memory tool backed by CortexDB (CortexDB 0.15.0)

Anthropic's memory tool ({"type": "memory_20250818", "name": "memory"}) is client-side: Claude asks for file operations on a /memories directory and your application carries them out. cortexdb.memory_tool.CortexMemoryTool carries them out on a CortexDB scope. It subclasses the Anthropic SDK's BetaAbstractMemoryTool (pip install 'cortexdbai[anthropic]', anthropic 0.69 or later), so it goes straight into client.beta.messages.tool_runner(..., tools=[memory]). CortexMemoryFiles is the same handler without the Anthropic SDK, for your own tool loop: handle(tool_use.input) answers the tool result's text and raises MemoryToolError for an error result.

  • create writes the file as an event labelled memory_file:<path> (modality: "document", content.kind: "text", directives.extract: [], so CortexDB derives nothing from the agent's own notes), citing the session's events when you pass provenance= (a list, or a callable). A file is the latest event with its path label.
  • str_replace and insert read the latest version, write a new one and forget the previous by id; rename writes the file under its new path and forgets the old; delete forgets every version, or erases them with erase=True.
  • on_write(path, text) -> str | None runs in your process before anything is written: return the text to write (rewritten or not), or None to refuse the write, which Claude is told.

The credential writes the scope and forgets there (an Owner, or a person's own home). Give the agent a scope of its own: a directory view lists the scope's labelled events.

from cortexdb.memory_tool import CortexMemoryFiles

notes = CortexMemoryFiles(alice, home,  # in production, a scope of the agent's own
                          on_write=lambda path, text: text.replace("hunter2", "[secret]"))
print(notes.handle({"command": "create", "path": "/memories/prefs.md",
                    "file_text": "Prefers email. Password hunter2.\n"}))
# File created successfully at: /memories/prefs.md
notes.handle({"command": "str_replace", "path": "/memories/prefs.md",
              "old_str": "email", "new_str": "phone"})
print(notes.handle({"command": "view", "path": "/memories/prefs.md"}).splitlines()[1])
#      1	Prefers phone. Password [secret].
print(notes.handle({"command": "delete", "path": "/memories/prefs.md"}))
# Successfully deleted /memories/prefs.md

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 | None the token's sub Sent as X-Cortex-Actor: by default the bearer token's sub (no header for a subject an issuer maps), user:default for the operator key or no bearer; None sends none
bearer str | None None PASETO v4 public / JWT bearer, or the operator key (omit for auth-disabled dev)
timeout float 60.0 Request timeout (seconds)
headers dict | None None Extra headers on every request
consistency ConsistencyTokens | None None A tracker every request feeds and demands from (read-your-writes across nodes)

with_options(actor=, headers=, timeout=, consistency=, bearer=, break_glass=, subject_token=) derives a client that shares the connection pool; break_glass(reason, ticket, note) and with_token(token) are shorthands.

License

Apache-2.0

Metadata

Release files for cortexdbai 0.14.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cortexdbai 0.14.0
File Size Uploaded Provenance Actions
cortexdbai-0.14.0.tar.gz 602.9 kB Without provenance Details for cortexdbai-0.14.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cortexdbai 0.14.0
File Interpreter ABI Platform Actions
cortexdbai-0.14.0-py3-none-any.whl Python 3 none any Details for cortexdbai-0.14.0-py3-none-any.whl

Total release size: 1.1 MB

Release files / cortexdbai-0.14.0.tar.gz

Download URL cortexdbai-0.14.0.tar.gz
Size 602.9 kB
Tags Source
SHA-256 checksum
How to use checksums
c3e38f22c69badbc970a07cf88d37037fea9b1d91652bfa8917822af1266305f
BLAKE2b-256 checksum
How to use checksums
ff72157880dc15fe62fb483b5635b62aa15c82153c36bee5d3c0b034bad58b8f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Release files / cortexdbai-0.14.0-py3-none-any.whl

Download URL cortexdbai-0.14.0-py3-none-any.whl
Size 482.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f2d74cefea6c41c0672cda5392e275ae571dac55d126b3af8c8d9a7acb9757a6
BLAKE2b-256 checksum
How to use checksums
84f7e419200ae60cee3438e8da880185c79e1ab9ac3db60149f6e3a18b36b56e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Security for cortexdbai 0.14.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.14.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page