Giving It Context
Four ways to give an agent the material it needs — one-off files, a reusable brief, a searchable corpus, and facts that persist across runs — and how to choose between them.
An agent only knows what you give it. "Context" is that material: the design doc, the meeting notes, last quarter's spreadsheet, the fact that your client prefers email.
There are four ways to supply it. They differ in how long the material lives and how it reaches the model — pasted in whole, or searched and sampled.
Pick one
| You have | Use | What it is | Reach for it when |
|---|---|---|---|
| A file or two, this once | A one-off file | Bytes you put in the content store and attach to a single run by their reference | You will not reuse the material. Nothing to name, nothing to clean up. |
| The same handful of documents, run after run | A bundle | A named, reusable brief: a handle plus its items, attached with --context | The grounding is stable and small enough to hand over whole. |
| More material than fits in one prompt | A dataset | A searchable corpus. The agent queries it by meaning and reads back the passages that matter | You have hundreds of pages, or you do not know in advance which part is relevant. |
| Facts that should survive the run | Memory | Durable facts an agent writes in one run and recalls by meaning in a later one | The agent should get better at your work over time, not start from zero each time. |
The first two put material into the prompt. The second two let the agent go and find material during the run, so the size of the corpus stops being the limit.
Bundles and one-off files combine with either of the other two — you attach them with
--context on the same command. Searching a dataset and recalling memories, though, are
two different agent recipes (kx/recipes/react-rag and kx/recipes/react-memory),
and a run binds one recipe. A single turn does not do both.
One-off files
Put the bytes in the content store, then attach the reference to one run. Nothing is named and nothing persists beyond the blob itself.
kx content put ./design.md
kx agent run --goal "summarize the design" --context-ref <hex32>kx content put prints the reference — a hash of the bytes, derived by the server:
ref=<hex32> size=<bytes> deduplicated=falseThe same bytes always produce the same reference. Attaching the same reference to the same goal therefore re-derives the same run identity, so re-running it returns the earlier result instead of paying for the work twice.
A reusable brief (a bundle)
A bundle is a named handle — namespace/collection/name — holding one or more items.
Author it once, attach it by name from then on.
kx context add team/ctx/spec --file design=./design.md --description "the design doc"
kx agent run --goal "summarize the design" --context team/ctx/specAttaching a bundle changes the run's identity: the same question with different grounding is a different run, cached independently. See Bundles.
A corpus to search (a dataset)
A dataset is a body of documents the agent searches rather than reads whole. You ingest once; each query returns the passages that match by meaning, not just by keyword.
kx datasets ingest my-corpus --file ./notes.md
kx datasets query my-corpus --text "what did we decide?" --k 5
kx agent run --goal "what did we decide about pricing?" --dataset my-corpusThe last line is the interesting one: the agent searches the corpus itself, reads what comes back, and searches again if it still cannot answer. That loop is Agentic RAG.
Datasets require a gateway built with the hnsw index (the vector search structure).
Without it, kx datasets answers that datasets are not wired on this gateway rather than
returning nothing.
Check what --dataset actually bound
On a gateway without the search recipe provisioned, kx agent run --dataset does not
fail. It prints a line saying the dataset was requested but the search agent is not
provisioned, and runs a plain agent with no grounding at all. Read that line before
you trust the answer. See Datasets.
Facts that persist (memory)
Memory is the only one of the four that a run can write. You can also seed and read it yourself from the command line:
kx memory add "the project deadline is March 3rd"
kx memory recall --text "when is my deadline?"For an agent to remember and recall on its own, the run must bind the memory recipe,
kx/recipes/react-memory — the one that grants the kortecx.memory.remember and
kortecx.memory.recall tools.
kx agent run does not select it; invoke that recipe directly, or use the SDK's memory
flow. See Memory.
Memory is off by default
Durable memory needs all three of: KX_SERVE_MEMORY=1, a served model (to turn text
into vectors), and a gateway built with the inference and hnsw features. Setting the
environment variable on its own is not enough. Without all three the memory commands
answer that memory is not wired on this gateway, rather than pretending to store
anything.
KX_SERVE_MEMORY=1 kx serve --dev-allow-localMemories are scoped to the party that wrote them, and any one of them can be erased with
kx memory forget <memory_id>.
When context does not fit
A model reads a fixed amount of text at once. On the serving path Kortecx budgets that
space in bytes, not tokens — a cap set by KX_SERVE_WINDOW_BYTES, 32 KiB by default.
When the attached material fits, it is passed through unchanged, byte for byte. When it does not, the runtime keeps the highest-relevance items that do fit and writes a visible line into the prompt saying what it dropped. The line looks like this — the counts here are made up, yours will be your own:
[context truncated: kept 2/3 items, dropped 5120B]The model sees that line. You see it in the run's prompt. Nothing is trimmed silently.
Two properties follow:
- The cut is deterministic. The same items and the same window size produce the same prompt, every time — so a replay re-reads exactly the text the first run read.
- An item too large for the window fails closed. There is no half-document. If even the most relevant item will not fit the budget, the run stops with an overflow error instead of feeding the model a fragment it has no way to know is a fragment.
Raise the budget if your model can take more. Values outside the accepted range are ignored and the default is used instead:
KX_SERVE_WINDOW_BYTES=65536 kx serve --dev-allow-localIf you keep hitting the cap with whole documents, that is the signal to move from a bundle to a dataset — searching a corpus is the design that does not have a size limit.
Next
Running the Runtime
What kx serve opens — the gRPC endpoint, the event stream, and the optional web console — and the auth posture it refuses to start without.
Datasets
Give the runtime your documents so it answers from them — ingest text and files into a named corpus, then search it with hybrid retrieval that returns the same order on any machine.