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 a single new piece of context — a metric definition, a schema note, a join path, a gotcha — so your agent keeps it across sessions. This is what makes ClariLayer feel like "Claude Code finally understands my project": the corrections you make stick, instead of evaporating when the conversation ends.

Every time you correct your agent, or it discovers how a metric is actually computed, that knowledge can be remembered once and recalled forever after. The longer you use it, the more grounded your agent gets on your data — and the more annoying it would be to lose.

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 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 constantly; 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 compounds

Because remembered entries persist and are surfaced by recall, each one makes the next session a little better. The context you build is the moat: it is yours, it travels across claude.ai, Claude Code, Cursor, and Codex, and it is the bridge to shared team context as your team adopts ClariLayer.