Context and caching¶
Each request contains more than the latest message. minacode arranges the model’s context so the stable parts come first, the active conversation follows, and frequently changing task state comes last. This keeps the agent informed while giving supported providers a long, reusable prompt prefix.
What the model receives¶
Tool definitions are sent beside this message stack: built-in tools, Skill when skills are
installed, and MCP tools and resources from currently connected servers.
Configured but disconnected servers do not consume context.
Keeping context manageable¶
Large tool results are shortened before they enter the conversation; the agent can retrieve the
complete result later with Recall. Repeated skill instructions and MCP descriptions are replaced
with references to their first full copy instead of being sent in full again.
Compaction¶
As the estimated request approaches runtime.max_context_tokens, minacode compacts: the older
part of the conversation is replaced by a short summary, and the most recent messages are kept as
they are. The trigger reserves the configured provider output cap (16K when unspecified), tool
schemas, and a safety margin of at least 4K. The session continues in the same turn, so a long task
does not have to stop.
The summary in the active context is lossy, but each compaction also captures a bounded verbatim excerpt of the evicted messages as a history segment. Earlier snapshots in the append-only session log remain the cold source of truth, so compaction does not rewrite them.
The bounded history index is a separate context section before conversation history. The agent
uses RecallContext to retrieve a seg.N excerpt directly or regex-search stored segment titles
and text for earlier detail. Task memory (goal, plan, facts, checks) follows conversation history
and is carried across untouched, which is why decisions worth keeping belong there.
Run /compact to compact immediately rather than waiting for the threshold, for example before
starting a large refactor. /status reports how many compactions a session has done.
Prompt caching¶
Prompt caching lets a provider reuse work for an unchanged beginning of a request. The next request usually begins with the same instructions, environment, tools, history index, and earlier conversation, so only the new tail needs to be processed. Task memory follows conversation history so updating it does not invalidate that larger prefix. Connecting an MCP server, changing installed skills, switching models, or otherwise changing an early section can reduce the next request’s cache hit.
A request is reused only up to its first difference, so a change near the beginning — connecting an MCP server, installing a skill, switching models — shortens the reusable prefix. That is why the stable sections are placed first.
OpenAI-compatible providers may reuse matching prefixes automatically; minacode supplies a stable cache key where the provider supports one. For Anthropic, minacode explicitly marks the tools and system instructions as an ephemeral cacheable prefix. Provider support and accounting differ.
Checking the hit rate¶
/status reports the cached prompt tokens the provider counted — once for the whole session, and
again for the most recent request:
The ratio varies with the provider, model, prompt length, and conversation. When request prefixes line up, it can reach 90–99%. This is an observation, not a guaranteed rate.