---
title: "Context & Knowledge"
description: "Build agent-aware context and knowledge surfaces while keeping engines, data access, and reusable presentation in their proper layers."
---

# Context & knowledge

Context and knowledge are shared responsibilities: the runtime makes state and
access durable, Toolkit presents reusable surfaces, and each app owns the
domain records that make context useful.

<WireframeBlock id="doc-block-toolkit-context-knowledge">
  <Screen
    surface="desktop"
    html={
      "<div style='min-height:520px;box-sizing:border-box;padding:24px;display:grid;grid-template-columns:1fr 260px;gap:16px'><main class='wf-card' style='display:flex;flex-direction:column;gap:12px'><div style='display:flex;align-items:center;gap:10px'><h2 style='margin:0'>Context X-Ray</h2><div style='flex:1'></div><span class='wf-pill'>24.6K / 128K tokens</span></div><div class='wf-box' style='display:flex;align-items:center;gap:8px'><span data-icon='lock'></span><div style='flex:1'>System &middot; ordered, not evictable</div><small class='wf-muted'>6.1K</small></div><div class='wf-box' style='display:flex;align-items:center;gap:8px;border-color:var(--wf-accent)'><span data-icon='check'></span><div style='flex:1'>Pinned &middot; roadmap.md</div><small class='wf-muted'>1.2K</small></div><div class='wf-box' style='display:flex;align-items:center;gap:8px'><div style='flex:1'>Conversation &middot; last 12 turns</div><small class='wf-muted'>14.8K</small></div><div class='wf-box' style='display:flex;align-items:center;gap:8px;opacity:.55'><span data-icon='x'></span><div style='flex:1'>Evicted &middot; old tool output</div><small class='wf-muted'>2.5K</small></div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Budget</strong><div style='height:120px;border-radius:8px;background:var(--wf-accent-soft);display:flex;align-items:center;justify-content:center'><strong>48%</strong></div><small class='wf-muted'>Share of the context window used by system, conversation, tool results, and evicted segments.</small><div style='flex:1'></div><button class='primary'>Pin selection</button></aside></div>"
    }
  />
</WireframeBlock>

## Ownership boundary

| Layer   | Owns                                                                                       |
| ------- | ------------------------------------------------------------------------------------------ |
| Core    | Application state, scoped data access, Context X-Ray engine, resource and block contracts. |
| Toolkit | Reusable Context X-Ray presentation and agent-facing context UI.                           |
| App     | Domain knowledge, selection rules, resource taxonomy, and product-specific context.        |

The Context X-Ray engine remains Core-owned. Use Toolkit presentation to show
that context consistently, but keep the actual app-state and access decisions
on the Core/action surface.

## Pieces {#pieces}

| Piece                                                              | Purpose                                                               |
| ------------------------------------------------------------------ | --------------------------------------------------------------------- |
| `<ContextXRayPanel>` from `@agent-native/toolkit/app/context-xray` | Framework-styled panel; the app supplies manifest data and callbacks. |
| `<ContextXRayPanelView>`                                           | Lower-level panel for custom layouts.                                 |
| `<ContextMeterView>`                                               | Compact token-budget donut with a popover breakdown.                  |
| `<ContextTreemapView>`                                             | Treemap of context usage by segment group and size.                   |
| `<ContextSegmentRowView>` / `<SegmentProvenancePopoverView>`       | One segment row and its provenance popover (source, tokens, status).  |
| `formatContextTokens()`                                            | Shared token-count formatting (for example `24.6K`).                  |

## Usage {#usage}

Import the presentation views from `@agent-native/toolkit/context-ui` and feed
them your own manifest data:

```tsx
import {
  ContextMeterView,
  ContextXRayPanelView,
  formatContextTokens,
} from "@agent-native/toolkit/context-ui";
```

For a framework-styled panel, import `ContextXRayPanel` from
`@agent-native/toolkit/app/context-xray`. It receives the context manifest,
optimistic pin/evict state, and pin/evict/restore callbacks from the app; it
does not fetch the manifest or call actions itself. The lower-level views remain
available from `@agent-native/toolkit/context-ui` when an app needs a custom
layout. Core owns the context engine, manifest actions, and access decisions.

## Build a useful context surface

Use [context awareness](/docs/context-awareness) to make navigation,
selection, and focused objects visible to the agent. Use [Resources](/docs/toolkit-resources)
for browsable files and attachments, and use scoped actions for every read or
write. Context should describe what the user is working on without bypassing
the app's access model.

For knowledge that comes from a provider, preserve provider credentials and
resource access checks before exposing retrieval to the agent. Do not treat a
presentation component as an authorization boundary.

## What's next

- [**Context Awareness**](/docs/context-awareness) — the navigation, selection,
  and app-state contract these views present.
- [**Agent UX**](/docs/toolkit-agent-ux) — composer context chips, approvals,
  and the runs tray.
- [**Resources**](/docs/toolkit-resources) — resource trees, search, and
  attachments the agent can read.
- [**Security**](/docs/security) — scoped access and credential handling.