Managing agent context
On this page
This page is generated from docs/source/guides-managing-agent-context/ — each section below links to its own source.
An agent does not arrive at a task knowing nothing. It arrives carrying directives, memories, a record of how this person wants to be asked, and whatever confirmations were granted in advance. All of that is context: it shapes how a process runs without being part of what the process produces.
A Context Overlay is a set of that material applied deliberately, so the same workflow can be run again under the same conditions — or run twice under deliberately different ones, and the difference attributed to the context rather than to chance.
Three things that share the word overlay
“Overlay” already means three unrelated things in this documentation, which is why the Term on this page is Context Overlay and not the bare word.
| where | what it means |
|---|---|
| this page | a set of context material applied to a run |
getting-started §6 | a BRANCH of the folio-intent gateway — converting a repository you already have |
getting-started §art | positioning text ON cat artwork, where an undeclared region means “do not overlay” |
None is wrong. They are simply different, and a reader who meets the bare word in one section and carries its meaning into another will be misled in a way that is hard to notice, because every sentence still parses.
So: Context Overlay when this page’s sense is meant. Where the other two are meant, name them — the gateway branch, or the art region.
What a Context Overlay is
Context is generated in several different ways, and the point of the Term is that they compose. A Context Overlay MAY be assembled from any of them:
- Agent directives — the instruction files an agent reads on arrival.
- Memory — durable facts an agent carries between sessions.
- Interaction preferences — how this person wants to be asked.
- Waivers — confirmations granted in advance, each naming one gate.
- Methodologies — an adopted way of reaching a judgement.
What makes them one kind of thing is not their format. It is their relation to a running process:
Context is READ during a process and never written by one.
That is the definition the graph layer uses, and it is checkable rather than a matter of taste. A step that writes to a Context graph is a defect, not an update — which is exactly what makes an overlay reproducible: if a run could modify its own context, the second run would not be the same experiment.
What the Context layer holds
The Context layer is declared, not inferred. Five graph typologies currently sit in it, and the schema requires each kind to say which layer it belongs to, so a kind that has not decided does not compile:
| kind | what it holds |
|---|---|
memory | durable facts an agent carries between sessions |
interaction | how a person wants to be asked — read at session start |
waiver | confirmations granted in advance, each naming one gate |
methodology | an adopted way of reaching a judgement, kept whole |
fsh-guts | deprecated and throwaway structured content, kept addressable |
Ask the code rather than this table — graphTypologiesOfLayer("context") returns
the live answer, and a count written into prose is a claim nothing re-derives.
The shapes are in
schemas/cat-harness.ts.
fsh-guts is the entry that reads oddly and is worth the sentence: it holds
structured material that COULD be rendered, which is what makes it look like
content. It is context because no running process writes it.
Why overlaying makes a test repeatable
The reason to name this at all is testing.
If context is ambient — whatever happened to be in the environment when the run started — then two runs of the same workflow are not comparable, and a difference in outcome cannot be attributed. Was it the model? The prompt? A memory entry one session wrote and another did not have?
Overlaying context makes that question answerable. The workflow is held fixed, the Context Overlay is stated, and a difference between runs is a difference between overlays. It is the same move as pinning a dependency version: not because the version is special, but because an unpinned one makes every other measurement unreliable.
This is what lets the repository ask how models compare across sub-workflows
under a controlled overlay of context and memories — a question named as
open research in agentic-harness, not as something
settled here.
Where the rules live
This page explains the concept. The discipline is in the skills, and where the two disagree the skill wins:
agent-memory— the three entry labels, why entries are authored as nodes rather than in the generated file, and the injection budget.content-context-and-state-graphs— the one question that settles a layer, and why a step writing to a Context graph is a defect.confirmation-waiver— a confirmation granted in advance, scoped to a session or a process run.interaction-modality— how a person wants to be asked.
Setting an agent’s context deterministically from the knowledge graph at each
task is not yet built; it is tracked as bean 3q47. Saying so here is
deliberate — a page that described it as working would read exactly like one
that described something real.