Governed Memory
Decide what CortexDB learns from your events — derivation policies, recorded decisions, corrections that stay corrected, review before commit and re-derivation.
CortexDB's background enrichment reads the events you write and learns from them: facts, entities, beliefs, episodes. Governed memory puts that learning under your rules. You write a derivation policy as data, test it on real events, and activate it. From then on every candidate memory the extraction model proposes is judged against the policy, and the verdict is recorded with the rule that decided it. When something wrong is learned anyway, a correction removes it and keeps it from coming back.
Your logic enters as data, never as code inside CortexDB. Work that needs your own code runs on your compute, reading a change feed and writing its results back.
Experimental
Every governed-memory route answers with X-Cortex-Stability: experimental. Check
GET /v1/admin/version for the route's capability before you call it: a server without it answers
404, which reads like "not found". Most routes need data format 11; a server held at format 10
(CORTEX_FORMAT_CEILING=10) answers 503 FORMAT_UPGRADE_PENDING on them
(Upgrading).
Without a policy, nothing changes
A deployment that sets no derivation policy, writes no subject settings and makes no correction
learns and answers with every stage on. Provenance is stored on every fact enrichment derives, and served
only when a read asks for it (include=derivation).
How a candidate memory is judged
- An event is written. The policy decides first whether enrichment reads it at all: its
mode(off,explicit,review,automatic), itsstages, and itssourcesrules (roles, actors, labels, intents). Detectors can mask sensitive values before the model sees the text, or skip the event. - The extraction model proposes candidates. The policy's instructions and examples steer what it looks for.
- The deny rules run first. Topics, detectors and grounding rules judge each candidate before anything else sees it. Denied content is never stored, never embedded and never logged. Only the rule's id and a count are kept.
- The routing rules run last. Writer rules (who may set a field), cardinality and conflict rules, and review rules decide whether a candidate is stored, held for review, or rejected.
- The verdict is recorded. Every accepted fact carries how it was made: the rule, the policy's
hash, the models and the prompt version.
GET /v1/derivation/decisionsanswers what became of one event.
What is exact, and what is a model's judgment
| Control | How it decides |
|---|---|
| Detectors (payment cards, IBANs, national ids, secrets, contact details, precise locations) | Exact. Checksummed formats are verified, not guessed |
| Stages, sources, grounding, writer rules, modes | Exact. They read the event's own fields and the candidate's claim |
| Topics (the 20-category sensitive-topic taxonomy and your own topics) | Model-judged. The extraction model labels each candidate's topic, so a denied topic can leak when the model labels a candidate otherwise |
Measure a topic policy with the test sandbox before you rely on it: it shows each candidate's verdict on your own events, and how many candidates had no topic label.
The controls
| You want to | Use | Page |
|---|---|---|
| Set what may be learned, from which sources, about which topics | A derivation policy, staged through a change set | Derivation Policies |
| Try a policy before activating it | POST /v1/derivation/policy/test | Derivation Policies |
| Let a user turn memory off, deny a topic, or give a consent | Subject settings, PUT /v1/derivation/settings | Derivation Policies |
| Fix a wrong memory, and keep it fixed | POST /v1/corrections: reject, replace, pin, confirm, undo | Corrections |
| Approve memories before they are stored | A policy's review rules and the review queue | Review |
| Apply a changed policy to what was learned before | regate (free) or reextract (priced, capped) | Re-derivation |
| See why a fact exists | include=derivation and GET /v1/derivation/decisions | Facts, Derivation status |
| Derive on your own compute | The change feed, derived_by, declared episodes | Change Feed |
| Show a person what is known about them | GET /v1/memory/about | Memory About |
| Report what was derived over a period | GET /v1/derivation/report | Re-derivation |
Guarantees
- Policies are layered. Restrictions accumulate down the scope tree and along the org chart: a
child can only tighten what an ancestor sets, and a staged child that would widen it is refused
(
422 DERIVATION_POLICY_WIDENS). Steering (instructions, examples, models, conflict rules) takes the nearest scope's value. Nothing widens what the server's own settings allow. - A policy changes only through a change set, with a preview of each scope's policy before and after, so it is reviewed and approved like an access change.
- Corrections converge. A rejected memory stays rejected through re-enrichment, rebuilds, failovers and scope moves, on every replica, whatever order the replicas learn in.
- Held candidates are invisible. A candidate held for review is in no store and no index: no recall, answer or read sees it until it is approved.
- Erasure reaches all of it. Erasing an event erases what was learned from it, and the corrections, held candidates, review decisions, declared episodes and policy examples that cite it. A person's erasure also erases the corrections about that person.
- Spend is bounded. A policy's daily budget defers its extraction to the next UTC midnight once spent; a policy test and a re-extraction run under caps you set.
Which duties the controls help with
CortexDB provides controls; whether a deployment meets a law depends on how it uses them. The controls map to common duties like this:
| Duty | Controls that help |
|---|---|
| Data minimization, purpose limitation | mode: explicit, stages, source rules, topic and detector denials |
| Consent for sensitive categories (for example GDPR Article 9, Washington's consumer health data) | deny_unless_consent topics and a subject's recorded consents, audited as derivation_consent |
| A user's right to limit sensitive data (California's "limit the use") | limit_spi in subject settings |
| Objection, and turning memory off | objection and mode: off in subject settings |
| Rectification | Corrections (replace, reject) that stay applied |
| Access and portability requests | GET /v1/memory/about, the export |
| Erasure | Erasure reaches every governed record; receipts name the feed consumers that may hold a copy |
| Risk assessments, answering a regulator | GET /v1/derivation/report, the audit trail |
| New York's General Business Law Article 48 (users not established as adults) | The opt-in read-time use rule; CortexDB verifies no age |
Getting started
- Read the templates:
GET /v1/derivation/templates(consumer@1,minimal@1,enterprise@1,minor@1,health_app@1). - Test one on your events:
POST /v1/derivation/policy/testwith the template's body as the draft. - Stage it at your application's scope in a change set, preview it, and activate it.
- Watch
GET /v1/derivation/status?scope=…: itsgovernanceblock counts what was learned under an older policy. Run aregatedry run to see what the new policy would retire. - Give users a way to correct what was learned:
POST /v1/corrections.