Agent Context
An agent’s answer is only as good as what the model sees when it answers. That material is the agent’s context, and it comes from several places with different owners and lifetimes: some you write in advance, some the crew produces while it deliberates, and some the runtime adds on its own.
This page is organized by where context comes from, following the sources that LLM agent context is usually drawn from. It lists the parts of an agent’s context in Kubemoot and says plainly where Kubemoot does not cover a source yet, with the proposed approach labeled as a proposal. Context engineering in general also names parts such as examples and output format; here those live in the instructions, written as ADL in PromptModules.
Sources at a glance
The last column separates trusted instructions, which you or your user wrote and the model should follow, from untrusted data, which the model reads but must not obey. See Why the split matters in a crew.
| Source | Kubemoot covers | Trust |
|---|---|---|
| Static or configured | ||
| System prompt | PromptModule resources written in ADL and the Agent spec, rendered into the system prompt at agent start | Trusted instructions |
| Tool definitions | MCP tools through the crew’s gateway, narrowed per agent by enabledTools | Trusted instructions |
| Few-shot examples | Written inside a PromptModule next to the rules they illustrate; no separate mechanism | Trusted instructions |
| Skills or instruction files loaded on demand | Skill resources the coordinator selects and injects for the discussion that needs them | Trusted instructions |
| Conversational | ||
| User messages | The question sent to the crew’s discussion gateway | Trusted instructions |
| Conversation history | The kubemoot_conversations bucket; the last 10 turns, expiring after 24 hours of inactivity (defaults) | Your earlier turns are trusted instructions; the crew’s earlier answers are untrusted data |
| Conversation compaction | Not yet. Proposed: an adopted agent harness that compacts long conversations, rather than growing Kubemoot’s own runtime | Not applicable |
| Retrieved | ||
| RAG | RAGSource documents, indexed into a vector store. Searched per question when named in spec.ragSources, or on demand when the agent lists <source>_search in spec.enabledTools | Untrusted data |
| Keyword or structured search | workspace_query (SQL over the workspace), the coordinator’s resume search, and the gateway’s optional tool search | Untrusted data |
| Web search and fetch | A web search tool server, when the crew has one | Untrusted data |
| Tool and environment output | ||
| Tool results | Returned through the gateway; large ones are stored in the workspace and passed by reference | Untrusted data |
| Environment observations | Through tools, such as kubectl output | Untrusted data |
| Errors and feedback | Tool errors, failure signals to the table, and the compute contract’s re-prompt | Tool errors are untrusted data; the re-prompt is runtime text |
| Memory | ||
| Working memory | Within one agent call; across agents, the discussion thread is the crew’s shared working state | Untrusted data where it holds peers’ words |
| Long-term memory | Crew memory: facts about the domain, written by REMEMBER: lines and injected before each query. Not yet for facts about users | Untrusted data |
| Episodic memory | Not yet. Proposed: past discussions as retrievable episodes in the crew memory design, following the Open Memory Protocol | Not applicable |
| Multi-agent | ||
| Messages from other agents | The discussion thread, the table: the coordinator’s brief and each agent’s signals and evidence | Untrusted data |
| Metadata or runtime | ||
| Injected runtime context | The discussion frame, the agent’s own description and tools, the crew resumes, and the requester’s time zone and date passed to tools | Runtime text |
| Token budgets | Not yet. Proposed: a context budget per agent call, set by the operator | Not applicable |
| User preferences or profile | Not by Kubemoot. An application in front of a crew supplies them, for example as runtime metadata | Not applicable |
Static or configured
This context is written before any question arrives. It is the part you control most directly, and it is trusted.
System prompt. Instructions are PromptModule resources written in ADL, the
Architecture Definition Language of Mark Richards and Neal Ford applied to agents, and
attached to an Agent through spec.promptRefs. The Agent spec adds the rest of the
declaration: its capabilities, its role, and the tools and knowledge sources it may
use. Prompt text never lives inline in the spec.
Because these are Kubernetes resources, they follow the path of the rest of your configuration: stored in Git, reviewed in a pull request, applied by GitOps, guarded by RBAC. The operator assembles the PromptModules into one system prompt and mounts it into the agent. The agent reads it when it starts, so editing a PromptModule changes the prompt hash on the pod and rolls the agent. See Agent Definition Language.
Tool definitions. An agent is offered the names, descriptions and parameters of the
MCP tools it may call. It reaches them through its crew’s MCP gateway, which aggregates
every tool server of the crew, and spec.enabledTools and spec.disabledTools narrow
the set to the few that fit the agent’s job. Keep the set small, because tool-calling
reliability falls as the list grows. If an agent declares tools the gateway does not
offer, it signals failure rather than answering without them. Definitions are read
from the gateway each time the agent looks, so a tool server added later is picked up
without a restart. See MCP Tools.
Few-shot examples. Kubemoot has no separate example mechanism. An example is text you write inside a PromptModule, next to the rules it illustrates.
Skills. A Skill is a crew-level procedure written in ADL. Its body stays out of
every prompt until a discussion needs it: the coordinator reads each skill’s
description when it chooses who joins, selects the skills that fit the question, and
only the selected bodies are loaded and added for that discussion. See the
Skill reference.
Conversational
User messages. The question you send arrives at the crew’s discussion gateway and opens a turn. It is the one input the crew treats as the request to act on.
Conversation history. A conversation is your ongoing exchange with a crew,
identified by a conversationId. It holds a history of turns, each a question and
the answer the crew settled on. On a follow-up, the coordinator places the recent turns
in front of the discussion so the question is read in context.
The history is bounded and durable. It keeps the most recent turns (ten by default),
expires after a period of inactivity (a day by default), and is stored in the NATS KV
bucket kubemoot_conversations under the key conv.<conversationId>, so a session
survives a coordinator restart. Supplying the same conversationId continues a
conversation; omitting it starts a new one. Old turns drop off the end. Kubemoot does
not compact or summarize them. See
Conversations, Turns & Threads.
Retrieved
RAG. Knowledge is reference material the crew retrieves rather than remembers. A
RAGSource points at documents; the operator indexes them into a vector store and runs
a query service for each source. An agent gets that reference text in one of two ways.
Up front. The agent names the source in spec.ragSources, with a topK (default 5)
and a priority. The operator resolves the source to its query service and passes the
endpoint to the agent as an environment variable, and the agent’s network policy allows
only the services it is configured to call. When the agent answers, the runtime searches
the source with the user’s question (in a discussion, the question and not the whole
thread) and places the top results in the system prompt ahead of every model call.
On demand. The query service is also an MCP server with one tool, <source>_search
(for a RAGSource named kubectl-reference, kubectl-reference_search), taking a query
and an optional top_k (1 to 100). For each RAGSource the operator generates an
MCPServer named <source>-search that points the crew’s MCP gateway at the query
service, so the tool reaches agents the way every other tool does. The agent lists
<source>_search in spec.enabledTools and leaves the source out of spec.ragSources.
It searches when it decides it needs reference text, and the passages arrive as a tool
result, each with its source path and score. Nothing is added to the system prompt, so a
question the live data answers costs no reference text.
The generated MCPServer carries the RAGSource’s labels (without the ones Helm and Flux
own), so a gateway that selects tool servers by the crew’s instance label finds it. A
RAGSource with spec.queryService.enabled: false, or one the operator created for
itself (the tool index, a crew’s agent resumes), gets no tool.
Which to choose. Search up front when every question the agent gets needs the
reference text and the model is too small to be trusted to ask for it: the text is always
there, and no model round trip is spent asking. Search on demand when only some questions
need it: an advisor that mostly reads live cluster data and sometimes needs to know how a
setting behaves loads reference text for those questions only. The cost is that the model
must decide to call the tool, and a search adds one model round trip, so say when to
search in the agent’s prompt module (a question about how a tool, an API or a setting
behaves) and when not to (a question the live data answers). An agent can use both, for
different sources. Keep topK and top_k small either way, because large retrieved
payloads degrade tool calling. See the
RAGSource guide and the
Agent reference.
Keyword and structured search. Three mechanisms answer a precise question without loading a whole document:
workspace_queryruns one read-only SQLSELECTover named artifacts in the workspace, so counting and totalling are done by a database instead of by the model.workspace_listlists what the discussion has stored, andworkspace_describegives each table’s columns, types and example values (see List and describe the workspace).- The coordinator has a query service of its own. The operator indexes the crew’s
resumes into a per-crew
RAGSourceand points the coordinator at it, so the coordinator can narrow the crew to the agents whose expertise matches the question. - The MCP gateway can offer a tool search so an agent finds a tool by intent. It is optional and off unless the gateway enables it.
Web search and fetch. A crew gets web content only when it includes a web search tool server. The content arrives as tool results and is treated as untrusted data.
Tool and environment output
Tool results. A result returns to the model inside the agent’s tool loop and becomes part of that call’s context. A Tooler’s findings are then published to the thread for the other agents. A result above a size threshold goes to the workspace and travels by reference.
Environment observations. Kubemoot gives an agent no direct view of its
environment. What an agent observes, such as the output of kubectl, arrives as a tool
result.
Errors and feedback. A failed tool call returns its error to the model. When the
same tool keeps failing the same way, keeps failing after several corrections, or the error rate climbs, the loop stops and the agent
publishes a failure signal that the whole table sees. For a compute agent, the runtime
adds one more kind of feedback: if the agent states a number without running code, the
runtime re-prompts it to compute the result by running the code over the data.
Workspace
The workspace holds bulk data for one discussion. A tool output or contribution above a
size threshold is stored whole in a NATS object store and passed to the table by
reference: the message carries a preview and a reference envelope, and an agent that
needs more reads a bounded slice with head, tail, grep, select, count, rows
or jq. The optional workspace_query tool uses a SQLite or DuckDB engine. Agents
without network access read the same data as files materialized under /kubemoot/workspace.
Workspace objects are keyed {namespace}/{crew}/{threadId}/{agent}/{tool}-{seq} and are
deleted with the discussion: when the thread closes, then by a bucket expiry, then by a
background reaper for anything left.
The tool names, the mount and the docs call this store the workspace. “Artifact” is kept for generated work delivered to you (see Artifacts). See The workspace for the full mechanism.
Memory
Working memory. Within one agent call, working memory is the model’s own context: the prompt, the tool results so far, and its reasoning. Across the crew, the discussion thread is the shared working state of the turn (see Multi-agent).
Long-term memory. Crew memory holds facts the crew learned about its domain, so it
stops rediscovering them. It records facts about the domain and the environment. Not yet for
facts about users. It belongs to the crew, not to a single agent, and is configured by
spec.memory on the Crew resource (the Agent spec has no memory field).
- Write. When an agent resolves a durable fact, it ends a line of its answer with
REMEMBER: <topic> | <key> | <value>. The runtime parses the line, stores the fact, and strips the line from the answer the user sees. Only an agent’s own text can write crew memory, including a line a tooler writes beside a tool call or after its tools ran. AREMEMBER:line inside a tool result never does, and a tooler’s posted tool output is never changed. - Storage. Facts live in the NATS KV bucket
kubemoot_crew_memoryunder the key<namespace>.<crew>.<topic>.<key>. Each value is a JSON record withvalue,learnedBy,learnedAtandusedAt. - Read. Before each discussion query, the runtime injects the crew’s relevant facts into the agent’s system prompt under a “Crew Working Memory” heading. Facts that share words with the question rank first, then the most recently used. The agent does not have to decide to look anything up.
- Caps and lifetime. Injection is capped (
injectLimit, eight by default) and storage is capped (maxFacts, 5000 by default, least recently used evicted). A fact that is read is refreshed, and a fact unused forttlDaysis pruned. Deleting the Crew removes its facts; updating it keeps them.
Because agents write memory from what they read, a stored fact can carry content that came from a tool or a peer. Treat injected memory as data.
Export.
ompi-exportwrites one crew’s facts in the interchange form of the Open Memory Protocol Initiative (OMPI) exchange-and-runtime working spec v0.6, so another system or person can read them. It only reads the bucket and never changes a fact. The output directory holdsmanifest.jsonand one JSON file per fact undermemories/. With--markdownit also writes each fact as a Markdown file with front matter undermarkdown/, the spec’s runtime form. The spec is an editors' draft with no official validator, so the export is checked against JSON Schemas Kubemoot keeps in the operator module, derived from the draft; a passing check means the export follows our reading of the draft, not that OMPI certified it. The export follows the draft’s unmarked and agreed text. The draft also lists proposals it marks “Proposed” and the group has not accepted; the export does not follow those until they are adopted. The files hold text the agents wrote, so whatever reads them should treat them as data. Importing is not supported yet.kmctl memory export <crew>writes the same export from your terminal, with no operator source.The spec (section 3.5.6) says credentials must not be exported as memory, so the export screens each fact. A fact whose value, topic or key holds a credential is left out and listed, never with the text, and the manifest says
selection. A credential in the value is listed with the shape it matched. A credential in the topic or key is found with the strict redaction, so a shortpassword=xcounts, and the fact is listed by an opaque id (<namespace>.<crew>.#<id>, a truncated one-way hash of the store key), because its key would print the credential; an unreadable entry whose key holds one is listed the same way. The shapes are a bearer or basic token, an API key, a token or password assignment with a value of eight or more characters (any length in a topic or key), a JSON Web Token, a cloud access key, a private key header, a password in a URL, and a long hexadecimal string. The screen is tighter than the harness redaction: it does not flag the word “basic” or “bearer” before an ordinary word, a content digest such assha256:..., or a bare commit hash or SHA-256 unless a word like key, secret, token or password sits next to it. It still matches shapes, so it can leave out a fact that only looks like a credential.--allow-unscreenedexports every fact as stored, for operators who accept that the files may hold credentials.What maps, and how:
Crew memory OMPI memory object <namespace>.<crew>.<topic>.<key>identifier, a name-based UUID of that key, so a fact keeps its identifier in every exportthe spec version the export follows protocol_versionon every memory, the same value as the manifesttopic and key title(“topic / key”) andpath(topic/key, reduced to letters, digits, underscore and hyphen; the original topic and key stay inx-kubemoot)value body, withmedia_typetext/plainlearnedAtcreated_at(the agent’s record of when it learned the fact, since the store keeps only the time of the latest write; that time stands in whenlearnedAtis missing)the store’s write time updated_atthe store’s revision number version, with the comparatorintegerlearnedByone provenanceentry,kindagent,contributionauthored; left out when no agent is recordednamespace and crew scopecrew:<namespace>/<crew>usedAt, namespace, crew, topic, keythe x-kubemootextension fieldThe manifest names the spec version (
protocol_version), theminimalprofile, anoriginthat stays the same for one crew (override it with--origin), the time of the export, andintentcopy. It sayssnapshotwhen every readable fact is in the export andselectionwhen some were left out; each left-out entry is printed with its reason.Some things are left out because the store does not hold them. Crew memory records no evidence, so the export carries none and says so in
x-kubemoot(evidenceUnavailable). It reads only the current value of each key, so it writes nosupersedeslinks and no earlier values. It writes nochecksum, because the draft does not yet say how to compute one. The revision number is a counter for the whole bucket, and reading a fact refreshes it, so a version change does not always mean the text changed, andupdated_atmoves with it.The scope names the crew that owns the memory. To a receiver a crew is one owner, however many agents it has, and the draft treats scope tags as opaque, so the tag needs no convention. What the crew’s agents did with a memory belongs in
provenance: the agent that learned it isauthored, and when crew memory records them, agents that confirmed it areverifiedand an agent that disputed it iscontradicted. The export writes onlyauthoredtoday, because the store records only the agent that wrote each fact.
kubectl -n nats port-forward svc/nats 4222:4222
cd operator && go run ./cmd/ompi-export --namespace <namespace> --crew <crew> --out ./memory --markdown
Add --allow-unscreened to keep facts that hold a credential in the export.
Episodic memory. Not yet. Kubemoot does not retrieve past discussions into a new one. Proposed: past discussions as retrievable episodes in the crew memory design, following the Open Memory Protocol.
See the Crew reference for every field and the duplicate and conflict rules.
Multi-agent
Discussion thread (the table)
This source is what is distinctive about a crew. Each turn runs on its own thread, and the thread is the shared context for everyone at the table. Agents do not each receive a private copy of the question; they read the same running record and reason over what their peers have contributed.
The thread lives on the message bus on the subject
kubemoot.discuss.<namespace>.<crew>.<channel>.<threadId>. It carries, in order:
- The question, as the user asked it, and the previous turns when it is a follow-up.
- The coordinator’s brief. The coordinator selects the subcommittee for the question and posts a framing brief that tells the selected agents what the question is about and where to look.
- Each agent’s signals and evidence. Every contribution carries a consensus signal
(
agree,concern,stand_aside,block,failure) and the finding behind it, including the data a Tooler retrieved. Analysts read the Toolers’ findings in the review phase before they weigh in. - Workspace references. A contribution too large to carry inline appears as a short preview plus a reference to the object in the workspace.
The runtime formats the thread for each agent as a labelled transcript (user question, advisory, responses, concerns, stand-asides, synthesis), so an agent sees which peer said what. The thread is one turn long: it closes when the answer settles, and a reply reopens it for another round. Subjects carry the namespace and crew name, so two crews never see each other’s threads. That is naming separation, not an access boundary; see Isolation and SECURITY.md.
Most writing on context engineering describes a single agent. The thread exists only because several agents deliberate together. See The Moot, Signals & Protocol and The Table and the Harnesses.
Metadata or runtime
Injected runtime context. The runtime adds a short list of items without your writing them, and only these:
- The discussion frame. In a discussion, the agent’s prompt opens with a line that it is taking part in a team discussion on a named thread, and the system prompt ends with the thread’s identifier so prompt modules and tools can refer to it.
- The agent’s own card. For the quick “should I contribute?” check, the agent is shown its own name, its description, the tools it has, and the technologies the coordinator named for the question.
- The crew roster, for the coordinator. The coordinator reasons over the crew’s resumes, a catalog of what each agent can do, to choose which agents to convene. The operator compiles the resumes from the Agent specs.
- Where and when the requester is. A client may send the requester’s time zone and local date and time with a question. The runtime passes them on the thread and hands them to tools as MCP metadata, so a tool that needs “today” uses the requester’s date rather than the server’s clock. They are not written into the prompt text.
The runtime injects no description of the agent’s permissions; Kubernetes RBAC and network policy enforce them around the agent. Kubemoot sets no token budget on any part of the context. Not yet. Proposed: a context budget per agent call, set by the operator.
User preferences or profile. Not by Kubemoot. An application in front of a crew supplies them, for example as runtime metadata.
Why the split matters in a crew
Prompt injection enters through untrusted data: text that reads like an instruction but arrives as content. Retrieved documents, web pages, tool output and other agents' messages are all content. Only the static and configured sources and your own messages are instructions.
A crew widens the path. An agent that reads an injected web page or a poisoned tool result can restate it in its contribution. The contribution goes onto the discussion thread, where every peer reads it, and a peer may repeat it again in its own contribution or store it in crew memory. For that reason other agents’ contributions are untrusted data too, even though they come from agents in your own crew.
What this means in practice:
- Write rules that govern behavior in PromptModules, not in places an outside source can edit.
- Give each agent only the tools it needs with
enabledTools, so an injected instruction has little to call. - Put tools that read external content on agents whose other tools are read-only.
- Treat a surprising instruction inside a contribution, a retrieved passage or a stored fact as a finding about the content, not as an order.
For the full path an instruction takes through a crew, what defends it and what does not, see the Crew threat model.
Artifacts (planned)
Artifacts are generated work that outlives the discussion that produced it: a report, a manifest, a dataset a crew builds and hands to the user. This is the sense the A2A protocol uses for the word. Artifacts are planned and not shipped; nothing in Kubemoot today keeps generated work beyond the discussion’s lifetime. The discussion artifact store described under Workspace is temporary by design and is the reason for the planned rename.
Open standards
Crew memory can be exported in the exchange format of the Open Memory Protocol Initiative (OMPI), working spec v0.6 (see Memory). The spec is a draft and may change. Importing OMPI memory and storing memory natively in that format are planned. Until then, memory is stored as Kubemoot’s own JSON record.
Related
- Crews & Agents - how an agent composes instructions, tools, knowledge and memory.
- Agent Definition Language - the language the instructions are written in.
- Conversations, Turns & Threads - the conversation and thread vocabulary.
- The Table and the Harnesses - the layer above the single-agent loop.
- The workspace - the workspace mechanism.
- Crew reference - the
spec.memoryfields.