Concepts

The Reasoning Trail

How ClariLayer keeps the reasoning behind your context: assumptions and caveats attached to entries, variant and conflict edges, and corrections captured for good.

Every data tool you already own stores the current definition of a metric. Warehouses store the SQL. Semantic layers store the joins. dbt stores the lineage. None of them store the assumption the definition rests on, the caveat that is still open, or the correction you made last quarter that must never be re-litigated.

That reasoning is not metadata. It is the memory of why your context is what it is — and an AI agent that answers questions about your data without it is structurally guessing.

Reasoning rides on the entry

In ClariLayer, reasoning is not a separate comments surface. It travels with the context entry itself. Every entry — a definition, a schema note, a reusable query — carries its provenance (where it came from: you, a SQL import, a data dictionary, dbt, a semantic model, or a fact your agent proposed) and its status (asserted or caveat).

On top of that, an entry can carry reasoning attachments: the assumptions it depends on and the caveats it has earned. An assumption records something the definition takes for granted — "billing exports land by 6am UTC," "test workspaces are already excluded upstream." A caveat records a known reason for care — most importantly, the caveat reconcile attaches when an entry's declared shape and the actual result your agent got back disagree.

When your agent recalls an entry, the attachments come along. The answer it gives you is grounded not just in what the definition says but in what it assumes and where it is known to be fragile.

The attachment lifecycle

Reasoning ages, so attachments have a real lifecycle instead of accumulating forever:

Archive retires an assumption or caveat that no longer applies — it leaves the entry's active reasoning but is kept as durable history, so the record of having once been a concern is never lost.
Restore reactivates an archived attachment when the concern turns out to still be live.
Forget permanently deletes an attachment — the deliberate, no-undo path for reasoning that was simply wrong.

Superseding an entry works the same way: iteration creates a new version rather than rewriting the old one, so the evidence trail stays inspectable.

Edges: variants and conflicts

Some of the most valuable reasoning is about how two pieces of context relate. ClariLayer records that as edges between entries:

A variant_of edge says two definitions are deliberate variants of the same concept — "active user (7-day)" and "active user (28-day)" are both real, and the edge keeps them related instead of letting them masquerade as duplicates or contradictions.
A conflicts_with edge says two entries genuinely disagree. The disagreement stays visible: when your agent recalls one side, the conflict is labeled rather than silently resolved by whichever entry ranked higher.

This is the single-player version of a truth every team learns eventually: the problem was never disagreement, it was invisible disagreement. An edge makes the disagreement a first-class fact your agent can reason about.

Corrections are captured

The most common reasoning event is the simplest one: you correct your agent. "No — net revenue must net refunds." ClariLayer is built to capture that correction as durable context, so the next session starts from the corrected understanding instead of rediscovering it. A captured correction lands with provenance you and status asserted, and it can carry the reasoning — what was wrong, what is right, and why — rather than just the final string.

How your agent uses the trail

An answer grounded in the Reasoning Trail looks different from an answer grounded in bare SQL:

Active Customer means an account with at least one billable subscription in the trailing 30 days, excluding internal test workspaces (saved by you). This definition assumes the billing export is current, and it carries a caveat from the last reconcile — the actual result was missing a column the definition declares, so confirm the window before ARR-facing work. A 7-day variant exists and is linked as a deliberate variant.

That is a categorically different answer than the same agent reading the SQL alone: it names the assumption, carries the caveat, and knows the variant exists.

What belongs in the trail

A useful Reasoning Trail is selective. The highest-value entries are the decisions that explain why a definition differs from the intuitive one, the assumptions a consumer would otherwise discover the hard way, and the caveats that are still open.

Attach an assumption when a definition depends on something outside the SQL — a pipeline schedule, an upstream filter, a fiscal-calendar quirk.
Keep a real caveat active until it is resolved; archive it when it is, so the history survives.
Link deliberate variants with variant_of instead of deleting one, and record genuine disagreements with conflicts_with instead of picking a winner silently.
Capture corrections the moment you make them — they are the reasoning your future sessions inherit.

For teams

The same trail scales up. The Governed Context Edge — in a hand-run private pilot today — carries this reasoning across the team boundary: a definition proposed up to the shared canon arrives with its provenance, status, assumptions, and caveats attached, and conflicts between teammates' definitions are adjudicated in the open rather than overwritten. See For teams.