Beliefs - Naïve

A belief is a claim the company holds: a subject, a predicate and an object, with a status and a confidence.

This endpoint exists to answer one question: why did recall not return that? A read surface that silently applies three filters and reports one boolean makes that question unanswerable, so every row carries recallable and the three filters behind it.

List beliefs

GET /v1/brain/beliefs?status=&level=&key=&include_shadowed=&cursor=&limit=

Parameter	Values	Notes
`status`	one status	Overrides the default filter entirely.
`level`	`company` \| `team`	Anything else is `400 invalid_input`. There is no `agent` level.
`key`	normalised key	Exact match.
`include_shadowed`	`true`	Removes the default status filter.
`cursor` · `limit`	keyset, max 200	See `GET /v1/limits`.

There is a default filter and the response tells you about it. With no status and no include_shadowed=true, the list is restricted to candidate, active and confirmed — the recallable set. Superseded, contradicted, expired and deleted beliefs are excluded.applied_filters in every response states exactly what was applied. A default filter nobody is told about is the whole disease this endpoint treats.

{
  "items": [
    {
      "belief_id": "claim-…",
      "key": "acme-ltd:renewal-owner",
      "statement": "ACME Ltd renewal owner is Dana Okafor",
      "subject": "ACME Ltd",
      "predicate": "renewal owner is",
      "object": "Dana Okafor",
      "level": "company",
      "partition": null,
      "lane": null,
      "lane_unavailable_because": "no lane column exists on any brain_* table",
      "status": "confirmed",
      "confidence": 0.8,
      "valid_from": "2026-07-29T09:00:00.000Z",
      "valid_to": null,
      "observed_at": "2026-07-29T09:00:00.000Z",
      "created_at": "2026-07-29T09:00:02.000Z",
      "expires_at_unavailable_because": "brain_claims has valid_from/valid_to (temporal validity of the assertion) and no retention column; a belief in this build never lapses",
      "supersedes": null,
      "shadows": null,
      "shadows_unavailable_because": "shadowing is a level relation; with no agent level and no lane, a company/team pair cannot be resolved here",
      "uses": null,
      "uses_unavailable_because": "no recall-count column exists on brain_claims",
      "recallable": true,
      "filters": {
        "status_ok": true,
        "not_expired": true,
        "not_expired_measures": "valid_to (temporal validity), not retention",
        "scan_ok": true,
        "scan_ok_measures": "the knowledge base's own status is 'active'"
      }
    }
  ],
  "next_cursor": null,
  "applied_filters": {
    "status": ["candidate", "active", "confirmed"],
    "level": "none",
    "key": "none"
  },
  "levels_absent": {
    "agent": "no brain_* table carries an agent level; `level: \"agent\"` cannot be returned"
  }
}

`recallable` and the three filters

recallable is the AND of three checks, each reported separately so a false can be diagnosed without guessing:

Filter	Asks
`status_ok`	is the status one of `candidate`, `active`, `confirmed`?
`not_expired`	is `valid_to` in the future, or absent?
`scan_ok`	is the knowledge base this belief lives in `active`? A KB still provisioning, or in error, is not readable.

Each filter carries a *_measures string saying what it actually tested, because the obvious reading is wrong in one case — see below.

🔴 `not_expired` does not measure retention

valid_to is the temporal validity of the assertion: this was true until then. It is not a retention deadline. There is no retention column on any brain table, so:

expires_at is absent from the response entirely, and expires_at_unavailable_because explains why. Reporting it even as null would imply a lifecycle that does not exist.
A belief in this build never lapses. Nothing ages out.
GET /v1/brain/retention answers 501 for the same reason.

If your product promises customers that stored knowledge expires, that promise is not enforced by this API today.

Fields that are `null` everywhere

Field	Why
`lane`	no lane column exists on any brain table
`shadows`	shadowing is a level relation, and with no agent level and no lane there is nothing to resolve
`uses`	no recall-count column exists
`partition`	`null` for company-level beliefs; the KB name for team-level ones

One belief

GET /v1/brain/beliefs/{id}

The same object, unpaged. 404 not_found if the belief does not belong to your company.

The four that refuse

These share the /v1/brain prefix and answer 501 not_configured.

Reaffirm

POST /v1/brain/beliefs/{id}/reaffirm A reaffirmation is an event — this was checked again, on this date, by this actor. No table records one, and no recall-count column exists. The only way to implement it today would be to bump observed_at, which would silently rewrite when the claim was first observed and destroy the column that orders belief history.

Lessons

GET /v1/brain/lessons · POST /v1/brain/lessons A lesson is not a belief with a different label. Serving lessons out of the claims table would make one row mean two things — the two-vocabulary collision the brain exists to end.

Retention

GET /v1/brain/retention

Read this one twice. 200 {"policies": []} would say no retention policies are configured, which a reader hears as the default applies. 501 says there is no retention mechanism. Those are different facts, and the second one is true.brain({ retention }) in naive.config.ts compiles a per-content ceiling. Nothing server-side reads or stores it.

Decisions

GET /v1/brain/decisions A read view over the policy decision ledger filtered to brain resources — explicitly not a second ledger. There is no first ledger to view. See GET /v1/policy/decisions.

Availability

These operations exist at the company prefix only. There is no /v1/users/{user_id}/brain/beliefs. Company-scoped and tenant-scoped brain operations are listed in the Brain overview. Like every /v1/brain route, they require the brain primitive to be enabled on the AccountKit and are metered against the plan quota.

{
  "items": [
    {
      "belief_id": "claim-…",
      "key": "acme-ltd:renewal-owner",
      "statement": "ACME Ltd renewal owner is Dana Okafor",
      "subject": "ACME Ltd",
      "predicate": "renewal owner is",
      "object": "Dana Okafor",
      "level": "company",
      "partition": null,
      "lane": null,
      "lane_unavailable_because": "no lane column exists on any brain_* table",
      "status": "confirmed",
      "confidence": 0.8,
      "valid_from": "2026-07-29T09:00:00.000Z",
      "valid_to": null,
      "observed_at": "2026-07-29T09:00:00.000Z",
      "created_at": "2026-07-29T09:00:02.000Z",
      "expires_at_unavailable_because": "brain_claims has valid_from/valid_to (temporal validity of the assertion) and no retention column; a belief in this build never lapses",
      "supersedes": null,
      "shadows": null,
      "shadows_unavailable_because": "shadowing is a level relation; with no agent level and no lane, a company/team pair cannot be resolved here",
      "uses": null,
      "uses_unavailable_because": "no recall-count column exists on brain_claims",
      "recallable": true,
      "filters": {
        "status_ok": true,
        "not_expired": true,
        "not_expired_measures": "valid_to (temporal validity), not retention",
        "scan_ok": true,
        "scan_ok_measures": "the knowledge base's own status is 'active'"
      }
    }
  ],
  "next_cursor": null,
  "applied_filters": {
    "status": ["candidate", "active", "confirmed"],
    "level": "none",
    "key": "none"
  },
  "levels_absent": {
    "agent": "no brain_* table carries an agent level; `level: \"agent\"` cannot be returned"
  }
}

​List beliefs

​recallable and the three filters

​🔴 not_expired does not measure retention

​Fields that are null everywhere

​One belief

​The four that refuse

​Reaffirm

​Lessons

​Retention

​Decisions

​Availability

List beliefs

`recallable` and the three filters

🔴 `not_expired` does not measure retention

Fields that are `null` everywhere

One belief

The four that refuse

Reaffirm

Lessons

Retention

Decisions

Availability