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
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")
Using CortexDB as an agent's memory
If an agent uses this client as its memory, its prompt can carry this guidance:
- What memory is for: carrying what was learned into later sessions, so work is not redone and mistakes are not repeated.
- Read before answering. Before answering anything that may depend on an earlier session (a person's
preferences, a decision, what was tried before),
recallfirst. - Store what the environment will not show later with
experience: decisions and their reasons, preferences, rules, outcomes and corrections. Skip what can simply be read again, such as files, pages or tool output. - Record a rule with its basis: how it is known, and whether it was confirmed.
- Leave what to record to the model. There is no fixed list of what to store.
- Fix, don't forget. When a memory is wrong,
correctit (CortexDB 0.15.0), so it is not learned again;memory_aboutshows what is known about a subject, with its sources.
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.
Voice mode (experimental)
A server in voice mode (CORTEX_PROFILE=voice, the server's docs/VOICE_MODE.md) is the memory
of a live voice agent. recall(..., profile="voice") takes the short read path of a voice turn
(recall_profile_voice_v1, served by every CortexDB server from 0.16.0, voice mode or not), and a call
keeps its caller's memories in RAM for the call (client.sessions, voice_sessions_v1, voice mode
only; any other server raises VoiceSessionsDisabledError).
caller, call = "ws:acme/caller:9f2c1e", "call_01JF8M2Q7R"
started = c.sessions.start(caller, call, query="billing question") # the brief, at most 400 tokens
print(started["brief"]["context_block"])
pack = c.recall(caller, query="what did I order last time", profile="voice", session=call)
c.experience(caller, text="Change my delivery address to Pune.", wait="captured",
labels=[f"session:{call}"]) # the call's next recall finds it at once
c.sessions.end(caller, call)
alpha(0.0 to 1.0) weighs the vector list against BM25 in fusion:1.0is vector-only.- A session is its principal's: another caller naming the same id holds its own, and
getandendof a session someone else started raiseSessionNotFoundError, as they do after a restart or a leader change (the next voice recall naming the session opens it again). - A start past the server's session limits still answers its brief, with
working_set["state"] == "refused"and asession_not_heldwarning: the call's recalls are then answered by the index. A voice adapter treats every session failure as "no working set" and goes on.
Moving an existing store to voice mode (CortexDB 0.16.0)
A data directory is pinned to the embedding model it was first written with, so a store embedded
with OpenAI (or the mock embedder) cannot simply start in voice mode. The trusted operator moves it
online with the re-embed routes (a single node with no segment store; a cluster moves by export and
import): a dry run first, then a job that builds a complete second set of vector indexes under the
target model beside the live ones, which keep serving at full quality. Once the job has caught up it
stays current (ready), and a restart with the target configured (the record's restart_with)
swaps the indexes before anything serves.
import os
import time
from cortexdb import Cortex, V1ConflictError
# The deployment's operator key; `actor=None` sends no X-Cortex-Actor.
operator = Cortex("http://localhost:3141", bearer=os.environ["CORTEX_API_KEY"], actor=None)
TARGET = "local:potion-multilingual-128M" # "local" alone is the same; or "local:granite-embedding-107m-multilingual"
plan = operator.admin_reembed(TARGET) # a dry run: nothing changes
print(plan["current_pin"], "->", plan["target_pin"])
print({name: family["rows"] for name, family in plan["families"].items()})
print(plan["estimate"]) # seconds, disk_bytes, memory_bytes, cost_usd (0 in process)
for blocker in plan["blockers"]: # each one would refuse the start
print(blocker["code"], blocker["message"])
try:
job = operator.admin_reembed(TARGET, dry_run=False)["job"]
except V1ConflictError as exc: # 409: the first blocker's code, every one in exc.blockers
print(exc.error_code, exc.detail("blockers"))
raise
while job["state"] == "building": # the live index serves meanwhile
time.sleep(2)
job = operator.admin_reembed_status()["job"]
print(job["state"], job["restart_with"]) # "ready": restart with these settings to swap
tois"provider:model", a provider alone ("local"is the voice profile's model), or a mapping withproviderand optionallymodelanddims(a remote model's width).- The refusals are 409s whose class is the first blocker's (
errors.SegmentsPresentError,errors.JobActiveError,errors.OldIndexRetainedError,errors.TargetIsCurrentError,errors.TargetUnavailableError, ...), each withblockers; the dry run answers 200 and lists the same blockers. A configured segment store (CORTEX_ICE_URL) blocks a start whether or not it sealed anything (SEGMENTS_PRESENT). Besides those:errors.InvalidRequestError(422, an empty provider),errors.InvalidBodyError(422, a field the server does not know),errors.ReembedUnavailableError(503, a server with no job surface) anderrors.ReembedFailedError(500, a store failed). - An erasure, a forget or a retention sweep that runs during the job reaches the new indexes too.
A restart on the current model resumes the job: a building one walks again from the start,
keeping the chunk rows its copy holds (
progressrestarts at 0). - The swapping restart records its checks in the job's
verify(ok: falsekeeps the old index). After a crash rather than a graceful stop, the record readsswapping,phase: "repairing", while the server serves and embeds what the copy missed, thenswapped. admin_reembed_cancel()stops a job that isbuildingorreadyand deletes what it built; the live index never changed.- The swap deletes the old index unless the start said
retain_old_index=True(or the checks failed); thenadmin_reembed_cleanup()deletes it later (old_index_retainedsays one is pending), and until then a new start is refused withOLD_INDEX_RETAINED. - The server's
docs/VOICE_MODE.md("Moving an existing store to voice mode") has the whole flow, the console's and the CLI's included.
What's new in 0.15.0 for CortexDB 0.16.0
cortexdbai 0.15.0 is the client side of CortexDB 0.16.0's voice mode and
online re-embed. Each item needs a server that lists its capability
(capabilities()): a server before 0.16.0 refuses the voice recall fields (422
INVALID_BODY) and answers 404 for a route it does not serve, which reads like
a missing record.
- Voice calls (
voice_sessions_v1, experimental):client.sessions.startopens a call's session and returns its brief, and the server then holds the caller's memories in RAM for the call;getreads the session andendends it. Only a server in voice mode serves them: any other raisesVoiceSessionsDisabledError(Voice mode). - Voice recall (
recall_profile_voice_v1):profile="voice", the short read path of a live voice turn, andalpha, the vector list's weight against BM25, onrecallandrecall_stream, each sent only when given. - The online re-embed (the trusted operator's, on a single node):
admin_reembed(a dry run unlessdry_run=False),admin_reembed_status,admin_reembed_cancelandadmin_reembed_cleanup(Moving an existing store to voice mode). - Typed errors for the new codes: the sessions'
VOICE_SESSIONS_DISABLEDandSESSION_NOT_FOUND, and the re-embed'sSEGMENTS_PRESENT,JOB_ACTIVE,OLD_INDEX_RETAINED,TARGET_IS_CURRENT,TARGET_UNAVAILABLE,TARGET_MOCK,DISK_INSUFFICIENT,SCOPE_MIGRATION_ACTIVE,REEMBED_UNSUPPORTED_ON_CLUSTER,REEMBED_NOT_CANCELLABLE,REEMBED_NOTHING_TO_CLEAN,REEMBED_UNAVAILABLEandREEMBED_FAILED.
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'sextractionblock (below). - Derivation policies (
derivation_policy_v1):derive_recordfor 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) andaudit_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 oncreate_belief, andderivation_status(scope, derived_by=[...]). - Importers:
mode=onimport_mem0,import_zep,import_lettaandimport_openai;dropped_derived_by(job). - Corrections (
corrections_v1):correctand its shorthandsreject,replace,pinandconfirm,corrections,correction,undo_correctionandmemory_about;resolve_conflicttakesloser=and answerscorrection_ids(below). - Review before commit (
derivation_review_v1):review,review_decideand its shorthandsapproveandreject_held, and the held itemsmemory_aboutlists (below). - Re-derivation (
derivation_rederive_v1):rederive(scope, mode), aregateor areextract, a dry run unlessdry_run=False, of the unsynced rows unless it namesevent_ids;rederive_job,rederive_waitandrederive_cancelfollow the job, andderivation_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 workercortexdb.workers.DerivationWorker(withFileCursorandMemoryCursor; below) andcortexdb.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=onrecall,recall_stream,answerandcompose(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'sFORMAT_ARMED_ONE_WAYandONE_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 mostwaitseconds (120 by default,CHANGESET_WAIT_SECONDS;changeset_apply's bounds its three steps together), then raisesV1EvaluationPendingError.wait=0returns the raw 202 as anEvaluationPending. The preview waited 60 s by default. - A version downgrade names what it drops:
INVALID_ACCESS_RECORD(a change set withoutconvert) orINVALID_SCOPE_TREE(a legacy registry write),reason == "version_downgrade", withpathanddropped. - 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, andcheck_mintleaves a chain token's lifetime to the server.InvalidBodyErrorandInvalidTokenClaimErrorreadlifetime_sandceiling_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
CortexandAsyncCortexalike: the access API (access_check,access_explain, the lookups,access_limits), AuthZEN 1.0, change sets (changeset_applyand 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, withretriable,details(named properties for each documented key) andretry_after. - Consistency tokens:
consistency=Trueon writes and reads,consistency=<token>orat_least=<token>to demand one, andConsistencyTokensto carry them per root. - The new read and write fields:
extra_scopes(up to 40),coverage,beliefs="merged",mounts="default",purpose,session;provenance,intent,subjectand the envelope's other fields; streams asStreamEventiterators; a declared belief'sidempotency_key. - Paging and by-id reads: every listing pages with
pages()(events newest first by theirle1.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=Truereturns embeddings; the timeline takesas_of. - Auth: the actor follows the token,
mint_token's chain fields withmint_agent_tokenandmint_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 aV1UnavailableError), no longer a bareV1APIError: anexcept V1APIErrorkeeps catching everything, but atype(err) is V1APIErrorcheck no longer matches.V1NotConfiguredErroris now aV1UnavailableError, andV1InvalidRequestErroraV1BadRequestError. For a body withoutretriable,retriableis the code's documented default instead ofFalse. - The actor follows the token. A client built with a token bearer and no
actorsends the token'ssubasX-Cortex-Actor(0.12 sentuser:default, which the server refuses with 401ACTOR_MISMATCHfor any other subject), and no header for a token whose subject an issuer maps. The operator key and no bearer still senduser:default; passactorto choose. viewis the server's.recall,recall_stream,answerandcomposesendviewonly when you pass it (0.12 sent"holistic"). The server readsholisticas before, butgranularat an org tree's shared scope (team, org, group, compartment), whereholisticis 422VIEW_NOT_ALLOWED_AT_SCOPE.- Local refusals. A request the server always refuses fails before it is
sent, with
ValueError: anextra_scopeslist past 40, a malformed break-glass header, a mint whose chain fields breakmint_chain_v1's rules, more than 1,024provenanceids. - 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,tenantorscopes; only the trusted operator mints deployment-wide, and only for aservice:orsystem:subject), mints are held to their lifetime ceilings, a token that carriesscopesmust confine every capability it uses, and a tenant indenyrefuses the operator key's data reads without break-glass. A header that does not parse is 400INVALID_HEADER(a malformed break-glass header wasBREAK_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"]onfacts,fact,facts_timeline,beliefsandbelief_whyadds onederivationobject per row:verdict("accepted"for a fact the enrichment plane wrote,"declared"for a write-back,Nonefor a row with no stamp, written before 0.15.0 or as a typed triple), the extractionmodelandentity_model,prompt_version,gate_version,policy_hash("dp1:none": no derivation policy), andrule,topic,derived_by,pinned,confirmedandunsynced. A belief's is computed from its supporting facts. A server without the capability ignores the parameter;derivation_of(row)is thenNone.derivation_decisions(scope, event_id): the event'soutcome(learned,nothing_admitted,held_only,pending,skippedwith itsreason, orfailedwithretrying), the models, prompt version and policy, andrejectedcounted by rule id. A reader of the event only: anything else is 404NOT_FOUND, as on a server before 0.15.0, which has no such route, so checkcapabilities()first: the two 404s read alike.derivation_status(scope)gainsextraction: the scope's events by recorded outcome, what the enrichment scanner has yet to derive (pending), and its owncaught_up(the top-levelcaught_upstays 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'swarnings, asdirective_not_enforced:<name>;unenforced_directives(ack)reads the names from an ack, a bulkresultsitem or an import job. A change set whose companion put leavesenrichout keeps the stored value, andenrich_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 infacts_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 withpages()),correction(scope, id)reads one with the facts it changed, andundo_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. Itsincludeis("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'smemoryAbout()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 exactlyscope, oldest first (descend=Trueadds the scopes under it the caller may read withscope.read.descend). Each item has itsheld_id(hld_…),event_id, thecandidate(kind,subject,predicate,objectortext,quote,topic,confidence), therulethat held it,held_at,lapse_atandsource(the text around the quote, orNoneonce its event is no longer here to quote).opencounts every item the filters select;limitis 1 to 200 (50 by default), andpages()followsnext_cursor.review_decide(scope, decisions)decides 1 to 100 candidates, each{"held_id", "decision": "approve" | "reject", "bind"?, "reason"?};approve(scope, held_id, reason=)andreject_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: Truewhile 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. (rejectcorrects 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_DECIDEDwithdetails["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, abindon an approval,bind="subject", a malformedheld_id) raisesValueErrorbefore anything is sent. - A reviewer is a Writer of the scope, or a principal the policy's
review.reviewersnames, with Reader on the scope; deciding needsscope.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 ofkind: "held", with theirheld_id,ruleandlapse_at, andcounts["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.
createwrites the file as an event labelledmemory_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 passprovenance=(a list, or a callable). A file is the latest event with its path label.str_replaceandinsertread the latest version, write a new one and forget the previous by id;renamewrites the file under its new path and forgets the old;deleteforgets every version, or erases them witherase=True.on_write(path, text) -> str | Noneruns in your process before anything is written: return the text to write (rewritten or not), orNoneto 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.
Links
License
Apache-2.0
Metadata
Release files for cortexdbai 0.15.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cortexdbai-0.15.0.tar.gz | 627.9 kB | Without provenance | Details for cortexdbai-0.15.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cortexdbai-0.15.0-py3-none-any.whl | Python 3 | none | any | Details for cortexdbai-0.15.0-py3-none-any.whl |
Total release size: 1.1 MB
Release files / cortexdbai-0.15.0.tar.gz
| Download URL | cortexdbai-0.15.0.tar.gz |
|---|---|
| Size | 627.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
607253616b45c654459753e809fcc421f48731258277657e8fa20a4749af47e2
|
|
BLAKE2b-256 checksum How to use checksums |
851b8edf59d6b44a8327b4063dfd6abd202f28b33e719721efff1c320ae97dfe
|
| 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.15.0-py3-none-any.whl
| Download URL | cortexdbai-0.15.0-py3-none-any.whl |
|---|---|
| Size | 498.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
040a6ff7b321b9dfa5939c49cd2e4b7d2985b67c877024636efb74920f76a83c
|
|
BLAKE2b-256 checksum How to use checksums |
3472671fd97dde612f2db1be9c31b61124e3200405488ba68dbe4cec388ee794
|
| 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.15.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.