> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Context

> Context shows what the project knows as entities with the Files they cite, and builds one bounded packet of passages and entities for a question.

Concept · core

> **Use when**
>
> You list the entities that cite a File, check where an entity came from, or build a packet of passages and entities for one question.

> **Looking for something else?**
>
> Finding passages for a question (card [Search](https://docs.pnbr.io/concepts/search.md)). Choosing what a client sees, and saving a definition (card [View](https://docs.pnbr.io/concepts/view.md)). Changing an entity (card [Entity](https://docs.pnbr.io/concepts/entity.md)).

## For

Context reads the Graph and the Files together. It answers two kinds of
question. The first is what the project knows and from which Files. Explore and
entity answer it. The second is what to put in front of an agent for one
question. Compile and materialize answer it.

Explore lists entities, the most recently changed first, each with the Files
its citations name. Entity shows one entity with its properties, its citations
and the relationships that touch it.

A definition is a purpose and a scope. Compile checks a definition against the
project's Shapes and keeps nothing. Materialize runs a question inside the
definition. It returns a packet of passages, entities and relationships, with
warnings, a token budget and text that is ready to give to an agent.

Context only reads. It changes no File and no entity. A packet is a reading at
one moment. Only the published version of a saved definition keeps a packet
receipt, and the packet receipt never changes (card [View](https://docs.pnbr.io/concepts/view.md)).

Context does not tell you that a source went stale. An entity keeps citing a
replaced version or a trashed File, and nothing in Context marks it. You
compare each citation with its File yourself (recipe [find-stale-entities](https://docs.pnbr.io/guides/find-stale-entities.md)).

## Use when

* You need every entity that cites a File.
* You need to see which Files, versions and passages one entity came from.
* You need one packet of passages and entities to give to an agent.
* You need to compare what a question returned at two moments.

## Not this

* Finding passages for a question, with no entities: use card [Search](https://docs.pnbr.io/concepts/search.md).
* Choosing what a client or a Brain can see: use card [View](https://docs.pnbr.io/concepts/view.md).
* Changing an entity or its citations: use card [Entity](https://docs.pnbr.io/concepts/entity.md) and card [Workspace](https://docs.pnbr.io/concepts/workspace.md).

## Rules

1. `context.1` Explore lists entities, not passages. `penumbra context explore`
   lists the entities that match your words and filters, the most recently
   changed first. It filters by Shape, entity type, relationship type, File
   and date. **Enforced:** a page holds 1 to 200 entities, and a `--limit`
   outside that range is refused with `invalid_option`. **Your job:** read the
   next page with the `--cursor` value of the `next:` line, until no such line
   shows.
2. `context.2` A File filter finds an entity through the citations of its
   current revision. `--file-id` may repeat. It matches a citation on any
   version of the File. **Your job:** an entity whose citations wait for
   confirmation, or that has none, is not found by this filter. Check those
   apart (card [citations-to-confirm](https://docs.pnbr.io/concepts/citations-to-confirm.md)).
3. `context.3` Context does not say whether a cited File is trashed, purged or
   replaced. A citation gives the File ID, the version ID, the content digest
   and the passage ID. Nothing marks a trashed File or an older version.
   Explore lists at most 32 citations for each entity, and its text names only
   the Files. **Your job:** read the IDs with `--json` or with
   `penumbra context entity`. Read the state of each File with
   `penumbra files list --all`, and its current version with
   `penumbra files versions`. Then compare.
4. `context.4` `penumbra context entity <entity-id>` shows the properties, the
   citations of the current revision and the relationships. **Enforced:** a page
   holds 1 to 100 relationships, and a `--relationship-limit` outside that range
   is refused with `invalid_option`. **Your job:** read more relationships with
   `--relationship-cursor`. A relationship shows no citations here.
5. `context.5` Compile checks a definition and keeps nothing. A definition is a
   purpose of 1 to 1,024 characters and a scope. A scope lists Files,
   collections, entities, Shapes, entity types and relationship types. An empty
   scope is the whole project. **Enforced:** a Shape or type that the project
   does not have is refused with `shape_scope_unavailable`,
   `entity_type_scope_unavailable` or `relationship_type_scope_unavailable`.
   A File in the scope that is trashed, purged or unreadable is refused with
   `file_not_found` or `file_scope_unavailable`.
6. `context.6` A scope names Files, never versions. A File in a scope is read at
   its current version each time. **Your job:** after a replace, a packet made
   before it holds the old text and a new packet holds the new text. The
   definition needs no change.
7. `context.7` `penumbra context materialize "<question>"` returns one packet
   for one question. It holds up to 20 passages from Files search, up to 20
   entities, up to 20 relationships, and the passages that those entities cite.
   `--mode` is `lexical`, `hybrid` or `semantic`, and the default is `hybrid`.
   **Your job:** read the line of the packet that starts with "files searched:". It shows the mode
   that ran and how many File versions are ready for search by meaning. Use
   `lexical` when the question needs exact words.
8. `context.8` A packet fits a token budget. `--max-tokens` runs from 512 to
   32768, and the default is 4000. **Enforced:** a budget too small for the
   material is refused with `context_budget_too_small`. **Your job:** when the
   budget cuts material, the packet says `truncated` and warns with
   `graph_token_budget_exhausted` or `evidence_token_budget_exhausted`. A cut can
   remove a passage that supports an entity that the packet still holds. Then
   the packet also warns with `evidence_support_omitted` and names up to 10
   passages. Raise the budget or narrow the scope before you rely on the packet.
9. `context.9` A passage that an entity cites comes from the version that its
   citation names, which may not be the current version. **Your job:** read the
   `version=` ID on each passage line against the File's current version. A
   citation that Penumbra cannot open is left out, and the packet warns with
   `graph_evidence_unavailable`. The entity stays in the packet without that
   source.
10. `context.10` `--context <file>` reuses a compilation saved with
    `penumbra context compile --out <file>`. **Enforced:** if the project's Shapes
    or the definition changed since, materialize is refused with
    `context_compilation_changed`. Compile again. A file that is not a saved
    compilation is refused with `invalid_context_input`.
11. `context.11` Only `penumbra context slice materialize` keeps a packet
    receipt. `penumbra context materialize` keeps nothing. A packet receipt holds the exact
    packet, and neither one changes later. **Your job:** materialize again for
    today's answer. `penumbra context receipt <receipt-id> --packet` shows the old
    packet. `penumbra context diff receipts <left-id> <right-id>` shows what
    changed between two.
12. `context.12` `penumbra context slice materialize` takes a `--request-id`.
    **Enforced:** the same ID with the same question returns the first receipt
    and makes no second one. The same ID with another question is refused with
    `idempotency_conflict`. **Your job:** after a lost reply, run it again with the
    same ID (problem [reply-lost](https://docs.pnbr.io/troubleshooting/reply-lost.md)).
13. `context.13` Context commands do not wait for approval. **Enforced:** explore,
    entity, compile, materialize and `penumbra context slice materialize` run at
    once. Penumbra holds only the publication of a saved definition that a key
    or a connected agent makes (card [View](https://docs.pnbr.io/concepts/view.md)).
14. `context.14` Access limited to a View cannot compile or materialize on its
    own definition. **Enforced:** the refusal is `view_operation_unavailable`,
    and that access materializes the View's published version instead (card
    view).
15. `context.15` A scope that names exact entities searches no relationships.
    **Your job:** read the compile warning
    `relationships_omitted_under_exact_node_scope`, and name relationship types
    in the scope when you need relationships.

## Failure signs

* Entities cite a version that a new edition replaced: problem
  [entities-cite-replaced-version](https://docs.pnbr.io/troubleshooting/entities-cite-replaced-version.md).
* An entity's only citations point to a trashed File: problem
  [entity-rests-on-trashed-file](https://docs.pnbr.io/troubleshooting/entity-rests-on-trashed-file.md).
* You need the entities of one exact version: problem [what-cites-this-version](https://docs.pnbr.io/troubleshooting/what-cites-this-version.md).
* You need every entity that rests on an old version or a trashed File: recipe
  [find-stale-entities](https://docs.pnbr.io/guides/find-stale-entities.md).
* A packet warns `graph_evidence_unavailable`: rule [context.9](https://docs.pnbr.io/concepts/context.md#rule-context-9).
* Materialize is refused with `context_compilation_changed`: rule [context.10](https://docs.pnbr.io/concepts/context.md#rule-context-10).
* Compile is refused with `file_not_found` or `file_scope_unavailable`: a File in
  the scope is trashed, purged or unreadable (rule [context.5](https://docs.pnbr.io/concepts/context.md#rule-context-5)).
* An entity you know is missing from the entities of its File: rule
  [context.2](https://docs.pnbr.io/concepts/context.md#rule-context-2).

## Doors

| Door | Call |
| - | - |
| CLI | `penumbra context explore`, `penumbra context entity`, `penumbra context compile`, `penumbra context materialize`, `penumbra context slice materialize`, `penumbra context slice receipts`, `penumbra context receipt`, `penumbra context diff receipts` |
| MCP | None. No MCP tool serves Context. Use the CLI, the SDK or HTTP. |
| SDK | `project.context`, with `explore`, `getEntity`, `compile`, `materialize`, `receipts` and `diff` |

## The CLI word

The CLI calls a View a Slice and an entity a node.

## HTTP reference

* [Search files](https://docs.pnbr.io/api/http-files-search.md)
* [Resolve citations](https://docs.pnbr.io/api/http-files-chunks.md)
* [Search graph](https://docs.pnbr.io/api/http-graph-search.md)
* [Get entity context](https://docs.pnbr.io/api/http-context-entity.md)
* [Explore context](https://docs.pnbr.io/api/http-context-explore.md)
* [List views](https://docs.pnbr.io/api/http-views-slices-list.md)
* [Create view](https://docs.pnbr.io/api/http-views-slices-create.md)
* [Get view](https://docs.pnbr.io/api/http-views-slices-get.md)
* [Update view draft](https://docs.pnbr.io/api/http-views-slices-update.md)
* [List view versions](https://docs.pnbr.io/api/http-views-versions-list.md)
* [Publish view version](https://docs.pnbr.io/api/http-views-versions-publish.md)
* [Get view version](https://docs.pnbr.io/api/http-views-versions-get.md)
* [Read view context](https://docs.pnbr.io/api/http-views-versions-materialize.md)
* [Get context receipt](https://docs.pnbr.io/api/http-views-receipts-get.md)
* [Get context packet](https://docs.pnbr.io/api/http-views-receipts-packet.md)
* [Retire view](https://docs.pnbr.io/api/http-views-retire.md)

## Keep going

[File](https://docs.pnbr.io/concepts/file.md) · [Passage and citation](https://docs.pnbr.io/concepts/passage.md) · [Entity](https://docs.pnbr.io/concepts/entity.md) · [Search](https://docs.pnbr.io/concepts/search.md) · [View](https://docs.pnbr.io/concepts/view.md) · [Entities still cite a replaced version](https://docs.pnbr.io/troubleshooting/entities-cite-replaced-version.md) · [An entity rests on a trashed File](https://docs.pnbr.io/troubleshooting/entity-rests-on-trashed-file.md) · [No lookup finds the entities of one version](https://docs.pnbr.io/troubleshooting/what-cites-this-version.md) · [Find entities that rest on an old version or a trashed File](https://docs.pnbr.io/guides/find-stale-entities.md)

Penumbra Grammar 0.6.26


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.