Quickstart

remember

Save durable context without silent overwrite: collisions are non-destructive, explicit replace updates in place, and supersede records lineage.

remember is the retention mechanic. It saves one confirmed piece of context — a project decision, definition, note, constraint, join path, or caveat — so your AI can use it in later sessions.

Save durable context after you confirm it. Agent-triggered writes are explicit tool calls; ClariLayer does not force every conversation detail into memory. You can correct, replace, supersede, or forget context as the work changes.

What it saves

remember saves one context entry. You give it a type and a name, the content to store, and optionally a SELECT query, structured metric contract, or CRM contract. A materially different entry with the same natural key is not overwritten silently; ClariLayer returns a structured collision and writes nothing until the caller makes the replacement decision explicit.

Typical things worth remembering:

a decision — "Show the product demo first and keep technical detail in the docs";
a project constraint — "This launch page is for individual AI workers, not the team pilot";
a definition — "Active Customer means an account with at least one billable subscription in the trailing 30 days, excluding internal test workspaces";
a schema note — "fct_orders.amount is in cents, not dollars";
a join path — "join users to orgs on users.org_id, never on email";
a gotcha — "refunds live in fct_refunds, so revenue queries must subtract them or they double-count."

How to run it

You rarely call remember directly; you let your agent do it as part of the conversation. A natural prompt:

Remember that our revenue numbers must subtract refunds from fct_refunds, or they double-count.

Your agent calls remember with that content, and it is saved to your store. A definition can also carry the SQL or strict CRM contract that backs it, which sets up a supported warehouse or HubSpot reconcile later.

Updating without silent overwrite

The default is non-destructive:

Repeating an identical (type, name) and payload is an idempotent no-op.
Sending materially different content for the same natural key returns a collision; the existing entry stays unchanged.
To overwrite that exact entry in place, reissue the exact key and payload with replace: true.

Natural-key collision detection normalizes case and whitespace, but replace: true targets the exact stored key. A case- or whitespace-variant request can therefore report a collision without becoming an alternate way to overwrite the original.

An in-place replacement returns the entry to asserted. If an existing structured metric or crm contract is omitted from the replacement payload, it is preserved; send metric: null or crm: null only when you intend to clear it.

Replacement versus supersede lineage

replace: true overwrites one entry in place; it does not create a historical lineage edge. When the old statement should remain visible as history, save the revised statement as a distinct entry, then call supersede to point the old entry to the new one. That marks the old entry superseded while keeping the replacement as the live context.

Status and provenance

A remembered or replaced entry is saved with status asserted and provenance you. asserted is the honest baseline: the entry has not been contradicted, but it is not stamped as proven. Provenance you records that you are the source, as opposed to something imported by bootstrap.

Remembering is not verifying. A saved definition has the same trust property as the words you typed. That is the gap reconcile narrows for its two supported adapters: warehouse actual_sample for SQL definitions and row-free HubSpot crm_evidence for CRM contracts. A mismatch becomes a caveat; a clean or inconclusive check remains asserted.

remember vs reconcile

remember captures a claim. It is fast and always available, and it is the right tool for institutional memory and corrections.
reconcile checks a captured claim against supported source evidence. It is how an asserted definition earns a caveat when its declaration and the observed evidence disagree.

Use remember for confirmed context worth carrying forward. Use reconcile when you want to know whether a supported SQL or HubSpot definition still holds against the evidence your agent collected.

After a confirmed live write, the managed completion loop calls context_checkpoint with the active entry as evidence. The durable, idempotent receipt persists the agent's context_updated declaration and validates ownership and eligibility of the referenced ClariLayer object. It does not independently prove the entry changed or that an external deployment or source result is correct.

It carries forward

Remembered entries persist and can be surfaced by recall in a later session. The context can travel across claude.ai, Claude Code, Cursor, and Codex, subject to each client's connection and recall behavior.