Guides

AI Agent Context Guide

Use a recall-first loop for durable project context, with explicit saves, corrections, optional Analytics reconciliation, and completion checkpoints.

Your AI should not lose a confirmed project decision when one session ends. With the ClariLayer MCP installed, it can recall the context you chose to save, use it in a later task, and keep its source and applicability visible. For supported Analytics definitions, it can also surface a caveat when reconciliation found a mismatch. This guide shows the working loop in practice.

If you have not connected yet, start with the Quickstart — connect Claude Code, Cursor, or Codex with a context key and add that local client's managed instructions, or add the production ClariLayer custom Connector to claude.ai over OAuth. This guide assumes your agent has general recall_context, remember, and context_checkpoint tools available. Analytics tools appear when their supported route is relevant.

Start with one useful rule

If your store is empty, follow the one-artifact step. Otherwise choose a saved rule and ask your agent a question using its name. Have the agent recall before answering. A browser preview is a scoped read; it does not establish agent use or correctness.

The recall-first loop

The working loop is five moves:

recall relevant general context with recall_context; for supported Analytics or CRM work, also use get_analysis_context when relevant (recall).
work from the recalled context, preserving its source and applicability. Carry Analytics trust status into specialist results.
remember a confirmed durable change. If the result is only a suggestion, propose it and stop for human acceptance instead of treating it as live context (remember).
reconcile a compatible live definition against the supported source evidence when the work checks or changes it (reconcile).
checkpoint only a confirmed live outcome, or a genuine no_update_required decision, with context_checkpoint before reporting the task complete. Proposal-only work cannot complete this loop.

When your agent recalls before answering, it can use your selected working context instead of starting from an empty session.

For a first task, saving one rule and recalling it is enough to inspect what the agent received. Reconcile is a follow-on for supported definitions, not a prerequisite for basic reuse or Engineering context.

Make recall the default

Installation and approval details

Recall is a tool your agent decides to call — ClariLayer exposes it, but it does not force a call. For Claude Code, Codex, or Cursor, use the Quickstart's client selector to copy one managed-install prompt. The selection targets exactly one local project instruction file; it never probes your browser or filesystem to guess. The claude.ai OAuth path connects as a custom Connector and does not install a project instruction file.

Copying the prompt is not a file write. Your local agent calls get_project_stanza, inspects only the selected target, and asks before editing. A recognized managed range can be updated without touching surrounding content. An exact legacy stanza can be migrated once; legacy text whose sentinel remains but whose full bytes differ, malformed markers, or incompatible Cursor frontmatter returns conflict/manual review with no change. For Claude Code and Codex, otherwise-unrecognized existing text is preserved while the managed range appends on first install. A current block returns already current; an approved create or update returns installed; declined approval stops without claiming an installation state.

The managed block tells future sessions to recall first, write confirmed durable changes, reconcile when appropriate, and call context_checkpoint before completion. This remains a behavioral protocol, not a technical guarantee that every arbitrary client will comply.

Reading what recall returns

General recall_context entries include the complete address needed for later retrieval:

summary and entry ID — a bounded preview plus the address for the full entry.
source — provenance and available capture-source metadata.
applicability — whether the context is general or bounded, with project references and conditions where present.

Analytics get_analysis_context entries carry content previews, provenance, asserted or caveat status, and a type/name address. There is no public query-history bootstrap source or importer.

Both recall paths return bounded previews. Call get_context_entry with the entry_id returned by general recall, or with the type/name address returned by Analytics recall, when you need the complete body, CRM contract, or stored SQL.

Use status to shape the answer. An asserted entry has not been contradicted, but it may be unreconciled, inconclusive, or cleanly reconciled, so ground on it without presenting it as proven. A caveat entry has a known mismatch, so carry the caveat into the answer. The stronger verified status remains gated and is not part of the live public result contract — see Verified vs Asserted for why.

For general recall, project and purpose are relevance hints, never access controls or hard filters. Preserve a bounded entry's applicability even when it is recalled elsewhere. For Analytics recall, use_case is a precision hint rather than a silent hard filter. Scoped and unscoped entries are preferred; if the scoped set is empty or weak, a strong cross-scope match can be returned with use_case_mismatch and the relevant warning fields. Use strict_use_case: true only when cross-scope rescue would be unsafe.

Remember confirmed changes as you go

When you confirm a durable decision — "lead the launch page with the product demo" — have your agent remember it so the next session can start from the same direction. A remembered entry is saved asserted with provenance you. Remembering stores the statement; it does not prove it correct.

Good things to remember include adopted product decisions, project constraints, preferred approaches, recurring caveats, and the precise Analytics inclusion and exclusion rules people rely on.

Reconcile when a number looks off

The acute moment is "why don't these two numbers match?" When it happens, have your agent reconcile the relevant definition. Capability v43 has two explicit live adapters: compatible stored SQL definitions plus warehouse actual_sample, and HubSpot CRM contracts plus bounded, row-free crm_evidence. HubSpot reconciliation is generally available to authenticated organizations behind the mandatory server-side global emergency switch. This explicit adapter boundary is not a claim that every source the agent can reach is already supported.

In the personal MCP reconcile path, ClariLayer does not receive your source credentials or run SQL server-side, and it never calls HubSpot. Your agent collects the supported evidence with its own authorized connection; the separately gated team connector surface uses only explicitly configured connectors under its own controls. For HubSpot, follow the single canonical complete capability-probed, row-free recipe; it defines pagination, caps, completeness, unavailable observations, and exact/lower-bound count semantics. Reconcile is how an asserted definition earns a caveat when it has drifted from the evidence.

Checkpoint the context decision before completion

Completion protocol and receipt limits

After the recall and any confirmed live write/reconcile, your agent calls context_checkpoint. A context_updated declaration must reference at least one active live context entry. A proposal can be included only as supplemental evidence; proposal-only work stops for human acceptance, remains pending review, and cannot claim completion. If the task made no durable context change, the agent can declare no_update_required only after checking the relevant facets and deciding the context was already current or the task changed nothing durable.

If the tool returns update_failed, the managed instructions tell the agent to retry or report the failure instead of calling the task complete. A successful receipt persists the agent's bounded managed-protocol declaration and validates the referenced ClariLayer objects. It does not independently prove that an entry changed, external deployment happened, a Databricks validation passed, a query is correct, or saved context is semantically equivalent to another system.

A grounded answer looks like this

An answer grounded in ClariLayer carries the definition, its provenance, and its status:

Active Customer means an account with at least one billable subscription in the trailing 30 days, excluding internal test workspaces (saved by you). Heads up: this definition currently has a caveat — when I reconciled it last, the actual result did not match the declared shape, so confirm the window before using this for ARR-facing work.

That answer uses your saved definition, names where it came from, and is honest about its trust state. It does not pretend the raw SQL alone contains the business truth.

Continue across sessions

When you confirm a durable correction and ask your agent to save it, later tasks can recall that context across claude.ai, Claude Code, Cursor, and Codex. Recall reads saved context; it does not add a new rule. The Governed Context Edge adds org canon, Diff-to-team, and adjudication in a hand-run private pilot. Request access on the For teams page.