Quickstart | ClariLayer Docs

Quickstart

Choose your AI client, connect ClariLayer, save one rule, and recall it.

1. Connect your client

Choose a setup route: Claude Code Cursor Codex claude.ai Other AI client

Ask Claude Code to set it up

Copy this prompt and paste it into Claude Code. Your AI will help you set up the connection and check it. You may need to complete a browser sign-in or restart your AI.

Connection status updates only after ClariLayer receives a successful health check.

View setup prompt

Help me connect ClariLayer to Claude Code.

This prompt authorizes connection setup only. Do not upload or bootstrap any context, call write tools, or create or edit project instruction files. Do not claim that copying this prompt or writing configuration means the connection works.

Connection details:
- Server name: `clarilayer`
- Transport: remote MCP over Streamable HTTP
- URL: https://app.clarilayer.com/api/mcp/mcp

Preserve all unrelated client configuration. Inspect through the client's settings or a private local helper that emits only the server-present, transport-matches, and URL-matches booleans. Never read an entire config into chat or emit raw config, CLI output, headers, or token values. If a server named `clarilayer` already exists, do not overwrite, remove, rename, or duplicate it. Compare its transport and URL with the details above, report any difference, and ask me before making a narrowly scoped update through the client's supported settings.

Prefer OAuth when this client exposes a compatible login flow. ClariLayer OAuth has not been verified end to end for every client, so do not promise it will be available. If OAuth is unavailable and this client supports secure bearer-token, API-key, or Authorization-header configuration, tell me to create or copy a ClariLayer context key and enter it directly in that secure client field. Never ask me to paste, send, or repeat the key in this chat, and never place it in chat text, command history, logs, screenshots, or project files.

For Claude Code, inspect the existing MCP entry first. If no `clarilayer` entry exists and you can run the local CLI, add it with `claude mcp add --transport http clarilayer https://app.clarilayer.com/api/mcp/mcp`. Then use Claude Code's `/mcp` flow to authenticate when OAuth is offered. If you cannot operate the local CLI, guide me through the same steps.

After setup, tell me if the client needs a refresh or restart. Verify only with read-only MCP tool discovery and then `clarilayer__health`. Report the connection as working only after the health call succeeds. If you cannot access connector settings or tools from this session, give me the exact UI or CLI steps I must perform and wait for me to report the result.

Set up Claude Code Already have an account? Sign in

Manual connection settings

Run in your terminal

claude mcp add --transport http clarilayer https://app.clarilayer.com/api/mcp/mcp --header "Authorization: Bearer cl_YOUR_CONTEXT_KEY"

Replace cl_YOUR_CONTEXT_KEY with the context key you mint in ClariLayer. The key is shown once at creation, so paste it straight into the command above. Keep it out of prompts, tickets and screen recordings.

Optional: install or update project instructions

Install or update ClariLayer instructions

This Claude Code prompt targets only CLAUDE.md. Paste it into that local agent. The agent inspects one file and asks before editing. An already-current or conflict decision, or an approved write, reports installed, already current, or conflict/manual review; declined approval stops without claiming an installation state. Copying it here does not edit your repository.

Install or update ClariLayer's managed instructions for Claude Code.

ClariLayer's browser and remote MCP server have not edited any local file. You are the local agent performing this repository-local inspection. The user's act of pasting this scoped update prompt authorizes a safe create or replacement limited to the recognized ClariLayer managed range or an exact published legacy block in the one target below. Do not ask for redundant approval for that safe case. An ambiguous, malformed, or hand-edited legacy conflict requires an exact one-file diff and explicit confirmation before any change.

1. Call the ClariLayer MCP tool `get_project_stanza` with `mode: "full"`. Use its structured `managed_block`, `managed_block_template`, `managed_instance`, `legacy_stanza`, `legacy_stanzas`, `legacy_managed_blocks`, `append_once_sentinel`, `client_targets`, and `managed_apply_guidance` fields exactly; do not recreate or paraphrase their contents.
2. Select only the `claude-code` descriptor and confirm that it names exactly `CLAUDE.md`. If the descriptor or the pinned metadata below differs, change nothing and report `conflict/manual review`.
3. Inspect exactly `CLAUDE.md`. Do not inspect or modify any other project instruction target.
4. This selected target has no required preamble.
5. No authenticated project report scope was supplied. Use managed_block as target_managed_block and do not invent instance metadata.
6. If the selected target already contains a range byte-identical to target_managed_block, change nothing and report `already current`.
7. If the current target contains one exact published v1/v2/v3 managed range, replace only that range with target_managed_block. Do not remove or rebind an exact scoped current-v4 range without authenticated project report scope; leave it unchanged, report `conflict/manual review`, and guide the user to the signed-in Connect update path. If it contains one exact legacy_stanza or legacy_stanzas item, replace only those exact bytes. A normal new install or these safe replacements are already authorized by this prompt: preserve every byte outside the selected range and do not ask again.
8. If legacy heading text is present but no exact legacy block matches, or a managed range is hand-edited, unknown/newer, malformed, or ambiguous, change nothing. Show the complete exact one-file proposed diff with no elision and ask for confirmation; without confirmation report `conflict/manual review`. Never silently downgrade an unknown/newer range.
9. Translate the canonical guidance's internal `already-current` label to `already current`, and `conflict/manual-review` to `conflict/manual review`. After an authorized create or replacement, report `installed`. Report exactly one terminal state with no alternate spelling: `installed`, `already current`, `conflict/manual review`.
10. Before any write, retain the exact bytes before and after the selected range. After the write, re-read the complete selected target. Report `installed` and submit a local attestation only if the installed range equals target_managed_block, carries the pinned version/hash and no instance metadata, and every surrounding byte is unchanged. If verification fails, report `conflict/manual review` and do not attest installation.
11. No authenticated project report scope was supplied. Do not call sync_instruction_setup or invent project/installation identifiers; report only the local terminal state.

Selected target: CLAUDE.md
Managed protocol version: 4
Managed payload hash: sha256:2a549743ee65b0cc81e8bd57cc30cf437fd30278f1780730616448fd3ac83a0d
Managed begin marker: <!-- BEGIN CLARILAYER MANAGED INSTRUCTIONS -->
Managed end marker: <!-- END CLARILAYER MANAGED INSTRUCTIONS -->
This target has no required preamble. Do not invent one.

Canonical fail-safe guidance:
Select exactly one client target; never touch more than one instruction file. target_managed_block means managed_block_template with only its four typed placeholders filled from the explicit Connect report scope and locally computed refs; without that scope it means the generic managed_block. For Cursor, if the selected target already exists, require its exact required_preamble before any already-current, append, or replacement decision; otherwise return conflict/manual-review and change nothing. If that target contains exactly one well-formed managed range with the published begin marker before the end marker, compare the entire range: when it is byte-identical to target_managed_block return already-current and change nothing. During an explicit scoped Connect update, an exact generic managed_block or an exact current-v4 range carrying only the four recognized typed instance metadata lines may be rebound by replacing only that range with target_managed_block. When it is byte-identical to one legacy_managed_blocks item replace only that marked range. Any other well-formed range, including a hand-edited or unknown/newer version, is conflict/manual-review: show the complete exact one-file replacement diff and require confirmation before replacing it. Duplicate, nested, reversed, or unmatched markers are conflict/manual-review: change nothing. With no managed marker, replace only a byte-identical legacy_stanza or one exact legacy_stanzas item. If append_once_sentinel exists but the full legacy bytes differ, return conflict/manual-review and change nothing. If neither markers nor the legacy sentinel exists, append target_managed_block during an explicit scoped Connect update, otherwise append managed_block, to an existing Claude Code or Codex target, or create the selected target with the same selected block. For Cursor, create the target with its exact required_preamble, a blank line, then that selected block. An unscoped update must not remove or rebind a recognized scoped current-v4 range. Before a write, retain the exact surrounding bytes. After a write, re-read the selected target and require the current managed range, version and hash plus byte-identical surrounding content before reporting installed or attesting the result. Never edit bytes outside the recognized managed range or exact legacy block, never delete unrelated content, and never claim the server or browser edited a file.

The browser and remote server did not edit a file.

Older shortened ClariLayer section?

Use this only for an early ClariLayer section that kept the old heading but was shortened or edited. The standard installer above remains the default and safely sends that state to manual review. Copying this opt-in recovery prompt only hands instructions to your selected local agent; the browser and remote server have not read or edited your repository.

Recover one older shortened ClariLayer section in Claude Code's project instructions.

This is a separate, opt-in guided legacy migration. The normal managed installer must remain fail closed for edited legacy text. ClariLayer's browser and remote MCP server have not read or edited this repository; you are the selected local agent, and only you may inspect or change the one target below after explicit approval.

Follow this algorithm exactly:

1. Call the ClariLayer MCP tool `get_project_stanza`. Use its structured `managed_block`, `managed_version`, `managed_hash`, `managed_markers`, and `client_targets` fields exactly; never recreate, paraphrase, or partially copy `managed_block`. Select only the `claude-code` descriptor. Require its `client` to be `claude-code`, its `target_file` to be `CLAUDE.md`, and its `required_preamble` to be null. Require all returned version, hash, and marker metadata to match the pinned values below, and require `managed_block` to carry those exact markers and metadata. Any mismatch is unsafe.
2. Read the entire byte content of exactly `CLAUDE.md`. Do not inspect or modify any other project instruction target. The browser and remote server have not performed this read or any write.
3. Recovery is eligible only if every condition below is true:
   - No managed begin marker or managed end marker occurs anywhere in the file.
   - The exact line `## ClariLayer — your data context layer (use it proactively)` occurs exactly once in the whole file, and that sole occurrence is a real Markdown H2 heading outside every backtick or tilde fenced code block. Heading-shaped text inside fenced code is not eligible.
   - The candidate section is unambiguously bounded from the first byte of that H2 heading through immediately before the next real Markdown H1 or H2 heading outside fenced code, or through EOF when no later H1/H2 exists.
   - Preserve the exact separator at that boundary instead of consuming it. Before a following heading, take the maximal contiguous whitespace-byte suffix immediately preceding that heading, require it to contain at least one complete line ending, and keep that suffix outside the replacement range so the following heading remains at the start of its original line. At EOF, likewise keep any maximal trailing whitespace-byte suffix that contains the file's final line ending outside the replacement range; if there is no final line ending, preserve the no-trailing-newline state. These preserved bytes are not part of `managed_block` and must not be normalized.
4. Fail closed on any unsafe state. A missing or duplicate exact heading, a heading that exists only inside fenced code, an unterminated or ambiguous fence, an ambiguous section boundary or boundary separator, any complete/malformed/partial/duplicate/nested/reversed managed marker, any selected-target or pinned-metadata mismatch, or any other uncertainty means: change nothing, report `conflict/manual review`, and recommend manual review. Never append `managed_block` over the legacy section.
5. Before writing, show the exact full one-file replacement diff for `CLAUDE.md`: the complete bounded candidate replacement range removed and the complete canonical `managed_block` added, while every preserved boundary or trailing suffix byte appears as unchanged context, with no elision, summary, or truncation. Ask for explicit approval of that exact diff. If approval is declined, write nothing and claim no terminal installation state.
6. Immediately before any approved write, re-read the whole file as bytes and require byte-for-byte equality, including line endings, with the bytes used to produce the shown diff. If any byte changed concurrently, stop without writing and report `conflict/manual review`.
7. After approval, replace only the bounded candidate replacement range with the returned canonical `managed_block`. Preserve every byte before and after that range, including the exact boundary/trailing suffix isolated in step 3, unrelated content, whitespace, line endings, and the existing trailing-newline state. Never synthesize a separator by altering `managed_block`; retain the original separator outside it. Do not modify another instruction target.
8. Re-read the whole target after the write. Verify that the inserted managed range is byte-identical to `managed_block`; the pinned begin and end markers each occur exactly once and in that order; the installed version and hash match both the returned and pinned values; the exact old heading is gone; and every byte outside the replaced range is unchanged. Only after every check passes, report the existing terminal state `installed` and a separate supplemental receipt/detail exactly `guided legacy migration`. Do not create a new terminal state. If any verification fails, report it honestly and never call the result `installed`.

Selected recovery client: claude-code
Selected target: CLAUDE.md
Required preamble: null
Exact legacy H2: ## ClariLayer — your data context layer (use it proactively)
Managed protocol version: 4
Managed payload hash: sha256:2a549743ee65b0cc81e8bd57cc30cf437fd30278f1780730616448fd3ac83a0d
Managed begin marker: <!-- BEGIN CLARILAYER MANAGED INSTRUCTIONS -->
Managed end marker: <!-- END CLARILAYER MANAGED INSTRUCTIONS -->

The browser and remote server did not edit a file.

Choose your client, copy the setup prompt, and paste it into that AI. The prompt can configure supported local clients or guide you through hosted settings. It does not contain a context key, authorize context uploads, or edit project instructions. You may need to complete browser sign-in or restart the client before its tools appear. Use the manual configuration under the selected client only when the assisted path cannot finish.

ClariLayer is the context layer you never have to curate. Start with one rule you want your AI to remember. Personal use is free, unmetered, and requires no credit card. See pricing.

After connecting, ask your agent to call clarilayer__health. A successful response confirms the authenticated workspace, not that a particular rule was used. If authentication fails, check your key or complete the claude.ai approval flow. Connection recovery has the details.

2. Save one artifact or rule

Pick one short SQL query, dbt model, note, dictionary entry, or semantic-model definition you already use. Ask your agent:

Read only this artifact I selected, with my permission. Help me save one durable rule in ClariLayer using remember or bootstrap. Ask about anything ambiguous before saving, and reuse an existing equivalent instead of creating a duplicate.

No file or source access? Describe one rule yourself, such as how your team handles refunds. Your agent reads a selected file locally and sends the chosen content to ClariLayer. The browser cannot inspect your files. ClariLayer holds no warehouse or CRM credentials, runs no SQL, and does not call your CRM provider in this personal MCP flow.

If you already have saved context, reuse an existing personal rule; when guided setup is available, you can choose it in Connect your AI. A pending proposal still needs Inbox review; it is not saved context for this exercise. The bootstrap reference covers all five source kinds: sql, dbt, claude_md, dictionary, and semantic_model.

3. Ask your AI to recall it

Ask: “Use ClariLayer recall before answering: what should I know about [the rule's name]?” Your agent calls get_analysis_context. Inspect the returned name, provenance and asserted or caveat status. If the summary is truncated or you need the complete body or stored SQL, ask for get_context_entry by type and name before relying on it. Read the recall reference.

When the guided setup is available, its browser preview lets you try the question against a scoped read of saved context. Preview does not run your agent or record agent use. After the agent's real recall, use Check agent reuse in Connect. Missing or partial activity is unknown; it does not prove the rule was never used. You can report whether the result was useful, or skip.

Optional: find context by meaning

You can search saved context by name without semantic indexing. When self-service consent is available, guided setup with an eligible selected starter reveals an optional organization-wide choice for an owner/admin. The older setup flow offers this choice before the connection instructions when the guide is off. Existing granted, withheld or revoked decisions are not re-prompted; an error dismissal writes nothing.

Enabling permits eligible existing and future entry names/main text and recall query text to be sent to Google through the Vercel AI Gateway; ClariLayer stores entry vectors. Indexing is asynchronous, and search availability depends on the service controls. Not now records withheld. Check progress or change consent in Account settings. Revocation removes stored embedding rows, but in-flight requests may finish and data already sent cannot be recalled. Read the semantic indexing privacy notice.

Credentials and other deployments

ClariLayer's MCP server is a remote, stateless Streamable HTTP endpoint at POST /api/mcp/mcp. Claude Code, Cursor, Codex, and other compatible clients can use the remote endpoint; claude.ai uses its hosted Connector flow. A client that supports only stdio needs a compatible HTTP bridge and is not directly supported by the generic route.

Use an MCP-capable client and a ClariLayer workspace. Local clients use a personal cl_… context key. context:read permits recall; saving or importing requires context:write. The full key is shown once: store it securely and keep it out of prompts, tickets and recordings. Revoke a lost key and create a replacement.

Prefer OAuth when the selected client offers a compatible flow. ClariLayer has not verified OAuth end to end in every client. When OAuth is unavailable, enter the context key directly in the client's secure bearer-token, API-key, or Authorization-header field; never paste it into AI chat. The production claude.ai connector uses OAuth approval, with no context key field. A self-hosted or other deployment must enable and configure OAuth before offering that path. Use the deployment's canonical app endpoint; do not replace it with a marketing URL.

Connection recovery and managed instructions

For a local-client authentication failure, check that the full key was installed and has not been revoked. For claude.ai, reconnect and finish the approval flow. Return to the client selector to open setup with your selected client; sign-in and signup preserve that choice.

Open Optional: install or update project instructions under your local client's snippet when you are ready to make recall part of your working routine.

The managed prompt names exactly one target for the client you selected. Copying it does not change your repository: your local agent inspects that one file, asks for approval before an edit, and preserves bytes outside the recognized ClariLayer range. An already-current or conflict decision, or an approved write, reports exactly installed, already current, or conflict/manual review; if you decline approval, the agent stops without claiming an installation state. A malformed managed range, a legacy stanza whose sentinel remains but whose full bytes differ, or incompatible Cursor frontmatter fails closed to manual review. For Claude Code and Codex, otherwise-unrecognized existing text is preserved while the managed range appends on first install.

If an early CLAUDE.md or AGENTS.md kept the exact old ClariLayer heading but shortened or edited the section underneath it, open Older shortened ClariLayer section? and explicitly copy the separate guided recovery prompt. The standard installer remains fail closed. The recovery option appears only for Claude Code and Codex, shows a full one-file replacement diff before asking for approval, and stops on ambiguous headings, fenced examples, marker fragments, or concurrent file changes. Cursor recovery stays manual because its frontmatter and target semantics differ. Neither copying option lets the browser or remote server read or write your repository.

Completion receipts for ongoing work

The managed instructions establish a completion loop: recall → confirmed live remember/reconcile → context_checkpoint. Your agent recalls before relevant data work, writes a confirmed durable change to live context with remember, and reconciles it when appropriate. If the suggestion still needs human review, it uses propose and stops for acceptance; proposal-only work cannot continue to a completion receipt. After an accepted proposal is live, or after another confirmed live outcome, the completion loop can continue.

A pending proposal is not live recall context, and an update_failed checkpoint does not allow completion. When the task made no durable context change, the agent can use no_update_required only after explicitly checking the relevant facets.

The receipt has a deliberately narrow meaning: it persists the agent's managed-protocol declaration (context_updated or no_update_required) and validates ownership and eligibility of any referenced ClariLayer objects. It does not independently prove that an entry changed during this task, that code deployed, that Databricks validation passed, that a query result is correct, or that the saved rule is semantically equivalent to an external system.

The four verbs

After connecting, your agent has four headline, everyday verbs. Each has its own page:

bootstrap — import selected SQL, dbt, CLAUDE.md notes, a data dictionary / codebook, and semantic-layer models so you do not start from a blank store.
recall — pull the most relevant saved context for the current task, in-flow (get_analysis_context).
remember — save a definition, schema note, join, or gotcha so your agent retains it across sessions.
reconcile — check a saved SQL definition against warehouse actual_sample evidence or a HubSpot CRM contract against row-free crm_evidence; a mismatch is flagged as a caveat. Salesforce contracts remain store/recall-only.

Beyond the four verbs

The four verbs above are the everyday surface. As you go deeper, the agent can also:

Record a completion receipt — after the relevant recall and confirmed write/reconcile path, call context_checkpoint so the task has a durable context_updated or no_update_required receipt.
Harvest a whole session — on your explicit request, distill the durable facts from a working conversation and stage them in your Context Inbox for review (via propose / propose_batch). Nothing is auto-saved; you approve each, and the transcript is never sent to ClariLayer — only the distilled candidate facts.
Manage what's saved — reversibly retire context with archive / restore (and archive_reasoning / restore_reasoning for the caveats and assumptions attached to an entry), or remove it for good with forget.

What "checked" means

ClariLayer is a trust product, so it is precise about what it can stand behind. When reconcile runs against a supported warehouse or HubSpot evidence path, a declared-vs-observed mismatch is flagged as a caveat; otherwise the entry stays asserted. Those are the only public outcomes. The verified status remains gated and is not live. Read Verified vs Asserted for exactly what each status means and why.

Where to go next

The Context Layer explains the mental model: why a personal, reconciled, in-flow context layer beats a hand-typed CLAUDE.md.
AI Agent Context Guide shows the recall-first working loop in practice.
SaaS Metrics Definition Library is a reference for the metric definitions teams argue about most.
The For teams strand covers what happens as your personal context merges into shared, governed team context.