Context Injection

Workspace files are injected into every agent's context in a specific order with strict token limits. Understanding these limits helps you design workspace files that stay within budget and do not crowd out conversation history or memory context.

Injection order

Workspace files are inserted between SOUL.md and the agent's system prompt in the assembled context:

text

1. SOUL.md                    (stable prefix, always first)
2. workspace/AGENTS.md       (priority file, always included)
3. workspace/USER.md         (priority file, always included)
4. workspace/IDENTITY.md     (priority file, always included)
5. other workspace/*.md      (alphabetical order, subject to budget)
6. Agent system prompt       (agent-specific, always included)
7. Memory context            (retrieved via RRF search)
8. Conversation history      (most recent turns)

Token limits

Scope	Limit	Behavior when exceeded
Per workspace file	20,000 tokens	File is truncated at the limit with a warning appended: `[truncated at 20K tokens]`
Total workspace files	150,000 tokens	Files beyond the total budget are excluded, lowest priority first
Priority files (AGENTS/USER/IDENTITY)	None — always included	Always included even if they push past the workspace budget

⚠Priority files are always injected but still subject to the per-file 20K token limit. If AGENTS.md exceeds 20K tokens, it will be truncated. Keep priority files concise and focused.

Budget tracking

The token_count column in workspace_files stores the estimated token count for each file. This is computed at write time using the same tokenizer as the configured default model. The context assembler uses these stored counts to make fast budget decisions without re-tokenizing on every request.

Priority ordering details

Files are sorted by their priority field in ascending order (lower priority number = included first). The three priority files have priority 0, 1, and 2 respectively. All other files have priority 100. Files with the same priority are sorted alphabetically by filename.

You can override the priority of a workspace file by adding a front-matter comment at the top:

markdown

<!-- priority: 10 -->
# Tech Stack Context

This document describes our technology choices...

Per-agent file filtering

By default, all workspace files are injected into all agents. You can restrict which files an agent sees by adding a tags filter in the agent config:

yaml

agents:
  - id: code-agent
    workspaceFiles:
      includeTags: [code, architecture]   # Only include files tagged with these
      exclude: [team-members.md]           # Explicitly exclude specific files

Tags are added to workspace files via front-matter:

markdown

<!-- tags: code, architecture -->
# Architecture Decisions

...