cortexdb-cli 0.7.0__tar.gz → 0.8.0__tar.gz

{cortexdb_cli-0.7.0 → cortexdb_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cortexdb-cli
-Version: 0.7.0
+Version: 0.8.0
 Summary: Command-line interface for CortexDB — the long-term memory layer for AI.
 Project-URL: Homepage, https://cortexdb.ai
 Project-URL: Documentation, https://cortexdb.ai/docs
@@ -36,9 +36,11 @@ Command-line interface for [CortexDB](https://cortexdb.ai) — the long-term mem
 
 Wraps the v1 HTTP API in a small, fast Click + Rich CLI. Anonymous signup
 in one command, no email or card; works against the public SaaS or any
-self-hosted CortexDB deployment. Version 0.7.0 covers CortexDB 0.14.0,
-shared memory included: the access API, change sets, the directory,
-applications, rollups, publishing and the new erasures.
+self-hosted CortexDB deployment. Version 0.8.0 covers CortexDB 0.15.0,
+governed memory formation included: derivation policies, corrections, review
+and re-derivation; and CortexDB 0.14.x, shared memory included: the access
+API, change sets, the directory, applications, rollups, publishing and the
+new erasures.
 
 ## Install
 
@@ -81,6 +83,49 @@ When a token expires you have two safe options:
 For a second brain alongside the first, isolate instead of replacing:
 `cortexdb --config-dir <dir> init`, or set `CORTEXDB_HOME`.
 
+## What's new for CortexDB 0.15.0 (cortexdb-cli 0.8.0)
+
+CortexDB 0.15.0 adds governed memory formation: control over what its
+background enrichment learns, and corrections that stay corrected. Each
+command below needs a server that serves its capability: a server before
+0.15.0 answers it 404, which reads like a missing record, and the hint says
+the server predates the command.
+
+- **`cortexdb derivation`**: `status` and `decisions` (what was learned from
+  an event, and why not), `policy`, `templates`, `taxonomy`, `test` (a draft
+  tried on real events, writing nothing), `stage` (stage, preview and
+  activate a policy), `settings`, `texts`, `feed` and `consumers`, and the
+  re-derivation jobs: `rederive` (a dry run unless `--apply`, of the unsynced
+  rows unless `--events`), `job`, `cancel` and `report`.
+- **`cortexdb corrections`** (`add`, `list`, `show`, `undo`) and **`cortexdb
+  memory about`** (`--corrections`): fix a wrong memory so it stays fixed,
+  rather than forget it.
+- **`cortexdb review`** (`list`, `approve`, `reject`): decide what a
+  derivation policy held back.
+- **`cortexdb episodes declare`** and **`episodes delete`**: a worker's own
+  episodes.
+- **New options**: `--derived-by NAME@VERSION` on `experience write`, `beliefs
+  create` and `episodes declare`; `--include derivation` on `facts list`,
+  `facts timeline`, `beliefs list` and `beliefs why`; `--session ID` on
+  `recall`, `search`, `answer` and `compose`.
+- **Warnings**: a write that names a directive nothing reads prints
+  "accepted, not enforced: NAME", and a change set that keeps a scope's
+  `enrich` says so.
+
+## What's new for CortexDB 0.14.1 (cortexdb-cli 0.7.1)
+
+- **Change sets that take long.** A staging, a preview or an activation whose
+  evaluation runs past the server's wait answers 202 and goes on. `changes
+  stage`, `parts`, `preview` and `activate` send the request again until it
+  answers, with a progress line, for `--wait` seconds (120 by default); past
+  it they exit 75 and say how to collect the answer. A 202 is never an error.
+- **The tenant-binding dry run** shows how the operator plane will decide the
+  real run, and says when `--apply` needs `--break-glass`.
+- **A write that would make a version-2 record version 1** is refused; the
+  hint names the fields it drops and `--convert`.
+- **Token lifetimes** are the server's settings: by default 90 days for a
+  person, 7 for an agent, 30 for a service, 24 hours with a chain claim.
+
 ## What's new for CortexDB 0.14.0 (cortexdb-cli 0.7.0)
 
 CortexDB 0.14.0 is the breaking release of shared memory. What changes for a
@@ -112,9 +157,9 @@ CLI user:
   compartment gets the server's default (granular there) instead of 422
   `VIEW_NOT_ALLOWED_AT_SCOPE`.
 - **Tokens.** A token that carries `scopes` holds only the families its
-  entries name, lifetimes are capped (7 days for a person or an agent, 30 for
-  a service, 24 hours with chain claims), and `act` must name a delegable
-  agent. Every mint names its tenant root (`--scope`, `--tenant` or its
+  entries name, lifetimes are capped (the server's settings since 0.14.1: by
+  default 90 days for a person, 7 for an agent, 30 for a service, 24 hours
+  with chain claims), and `act` must name a delegable agent. Every mint names its tenant root (`--scope`, `--tenant` or its
   `--confine` entries); only the operator mints deployment-wide, for a
   service. A minted token holds no more than its minter. `cortexdb tokens
   mint` mints with every field: `--confine`, `--exact` (the `CAP:PATH!`
@@ -150,10 +195,14 @@ cortexdb search   "..."                       granular event-level search
 cortexdb answer   "..."                       recall + LLM answer
 cortexdb compose  "..."                       a markdown document from memory
 cortexdb forget   --memory-id | --idempotency-key | --capture-key ...
-cortexdb episodes {list,get,delete}
+cortexdb episodes {list,get,declare,delete}
 cortexdb entities {list,get,link}
 cortexdb facts    {list,timeline}
 cortexdb beliefs  {list,why,build,create}
+cortexdb derivation {status,decisions,policy,templates,taxonomy,stage,test,settings,feed,consumers,texts}
+cortexdb corrections {add,list,show,undo}
+cortexdb memory   {about}
+cortexdb review   {list,approve,reject}
 cortexdb conflicts {list,show,resolve}
 cortexdb claims   {history}
 cortexdb concepts {list,coverage,synthesize}
@@ -192,7 +241,10 @@ takes a tenant root uses the first segment of it.
 (your application's admitted mounts), `--consistency`, `--at-least TOKEN` and
 `--purpose ID` (the purpose the read is for: a grant whose `when` names a
 purpose holds only for that one; `access check`, `access explain` and
-`access authzen evaluate` decide a chain for one too). A write returns a consistency token with `--consistency`; a read that passes it
+`access authzen evaluate` decide a chain for one too) and `--session ID` (the
+conversation session the read is made in, CortexDB 0.15.0: where a read-time
+use rule is in force, memory from other sessions, or older than its window, is
+withheld, and `warnings` says how many events). A write returns a consistency token with `--consistency`; a read that passes it
 to `--at-least` sees that write:
 
 ```bash
@@ -203,6 +255,175 @@ cortexdb recall "ship" --at-least "$TOKEN"
 `experience write` also takes `--provenance EVENT_ID` (erasing the source
 erases the write), `--intent` and `--idempotency-key`.
 
+### derivation: what CortexDB learned, and how (CortexDB 0.15.0)
+
+```bash
+cortexdb derivation status org:acme/user:alice                 # layers and extraction caught up?
+cortexdb derivation decisions org:acme/user:alice evt_0196...  # what became of one event
+cortexdb facts list --include derivation                       # how each fact was made
+cortexdb facts timeline --subject Alice --predicate lives_in --include derivation
+cortexdb beliefs list --include derivation
+cortexdb beliefs why belief_01... --include derivation
+```
+
+On a server that serves `derivation_provenance_v1`, `derivation status`
+adds the extraction line to the layer builds: how many of the scope's
+events the background enrichment has not derived yet, learned from, derived
+with nothing admitted, held for review or failed on, with its own caught-up.
+`derivation decisions` says what became of one event: learned, nothing
+admitted, held, pending, skipped (and why: enrichment off, a reference
+root, a `directives.extract` naming no model stage, a typed triple, no
+text) or failed (retrying or not), with the models, the prompt version and
+the policy; a rejected candidate is counted by its rule id, never shown.
+`--include derivation` adds each fact's or belief's derivation (verdict,
+models, prompt version, gate, policy; `no stamp` for a row made before
+0.15.0) as a column. An older server has no extraction line, answers
+`derivation decisions` with a 404 (the hint says so) and ignores
+`--include`.
+
+### derivation policies, settings, texts and the feed (CortexDB 0.15.0)
+
+```bash
+cortexdb derivation policy org:acme/app:companion/user:bob     # what derives here, under which rules
+cortexdb derivation templates                                  # consumer, minimal, enterprise, ...
+cortexdb derivation templates consumer > policy.json           # one template's body, to edit
+cortexdb derivation test org:acme/app:companion --file policy.json --recent 20   # try it first, writes nothing
+cortexdb derivation stage org:acme/app:companion --file policy.json   # stage, preview, activate
+cortexdb derivation stage org:acme/app:companion --template consumer
+cortexdb derivation settings org:acme/app:companion/user:bob --deny-predicate diet
+cortexdb derivation settings org:acme/app:companion/user:bob --consent "health:health coaching"
+cortexdb derivation texts org:acme --all                       # the policy texts, without their content
+cortexdb derivation feed org:acme/app:tutor --consumer acme-level --cursor-file level.cursor --follow
+cortexdb experience write --triple Alice level advanced --derived-by acme-level@1.1.0
+```
+
+A derivation policy is a registry record of kind `derive` at
+`<scope>/attrs:derive`: `derivation stage` stages it at the scope's root,
+prints the preview's derivation section (the record's hash before and after,
+the effective policy's before and after with the rules that move, the texts it
+names) and activates it with the preview's hash after asking (`--yes` skips
+the question). `derivation test` tries a draft first (the same `--file`, or
+`--changeset ID` for one you staged): extraction and the gate over the newest
+events (`--recent N`, 50 by default) or named ones (`--events FILE`), each
+candidate's verdict and rule beside the policy in force, the diff and the
+cost. It writes nothing, but its model calls are real: `--max-cost` (1 US
+dollar by default) caps them, and a larger estimate is refused before any
+call. `changes stage --file` also takes a `{"scope": SCOPE, "derive":
+{...}}` entry. `derivation policy` says whether anything derives at a scope and
+why not (the server's ceiling, which no policy widens), the mode, each
+restriction and where it was set, and the steering in force. `derivation
+settings` changes one scope's own restrictions and consents with no change set:
+it reads the record, changes what its flags name and writes the whole record
+back. `derivation feed` prints a scope's events and the erasures that touch
+them, one JSON object a line, for a worker outside CortexDB; `--cursor-file`
+resumes where the last run's printed items end. A write-back is a typed triple
+stamped `--derived-by NAME@VERSION` (`beliefs create` takes the stamp too).
+`stage`, `settings` and `texts` need a shard armed for apply format 11; the
+hint of a 503 `FORMAT_UPGRADE_PENDING` says what holds it. A server before
+CortexDB 0.15.0 answers `policy`, `templates`, `taxonomy`, `test`,
+`settings`, `texts` and `feed` with a 404, which reads like a missing record:
+the hint says the server predates the command's capability, and
+`GET /v1/admin/version` lists the capabilities a server serves.
+
+### corrections and memory about (CortexDB 0.15.0)
+
+```bash
+cortexdb memory about org:acme/app:companion/user:bob          # what is known, with sources and fact ids
+cortexdb corrections add org:acme/app:companion/user:bob --reject fact_0196... --reason "I never lived in Boston"
+cortexdb corrections add org:acme/app:companion/user:bob --replace fact_0196... --value Denver --valid-from 2026-03-01
+cortexdb corrections add org:acme/app:companion/user:bob --pin fact_0196...
+cortexdb corrections list org:acme/app:companion/user:bob
+cortexdb corrections undo org:acme/app:companion/user:bob cor_0196...
+```
+
+To fix a wrong memory, correct it rather than forget it: a forget of what was
+derived can be learned again from the events, a correction is not. A
+correction names the fact's claim, and changes every live fact of it in the
+scope and below: a reject deletes them and keeps the claim from being learned
+again (`--bind subject_predicate` or `subject` widen it to every value, or
+everything about the subject, for good), a replace writes the new value as
+your own fact and closes the old ones, a pin keeps any extracted value from
+superseding it, a confirm raises its authority. A reject and an undo ask first
+on a terminal, saying what they delete or bring back (`--yes` from a script).
+The same `corrections add` sent again replays its first attempt: its default
+idempotency key is a hash of the request. `memory about` lists every fact and
+belief about the scope's subject with the memories it came from, which is also
+the subject's export; `--corrections` adds the scope's corrections. A server
+before CortexDB 0.15.0 answers `corrections` and `memory about` with a 404,
+which reads like a missing fact or correction: the hint says the server
+predates `corrections_v1`.
+
+### review: what a derivation policy held back (CortexDB 0.15.0)
+
+```bash
+cortexdb review list org:acme/clinic:north                     # oldest first: what each states, why it was held
+cortexdb review list org:acme/clinic:north --topic health --descend --all --json
+cortexdb review approve org:acme/clinic:north hld_0196... --reason "confirmed with patient"
+cortexdb review reject org:acme/clinic:north hld_0196... --bind subject_predicate --yes
+```
+
+A derivation policy's review rules (a topic or predicate held for review, the
+`review` mode, a refused writer, a low confidence) hold a candidate memory
+CortexDB extracted before it is stored: a held candidate is in no store,
+recall or answer until a reviewer decides it. `review list` prints the open
+candidates held at a scope, oldest first: what each states, its topic, the
+rule that held it, when it was held and when it lapses, and the text around
+its quote while its memory is there to quote. `--topic`, `--rule` and `--descend`
+(the scopes under it you may read, with `scope.read.descend`) filter it;
+`--limit`, `--cursor` and `--all` page it. `review approve` makes each held
+candidate a fact of its memory and prints the fact's id. `review reject`
+erases each and keeps its claim suppressed by a correction of origin `review`
+(`cortexdb corrections list SCOPE --origin review`, which `corrections undo`
+reverses): this claim, from its memory and every memory captured before the
+decision (`--bind claim`, the default), or every value of its subject and
+predicate, past and future (`--bind subject_predicate`). A reject asks first on
+a terminal (`--yes` from a script). Each decision is its own: one that is
+refused (decided before, its memory erased meanwhile) leaves the others made,
+and the command exits 1 after printing every result; more than 100 go in
+requests of 100. A candidate nobody decides lapses after the policy's
+`review.lapse_days` (30 by default). A Writer of the scope, or a reviewer the
+policy names, decides; the routes need a shard armed for apply format 11. A
+server before CortexDB 0.15.0 answers `review` with a 404, which reads like a
+missing scope or candidate: the hint says the server predates
+`derivation_review_v1`.
+
+### outside workers: declared episodes and the feed's consumers (CortexDB 0.15.0)
+
+```bash
+cortexdb episodes declare org:acme/team:support --file outage-call.json --derived-by acme-sessionizer@2.1.0
+cortexdb episodes list --scope org:acme/team:support           # the declared ones are marked
+cortexdb episodes delete org:acme/team:support ep_0196...       # a declared episode
+cortexdb episodes delete evt_0196... --reason "posted by mistake"   # one event: the forget it always was
+cortexdb derivation consumers org:acme/app:tutor               # who reads the feed here
+```
+
+A worker outside CortexDB that groups events into an episode (a call, a
+session, a case) declares it: `outage-call.json` holds `events` (1 to 1,024
+`evt_` ids) and, as it needs them, `name`, `summary`, `started_at`,
+`ended_at`, `actors_involved`, `derived_by` and `idempotency_key`; the CLI
+checks its shape as the server does before sending. The episode is served
+beside the built ones with `declared: true` and is erased with any event it
+names. The same declaration sent again answers its first episode: the default
+idempotency key is a hash of the request. Only a declared episode can be
+deleted (a built one answers 404). `derivation consumers` lists the workers
+whose reads of `derivation feed` reach a scope, which an erasure's receipt
+names: their principal, what they read, the last event delivered, when they
+last read, whether they are idle and when their mark is purged. Declaring and
+deleting need a shard armed for apply format 11; below it `derivation
+consumers` says no consumer is recorded. A server before CortexDB 0.15.0 has
+none of these routes: `episodes declare` answers 405 there (the server lists
+episodes at that path), and `episodes delete` of a declared episode and
+`derivation consumers` answer 404; the hint says the server predates the
+capability.
+
+Writes say which of their directives nothing reads: `consolidate_into`,
+`confidence_floor`, `ttl_for_belief_layer`, `embed` and `async` are
+accepted and validated, but nothing reads them, and `experience`, each item
+of `experience bulk` and `import --server` print "accepted, not enforced:
+NAME" for each one they named. `changes stage`, `parts` and `preview` print "kept enrich: on at
+PATH" for a companion put that keeps the stored `enrich` (a put that does
+not name `enrich` keeps it; only `"enrich": "inherit"` clears it).
+
 ### access
 
 ```bash
@@ -241,6 +462,9 @@ cortexdb changes discard org-compile
 `--file` holds a list of records (each a put), operations
 (`{"path", "op": "put" | "delete", "record"}`), `{"records": [...]}` or
 `{"parts": [...]}`; `--delete PATH` adds deletes; `changes parts` stages more.
+A staging, a preview or an activation whose evaluation runs long answers 202
+(0.14.1): the command sends it again until it answers, for `--wait` seconds
+(120 by default), then exits 75 saying how to collect the answer.
 
 ### watch and notices
 

{cortexdb_cli-0.7.0 → cortexdb_cli-0.8.0}/README.md

@@ -4,9 +4,11 @@ Command-line interface for [CortexDB](https://cortexdb.ai) — the long-term mem
 
 Wraps the v1 HTTP API in a small, fast Click + Rich CLI. Anonymous signup
 in one command, no email or card; works against the public SaaS or any
-self-hosted CortexDB deployment. Version 0.7.0 covers CortexDB 0.14.0,
-shared memory included: the access API, change sets, the directory,
-applications, rollups, publishing and the new erasures.
+self-hosted CortexDB deployment. Version 0.8.0 covers CortexDB 0.15.0,
+governed memory formation included: derivation policies, corrections, review
+and re-derivation; and CortexDB 0.14.x, shared memory included: the access
+API, change sets, the directory, applications, rollups, publishing and the
+new erasures.
 
 ## Install
 
@@ -49,6 +51,49 @@ When a token expires you have two safe options:
 For a second brain alongside the first, isolate instead of replacing:
 `cortexdb --config-dir <dir> init`, or set `CORTEXDB_HOME`.
 
+## What's new for CortexDB 0.15.0 (cortexdb-cli 0.8.0)
+
+CortexDB 0.15.0 adds governed memory formation: control over what its
+background enrichment learns, and corrections that stay corrected. Each
+command below needs a server that serves its capability: a server before
+0.15.0 answers it 404, which reads like a missing record, and the hint says
+the server predates the command.
+
+- **`cortexdb derivation`**: `status` and `decisions` (what was learned from
+  an event, and why not), `policy`, `templates`, `taxonomy`, `test` (a draft
+  tried on real events, writing nothing), `stage` (stage, preview and
+  activate a policy), `settings`, `texts`, `feed` and `consumers`, and the
+  re-derivation jobs: `rederive` (a dry run unless `--apply`, of the unsynced
+  rows unless `--events`), `job`, `cancel` and `report`.
+- **`cortexdb corrections`** (`add`, `list`, `show`, `undo`) and **`cortexdb
+  memory about`** (`--corrections`): fix a wrong memory so it stays fixed,
+  rather than forget it.
+- **`cortexdb review`** (`list`, `approve`, `reject`): decide what a
+  derivation policy held back.
+- **`cortexdb episodes declare`** and **`episodes delete`**: a worker's own
+  episodes.
+- **New options**: `--derived-by NAME@VERSION` on `experience write`, `beliefs
+  create` and `episodes declare`; `--include derivation` on `facts list`,
+  `facts timeline`, `beliefs list` and `beliefs why`; `--session ID` on
+  `recall`, `search`, `answer` and `compose`.
+- **Warnings**: a write that names a directive nothing reads prints
+  "accepted, not enforced: NAME", and a change set that keeps a scope's
+  `enrich` says so.
+
+## What's new for CortexDB 0.14.1 (cortexdb-cli 0.7.1)
+
+- **Change sets that take long.** A staging, a preview or an activation whose
+  evaluation runs past the server's wait answers 202 and goes on. `changes
+  stage`, `parts`, `preview` and `activate` send the request again until it
+  answers, with a progress line, for `--wait` seconds (120 by default); past
+  it they exit 75 and say how to collect the answer. A 202 is never an error.
+- **The tenant-binding dry run** shows how the operator plane will decide the
+  real run, and says when `--apply` needs `--break-glass`.
+- **A write that would make a version-2 record version 1** is refused; the
+  hint names the fields it drops and `--convert`.
+- **Token lifetimes** are the server's settings: by default 90 days for a
+  person, 7 for an agent, 30 for a service, 24 hours with a chain claim.
+
 ## What's new for CortexDB 0.14.0 (cortexdb-cli 0.7.0)
 
 CortexDB 0.14.0 is the breaking release of shared memory. What changes for a
@@ -80,9 +125,9 @@ CLI user:
   compartment gets the server's default (granular there) instead of 422
   `VIEW_NOT_ALLOWED_AT_SCOPE`.
 - **Tokens.** A token that carries `scopes` holds only the families its
-  entries name, lifetimes are capped (7 days for a person or an agent, 30 for
-  a service, 24 hours with chain claims), and `act` must name a delegable
-  agent. Every mint names its tenant root (`--scope`, `--tenant` or its
+  entries name, lifetimes are capped (the server's settings since 0.14.1: by
+  default 90 days for a person, 7 for an agent, 30 for a service, 24 hours
+  with chain claims), and `act` must name a delegable agent. Every mint names its tenant root (`--scope`, `--tenant` or its
   `--confine` entries); only the operator mints deployment-wide, for a
   service. A minted token holds no more than its minter. `cortexdb tokens
   mint` mints with every field: `--confine`, `--exact` (the `CAP:PATH!`
@@ -118,10 +163,14 @@ cortexdb search   "..."                       granular event-level search
 cortexdb answer   "..."                       recall + LLM answer
 cortexdb compose  "..."                       a markdown document from memory
 cortexdb forget   --memory-id | --idempotency-key | --capture-key ...
-cortexdb episodes {list,get,delete}
+cortexdb episodes {list,get,declare,delete}
 cortexdb entities {list,get,link}
 cortexdb facts    {list,timeline}
 cortexdb beliefs  {list,why,build,create}
+cortexdb derivation {status,decisions,policy,templates,taxonomy,stage,test,settings,feed,consumers,texts}
+cortexdb corrections {add,list,show,undo}
+cortexdb memory   {about}
+cortexdb review   {list,approve,reject}
 cortexdb conflicts {list,show,resolve}
 cortexdb claims   {history}
 cortexdb concepts {list,coverage,synthesize}
@@ -160,7 +209,10 @@ takes a tenant root uses the first segment of it.
 (your application's admitted mounts), `--consistency`, `--at-least TOKEN` and
 `--purpose ID` (the purpose the read is for: a grant whose `when` names a
 purpose holds only for that one; `access check`, `access explain` and
-`access authzen evaluate` decide a chain for one too). A write returns a consistency token with `--consistency`; a read that passes it
+`access authzen evaluate` decide a chain for one too) and `--session ID` (the
+conversation session the read is made in, CortexDB 0.15.0: where a read-time
+use rule is in force, memory from other sessions, or older than its window, is
+withheld, and `warnings` says how many events). A write returns a consistency token with `--consistency`; a read that passes it
 to `--at-least` sees that write:
 
 ```bash
@@ -171,6 +223,175 @@ cortexdb recall "ship" --at-least "$TOKEN"
 `experience write` also takes `--provenance EVENT_ID` (erasing the source
 erases the write), `--intent` and `--idempotency-key`.
 
+### derivation: what CortexDB learned, and how (CortexDB 0.15.0)
+
+```bash
+cortexdb derivation status org:acme/user:alice                 # layers and extraction caught up?
+cortexdb derivation decisions org:acme/user:alice evt_0196...  # what became of one event
+cortexdb facts list --include derivation                       # how each fact was made
+cortexdb facts timeline --subject Alice --predicate lives_in --include derivation
+cortexdb beliefs list --include derivation
+cortexdb beliefs why belief_01... --include derivation
+```
+
+On a server that serves `derivation_provenance_v1`, `derivation status`
+adds the extraction line to the layer builds: how many of the scope's
+events the background enrichment has not derived yet, learned from, derived
+with nothing admitted, held for review or failed on, with its own caught-up.
+`derivation decisions` says what became of one event: learned, nothing
+admitted, held, pending, skipped (and why: enrichment off, a reference
+root, a `directives.extract` naming no model stage, a typed triple, no
+text) or failed (retrying or not), with the models, the prompt version and
+the policy; a rejected candidate is counted by its rule id, never shown.
+`--include derivation` adds each fact's or belief's derivation (verdict,
+models, prompt version, gate, policy; `no stamp` for a row made before
+0.15.0) as a column. An older server has no extraction line, answers
+`derivation decisions` with a 404 (the hint says so) and ignores
+`--include`.
+
+### derivation policies, settings, texts and the feed (CortexDB 0.15.0)
+
+```bash
+cortexdb derivation policy org:acme/app:companion/user:bob     # what derives here, under which rules
+cortexdb derivation templates                                  # consumer, minimal, enterprise, ...
+cortexdb derivation templates consumer > policy.json           # one template's body, to edit
+cortexdb derivation test org:acme/app:companion --file policy.json --recent 20   # try it first, writes nothing
+cortexdb derivation stage org:acme/app:companion --file policy.json   # stage, preview, activate
+cortexdb derivation stage org:acme/app:companion --template consumer
+cortexdb derivation settings org:acme/app:companion/user:bob --deny-predicate diet
+cortexdb derivation settings org:acme/app:companion/user:bob --consent "health:health coaching"
+cortexdb derivation texts org:acme --all                       # the policy texts, without their content
+cortexdb derivation feed org:acme/app:tutor --consumer acme-level --cursor-file level.cursor --follow
+cortexdb experience write --triple Alice level advanced --derived-by acme-level@1.1.0
+```
+
+A derivation policy is a registry record of kind `derive` at
+`<scope>/attrs:derive`: `derivation stage` stages it at the scope's root,
+prints the preview's derivation section (the record's hash before and after,
+the effective policy's before and after with the rules that move, the texts it
+names) and activates it with the preview's hash after asking (`--yes` skips
+the question). `derivation test` tries a draft first (the same `--file`, or
+`--changeset ID` for one you staged): extraction and the gate over the newest
+events (`--recent N`, 50 by default) or named ones (`--events FILE`), each
+candidate's verdict and rule beside the policy in force, the diff and the
+cost. It writes nothing, but its model calls are real: `--max-cost` (1 US
+dollar by default) caps them, and a larger estimate is refused before any
+call. `changes stage --file` also takes a `{"scope": SCOPE, "derive":
+{...}}` entry. `derivation policy` says whether anything derives at a scope and
+why not (the server's ceiling, which no policy widens), the mode, each
+restriction and where it was set, and the steering in force. `derivation
+settings` changes one scope's own restrictions and consents with no change set:
+it reads the record, changes what its flags name and writes the whole record
+back. `derivation feed` prints a scope's events and the erasures that touch
+them, one JSON object a line, for a worker outside CortexDB; `--cursor-file`
+resumes where the last run's printed items end. A write-back is a typed triple
+stamped `--derived-by NAME@VERSION` (`beliefs create` takes the stamp too).
+`stage`, `settings` and `texts` need a shard armed for apply format 11; the
+hint of a 503 `FORMAT_UPGRADE_PENDING` says what holds it. A server before
+CortexDB 0.15.0 answers `policy`, `templates`, `taxonomy`, `test`,
+`settings`, `texts` and `feed` with a 404, which reads like a missing record:
+the hint says the server predates the command's capability, and
+`GET /v1/admin/version` lists the capabilities a server serves.
+
+### corrections and memory about (CortexDB 0.15.0)
+
+```bash
+cortexdb memory about org:acme/app:companion/user:bob          # what is known, with sources and fact ids
+cortexdb corrections add org:acme/app:companion/user:bob --reject fact_0196... --reason "I never lived in Boston"
+cortexdb corrections add org:acme/app:companion/user:bob --replace fact_0196... --value Denver --valid-from 2026-03-01
+cortexdb corrections add org:acme/app:companion/user:bob --pin fact_0196...
+cortexdb corrections list org:acme/app:companion/user:bob
+cortexdb corrections undo org:acme/app:companion/user:bob cor_0196...
+```
+
+To fix a wrong memory, correct it rather than forget it: a forget of what was
+derived can be learned again from the events, a correction is not. A
+correction names the fact's claim, and changes every live fact of it in the
+scope and below: a reject deletes them and keeps the claim from being learned
+again (`--bind subject_predicate` or `subject` widen it to every value, or
+everything about the subject, for good), a replace writes the new value as
+your own fact and closes the old ones, a pin keeps any extracted value from
+superseding it, a confirm raises its authority. A reject and an undo ask first
+on a terminal, saying what they delete or bring back (`--yes` from a script).
+The same `corrections add` sent again replays its first attempt: its default
+idempotency key is a hash of the request. `memory about` lists every fact and
+belief about the scope's subject with the memories it came from, which is also
+the subject's export; `--corrections` adds the scope's corrections. A server
+before CortexDB 0.15.0 answers `corrections` and `memory about` with a 404,
+which reads like a missing fact or correction: the hint says the server
+predates `corrections_v1`.
+
+### review: what a derivation policy held back (CortexDB 0.15.0)
+
+```bash
+cortexdb review list org:acme/clinic:north                     # oldest first: what each states, why it was held
+cortexdb review list org:acme/clinic:north --topic health --descend --all --json
+cortexdb review approve org:acme/clinic:north hld_0196... --reason "confirmed with patient"
+cortexdb review reject org:acme/clinic:north hld_0196... --bind subject_predicate --yes
+```
+
+A derivation policy's review rules (a topic or predicate held for review, the
+`review` mode, a refused writer, a low confidence) hold a candidate memory
+CortexDB extracted before it is stored: a held candidate is in no store,
+recall or answer until a reviewer decides it. `review list` prints the open
+candidates held at a scope, oldest first: what each states, its topic, the
+rule that held it, when it was held and when it lapses, and the text around
+its quote while its memory is there to quote. `--topic`, `--rule` and `--descend`
+(the scopes under it you may read, with `scope.read.descend`) filter it;
+`--limit`, `--cursor` and `--all` page it. `review approve` makes each held
+candidate a fact of its memory and prints the fact's id. `review reject`
+erases each and keeps its claim suppressed by a correction of origin `review`
+(`cortexdb corrections list SCOPE --origin review`, which `corrections undo`
+reverses): this claim, from its memory and every memory captured before the
+decision (`--bind claim`, the default), or every value of its subject and
+predicate, past and future (`--bind subject_predicate`). A reject asks first on
+a terminal (`--yes` from a script). Each decision is its own: one that is
+refused (decided before, its memory erased meanwhile) leaves the others made,
+and the command exits 1 after printing every result; more than 100 go in
+requests of 100. A candidate nobody decides lapses after the policy's
+`review.lapse_days` (30 by default). A Writer of the scope, or a reviewer the
+policy names, decides; the routes need a shard armed for apply format 11. A
+server before CortexDB 0.15.0 answers `review` with a 404, which reads like a
+missing scope or candidate: the hint says the server predates
+`derivation_review_v1`.
+
+### outside workers: declared episodes and the feed's consumers (CortexDB 0.15.0)
+
+```bash
+cortexdb episodes declare org:acme/team:support --file outage-call.json --derived-by acme-sessionizer@2.1.0
+cortexdb episodes list --scope org:acme/team:support           # the declared ones are marked
+cortexdb episodes delete org:acme/team:support ep_0196...       # a declared episode
+cortexdb episodes delete evt_0196... --reason "posted by mistake"   # one event: the forget it always was
+cortexdb derivation consumers org:acme/app:tutor               # who reads the feed here
+```
+
+A worker outside CortexDB that groups events into an episode (a call, a
+session, a case) declares it: `outage-call.json` holds `events` (1 to 1,024
+`evt_` ids) and, as it needs them, `name`, `summary`, `started_at`,
+`ended_at`, `actors_involved`, `derived_by` and `idempotency_key`; the CLI
+checks its shape as the server does before sending. The episode is served
+beside the built ones with `declared: true` and is erased with any event it
+names. The same declaration sent again answers its first episode: the default
+idempotency key is a hash of the request. Only a declared episode can be
+deleted (a built one answers 404). `derivation consumers` lists the workers
+whose reads of `derivation feed` reach a scope, which an erasure's receipt
+names: their principal, what they read, the last event delivered, when they
+last read, whether they are idle and when their mark is purged. Declaring and
+deleting need a shard armed for apply format 11; below it `derivation
+consumers` says no consumer is recorded. A server before CortexDB 0.15.0 has
+none of these routes: `episodes declare` answers 405 there (the server lists
+episodes at that path), and `episodes delete` of a declared episode and
+`derivation consumers` answer 404; the hint says the server predates the
+capability.
+
+Writes say which of their directives nothing reads: `consolidate_into`,
+`confidence_floor`, `ttl_for_belief_layer`, `embed` and `async` are
+accepted and validated, but nothing reads them, and `experience`, each item
+of `experience bulk` and `import --server` print "accepted, not enforced:
+NAME" for each one they named. `changes stage`, `parts` and `preview` print "kept enrich: on at
+PATH" for a companion put that keeps the stored `enrich` (a put that does
+not name `enrich` keeps it; only `"enrich": "inherit"` clears it).
+
 ### access
 
 ```bash
@@ -209,6 +430,9 @@ cortexdb changes discard org-compile
 `--file` holds a list of records (each a put), operations
 (`{"path", "op": "put" | "delete", "record"}`), `{"records": [...]}` or
 `{"parts": [...]}`; `--delete PATH` adds deletes; `changes parts` stages more.
+A staging, a preview or an activation whose evaluation runs long answers 202
+(0.14.1): the command sends it again until it answers, for `--wait` seconds
+(120 by default), then exits 75 saying how to collect the answer.
 
 ### watch and notices
 

{cortexdb_cli-0.7.0 → cortexdb_cli-0.8.0}/cortexdb_cli/__init__.py

@@ -1,3 +1,3 @@
 """CortexDB CLI - command-line interface for the v1 memory API."""
 
-__version__ = "0.7.0"
+__version__ = "0.8.0"

{cortexdb_cli-0.7.0 → cortexdb_cli-0.8.0}/cortexdb_cli/commands/admin.py

@@ -95,7 +95,7 @@ def admin_layers(ctx: click.Context) -> None:
 
 # -- retention (unified WAL) -------------------------------------------------
 #
-# The operator surface over the D1 retention plane. Every write here is
+# The operator surface over the retention plane. Every write here is
 # irreversible in effect - an applied sweep removes expired captured events,
 # everything about them under an `erase` rule, their raw data under a
 # `keep_learned` one - so reporting is the default on both mutating commands

{cortexdb_cli-0.7.0 → cortexdb_cli-0.8.0}/cortexdb_cli/commands/admin_access.py

@@ -151,7 +151,11 @@ def tenant_settings(ctx, root, mode, readiness_ticket, clear_readiness):
 def tenant_binding(ctx, root, from_tenant, apply_):
     """Bind a root's records and tombstones to the tenant it names (POST /v1/admin/access/tenant-binding).
 
-    A DRY RUN unless --apply; running it again is safe.
+    A DRY RUN unless --apply; running it again is safe. The dry run says how
+    the operator plane decides the real run (operator_plane: whether it
+    registers the root, is in-band, the tenant's mode): when it says
+    break_glass_required, pass --break-glass REASON --break-glass-ticket
+    TICKET with --apply.
     """
     cfg = ctx.obj
     scope = root_or_die(cfg, root)
@@ -169,6 +173,15 @@ def tenant_binding(ctx, root, from_tenant, apply_):
                       + (", root registered" if d.get("root_registered") else ""))
         if d.get("consistency_token"):
             console.print(f"[dim]  consistency token: {escape(str(d['consistency_token']))}[/dim]")
+        plane = d.get("operator_plane")
+        if isinstance(plane, dict):
+            # 0.14.1 (p6a C): how the operator plane decides the run.
+            console.print(f"  operator plane: mode {escape(str(plane.get('mode')))}"
+                          + (", the run registers the root" if plane.get("registers_root") else "")
+                          + (", an in-band path for the operator key" if plane.get("in_band") else ""))
+            if plane.get("break_glass_required"):
+                console.print("[warning]  The real run needs break-glass: add --break-glass REASON "
+                              "--break-glass-ticket TICKET to --apply (else 403 BREAK_GLASS_REQUIRED).[/warning]")
         if d.get("dry_run"):
             console.print("[dim]Nothing was changed. Run again with --apply.[/dim]")