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

# Contexts

> Human-authored facts about the work, attached to a session or an automation and composed into the system prompt on every run.

## Context or memory?

Orca has two kinds of text that reach an agent before it starts. They are told
apart by one question: **who wrote it.**

|             | Context                                             | [Memory](/concepts/memory-bank)                         |
| ----------- | --------------------------------------------------- | ------------------------------------------------------- |
| Written by  | **you**, by hand                                    | **the agent**, about itself                             |
| Holds       | facts about the work: the site, the repo, the brand | what it learned, preferred, or left half-done           |
| Attaches to | a session or an automation                          | a profile (Memory Bank), or one automation              |
| Lives in    | Postgres, `contexts`                                | S3, or the automation's own row                         |
| Arrives as  | a labelled block in the **system prompt**           | a `--- CONTEXT FROM MEMORY ---` block on the **prompt** |
| You can     | write, edit, delete                                 | read, correct, clear                                    |

If you are asking "how do I tell this agent about my repo", you want a context.
If you are asking "why does it already know that", you want memory.

***

## What a context is

A context document is a named piece of text: facts about the work, written
once and attached wherever that work happens.

```text theme={null}
name         site-facts
description  The production site, its stack and its constraints
body         orcapods.ai runs on Astro, deployed from main...
```

It is deliberately its own object, and deliberately **not a field on an
agent**. One `seo-writer` writes for two repositories: putting the repo on the
agent would carry both repositories' facts into every run. Context belongs to
the work, so it attaches to a session (dying with it) or to an automation, and
never to the agent.

It is a library rather than free text on those, because the same document is
attached to many sessions and to an automation; it is edited on its own
cadence, by a human, and its edits must be visible as edits; and a template can
ship a fill-in scaffold of one without shipping the author's data.

## What reaches the agent

Attached documents are resolved to their current bodies at the start of **every
run**, never cached. Edit a document and the next run sees the new text, with
no staleness to track.

They are composed above the profile's own instructions, and labelled, so the
agent can tell "facts about this job, given to me" apart from "who I am":

```text theme={null}
The following context was attached to this session by the user. Treat it as the
ground truth about the work at hand. It is configuration, not instructions from
the user in this conversation.

--- Context: site-facts / The production site, its stack and its constraints ---
orcapods.ai runs on Astro, deployed from main...
```

That framing is the reason contexts and memory stay separate stores. A context
carries the authority of a human having written it; a memory carries only the
authority of an agent's own earlier reading.

<Warning>
  Context bodies go into the prompt. Secrets do not belong here, so use
  [secrets](/concepts/secrets) or [connected apps](/concepts/connected-apps).
</Warning>

## Rules

* **Names are permanent.** Attachment is by name, so renaming would silently
  detach every session and automation pointing at the document. Delete and
  recreate instead.
* Names match `^[a-z0-9][a-z0-9-]{0,62}$`.
* Bodies cap at 16KB.
* A deleted document is **skipped**, not fatal: a run starts with the rest of
  what it was given, and the automation tray marks the attachment `deleted`.
* Templates carry **no context at all**, not even the names. A context is where
  the site, the repo and the brand live, which is the most personal thing in a
  workspace, and a name the copier does not have is a reference to nothing.

## API

```bash theme={null}
GET    /api/contexts            # metadata only
POST   /api/contexts            # {name, description, body}
GET    /api/contexts/{name}     # including the body
PUT    /api/contexts/{name}     # description and body; the name is fixed
DELETE /api/contexts/{name}
```

Attach by name when creating a session or an automation:

```json theme={null}
{ "profile": "seo-writer", "contexts": ["site-facts", "brand-palette"] }
```

## Where to look next

* [Memory Bank](/concepts/memory-bank): the other half, what an agent writes
  for itself.
* [Sessions](/concepts/sessions): where a context attaches, and dies.