Docs / Specification

contract read · 20-read.md · 21-memory.md · guide · card

Synthesized memory

Implementers use this page for stored claims, entity identities, relationships and prediction outcomes. Memory uses the same tables, commit operations and access controls as ingested data. The memory commands and tools write, revise and retrieve these records. Subject erasure uses the disclosure contract’s erase operation.

Memory tables and the operations that write and read their rows:

declare

Memory table schemas, required columns, trust tiers, scopes and relation types.

• canonical-columntestA table naming a shape and omitting one of its canonical columns raises MemoryShapeColumnMissing when the declaration loads.
  Why

  P1
• undeclared-relationtestFor a rel_type outside the allowed union, synthesis writes the candidate edge to the dead-letter table and raises MemoryUndeclaredRelation. No row uses the unknown type.
  Why

  A-read#memory-vocabulary-schedules
• relation-traitstestA [relation].declared entry is a bare name, or a table of name, direction, cardinality and walkable. A bare name or an omitted trait reads directed, many and not walkable. Reserved relations carry the reserved-traits table.
  Why

  because a relation marked walkable by default lets a dense relation fan a walk across the store
• reserved-relationstestReserved relation types are supports, contradicts, supersedes, about and derived_from. Deployments add types through [relation].declared. contextful memory relations rename rewrites stored edges before removing an old name.
  Why

  A-read#memory-vocabulary-schedules
• settlement-shapestestThe predictions shape carries one column per registration field, deadline_at resolved for a horizon; the outcomes shape carries one column per observation field. Both key on prediction_id.
  Why

  because the label join reads these columns by name, and one row per prediction keeps one label per prediction
• availabilitytestA shaped memory table accepts [table.available_time] under declarationstore.available-time.declaration[pipeline.tables.available_time] declares AvailableTime, omitted from canonical serialization when unset. column holds the source availability instant as timestamptz, which landing keeps and availability bounds compare alone; zone defaults to UTC. and content_hash_column under table-blockstore.declare.table-blockA table block takes TableDecl, canonical serialization omitting unset keys. A key applies from the next read, rewriting no committed part; columns types every landing under typed-landing., carrying both into every read and landing.
  Why

  because a conclusion’s publication time differs from its economic validity and shared availability bounds exclude later conclusions from historical recall

synthesize

Claim extraction, entity resolution, consolidation, evidence, deduplication, audit records and coverage gaps.

• extract-attemptstestFor a schema-invalid response, the synthesis pass retries extraction with validation feedback. Each batch receives at most 3 attempts in total.
• dead-lettertestA batch exhausting extract-attemptsread.synthesize.extract-attemptsFor a schema-invalid response, the synthesis pass retries extraction with validation feedback. Each batch receives at most 3 attempts in total. writes the response, template hash and drop reason to the dead-letter table, raises MemoryExtractExhausted, and leaves the cursor unadvanced.
  Why

  A-read#memory-writes-validate
• dead-letter-evidencetestEvery dead letter a synthesis batch writes carries evidence, the {table, run, seq} reference of each source row the batch carries.
  Why

  because a dead letter repeats its batch’s content, and erasure finds that content through the rows it came from
• pass-cursortestThrough the writing credential’s session, synthesis reads committed source rows absent from its cursor, in batches under prompt-boundread.synthesize.prompt-boundA batch packs marked rows up to 32 KiB; a marked row over that bound travels in a batch of its own.. The cursor records each batch after its claims commit.
• prompt-boundtestA batch packs marked rows up to 32 KiB; a marked row over that bound travels in a batch of its own.
  Why

  because one oversized row neither stalls the pass nor drags its neighbours past the bound
• row-captestSynthesis marks each row, capped at 16384 chars under value-capconnector.infer.value-capMarking removes control characters other than newline and tab from a value, and a value past its declared character cap keeps its first cap characters and a truncation mark, its closing line still following.. Truncated rows reach the model; their batch commits and advances the cursor. The pass report counts these rows in truncated.
  Why

  because a silent cut hides that a conclusion rests on a partial row
• attributiontestEvery landed claim carries grant_id, the chain-final revocation identifier of the credential that wrote it, agent, that credential’s agent member, and _authored_by, its on-behalf-of principal.
  Why

  because a reader weighs a conclusion by which grant could have produced it
• claim-tainttestA source row carries its own _taint, else ingested:third-party. Every row a batch commits lands under taintstore.reserve.taintOn each row from model output, the engine injects _taint under provenance-order, replacing any producer value; other rows omit _taint. with the least-trusted label among the batch’s rows.
  Why

  because a row no label vouches for is trusted least, and a claim re-synthesized from claims stays as low as its origin
• cadencetestBy default, contextful memory synthesize starts synthesis. A scheduled [[job]] of kind synthesize targeting the claims table replaces that default. Each execution advances only through pass-cursorread.synthesize.pass-cursorThrough the writing credential's session, synthesis reads committed source rows absent from its cursor, in batches under prompt-bound. The cursor records each batch after its claims commit..
  Why

  A-read#gleaning-declared-single
• confidence-calibrationtestModel-emitted confidence carries uncalibrated until a shape-and-predicate isotonic map trained on settled outcomes lowers held-out Brier score. A validated map supplies the reported calibrated confidence.
  Why

  A-read#memory-confidence-retention

unsettled: Which consolidation merges two claims of one dedup key, and what record does a coverage gap leave? owner: read-path affects: read.synthesize

revise

Claim replacement within a validity interval, confidence decay, direct writes, timestamps, expiry, retention and promotion.

• tiertestThe writer assigns tier, a Tier, from write method and grounding, excluding payload values: synthesis uses derived, direct writes use curated, fetched results use researched. Mixed grounding takes the lowest tier.
  Why

  A-read#claim-standing-derived
• supersedetestAn equal-or-higher-tier claim replaces a live prior matching subject, predicate and scope when both are open-ended or share valid-from, except unscoped-collisionread.revise.unscoped-collisionUnscoped direct writes sharing subject, predicate and valid-from but different objects record both claim ids in the dead-letter table. Neither claim replaces the other until an explicit revision resolves the conflict.. The prior ends at the successor’s start and names the successor.
  Why

  A-read#claim-standing-derived
• direct-writetestThe direct write accepts claims alone. Naming memory_episodes, memory_entities, memory_edges or memory_preferences raises MemoryDirectWriteShapeRefused; an entity row enters through entity-upsertread.resolve-entity.entity-upsertcontextful memory entity upsert --table <entities> --id <id> --kind <kind> --name <name> [--alias <alias>]... writes one row to the first declared memory_entities table. Synthesis resolves against that table; upsert requires its read and write grants..
  Why

  A-read#agent-third-party
• observed-attestcontextful memory write --observed-at <instant> lands the claim with valid_from at that instant; without it, valid_from is the write’s own instant.
• dedup-keytest--dedup-key <key> derives claim_id from the key beside the subject, predicate, object and scope, and a write whose claim_id the table already holds lands nothing.
  Why

  because a retried write restates one observation, while one fact observed twice under two keys keeps two validity intervals
• observed-ordertestFor matching subject, predicate and scope with a different object, a write whose valid_from precedes an unsuperseded claim’s valid_from raises MemoryObservationOutOfOrder. The write stores nothing.
  Why

  because retiring the later claim at the earlier instant ends it before it starts, and it then answers at no instant
• citation-livetestIf a cited keyed-table row reads through the writer’s session as a replaced key version, a direct write raises MemoryCitationNotLive. The write stores nothing.
  Why

  because such a claim rests on a replaced version from its first read, while a citation no readable row carries lands undigested and recall withholds it
• unscoped-collisiontestUnscoped direct writes sharing subject, predicate and valid-from but different objects record both claim ids in the dead-letter table. Neither claim replaces the other until an explicit revision resolves the conflict.
  Why

  A-read#claim-standing-derived
• retention-defaulttestClaims retain recorded validity until explicit expiry or erasure. With decay_half_life, ranked scores decrease by half per half-life since valid_from. Score decay neither deletes claims nor changes validity.
  Why

  A-read#memory-confidence-retention
• served-writetestA writable HTTP server accepts POST /memory/claims under per-request network credentials and stores declared claims through the direct-write operation. The read MCP tool set remains closed.
  Why

  A-read#served-claim-write
• served-scopetestA claim write raises MemoryClaimScopeRefused if actor differs from admitted on_behalf_of, session differs from admitted task, or session contains a colon. Accepted claims take scope from credential members rather than payload values.
  Why

  A-read#served-claim-write
• browser-requesttestAn Origin header on the served claim-write route raises MemoryClaimBrowserRefused before credential admission and commits nothing.
  Why

  A-read#served-claim-write
• malformed-requesttestMalformed JSON, unknown fields, a client-selected claim scope, or an empty dedup key on the served claim-write route raises MemoryClaimMalformed and commits nothing.
  Why

  A-read#served-claim-write
• served-deduptestA served claim write passes its dedup_key to dedup-keyread.revise.dedup-key--dedup-key <key> derives claim_id from the key beside the subject, predicate, object and scope, and a write whose claim_id the table already holds lands nothing., returns landed: false on restatement, and returns the bound scope on both outcomes.
  Why

  A-read#served-claim-write
• served-faulttestA served claim write whose store effect refuses raises MemoryClaimWriteRefused and lands nothing.
  Why

  A-read#served-claim-write

unsettled: What binds the asserted agent member to the writer? owner: authority affects: read.revise

unsettled: What declared bound expires a researched claim, and which served write promotes a claim to curated? owner: read-path affects: read.revise

recall

Ranked and keyed claim retrieval, read timestamps, tier ordering, scope and tombstone filters, and evidence checks.

• evidence-unresolvedtestAn unreadable or masked source row, an unknown table, a reference into another memory row, or malformed lineage suppresses the claim and raises MemoryEvidenceUnresolved.
  Why

  A-read#memory-access-follows
• evidence-referencestestFor claims citing more than 256 entries of evidence, recall returns the first 256 in cited table, run and sequence order. evidence_omitted reports the remaining count.
  Why

  A-read#memory-access-follows
• evidence-omitted-columntestevidence_omitted is a reserved projected column of ranked-armread.recall.ranked-armFor memory_facts, corpus.retrieve returns only claims without superseded_by and with valid_to null or after the read's anchor. Each claim's evidence passes the evidence check., null for a row outside a memory_facts table under reserved-columns-project-nullread.retrieve.reserved-columns-project-nullReserved projected columns — modality, language, prompt hash, kind — render null for a table lacking them, and its rows stay in the union..
• evidence-gate-boundtestRecall suppresses a claim with more than 4096 entries of evidence as unresolved and raises MemoryEvidenceOverflow.
  Why

  A-read#memory-access-follows
• evidence-keytestClaim writes stamp each citation to a keyed table with a pepper-keyed digest of the cited row’s key. If that row is unreadable, recall resolves the digest’s live version.
  Why

  A-read#citation-keyed-table
• evidence-key-maskedtestIf the writer’s session masks or zone-nulls a cited key column, the citation carries no digest. Masked or nulled non-key columns leave the digest intact.
  Why

  because a masked key cell digests a value no other session reads, while a cell outside the key plays no part in matching it
• evidence-no-valuetestA citation stored in a memory row carries the cited table, run, sequence and key digest, and no cell value of the cited row.
  Why

  A-read#citation-keyed-table
• evidence-staletestRecall counts a served claim under stale in contextful.recall if the key digest resolves while the cited run and sequence are unreadable. The block names no claim.
  Why

  A-read#citation-keyed-table
• ranked-armtestFor memory_facts, corpus.retrieve returns only claims without superseded_by and with valid_to null or after the read’s anchor. Each claim’s evidence passes the evidence check.
• recall-block-presencetestA corpus.retrieve response carries the contextful.recall block exactly when one of its arms reads a memory_facts table, whichever of prefix and tables chose the arms.
  Why

  because the block counts what claim arms withheld, and a read with no claim arm withheld no claim
• suppression-counttestA suppressed claim is absent from the rows; the contextful.recall block counts suppressions per error identifier and names no claim.
  Why

  because a count discloses that a conclusion was withheld, never what it concluded
• keyedtestmemory.recall accepts table, subject, observed_at, as_of_ingest and limit. Returned claims match subject exactly, with valid_from and valid_to covering observed_at under valid-as-ofstore.bound-time.valid-as-ofvalid_as_of filters the same inner source with from <= valid_as_of AND (to IS NULL OR to > valid_as_of) over the declared pair..
• cli-verbtestcontextful memory recall forwards arguments to memory.recall and prints the tool’s JSON response. The command appends the call’s read entry under read-entrydisclosure.record.read-entryEach read tool call the face answers with a result, over stdio or HTTP, appends one entry, and the result leaves only after that entry's append group syncs; initialize, ping and tools/list append none..
• keyed-clockstestas_of_ingest bounds reads under as-ofstore.bound-time.as-ofInside each table's FROM-source, as_of selects the newest reachable snapshot created at or before the bound plus the committed runs at or before it that the snapshot omits.; without that argument, reads use the latest committed state. Missing observed_at defaults to the call’s instant. contextful.bounds echoes supplied bounds by argument name with a per-name inclusive map.
• keyed-historytestKeyed recall returns a replaced claim for observed_at within that claim’s validity interval. The query filters by validity alone, excluding superseded_by from filtering.
  Why

  because the question is what held at that instant, and the retired claim is the answer its interval records
• keyed-gatetestEvery keyed claim passes evidence-gate-boundread.recall.evidence-gate-boundRecall suppresses a claim with more than 4096 entries of evidence as unresolved and raises MemoryEvidenceOverflow., and every evidence entry, served or omitted, passes evidence-unresolvedread.recall.evidence-unresolvedAn unreadable or masked source row, an unknown table, a reference into another memory row, or malformed lineage suppresses the claim and raises MemoryEvidenceUnresolved.; the response carries suppression-countread.recall.suppression-countA suppressed claim is absent from the rows; the contextful.recall block counts suppressions per error identifier and names no claim..
• keyed-windowtestKeyed recall checks claims in order and stops after retaining one claim beyond the row ceiling. The suppression count covers claims checked before that stop.
  Why

  because a one-row recall over a subject with thousands of claims otherwise resolves every claim’s evidence
• keyed-evidence-batchtestThe keyed read resolves a claim’s citations into one table and run with one statement, listed among the executed SQL under internals: true.
  Why

  because one statement per citation costs a claim at the gate bound one engine round trip per entry
• keyed-ordertestKeyed claims order by tier, curated first, then valid_from, newest first, then claim_id; limit and the table’s ceilings bound them under row-ceilingread.respond.row-ceilingThe executor applies each table's limits.max_rows to delivered rows. Truncation detection uses an extra-row probe (1 rows). This ceiling limits no work performed..
• keyed-not-claimstestA granted table declaring a shape other than memory_facts, or no memory shape, raises MemoryRecallNotClaims.
  Why

  because a keyed read answers with a claim’s subject, validity and evidence, which no other table carries
• confidence-labeltestEach keyed claim’s confidence_label is calibrated or uncalibrated under confidence-calibrationread.synthesize.confidence-calibrationModel-emitted confidence carries uncalibrated until a shape-and-predicate isotonic map trained on settled outcomes lowers held-out Brier score. A validated map supplies the reported calibrated confidence.. Fitting uses the declared labels table, joining prediction_id to claim_id through the caller’s session.
  Why

  A-read#claim-standing-derived
• stale-revisiontestA stale citation remains subject to keyed-gateread.recall.keyed-gateEvery keyed claim passes evidence-gate-bound, and every evidence entry, served or omitted, passes evidence-unresolved; the response carries suppression-count.; only a newly committed source row advancing pass-cursorread.synthesize.pass-cursorThrough the writing credential's session, synthesis reads committed source rows absent from its cursor, in batches under prompt-bound. The cursor records each batch after its claims commit. starts synthesis against its live key version.
  Why

  A-read#claim-standing-derived
• usage-ledgertestmemory.recall, memory.explain responses carrying claims, and corpus.retrieve responses containing memory_facts record returned claim ids as contextful.memory.claims. The read entry includes caller credential, subject and read instant.
  Why

  A-read#memory-reads-expose

Scenarios

• read.recall.evidence-referencesread.recall.evidence-referencesFor claims citing more than 256 entries of evidence, recall returns the first 256 in cited table, run and sequence order. evidence_omitted reports the remaining count.: WHEN a claim cites 300 readable rows, THEN recall serves 256 entries with evidence_omitted = 44.
• read.recall.evidence-unresolvedread.recall.evidence-unresolvedAn unreadable or masked source row, an unknown table, a reference into another memory row, or malformed lineage suppresses the claim and raises MemoryEvidenceUnresolved.: WHEN entry 290 of 300 reads masked, THEN the claim is suppressed with MemoryEvidenceUnresolvedread.recall.evidence-unresolvedAn unreadable or masked source row, an unknown table, a reference into another memory row, or malformed lineage suppresses the claim and raises MemoryEvidenceUnresolved..

resolve-entity

Entity matching, aliases, identity cards, location relationships, edges and ownership queries.

• ambiguous-mentiontestIf a mention matches two canonical identities with no deterministic distinguishing key, resolution records an ambiguous skip, raises MemoryEntityAmbiguous and dead-letters the candidate claim.
  Why

  A-read#memory-writes-validate
• edge-endpointtestIf a candidate edge’s source or target resolves to no identity, resolution dead-letters the edge and raises MemoryEdgeEndpointUnresolved.
  Why

  A-read#memory-writes-validate
• graph-indextestExternal graph engines index admitted memory edges as derived data. Entity and ownership answers resolve through access-controlled store rows at the read frontier.
  Why

  A-read#memory-reads-expose
• ownership-answertestOwnership queries return targets of every caller-visible owned_by edge from the artifact. Results sort by newest _ingested_at, then principal id for equal timestamps.
  Why

  A-read#memory-reads-expose
• knowledge-cardtestmemory.explain accepts table, reference and an optional claims table. The tool resolves reference against table’s names and aliases and returns the identity’s entity_id, kind, name and aliases.
  Why

  because a caller holding a name or an alias in any script needs the canonical record without knowing its opaque id
• card-claimstestA card naming claims carries the claims keyedread.recall.keyedmemory.recall accepts table, subject, observed_at, as_of_ingest and limit. Returned claims match subject exactly, with valid_from and valid_to covering observed_at under valid-as-of. returns at the call instant, under keyed-gateread.recall.keyed-gateEvery keyed claim passes evidence-gate-bound, and every evidence entry, served or omitted, passes evidence-unresolved; the response carries suppression-count., whose subject equals the identity’s entity_id or its canonical name.
  Why

  because synthesis keys a resolved claim by canonical name and claim_id hashes the subject, so re-keying stored claims by id re-identifies every one
• card-candidatestestIf reference matches multiple identities without an exact canonical-name match distinguishing one, the card returns candidate entity_ids and no identity. With no matches, the card is empty.
  Why

  because naming one of several matches guesses on the caller’s behalf, and an absent identity is an answer, not a fault
• card-authorizationtestCards read table and claims through the caller’s session. Without a registered claims relation, cards return only identity. Cards without claims omit the claims table’s name from the response and read entry.
  Why

  because a grant on identities is narrower than a grant on what the workspace concludes about them
• card-cli-verbtestcontextful memory explain forwards its arguments, including --internals, to memory.explain. The command prints the tool’s JSON response and appends the same read entry.
  Why

  because a read outside the audit chain is a read no owner can account for
• card-not-entitiestestA granted table declaring a shape other than memory_entities, or no memory shape, raises MemoryExplainNotEntities.
  Why

  because only a memory_entities table carries the identity, kind and aliases a card returns
• entity-upserttestcontextful memory entity upsert --table <entities> --id <id> --kind <kind> --name <name> [--alias <alias>]... writes one row to the first declared memory_entities table. Synthesis resolves against that table; upsert requires its read and write grants.
  Why

  because the claim write refuses entity rows, and an operator still names the identities mentions resolve to
• upsert-fieldstestBefore comparison or storage, upsert trims id, kind, name and each alias. An empty trimmed value raises MemoryEntityFieldEmpty and writes nothing.
  Why

  because a blank identity or alias matches no mention, and surrounding whitespace lands a second spelling of a held name
• upsert-mergetestFor an existing entity_id, upsert replaces kind and name, retaining stored aliases first. Supplied aliases follow, excluding those matching a stored alias after case-folding.
  Why

  because an alias an earlier upsert recorded keeps naming the entity for mentions already written with it
• alias-conflicttestAn upsert whose name or alias matches, case-folded, the name or an alias of another entity the session reads raises MemoryEntityAliasConflict, and nothing lands.
  Why

  because a mention two identities share resolves to neither: synthesis skips it under ambiguous-mentionread.resolve-entity.ambiguous-mentionIf a mention matches two canonical identities with no deterministic distinguishing key, resolution records an ambiguous skip, raises MemoryEntityAmbiguous and dead-letters the candidate claim. and a card lists candidates under card-candidatesread.resolve-entity.card-candidatesIf reference matches multiple identities without an exact canonical-name match distinguishing one, the card returns candidate entity_ids and no identity. With no matches, the card is empty.
• upsert-whole-tabletestAn upsert whose session read of the entities table returns truncated raises MemoryEntityTableTruncated, and nothing lands.
  Why

  because a merge over a cut read drops the held row’s aliases, and a conflict check over it misses the entity that carries the mention
• upsert-serialtestUpsert holds the table’s upsert lock during reading, conflict checking and storage. The new timestamp follows the stored row’s _ingested_at. Concurrent upserts on one table execute serially.
  Why

  because two upserts merging one snapshot lose an alias, and two checking one snapshot both claim one mention
• upsert-availabilitytestAn upsert into an entities table declaring available_time raises MemoryEntityAvailabilityDeclared, and nothing lands.
  Why

  because an operator’s identity carries no source availability instant, and a vintage table keeps the prior row beside the one an upsert replaces

unsettled: Which edges carry aliases and nearness’s parent closure? owner: read-path affects: read.resolve-entity

Scenarios

• read.resolve-entity.knowledge-cardread.resolve-entity.knowledge-cardmemory.explain accepts table, reference and an optional claims table. The tool resolves reference against table's names and aliases and returns the identity's entity_id, kind, name and aliases.: WHEN reference is an alias written in another script, THEN memory.explain returns the one identity carrying it.
• read.resolve-entity.card-candidatesread.resolve-entity.card-candidatesIf reference matches multiple identities without an exact canonical-name match distinguishing one, the card returns candidate entity_ids and no identity. With no matches, the card is empty.: WHEN reference is an alias two identities share, THEN the card lists both entity_ids and no identity.
• read.resolve-entity.card-authorizationread.resolve-entity.card-authorizationCards read table and claims through the caller's session. Without a registered claims relation, cards return only identity. Cards without claims omit the claims table's name from the response and read entry.: WHEN the caller holds a read grant on table and none on claims, THEN the card carries the identity and no claims.

settle

Prediction registration, observations, required verdict citations and outcome label views.

• registrationtestA registration requires one form (relative horizon, absolute deadline, open watch) and one source (metric, adjudicator, manual). Only metric requires and permits a comparator. Invalid registrations raise OutcomeRegistrationInvalid.
  Why

  A-read#memory-writes-validate
• source-mismatchtestAn observation raises OutcomeSourceMismatch if its metric series differs from registration, or its verdict’s resolution source or registered series is missing or differs. The error names each source by wire name.
  Why

  A-read#memory-writes-validate
• settling-citationtestAn adjudicator or manual verdict without an http or https settling citation raises OutcomeCitationMissing. The label view includes the citation.
  Why

  A-read#memory-writes-validate
• grace-windowtestThe label join keeps an observation from the prediction instant through the deadline plus an inclusive grace of 86400 s.
• calibration-reporttestCalibration reports group settled predictions by shape and predicate. Each group reports sample count, Brier score, expected calibration error over 10 equal-width bins, and confidence-calibrationread.synthesize.confidence-calibrationModel-emitted confidence carries uncalibrated until a shape-and-predicate isotonic map trained on settled outcomes lowers held-out Brier score. A validated map supplies the reported calibrated confidence.‘s held-out score over every fifth prediction.
  Why

  A-read#memory-writes-validate
• statement-boundtestA registration’s optional statement holds the falsifiable claim and participates in registration-conflictread.settle.registration-conflictA registration whose prediction_id a stored registration with any other field already holds raises OutcomeRegistrationConflict, and nothing lands.. Text exceeding 4096 B raises OutcomeStatementTooLong.
  Why

  because a registration reads on its own only with its claim text, and an unbounded text field lets one row outweigh the table
• metric-referencetestOptional metric uses <table>:<series_id> with non-empty parts and names the series without a store lookup. Malformed references or references under a source other than metric raise OutcomeMetricReferenceInvalid.
  Why

  because a registration precedes its series’ first landing, so a store lookup refuses every prediction made before its data exists
• deadline-datetestA bare YYYY-MM-DD in deadline_at resolves under instant-comparisonstore.bound-time.instant-comparisonEvery bound compares instants as timestamps, not strings; a date-only literal resolves to the start of the next day, exclusive. to the next UTC midnight. The entire named day precedes the deadline.
  Why

  because one date spelling then means one instant on every clock the engine compares
• predict-verbtestcontextful memory predict --into <table> --registration <json> validates registrationread.settle.registrationA registration requires one form (relative horizon, absolute deadline, open watch) and one source (metric, adjudicator, manual). Only metric requires and permits a comparator. Invalid registrations raise OutcomeRegistrationInvalid.. Under the admitted credential’s write grant, the command stores the registration in that predictions table and prints prediction_id: <id>.
  Why

  because a registration nothing lands leaves its outcome no prediction to settle against
• observe-verbtestcontextful memory observe --into <table> --observation <json> reads the stored prediction registration through the writer’s session. After checking source-mismatchread.settle.source-mismatchAn observation raises OutcomeSourceMismatch if its metric series differs from registration, or its verdict's resolution source or registered series is missing or differs. The error names each source by wire name. and settling-citationread.settle.settling-citationAn adjudicator or manual verdict without an http or https settling citation raises OutcomeCitationMissing. The label view includes the citation., the command stores the observation in that outcomes table and prints its label row.
  Why

  because a verdict is checked against the source registered before it, never one the observation asserts
• verb-attributiontestBoth verbs admit a capability token as contextful memory write does, and each landed row carries _authored_by from its subject under injectedstore.reserve.injectedThe engine injects non-null _ingested_at as Parquet TIMESTAMP(UTC, NANOS), _run_id, _site_id, int32 _batch_seq within a batch scope, and _authored_by for writes an authenticated subject authorized, replacing producer values..
  Why

  because a settled outcome is weighed by who registered and who observed it
• prediction-unregisteredtestAn observation naming a prediction_id no row of the declared predictions table carries in the writer’s session raises OutcomePredictionUnregistered, and nothing lands.
  Why

  because a verdict with no registration has no source to check it against
• restated-landingtestA registration or observation identical to the stored row of its prediction_id lands nothing, and the verb succeeds with its usual output.
  Why

  because a retried verb restates one registration, and landing it again commits a run that records nothing new
• registration-conflicttestA registration whose prediction_id a stored registration with any other field already holds raises OutcomeRegistrationConflict, and nothing lands.
  Why

  because rewriting a registration after the fact changes the deadline or source a verdict is scored against
• outcome-settledtestIf an observation differs from a stored verdict-bearing outcome for its prediction_id, the write raises OutcomeAlreadySettled. Observations replace stored outcomes without verdicts.
  Why

  because a verdict rewritten after scoring silently changes the calibration it fed
• label-jointestThe label view of Shapes runs over a declared predictions and outcomes table pair as read through the reader’s session.
  Why

  because the view’s grace window and self-rated filter then hold for every reader, not each reader’s own join
• calibration-verbtestcontextful memory calibration --table <claims> joins verdict-bearing labels to claims by prediction_id = claim_id through the caller’s session. The command prints calibration-reportread.settle.calibration-reportCalibration reports group settled predictions by shape and predicate. Each group reports sample count, Brier score, expected calibration error over 10 equal-width bins, and confidence-calibration's held-out score over every fifth prediction. with joined-prediction count, using JSON under --json.
  Why

  because a prediction’s shape, predicate and emitted confidence are those of the claim it scores

traverse

Graph traversal from a seed entity, bounded by time, hop count and readable edges in the caller’s session.

• calltestmemory.traverse accepts table, seed, rel_types, hops, as_of_ingest, observed_at and available_as_of. Under one frozen anchor, the tool returns reached edges whose valid_from and valid_to cover observed_at, using one-projectionread.respond.one-projectionCLI JSON output, HTTP and the tool protocol serialize the same response: columns, rows, truncated, and optional restriction, resolved-build, provenance, retrieval and time-bound blocks..
• clockstestMissing as_of_ingest uses the latest committed state; missing observed_at uses the call’s instant; missing hops defaults to 1. contextful.bounds echoes each supplied bound under keyed-clocksread.recall.keyed-clocksas_of_ingest bounds reads under as-of; without that argument, reads use the latest committed state. Missing observed_at defaults to the call's instant. contextful.bounds echoes supplied bounds by argument name with a per-name inclusive map..
• cli-verbtestThe contextful memory traverse verb passes its arguments through callread.traverse.callmemory.traverse accepts table, seed, rel_types, hops, as_of_ingest, observed_at and available_as_of. Under one frozen anchor, the tool returns reached edges whose valid_from and valid_to cover observed_at, using one-projection. and prints the same JSON response.
• enforced-edgestestEvery edge reads through the caller’s enforced session, and each edge’s citations pass evidence-unresolvedread.recall.evidence-unresolvedAn unreadable or masked source row, an unknown table, a reference into another memory row, or malformed lineage suppresses the claim and raises MemoryEvidenceUnresolved.; an edge failing either is neither returned nor walked through.
  Why

  because walking through a hidden edge reveals the node beyond it
• enginetestAn engine-backed walk answers through graph-indexread.resolve-entity.graph-indexExternal graph engines index admitted memory edges as derived data. Entity and ownership answers resolve through access-controlled store rows at the read frontier..
• directiontestA walk follows a directed relation from source_id to target_id and an undirected relation both ways. An absent rel_types walks every walkable relation.
  Why

  because an undirected relation holds from both of its ends
• not-edgestestA table declaring no memory_edges shape raises MemoryTraverseNotEdges.
  Why

  because a walk over another shape has no edge columns to read
• open-validitytestAn edge table declaring no valid_from or valid_to column holds each edge at every observed_at and orders a node’s edges by edge id.
  Why

  because the memory_edges shape requires neither column
• walkabletestA rel_types entry whose declared relation is not walkable raises MemoryTraverseRelationUnwalkable.
  Why

  A-read#traversal-walks-enforced
• hop-boundtestA walk follows at most 3 hops; a larger hops raises MemoryTraverseHopsExceeded.
  Why

  A-read#traversal-walks-enforced
• fan-outtestA node expands at most 64 memory-edges, ordered by valid_from newest first then edge id; the rest count in edges_omitted.
  Why

  A-read#traversal-walks-enforced
• frontier-captestA walk stops at 512 memory-edges and counts unexpanded edges in edges_omitted; a non-zero edges_omitted marks the walk incomplete, and truncated stays with truncation-causeread.respond.truncation-causeA truncated response carries contextful.truncation with by, ceiling and source: rows admits grant, table, request, template or face; bytes admits grant, table or request..
  Why

  A-read#traversal-walks-enforced
• omitted-readabletestedges_omitted counts only edges the caller’s session reads.
  Why

  because a count of hidden edges discloses their existence, as suppression-countread.recall.suppression-countA suppressed claim is absent from the rows; the contextful.recall block counts suppressions per error identifier and names no claim. avoids naming claims
• cycletestTraversal proceeds breadth-first by hop and expands each node at most once.
  Why

  because a revisited node adds no edge and a cycle otherwise exhausts frontier-capread.traverse.frontier-capA walk stops at 512 memory-edges and counts unexpanded edges in edges_omitted; a non-zero edges_omitted marks the walk incomplete, and truncated stays with truncation-cause.

unsettled: Does a graph arm seeded by the query’s resolved entities fuse into fusionread.rank.fusionFusion computes w_vec · clamp(cosine, 0, 1) + w_lex · rrf(bm25). Weights are 60 percent and 40 percent. rrf maps BM25 rank r to 61 / (60 + r). Absent documents score zero per leg; identifiers break ties. as a third leg, and at what weight? owner: read-path affects: read.traverse

Shapes

A declaration naming a shape and its declared relation types:

[[table]]
name  = "team_memory"
shape = "memory_facts"

[[relation.declared]]
name        = "reports_to"
direction   = "directed"
cardinality = "one"
walkable    = true

[[relation.declared]]
name        = "owns_service"
direction   = "directed"
cardinality = "many"
walkable    = true

The reserved-traits table:

The label view:

CREATE VIEW outcome_labels AS
SELECT p.prediction_id, p.subject, p.resolution_source,
       o.verdict, o.signal, o.settling_citation,
       epoch(CAST(o.observed_at AS TIMESTAMP)) - epoch(CAST(p.predicted_at AS TIMESTAMP)) AS lead_time_s
FROM predictions p
JOIN outcomes o ON o.prediction_id = p.prediction_id
WHERE o.observed_at IS NOT NULL
  AND o.signal IS DISTINCT FROM 'self-rated'
  AND epoch(CAST(o.observed_at AS TIMESTAMP)) >= epoch(CAST(p.predicted_at AS TIMESTAMP))
  AND epoch(CAST(o.observed_at AS TIMESTAMP)) <= epoch(CAST(p.deadline_at AS TIMESTAMP)) + 86400;