cortexdb-mcp 0.9.0__tar.gz → 0.10.0__tar.gz

{cortexdb_mcp-0.9.0 → cortexdb_mcp-0.10.0}/COVERAGE.md

@@ -7,7 +7,7 @@ the server code (the `sharedcontext` branch with lanes p5g, p5h and p5j merged),
 `docs/shared_memory/PHASE{0..5}_RELEASE_NOTES_DRAFT.md`.
 
 The server's own HTTP MCP endpoint (`POST /mcp`, `crates/cortex-api/src/v1/mcp.rs`, `CORTEX_MCP=on`) is a separate
-surface with its own five tools. The stdio server keeps today's tools, output shapes and default profile (design
+surface with tools of its own. The stdio server keeps today's tools, output shapes and default profile (design
 §13.8, §14.3); the tools it adds follow `/mcp`'s rule, read by default and writes opt-in.
 
 ## What 0.14.0 breaks, and what it did to the tools
@@ -122,6 +122,7 @@ What changed on the server after 0.9.0 was first built (`sharedcontext` 8b8bfb6d
 | `GET /v1/events` pages with a newest-first cursor (`le1.`) bound to its query; any other cursor is 422 `INVALID_CURSOR` | `memory_list` | `cursor` replaces `offset`; each page ends with `More: cursor=<next>`; `episode_type` is the server's `labels` filter, so the cursor pages the filtered listing |
 | Codes: 400 `INVALID_HEADER` for any header that does not parse, the break-glass header's included (`details {part, field, reason}`); 410 `ROLLUP_SUPERSEDED` (`details.current`); 422 `act_not_delegable` (and the token's 401 `INVALID_TOKEN_CLAIM`); 422 `field_not_applied`; 504 `DB_TIMEOUT`; 500 `INTERNAL_ERROR` (was `INTERNAL`); 500 `SCOPE_STORAGE_MISCONFIGURED`; 503 `WAL_OUTCOME_UNKNOWN` (was `SCOPE_MUTATION_UNKNOWN`); 405 `METHOD_NOT_ALLOWED`; every envelope's `request_id` | every tool | each says what to do: the setting behind the header, the current rollup to read or publish, the employee's own chain, the fields to drop, to narrow a timed-out call; `memory_store`'s retriable refusal names the idempotency key to retry with, so a write whose outcome is unknown is replayed, not stored twice. `IDEMPOTENCY_CONFLICT` and `CLUSTER_ROUTE_UNSUPPORTED` are mapped too. `cortexdb_check_call` flags a `field_not_applied` forget. The client keeps no table of statuses or retriable flags: it reads each envelope's |
 | `read_purpose_v1`: a read declares `purpose` (`[a-z0-9_-]{1,64}`) on `/v1/recall`, `/recall/stream`, `/answer`, `/compose` and `POST /v1/access/check`/`explain`; a roster path whose `when` names it holds only then, and every decision line records it | `memory_search`, `get_context`, `advanced_search`, `access_check`, `access_explain` | `purpose` on each, default `CORTEXDB_PURPOSE`; checked against the grammar before anything is sent (the setting's error names it); a call naming none sends the request it sent before. The layer GETs (`memory_list`, `memory_get`, the entity tools) take no purpose on the server, so none is sent there. `cortexdb_check_call` checks the grammar |
+| `derivation_use_rules_v1` (CortexDB 0.15.0): a read names its `session` on `/v1/recall`, `/recall/stream`, `/answer` and `/compose`; where a read-time use rule is in force, memory from other sessions or older than its window is withheld and `warnings` says `use_rule_withheld: <n> events from earlier sessions` | `memory_search`, `get_context`, `advanced_search` | `session` on each, per call (no setting: one server serves many conversations); checked before anything is sent (1 to 256 bytes with no control character); a call naming none sends the request it sent before. The layer GETs take none on the server. `cortexdb_check_call` checks the grammar |
 | Forget and its preview gain `events_under_legal_hold` and `derived_under_legal_hold` (facts, beliefs, episodes, understanding): what a legal hold keeps, counted in no deleted field | `memory_forget`, `memory_delete`, `memory_bulk_delete` (and its dry run), `forget_preview`, `forget_by_key` (and its preview) | each answer says what the hold kept ("Kept under a legal hold", a preview's "Would keep"): the events, erased when the hold is released, and the derived records by layer; nothing when it kept nothing |
 | The by-id reads take `?scope=` (a row elsewhere answers 404), and a cluster routes every by-id route by it, refusing one without (501 `CLUSTER_ROUTE_UNSUPPORTED`); `include_vectors=true` returns the embeddings | `memory_get`, `memory_status`, `resolve_conflict` | `memory_get` sent it already; `memory_status` (the exact scope the write went to) and `resolve_conflict` (the scope the conflict was listed at) take `tenant_id` and send it as `?scope=`, only when given, so a single node's call is unchanged. `rollups` by id and `directory_lookup` by id send their home and root already. No tool has a by-id fact, belief, concept or lifecycle read. `include_vectors` is not sent: an embedding is no text an agent reads, and it would fill the tool's answer |
 | `POST /v1/beliefs` takes `idempotency_key` (at most 256 bytes): the same key at the same scope answers the first declaration's belief, another declaration under it is 409 `IDEMPOTENCY_CONFLICT` | `belief_declare` | takes `idempotency_key`, and sends a fresh one when none is given (as `memory_store` does), so a retriable refusal names the key to retry with and a declaration whose outcome is unknown is never made twice; a server before 0.14.0 ignores the field |
@@ -131,6 +132,77 @@ What changed on the server after 0.9.0 was first built (`sharedcontext` 8b8bfb6d
 | p5w: under `deny` the operator key's change-set activation is in-band: 403 `BREAK_GLASS_REQUIRED` (`details.class: "in_band"`) without the header, 503 `NOTICE_UNAVAILABLE`, 503 `REGISTRY_STALE`; the preview gains `in_band` and `in_band_parts` | none previews or activates a change set; the operator key's tools meet `in_band` on a write into a private region or a shared scope | the `BREAK_GLASS_REQUIRED` hint says what the class refused (in-band work, or data reads); `REGISTRY_STALE` is retriable and read as the envelope says |
 | Codes no tool can meet | none | `ERASURE_NOT_CANCELLABLE`, `COHORT_UNSUPPORTED`, `SCIM_UNSUPPORTED`, `TENANT_SETTINGS_UNAVAILABLE`, the mint's `scopes_exceed_minter`, `caps_exceed_minter` and `deployment_mint_requires_operator`, `BLOB_STORE_ERROR`, and p5o's admin codes (`PERSIST_FAILED`, `ICE_FORK_UNSUPPORTED`, the repairs' `UNSUPPORTED_MEDIA_TYPE`, `CROSS_SHARD_REQUEST`): no tool cancels an erasure, asks a cohort, speaks SCIM, mints or calls an admin route; any of them still renders as a typed error |
 
+## CortexDB 0.15.0: how memories were made (`derivation_provenance_v1`)
+
+What N10's step 0 added to the server (`next`; `docs/GOVERNED_MEMORY_FORMATION.md` §18.11, §18.12, §18.16, §20.5),
+and what this server does with it. The tool ships in 0.10.0.
+§20.5's other tools wait for their routes, except `derivation_policy`, whose route has merged since (below).
+
+| Family | Covered | By, or why not |
+|---|---|---|
+| `include=derivation` on `GET /v1/facts/{id}` and `GET /v1/beliefs/why` | yes | `memory_why` for a fact or a belief id: the verdict, the models, the prompt and gate versions, the policy, and the rule, topic, `derived_by`, pinned, confirmed and unsynced when set |
+| `include=derivation` on `GET /v1/facts`, `/v1/facts/timeline`, `/v1/beliefs` | no | the listing tools (`entity_list`, `entity_get`, `entity_edges`, `get_insights`) render claims; `memory_why` reads one record's derivation by id, which is what an agent asks about |
+| `GET /v1/derivation/decisions` | yes | `memory_why` for a memory id (at `tenant_id`, else the configured scope), and for each of a fact's first five source memories (at the fact's own scope); a source whose decision fails is named and the answer goes on; a fact without `derivation` (an older server) asks for none |
+| The status route's `extraction` block (`GET /v1/derivation/status`) | no tool | a sync's or a connector's poll after a bulk load; `cortexdb_check_call` knows the route and says what the block reports |
+| `directive_not_enforced:<name>` in a write's ack and an import's job | nothing to do | `memory_store`, `entity_link` and `belief_declare` send no directive, so their acks carry none; a warning any ack carries is rendered (`Warning: ...`) |
+| `enrich_kept` in a change set's staging and preview | no | no tool stages or previews a change set |
+| The capability `derivation_provenance_v1` | yes | `memory_why` says so when a fact or belief carries no `derivation` (an older server ignores `include=`, and 404s the decisions route) |
+| The decisions route's refusals | yes | 404 `NOT_FOUND`, one answer for an absent event, one under another scope, a cancelled or a forgotten one, and for a server before 0.15.0: the hint names `tenant_id` and the version; 503 `FORMAT_UPGRADE_PENDING` (a shard below format 10) by `details.reason`; 400 `INVALID_QUERY` for a parameter besides `scope` and `event_id`, which `cortexdb_check_call` catches before the call |
+
+Its wording follows the server's own HTTP `/mcp`, whose `memory_why` answers the same reads: a `null` verdict is "no
+derivation stamp (written directly, or made before 0.15.0)", an outcome "learned (N accepted)", "derived, nothing
+admitted", "not derived yet", "held for review (N held)", "skipped: <reason>", "failed, a retry is queued" or
+"failed, dead-lettered", and what was rejected "rejected by rule: <rule> <count>", never its text.
+
+## CortexDB 0.15.0: governed memory formation (`derivation_policy_v1`, `derivation_feed_v1`, `derived_by_v1`)
+
+N10's policy routes as merged (`docs/GOVERNED_MEMORY_FORMATION.md` §7.2-§7.4, §13.1, §13.3, §18.1-§18.6, §18.15,
+§18.16, §18.19, §20.5). The stdio server adds the one read tool §20.5 names for them, `derivation_policy`, in every
+profile but `code`; the corrections and review tools (`memory_about`, `review_list`, `memory_correct`,
+`review_decide`, `correction_undo`) are in the two sections below.
+
+| Family | Covered | By, or why not |
+|---|---|---|
+| `GET /v1/derivation/policy` | yes | `derivation_policy(scope=None, include_texts=False)`: the hash (`dp1:none`: no policy), whether anything is learned at the scope and if not why (the ceiling: enrichment off, the enrichment allowlist, the scope's `enrich`, a reference root; or the mode `off`, or no stage), the mode and who set it, each restriction in words with who set it (the policy at a scope, through the org chart, or the subject settings) and the consents live now, the steering (texts by id and size, the model that runs when none is named), custom topics, predicates (cardinality, conflict, writers, requires), the values set without effect and why, the versions; below apply format 11 it says no policy can be activated yet. `include_texts` sends `include=texts` (an Owner with `derivation.administer.scope`) and adds each text in full. A 403 is the typed error; an older server's 404 says it predates the capability |
+| `GET /v1/derivation/templates`, `/taxonomy` | no | static catalogues for whoever writes a policy (`cortexdb derivation templates`, `taxonomy`, the console's editor), not a question an assistant answers for a user |
+| Derive records in change sets, their preview's `derivation` section | no | no tool stages, previews or activates a change set (an assistant does not rewrite an org's policy); `cortexdb derivation stage` does |
+| `PUT`, `GET`, `DELETE /v1/derivation/settings` | no | a person's own restrictions and consents are given or withdrawn deliberately, by the application or the person (`cortexdb derivation settings`); `derivation_policy` shows their effect (`settings.*` restrictions, the mode, the consents live) |
+| `GET /v1/derivation/texts`, `POST /v1/derivation/texts/erase` | no | an Owner's administration (`cortexdb derivation texts`); `derivation_policy` names the texts in force, and with `include_texts` shows them |
+| `GET /v1/derivation/feed` | no | a worker's long-running read with a cursor of its own, not an assistant's (`cortexdb derivation feed`, the SDK's worker) |
+| `derived_by` on typed triples and declared beliefs | no | `memory_store` writes a message and `belief_declare` a statement of the agent's own; neither is a write-back of a pipeline. `memory_why` shows a stamp a fact carries (`derived by: <name>@<version>`) |
+| Their refusals | hints | `DERIVATION_POLICY_INVALID` (by reason, with the field and record), `DERIVATION_POLICY_WIDENS` (the rule and the ancestor), `DERIVATION_MODEL_NOT_ALLOWED` (the allowed models), `DERIVATION_TEXT_INVALID`, `FEED_CURSOR_INVALID` and `DERIVED_BY_INVALID` (by reason), and the 404 of a derivation route on a server without it. Only `derivation_policy`'s 403 and 404 can reach a tool today; the rest render for a tool that later writes these routes |
+| `cortexdb_check_call` | yes | knows `GET /v1/derivation/policy` (`scope` required; `include` takes `texts` only) and says where a policy and a person's settings are written |
+
+## CortexDB 0.15.0: corrections (`corrections_v1`)
+
+N10 M3 (`docs/GOVERNED_MEMORY_FORMATION.md` §10, §18.7, §18.8, §18.17, §20.5): how a wrong memory is fixed. The tools
+§20.5 names for it; the review tools (`review_list`, `review_decide`) are in the next section.
+
+| Family | Covered | By, or why not |
+|---|---|---|
+| `GET /v1/memory/about` | yes | `memory_about(scope=None, include_corrections=False, limit=50, cursor=None)`, a read tool in every profile but `code`: the counts, each fact and belief with its id, validity, pin and first three sources (event, date, snippet), the corrections when asked for (said not to be served below format 11), the next cursor |
+| `POST /v1/corrections` | yes | `memory_correct(action, fact_id, value, valid_from, bind, reason, subject_principal, scope, idempotency_key)`, opt-in (`write`), destructive (a reject deletes facts): `target {fact_id}`; every rule of the body checked before sending; a fresh `mcp-` key unless given, which a retriable refusal names for the retry; the answer names the claim, the replacement, each effect, and the `correction_undo` call; a replay says nothing changed |
+| A correction's `target.claim` and a confirm's `valid` window | no | an agent names the fact `memory_about` or `memory_why` gave it; a claim stated as words and a conflict split's window are the console's and the SDK's |
+| `GET /v1/corrections`, `GET /v1/corrections/{id}` | no tool | `memory_about` with `include_corrections` lists a scope's corrections for an assistant; the full records and their snapshots are `cortexdb corrections list` and `show`'s; `cortexdb_check_call` knows the list route |
+| `DELETE /v1/corrections/{id}` | yes | `correction_undo(correction_id, scope=None)`, opt-in (`write`), destructive and idempotent: the facts restored, the pin removed, the replacement's memory erased |
+| A conflict's resolution as corrections (`correction_ids`, §18.20) | yes | `resolve_conflict` names the corrections a resolution was proposed as (format 11), which `memory_about` with `include_corrections` lists |
+| A wrong memory is a correction, not a forget | yes | `memory_correct`'s and `memory_forget`'s descriptions and the server instructions say so; `cortexdb_check_call` corrects `/v1/correct`, `/v1/correction`, `/v1/fix`, `/v1/memories/correct` and `/v1/facts/correct` to `POST /v1/corrections`, checks its body (its fields, exactly one target, `bind` with `reject`, `value` with `replace`, `valid` with `confirm`, the bounds), and the forget route's note points there |
+| Their refusals | hints | `CORRECTION_TARGET_UNKNOWN` (the claim, and that a replace of it is allowed), `CORRECTION_CONFLICT` (the open correction; undo it only if the user wants this one), `PROVENANCE_ERASED` on the corrections route, the 404 of a fact or a correction (who may undo), a server without the routes, `IDEMPOTENCY_CONFLICT` and `WAL_OUTCOME_UNKNOWN` as for every write |
+
+## CortexDB 0.15.0: review before commit (`derivation_review_v1`)
+
+N10 M6 (`docs/GOVERNED_MEMORY_FORMATION.md` §7.7, §11, §18.9, §18.10, §20.5): the candidates a derivation policy held
+for review before learning them, and their decisions.
+
+| Family | Covered | By, or why not |
+|---|---|---|
+| `GET /v1/review` | yes | `review_list(scope=None, topic=None, rule=None, descend=False, limit=50, cursor=None)`, a read tool in every profile but `code`: how many are open, each candidate's held id, what it states, its rule and topic, when it lapses, its source (event, date, snippet, or not here to quote), the next cursor |
+| `POST /v1/review/decisions` | yes | `review_decide(decision, held_ids, bind=None, reason=None, scope=None)`, opt-in (`write`), destructive (a rejection erases the candidate and suppresses its claim) and idempotent (a decision sent again answers `REVIEW_ITEM_DECIDED`): one decision kind for 1 to 100 ids, every rule checked before sending (ids `hld_` and 32 hex, each once; `bind` `claim` or `subject_predicate`, with reject only; reason 512 bytes); each result said: the fact an approval made, the correction a rejection left with its `correction_undo` call, a refused one's code and whether to call again |
+| Mixed decisions in one request (some approved, some rejected) | no | an assistant decides one kind per call; the SDK's `review_decide` and the console send mixed batches |
+| `include=held` on `GET /v1/memory/about` | no | `review_list` is the queue an assistant reads; `memory_about` keeps to what is known |
+| Their refusals | hints | `POLICY_DENIED` on the review routes (who reviews: a Writer of the scope or a principal `review.reviewers` names), a server without the routes (`derivation_review_v1`); `FORMAT_UPGRADE_PENDING` as for every format-11 route; a refused decision is its result's text, never an error |
+| `cortexdb_check_call` | yes | knows `GET /v1/review` (`scope` required) and `POST /v1/review/decisions` (`scope`, `decisions`; what a decision holds) |
+
 ## Server behaviour noted, not changed here
 
 - Fixed on the final server: `GET /v1/experience/status` answered `resend: "new_key"` for a `failed` write, which

{cortexdb_mcp-0.9.0 → cortexdb_mcp-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cortexdb-mcp
-Version: 0.9.0
+Version: 0.10.0
 Summary: MCP Server for CortexDB — expose memory operations to AI agents
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -21,6 +21,26 @@ MCP (Model Context Protocol) server that gives AI tools persistent long-term mem
 
 > **0.3.0 rewrites the server against the v1 CortexDB API.** Default surface is now `https://api-v1.cortexdb.ai`. The server **auto-signs-up anonymously** on first launch — no API key required.
 
+## What's new in 0.10.0 for CortexDB 0.15.0
+
+0.10.0 is the release for CortexDB 0.15.0, governed memory formation: control over what CortexDB learns from your
+memories, and corrections that stay corrected. It still works against an older server, where the tools it adds answer
+404 (their error says the server predates the route).
+
+- **New read tools**, in every profile but `code`: `memory_why` (why CortexDB holds a fact or a belief, or what it
+  learned from a memory), `derivation_policy` (what CortexDB learns at a scope, and what it will not), `memory_about`
+  (everything known about a subject, each fact and belief with its sources, optionally with its corrections) and
+  `review_list` (what a derivation policy held for review) ([How a memory was made](#how-a-memory-was-made-cortexdb-0150)).
+- **New write tools**, opt-in with `--tool-profile write` and marked destructive, so a client asks before it calls
+  them: `memory_correct` (reject, replace, pin or confirm a fact's claim), `correction_undo` and `review_decide`.
+- **`session`** on `memory_search` and `get_context`: the conversation session the read is made in, for a read-time
+  use rule.
+- **`cortexdb_check_call`** answers "fix a wrong memory" with a correction rather than a forget, and checks the
+  derivation reads.
+- **Errors**: a `What to do` for each new code a caller can act on.
+
+Every new tool takes `scope`, but `memory_why` takes `tenant_id`, as the older memory tools do.
+
 ## What's new in 0.9.0 for CortexDB 0.14.0
 
 0.9.0 is the release for CortexDB 0.14.0, the shared-memory release: per-person and agent tokens, org trees with
@@ -82,9 +102,9 @@ New fields on existing tools, each sent only when used, so a call without them s
 
 | Tool | Fields |
 |---|---|
-| `memory_search`, `get_context` | `extra_scopes` (at most 40 scopes read in the same pass), `coverage` (what was searched and each gap, with its reason), `at_least` (a consistency token to wait for), `purpose` (what the read is for: a roster path whose `when` names it holds only then) |
+| `memory_search`, `get_context` | `extra_scopes` (at most 40 scopes read in the same pass), `coverage` (what was searched and each gap, with its reason), `at_least` (a consistency token to wait for), `purpose` (what the read is for: a roster path whose `when` names it holds only then), `session` (the conversation session the read is made in: where a read-time use rule is in force, memory from other sessions is withheld; CortexDB 0.15.0) |
 | `get_context` | also `merged_beliefs` (beliefs rebuilt across the read set) and `app_mounts` (your application's mounted sources) |
-| `advanced_search` | `coverage`, `at_least`, `purpose` |
+| `advanced_search` | `coverage`, `at_least`, `purpose`, `session` |
 | `access_check`, `access_explain` | `purpose`: decide for a read declaring it |
 | `memory_list` | `cursor` (replaces `offset`), `at_least` |
 | `memory_get` | `at_least` |
@@ -225,7 +245,7 @@ The profiles (`--tool-profile`, or `CORTEXDB_TOOL_PROFILE`):
 | Profile | Tools |
 |---|---|
 | `all` (default) | every memory, access and code tool but the opt-in writes |
-| `write` | `all`, plus `publish` and `forget_by_key` |
+| `write` | `all`, plus `publish` and `forget_by_key`, and CortexDB 0.15.0's `memory_correct`, `correction_undo` and `review_decide` |
 | `read` | only the tools that write no memory (`acknowledge_notices` included: it changes only your notices) |
 | `code` | `code_explore`, `code_impact`, `code_inventory`, `code_graph` |
 
@@ -355,11 +375,11 @@ On Windows, MCP clients sometimes need the absolute path:
 |------|---------|-------------|
 | `memory_store` | `POST /v1/experience` | Store a new memory. Source/tags/type become labels; optional `idempotency_key`, `provenance` and `consistency` (a token to read it back with). Names where a redirected write landed. |
 | `memory_status` | `GET /v1/experience/status` | Did a store land? Check by event ID or idempotency key after a timeout; the answer carries the server's re-send advice; `tenant_id` is the write's scope. |
-| `memory_search` | `POST /v1/recall` | Search memories using natural language; `extra_scopes`, `coverage`, `at_least`, `purpose`. |
+| `memory_search` | `POST /v1/recall` | Search memories using natural language; `extra_scopes`, `coverage`, `at_least`, `purpose`, `session`. |
 | `memory_forget` | `POST /v1/forget` | Forget derived knowledge (facts, beliefs, episodes, understanding): about a subject with `query`, else the whole scope's. Keeps the memories themselves. Accepts `from_preview_id` from `forget_preview`. |
 | `forget_preview` | `POST /v1/forget/preview` | Non-destructive dry run of a forget: per-layer estimated deletion counts, a `preview_id`, and the tool that executes exactly that selector. |
-| `get_context` | `POST /v1/recall` (the server's view unless `CORTEXDB_VIEW` is set) | Deep context across the requested scope, authorized ancestors, and authorized descendants—never siblings; `extra_scopes`, `coverage`, `at_least`, `merged_beliefs`, `app_mounts`, `purpose`. |
-| `advanced_search` | `POST /v1/recall` + temporal | Search with structured filters (time / source / type); `coverage`, `at_least`, `purpose`. |
+| `get_context` | `POST /v1/recall` (the server's view unless `CORTEXDB_VIEW` is set) | Deep context across the requested scope, authorized ancestors, and authorized descendants—never siblings; `extra_scopes`, `coverage`, `at_least`, `merged_beliefs`, `app_mounts`, `purpose`, `session`. |
+| `advanced_search` | `POST /v1/recall` + temporal | Search with structured filters (time / source / type); `coverage`, `at_least`, `purpose`, `session`. |
 
 ### Event CRUD
 
@@ -403,6 +423,57 @@ On Windows, MCP clients sometimes need the absolute path:
 
 Validity boundaries carry a basis: `stated` boundaries render as "since/until \<date\>"; `observed` boundaries are knowledge bounds and render as "by \<date\>" — never "on \<date\>".
 
+### How a memory was made (CortexDB 0.15.0)
+
+| Tool | Maps to | Description |
+|------|---------|-------------|
+| `memory_why` | `GET /v1/facts/{id}?include=derivation`, `GET /v1/beliefs/why?include=derivation`, `GET /v1/derivation/decisions` | Why CortexDB holds a fact or a belief, or what it learned from a memory. Read-only, in every profile but `code`. |
+| `derivation_policy` | `GET /v1/derivation/policy[?include=texts]` | What CortexDB learns at a scope, and what it will not: the policy in force and who set each rule. Read-only, in every profile but `code`. |
+| `memory_about` | `GET /v1/memory/about` | Everything CortexDB knows about a subject, each fact and belief with its id and sources; optionally its corrections. Read-only, in every profile but `code`. |
+| `memory_correct` | `POST /v1/corrections` | Fix a wrong memory: reject, replace, pin or confirm a fact's claim. Opt-in (`--tool-profile write`), destructive. |
+| `correction_undo` | `DELETE /v1/corrections/{id}` | Undo a correction. Opt-in (`--tool-profile write`), destructive. |
+| `review_list` | `GET /v1/review` | What a derivation policy held for review before learning it: each candidate's held id, what it states, the rule that held it, when it lapses, its source. Read-only, in every profile but `code`. |
+| `review_decide` | `POST /v1/review/decisions` | Approve held candidates (each becomes a fact) or reject them (erased, their claim suppressed by a correction), 1 to 100 a call. Opt-in (`--tool-profile write`), destructive. |
+
+`memory_why` takes one id and answers the question an agent gets asked when a memory surprises someone: "why do you
+think that?". For a fact (`fact_...`) it gives the claim, how it was made (learned by CortexDB's extraction, or
+declared by a writer), with the extraction model, the prompt version, the gate version and the derivation policy, and
+the memories it came from, each with what CortexDB learned from it. For a belief (`belief_...`) it gives the same from
+its supporting facts, with what supports it. For a memory (`evt_...`) it says what became of it: candidates accepted,
+nothing admitted, held for review, not derived yet, skipped (and why: enrichment off, a typed triple, no text) or
+failed. A candidate CortexDB rejected is only counted, by the rule that rejected it; its text is never shown. It needs a
+server that lists `derivation_provenance_v1` (CortexDB 0.15.0): an older one answers without how a fact was made, and
+the answer says so. `tenant_id` names a scope at or above the record's own, as `?scope=`.
+
+`derivation_policy` answers "what do you remember about me, and what won't you?" for a scope (`scope`, default the
+configured one): whether CortexDB learns from the memories stored there at all and, if not, why (enrichment off on
+the server, the scope outside its enrichment allowlist, the scope's `enrich` off, an application's reference root, or
+a policy whose mode is off), the mode (every memory, only those marked `memory:remember`, each candidate held for
+review), what is never learned or learned only with consent and who set each rule (a policy at the scope or above it,
+the org chart, or the person's own settings), the steering (instructions, examples, the extraction model, how a
+predicate's conflicts resolve), the values set without effect, and the policy hash facts are stamped with (`dp1:none`:
+no policy). `include_texts=true` adds the instructions, examples and topic descriptions in full, for an Owner with
+`derivation.administer.scope`. It needs `derivation_policy_v1` (CortexDB 0.15.0); below apply format 11 the answer is
+the empty policy, and says so. Policies are written by change sets and a person's settings by
+`PUT /v1/derivation/settings`; no tool here writes either (`cortexdb derivation stage` and `settings` do).
+
+To fix a wrong memory, correct it rather than forget it: forgotten derived knowledge can be learned again from the
+kept memories, a corrected claim is not. `memory_about` ("what do you know about me?") lists the facts and beliefs at
+a scope, each with its id and the memories it came from (an item whose sources you may not read is left out), and
+with `include_corrections` the corrections made there. `memory_correct(action, fact_id, ...)` corrects the fact's
+claim, every live fact of it at the scope and below: `reject` deletes them and keeps the claim from being learned again
+(`bind` widens it to every value of the subject and predicate, or everything about the subject), `replace` with
+`value` makes the new value the user's own fact and closes the old ones, `pin` keeps any extracted value from
+superseding it, `confirm` raises its authority. `correction_undo(correction_id)` reverses one (its author, an Owner of
+its scope or the operator only). Both writes are opt-in (`--tool-profile write`) and destructive, so a client asks
+before it calls them; a retriable refusal names the idempotency key to retry with. They need `corrections_v1`
+(CortexDB 0.15.0) and a shard armed for apply format 11; `memory_about` is served at format 10.
+
+Against a server before CortexDB 0.15.0, `derivation_policy`, `memory_about`, `memory_correct`, `correction_undo`,
+`review_list` and `review_decide` answer 404, which reads like a missing record: their error's `What to do` says the
+server predates the route, and `GET /v1/admin/version` lists the capabilities a server serves. `memory_why` answers
+there without how a fact was made, and says so.
+
 ### Admin & Observability
 
 | Tool | Maps to | Description |
@@ -410,7 +481,7 @@ Validity boundaries carry a basis: `stated` boundaries render as "since/until \<
 | `health_check` | `GET /v1/auth/whoami` | Verify the bearer + reach the deployment policy; names an agent token's chain. |
 | `get_usage` | `GET /v1/auth/whoami` + headers | Tier, rate limit, token expiry, chain. |
 | `get_insights` | (in-process) | Proactive insights derived from stored episodes; names a layer it could not read. |
-| `cortexdb_check_call` | (static) | Check a CortexDB call before writing it, against 0.14.0's rules. |
+| `cortexdb_check_call` | (static) | Check a CortexDB call before writing it, against 0.14.0's rules and 0.15.0's derivation reads (the decisions route's query: `scope` and `event_id` only; the policy route's `scope`). |
 
 ### Removed from 0.3.0
 
@@ -476,8 +547,10 @@ covers the codes a caller can act on, among them `BREAK_GLASS_REQUIRED`, a confi
 `WAL_OUTCOME_UNKNOWN` (with the idempotency key to retry with), `IDEMPOTENCY_CONFLICT`, `DB_TIMEOUT`,
 `ROLLUP_SUPERSEDED` (naming the current build), `INVALID_CURSOR`, `CLUSTER_ROUTE_UNSUPPORTED`, `ACCESS_LIMIT_REACHED`,
 `SUBJECT_UNMAPPED`, `PUBLISH_PERSON_REQUIRED`, `FRESH_AUTH_REQUIRED`, `SCOPE_MOVING` and the token codes
-(`act_not_delegable` among them). The client keeps no table of statuses or retriable flags: a code it does not know is
-read by its status and the envelope's `retriable`.
+(`act_not_delegable` among them), and CortexDB 0.15.0's governed-formation codes (`DERIVATION_POLICY_INVALID`,
+`DERIVATION_POLICY_WIDENS`, `DERIVATION_MODEL_NOT_ALLOWED`, `DERIVATION_TEXT_INVALID`, `FEED_CURSOR_INVALID`,
+`DERIVED_BY_INVALID`, each by its `details`, and a derivation route an older server does not serve). The client keeps no
+table of statuses or retriable flags: a code it does not know is read by its status and the envelope's `retriable`.
 
 ## Examples
 

{cortexdb_mcp-0.9.0 → cortexdb_mcp-0.10.0}/README.md

@@ -4,6 +4,26 @@ MCP (Model Context Protocol) server that gives AI tools persistent long-term mem
 
 > **0.3.0 rewrites the server against the v1 CortexDB API.** Default surface is now `https://api-v1.cortexdb.ai`. The server **auto-signs-up anonymously** on first launch — no API key required.
 
+## What's new in 0.10.0 for CortexDB 0.15.0
+
+0.10.0 is the release for CortexDB 0.15.0, governed memory formation: control over what CortexDB learns from your
+memories, and corrections that stay corrected. It still works against an older server, where the tools it adds answer
+404 (their error says the server predates the route).
+
+- **New read tools**, in every profile but `code`: `memory_why` (why CortexDB holds a fact or a belief, or what it
+  learned from a memory), `derivation_policy` (what CortexDB learns at a scope, and what it will not), `memory_about`
+  (everything known about a subject, each fact and belief with its sources, optionally with its corrections) and
+  `review_list` (what a derivation policy held for review) ([How a memory was made](#how-a-memory-was-made-cortexdb-0150)).
+- **New write tools**, opt-in with `--tool-profile write` and marked destructive, so a client asks before it calls
+  them: `memory_correct` (reject, replace, pin or confirm a fact's claim), `correction_undo` and `review_decide`.
+- **`session`** on `memory_search` and `get_context`: the conversation session the read is made in, for a read-time
+  use rule.
+- **`cortexdb_check_call`** answers "fix a wrong memory" with a correction rather than a forget, and checks the
+  derivation reads.
+- **Errors**: a `What to do` for each new code a caller can act on.
+
+Every new tool takes `scope`, but `memory_why` takes `tenant_id`, as the older memory tools do.
+
 ## What's new in 0.9.0 for CortexDB 0.14.0
 
 0.9.0 is the release for CortexDB 0.14.0, the shared-memory release: per-person and agent tokens, org trees with
@@ -65,9 +85,9 @@ New fields on existing tools, each sent only when used, so a call without them s
 
 | Tool | Fields |
 |---|---|
-| `memory_search`, `get_context` | `extra_scopes` (at most 40 scopes read in the same pass), `coverage` (what was searched and each gap, with its reason), `at_least` (a consistency token to wait for), `purpose` (what the read is for: a roster path whose `when` names it holds only then) |
+| `memory_search`, `get_context` | `extra_scopes` (at most 40 scopes read in the same pass), `coverage` (what was searched and each gap, with its reason), `at_least` (a consistency token to wait for), `purpose` (what the read is for: a roster path whose `when` names it holds only then), `session` (the conversation session the read is made in: where a read-time use rule is in force, memory from other sessions is withheld; CortexDB 0.15.0) |
 | `get_context` | also `merged_beliefs` (beliefs rebuilt across the read set) and `app_mounts` (your application's mounted sources) |
-| `advanced_search` | `coverage`, `at_least`, `purpose` |
+| `advanced_search` | `coverage`, `at_least`, `purpose`, `session` |
 | `access_check`, `access_explain` | `purpose`: decide for a read declaring it |
 | `memory_list` | `cursor` (replaces `offset`), `at_least` |
 | `memory_get` | `at_least` |
@@ -208,7 +228,7 @@ The profiles (`--tool-profile`, or `CORTEXDB_TOOL_PROFILE`):
 | Profile | Tools |
 |---|---|
 | `all` (default) | every memory, access and code tool but the opt-in writes |
-| `write` | `all`, plus `publish` and `forget_by_key` |
+| `write` | `all`, plus `publish` and `forget_by_key`, and CortexDB 0.15.0's `memory_correct`, `correction_undo` and `review_decide` |
 | `read` | only the tools that write no memory (`acknowledge_notices` included: it changes only your notices) |
 | `code` | `code_explore`, `code_impact`, `code_inventory`, `code_graph` |
 
@@ -338,11 +358,11 @@ On Windows, MCP clients sometimes need the absolute path:
 |------|---------|-------------|
 | `memory_store` | `POST /v1/experience` | Store a new memory. Source/tags/type become labels; optional `idempotency_key`, `provenance` and `consistency` (a token to read it back with). Names where a redirected write landed. |
 | `memory_status` | `GET /v1/experience/status` | Did a store land? Check by event ID or idempotency key after a timeout; the answer carries the server's re-send advice; `tenant_id` is the write's scope. |
-| `memory_search` | `POST /v1/recall` | Search memories using natural language; `extra_scopes`, `coverage`, `at_least`, `purpose`. |
+| `memory_search` | `POST /v1/recall` | Search memories using natural language; `extra_scopes`, `coverage`, `at_least`, `purpose`, `session`. |
 | `memory_forget` | `POST /v1/forget` | Forget derived knowledge (facts, beliefs, episodes, understanding): about a subject with `query`, else the whole scope's. Keeps the memories themselves. Accepts `from_preview_id` from `forget_preview`. |
 | `forget_preview` | `POST /v1/forget/preview` | Non-destructive dry run of a forget: per-layer estimated deletion counts, a `preview_id`, and the tool that executes exactly that selector. |
-| `get_context` | `POST /v1/recall` (the server's view unless `CORTEXDB_VIEW` is set) | Deep context across the requested scope, authorized ancestors, and authorized descendants—never siblings; `extra_scopes`, `coverage`, `at_least`, `merged_beliefs`, `app_mounts`, `purpose`. |
-| `advanced_search` | `POST /v1/recall` + temporal | Search with structured filters (time / source / type); `coverage`, `at_least`, `purpose`. |
+| `get_context` | `POST /v1/recall` (the server's view unless `CORTEXDB_VIEW` is set) | Deep context across the requested scope, authorized ancestors, and authorized descendants—never siblings; `extra_scopes`, `coverage`, `at_least`, `merged_beliefs`, `app_mounts`, `purpose`, `session`. |
+| `advanced_search` | `POST /v1/recall` + temporal | Search with structured filters (time / source / type); `coverage`, `at_least`, `purpose`, `session`. |
 
 ### Event CRUD
 
@@ -386,6 +406,57 @@ On Windows, MCP clients sometimes need the absolute path:
 
 Validity boundaries carry a basis: `stated` boundaries render as "since/until \<date\>"; `observed` boundaries are knowledge bounds and render as "by \<date\>" — never "on \<date\>".
 
+### How a memory was made (CortexDB 0.15.0)
+
+| Tool | Maps to | Description |
+|------|---------|-------------|
+| `memory_why` | `GET /v1/facts/{id}?include=derivation`, `GET /v1/beliefs/why?include=derivation`, `GET /v1/derivation/decisions` | Why CortexDB holds a fact or a belief, or what it learned from a memory. Read-only, in every profile but `code`. |
+| `derivation_policy` | `GET /v1/derivation/policy[?include=texts]` | What CortexDB learns at a scope, and what it will not: the policy in force and who set each rule. Read-only, in every profile but `code`. |
+| `memory_about` | `GET /v1/memory/about` | Everything CortexDB knows about a subject, each fact and belief with its id and sources; optionally its corrections. Read-only, in every profile but `code`. |
+| `memory_correct` | `POST /v1/corrections` | Fix a wrong memory: reject, replace, pin or confirm a fact's claim. Opt-in (`--tool-profile write`), destructive. |
+| `correction_undo` | `DELETE /v1/corrections/{id}` | Undo a correction. Opt-in (`--tool-profile write`), destructive. |
+| `review_list` | `GET /v1/review` | What a derivation policy held for review before learning it: each candidate's held id, what it states, the rule that held it, when it lapses, its source. Read-only, in every profile but `code`. |
+| `review_decide` | `POST /v1/review/decisions` | Approve held candidates (each becomes a fact) or reject them (erased, their claim suppressed by a correction), 1 to 100 a call. Opt-in (`--tool-profile write`), destructive. |
+
+`memory_why` takes one id and answers the question an agent gets asked when a memory surprises someone: "why do you
+think that?". For a fact (`fact_...`) it gives the claim, how it was made (learned by CortexDB's extraction, or
+declared by a writer), with the extraction model, the prompt version, the gate version and the derivation policy, and
+the memories it came from, each with what CortexDB learned from it. For a belief (`belief_...`) it gives the same from
+its supporting facts, with what supports it. For a memory (`evt_...`) it says what became of it: candidates accepted,
+nothing admitted, held for review, not derived yet, skipped (and why: enrichment off, a typed triple, no text) or
+failed. A candidate CortexDB rejected is only counted, by the rule that rejected it; its text is never shown. It needs a
+server that lists `derivation_provenance_v1` (CortexDB 0.15.0): an older one answers without how a fact was made, and
+the answer says so. `tenant_id` names a scope at or above the record's own, as `?scope=`.
+
+`derivation_policy` answers "what do you remember about me, and what won't you?" for a scope (`scope`, default the
+configured one): whether CortexDB learns from the memories stored there at all and, if not, why (enrichment off on
+the server, the scope outside its enrichment allowlist, the scope's `enrich` off, an application's reference root, or
+a policy whose mode is off), the mode (every memory, only those marked `memory:remember`, each candidate held for
+review), what is never learned or learned only with consent and who set each rule (a policy at the scope or above it,
+the org chart, or the person's own settings), the steering (instructions, examples, the extraction model, how a
+predicate's conflicts resolve), the values set without effect, and the policy hash facts are stamped with (`dp1:none`:
+no policy). `include_texts=true` adds the instructions, examples and topic descriptions in full, for an Owner with
+`derivation.administer.scope`. It needs `derivation_policy_v1` (CortexDB 0.15.0); below apply format 11 the answer is
+the empty policy, and says so. Policies are written by change sets and a person's settings by
+`PUT /v1/derivation/settings`; no tool here writes either (`cortexdb derivation stage` and `settings` do).
+
+To fix a wrong memory, correct it rather than forget it: forgotten derived knowledge can be learned again from the
+kept memories, a corrected claim is not. `memory_about` ("what do you know about me?") lists the facts and beliefs at
+a scope, each with its id and the memories it came from (an item whose sources you may not read is left out), and
+with `include_corrections` the corrections made there. `memory_correct(action, fact_id, ...)` corrects the fact's
+claim, every live fact of it at the scope and below: `reject` deletes them and keeps the claim from being learned again
+(`bind` widens it to every value of the subject and predicate, or everything about the subject), `replace` with
+`value` makes the new value the user's own fact and closes the old ones, `pin` keeps any extracted value from
+superseding it, `confirm` raises its authority. `correction_undo(correction_id)` reverses one (its author, an Owner of
+its scope or the operator only). Both writes are opt-in (`--tool-profile write`) and destructive, so a client asks
+before it calls them; a retriable refusal names the idempotency key to retry with. They need `corrections_v1`
+(CortexDB 0.15.0) and a shard armed for apply format 11; `memory_about` is served at format 10.
+
+Against a server before CortexDB 0.15.0, `derivation_policy`, `memory_about`, `memory_correct`, `correction_undo`,
+`review_list` and `review_decide` answer 404, which reads like a missing record: their error's `What to do` says the
+server predates the route, and `GET /v1/admin/version` lists the capabilities a server serves. `memory_why` answers
+there without how a fact was made, and says so.
+
 ### Admin & Observability
 
 | Tool | Maps to | Description |
@@ -393,7 +464,7 @@ Validity boundaries carry a basis: `stated` boundaries render as "since/until \<
 | `health_check` | `GET /v1/auth/whoami` | Verify the bearer + reach the deployment policy; names an agent token's chain. |
 | `get_usage` | `GET /v1/auth/whoami` + headers | Tier, rate limit, token expiry, chain. |
 | `get_insights` | (in-process) | Proactive insights derived from stored episodes; names a layer it could not read. |
-| `cortexdb_check_call` | (static) | Check a CortexDB call before writing it, against 0.14.0's rules. |
+| `cortexdb_check_call` | (static) | Check a CortexDB call before writing it, against 0.14.0's rules and 0.15.0's derivation reads (the decisions route's query: `scope` and `event_id` only; the policy route's `scope`). |
 
 ### Removed from 0.3.0
 
@@ -459,8 +530,10 @@ covers the codes a caller can act on, among them `BREAK_GLASS_REQUIRED`, a confi
 `WAL_OUTCOME_UNKNOWN` (with the idempotency key to retry with), `IDEMPOTENCY_CONFLICT`, `DB_TIMEOUT`,
 `ROLLUP_SUPERSEDED` (naming the current build), `INVALID_CURSOR`, `CLUSTER_ROUTE_UNSUPPORTED`, `ACCESS_LIMIT_REACHED`,
 `SUBJECT_UNMAPPED`, `PUBLISH_PERSON_REQUIRED`, `FRESH_AUTH_REQUIRED`, `SCOPE_MOVING` and the token codes
-(`act_not_delegable` among them). The client keeps no table of statuses or retriable flags: a code it does not know is
-read by its status and the envelope's `retriable`.
+(`act_not_delegable` among them), and CortexDB 0.15.0's governed-formation codes (`DERIVATION_POLICY_INVALID`,
+`DERIVATION_POLICY_WIDENS`, `DERIVATION_MODEL_NOT_ALLOWED`, `DERIVATION_TEXT_INVALID`, `FEED_CURSOR_INVALID`,
+`DERIVED_BY_INVALID`, each by its `details`, and a derivation route an older server does not serve). The client keeps no
+table of statuses or retriable flags: a code it does not know is read by its status and the envelope's `retriable`.
 
 ## Examples