Contextfulv0.23.0

Docs / Guides

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

Reading and memory

The problem the read face solves

A caller, such as an agent holding a capability token, asks questions of stored tables. The caller sees only rows its grant admits, and no read writes a row. SQL queries, ranked retrieval and memory recall all pass through the same registered relations and return the same response shape.

The example agent wants the current status of one resource.

Naming what a caller reads

Each session connection registers one view per manifest table (connection-views). A bare table name in the caller’s SQL resolves to that caller’s restricted view (bare-name). The face exposes a closed tool set, so a caller reaches nothing outside it (tool-set).

The agent first calls context.describe and learns row counts, declared indexes and the published row ceiling (describe-payload).

Which statements run

The guard reads the SQL engine’s own parse tree, so no keyword list decides admission (engine-own-parse). The text has to parse to exactly one read-only SELECT (single-read-only-statement).

The agent joins documents to a read_parquet call, and the guard refuses the table function (table-function). It retries with a join to a table it holds no grant on; the error echoes only the requested name (unregistered-relation).

Operator statements run without that guard, and no network interface exposes them (statement-provenance). The operator runs a raw statement with contextful query (operator-verb).

Sequence diagram Sequence diagram. 5 participants, 9 messages. Participants: agent (A), tool server (T), statement guard (G), caller views (V), store (S). 1. agent → tool server: context.query with a token 2. tool server → caller views: register one view per table 3. tool server → statement guard: parse and walk the statement alt write, table function or unregistered name: 4. statement guard --> agent: error naming only the request else one read-only SELECT: 5. statement guard → caller views: run over restricted relations 6. caller views → store: scan committed parts 7. store --> caller views: rows 8. caller views --> tool server: admitted rows and cells 9. tool server --> agent: one envelope, exact truncated flag read altwrite, table function orunregistered nameone read-only SELECT agentagent tool servertool server statement guardstatement guard caller viewscaller views storestore context.query with a token register one view per table parse and walk the statement error naming only the request run over restricted relations scan committed parts rows admitted rows and cells one envelope, exacttruncated flag

The response

Every transport serializes one projection: columns, rows, truncated and optional blocks (one-projection). The serializer sets truncated from an over-fetched probe row, not from comparing counts (truncation-is-exact). Zero rows is a success, not an error (zero-rows-is-success).

Ranked retrieval

The agent switches to corpus.retrieve with the query “resource status” and a filter on resource_id (ranked-call). A table lacking resource_id contributes no rows instead of running unfiltered (unsatisfiable-arm-drops).

Ranking fuses vector cosine with lexical BM25 scores (fusion). A question’s timeframe orders rows but drops none (question-window-is-a-tier). Each stored vector sits beside the name of the model that produced it (model-identifier), so the rows themselves record which model embedded them.

To report that no document mentions a status change, the agent counts rows. A low top score proves no absence (coverage-is-a-count).

Sequence diagram Sequence diagram. 4 participants, 8 messages. Participants: agent (A), retrieval (R), table arm (W), vector sidecar (X). 1. agent → retrieval: corpus.retrieve with query and filter 2. retrieval → retrieval: split query into content tokens loop each registered table: 3. retrieval → table arm: recency-ordered candidate window opt sidecar under its size cap: 4. table arm → vector sidecar: nearest neighbours 5. vector sidecar --> table arm: candidates re-joined through enforcement 6. table arm --> retrieval: candidates above the relevance floor 7. retrieval → retrieval: fuse cosine and BM25, window first 8. retrieval --> agent: ranked rows with the retrieval block read loopeach registered table optsidecar under its size cap agentagent retrievalretrieval table armtable arm vector sidecarvector sidecar corpus.retrieve with queryand filter split query into contenttokens recency-ordered candidatewindow nearest neighbours candidates re-joined throughenforcement candidates above therelevance floor fuse cosine and BM25,window first ranked rows with the retrievalblock

Reads under one key reuse a pooled session and its connections (session-pool).

Reading at an earlier time

Every read tool takes three bounds: as_of freezes the corpus, valid_as_of picks what was true, and available_as_of sets a simulated present. An ASOF JOIN matches each row on availability (per-row-bound).

A read naming a published model build resolves that build, and an unknown build fails instead of widening to the latest state (unknown-build).

A credential carrying a horizon caps the simulated present. A call asking for a later available_as_of fails, naming the argument (exceeds-horizon).

Sequence diagram Sequence diagram. 4 participants, 9 messages. Participants: agent (A), tool server (T), as-of join (J), committed parts (S). 1. agent → tool server: context.query with three bounds 2. tool server → committed parts: scan snapshots committed by as_of Note over tool server,committed parts: as_of freezes the corpus for the whole eval 3. tool server → committed parts: keep rows valid at valid_as_of 4. tool server → committed parts: keep rows available by available_as_of Note over tool server,committed parts: available_as_of is the simulated present 5. tool server → as-of join: driving rows and right relation 6. as-of join → committed parts: right rows available by each driving instant 7. committed parts --> as-of join: latest available right row per key 8. as-of join --> tool server: joined rows 9. tool server --> agent: rows with the three bounds echoed read store agentagent tool servertool server as-of joinas-of join committed partscommitted parts as_of freezes the corpus forthe whole eval available_as_of is thesimulated present context.query with threebounds scan snapshots committed byas_of keep rows valid at valid_as_of keep rows available byavailable_as_of driving rows and right relation right rows available by eachdriving instant latest available right row perkey joined rows rows with the three boundsechoed

context.reference resolves one stored citation, and an erased source answers erased, distinct from missing (erased-verdict).

context.lineage answers which tables, models and steps feed one another (call). The caller’s session narrows the graph: a table it cannot read leaves the answer and remains only as a count (withheld-count).

Notifications

A subscription notifies each committed run once, in commit order, with no row content (commit-order). A resume position naming no committed run fails and names the oldest one available (position-unavailable).

Memory

Memory is claims about entities, kept in ordinary store tables with reserved relation types (reserved-relations). A synthesis pass extracts claims from source rows and retries an invalid response a bounded number of times (extract-attempts). An exhausted batch goes to a dead-letter table, and the cursor holds (dead-letter).

Sequence diagram Sequence diagram. 5 participants, 9 messages. Participants: synthesis pass (P), model endpoint (M), memory tables (T), recall (R), agent (A). 1. synthesis pass → model endpoint: extract from rows since the cursor 2. model endpoint --> synthesis pass: extracted claims alt invalid after bounded attempts: 3. synthesis pass → memory tables: dead-letter, cursor held else valid: 4. synthesis pass → memory tables: commit resolved, consolidated facts 5. agent → recall: recall about a vendor 6. recall → memory tables: read candidate facts 7. memory tables --> recall: facts with evidence references 8. recall → recall: read evidence through the caller's session 9. recall --> agent: facts whose evidence the caller reads run store read altinvalid after boundedattemptsvalid synthesis passsynthesis pass model endpointmodel endpoint memory tablesmemory tables recallrecall agentagent extract from rows since thecursor extracted claims dead-letter, cursor held commit resolved,consolidated facts recall about a vendor read candidate facts facts with evidencereferences read evidence through thecaller's session facts whose evidence thecaller reads

A mention matching two identities dead-letters its claim instead of guessing (ambiguous-mention). A writable server accepts operator claims through one direct-write route (served-write).

The agent asks memory what the workspace concluded about the resource. One fact cites a row masked for this caller, so recall suppresses that fact and answers with the rest (evidence-unresolved).

An edge walk follows only edges the caller reads, with citations that resolve (enforced-edges). A prediction registers through contextful memory predict and settles against later observations (predict-verb).