ClariLayer Docs

recall

Quickstart

recall

Pull deterministically ranked saved context in-flow with get_analysis_context, with honest use-case scoping, provenance, and status.

recall is how your agent pulls the right context mid-task without you leaving your flow. It is the user-facing name of the get_analysis_context MCP tool. When your agent is about to answer a question or write a query, it can recall the most relevant definitions, schema notes, saved queries, and notes you have stored, each ranked by relevance and tagged with its provenance and status.

This is the structural fix for the old "destination app" problem. You do not open a tool to look a number up; the context rides along inside claude.ai, Claude Code, Cursor, or Codex, and your agent reaches for it when it needs it.

What it returns

get_analysis_context takes a query describing what the agent is working on and returns your most relevant stored context, scoped to you. Each returned entry carries:

  • its content — the definition, schema note, saved query, or note;
  • its provenance — where it came from (you, sql_import, dbt, agent, dictionary, semantic_model, or the accepted legacy value query_history), so you can see whether it was hand-saved, imported, or agent-normalized. There is no public query-history bootstrap source or importer;
  • its status — asserted or caveat, so your agent can judge how much to trust it.

Recall is read-only and in-flow. It never mutates your store; it only surfaces what is already there. Because it reads, it needs only context:read — a read-only context key can recall.

Who decides when to recall

Recall is a tool your agent decides to call — ClariLayer exposes it; it does not force a call. In practice you get the most value by making recall the first step of your agent's loop. For Claude Code, Cursor, or Codex, the Quickstart generates one managed-install prompt from the local client you explicitly select. Your local agent inspects only that client's canonical instruction target, asks before editing, and installs a managed range that carries the recall-first and completion-checkpoint workflow into future sessions. The browser and remote server do not inspect or edit your files. The claude.ai path connects to the production custom Connector over OAuth and does not install a local project instruction file.

That is the difference between "can recall in-flow" (always true — the tool is there) and "always recalls first" (true only when your client config or prompt makes it so).

How ranking works

Ranking is deterministic. Exact-token relevance is compared first, then finite similarity (an entry with a finite score leads one with no score), then trust, an optional source tier, and finally stable input order. Trust and source tier never override either relevance key, so a less relevant entry cannot jump ahead merely because it has stronger trust metadata.

If you pass the tables your agent is touching, those references participate in relevance matching — useful when the same metric name means different things in different schemas. They are context, not a silent hard filter.

Honest use-case scoping

use_case is a precision hint. Recall prefers entries in that use case together with unscoped context. When there is no authoritative in-scope result, it can rescue a strong cross-scope match and label it use_case_mismatch instead of silently hiding it or pretending it is in scope. Inspect the additive honesty fields when present: use_case_warning, off_scope_entries, routing_confidence, and available_use_cases.

Set strict_use_case: true when the task must never use cross-scope fallback. In that mode, recall does not rescue off-scope entries.

A typical loop

  1. Your agent recalls ClariLayer context for the task at hand.
  2. It answers from the recalled definitions, carrying their status so known mismatches remain visible.
  3. If the task confirms a durable change, it remembers it. If the suggestion still needs review, it uses propose and stops for human acceptance instead of treating proposal-only work as live context.
  4. If a compatible recalled definition is checked or has drifted, it reconciles it through the supported warehouse actual_sample or HubSpot crm_evidence adapter.
  5. Before reporting completion, it calls context_checkpoint with context_updated and active live entry references, or no_update_required after explicitly checking that no durable context update was needed. Proposal-only work cannot reach this completing step.

The checkpoint receipt persists the agent's bounded managed-protocol declaration and validates its referenced ClariLayer objects. It does not independently prove that an entry changed, external code deployed, a warehouse validation passed, a query is correct, or saved context is semantically equivalent to another system. update_failed and proposal-only work are non-completing outcomes.

Over time this compounds: every correction and every new note persists, so your agent grounds on more of your context each week.

Status, honestly

A recalled entry's status is either asserted or caveat. asserted means saved but not contradicted; caveat means reconcile found a declared-vs-actual mismatch worth treating with care. The stronger verified status remains gated and is not part of the live public result contract — see Verified vs Asserted for what that means and why.

See also