Skip to main content

​
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. 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.
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”:
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.
Context bodies go into the prompt. Secrets do not belong here, so use secrets or connected apps.

​
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

Attach by name when creating a session or an automation:

​
Where to look next

  • Memory Bank: the other half, what an agent writes for itself.
  • Sessions: where a context attaches, and dies.