Overview
Context packs are task-focused subsets of your project brain. Instead of loading the entire brain, a context pack uses semantic search to find and assemble only the memory items most relevant to your current task. This provides more focused context within a smaller token budget.
How context packs work
- You describe your current task in natural language
- The system converts your task description into a vector embedding
- Memory items are ranked by semantic similarity to your task
- The most relevant items are assembled into a token-budgeted markdown document
Scopes
Context packs support three scopes:
relevant (default)
Uses semantic search to find task-related items. This is the most useful scope for active development work.
contox_context_pack(task: "implementing OAuth2 login", scope: "relevant")
The system searches all approved memory items and returns those most semantically similar to your task description.
full
Returns the complete brain document, truncated to the token budget. Useful when you need a broad overview rather than focused context.
contox_context_pack(task: "general project overview", scope: "full")
minimal
Returns only the top 5 highest-confidence items. Useful for quick checks or when working on well-understood areas.
contox_context_pack(task: "quick context check", scope: "minimal")
Token budget
The tokenBudget parameter controls the maximum size of the returned context pack (default: 4000 tokens):
contox_context_pack(task: "database migration", tokenBudget: 8000)
The assembler includes items in order of relevance until the budget is reached. Higher-relevance items are always included first.
Usage
Via MCP
The primary way to use context packs is through the MCP server:
contox_context_pack(
task: "Adding rate limiting to the API endpoints",
scope: "relevant",
tokenBudget: 6000
)
Via CLI
contox context-pack --task "Adding rate limiting" --scope relevant --budget 6000
When to use context packs vs. the full brain
| Scenario | Recommendation |
|---|---|
| Starting a new session | Full brain (GET /api/v2/brain) |
| Working on a specific feature | Context pack with relevant scope |
| Quick reference check | Context pack with minimal scope |
| Debugging a specific area | Context pack with relevant scope and detailed task description |
| Onboarding a new team member | Full brain with higher token budget |
Semantic search fallback
If semantic search is unavailable (e.g., embeddings have not been generated for some items), the system falls back to the full brain document, truncated to the specified token budget.
Tips for effective context packs
- Be specific in your task description -- "Implementing JWT refresh token rotation in the auth middleware" produces better results than "auth work"
- Include relevant terms -- Mention specific technologies, file names, or patterns you are working with
- Adjust the token budget -- Increase the budget for complex tasks that may span multiple areas of the project
- Use relevant scope by default -- It provides the best balance of focus and coverage
Next steps
- Brain Assembly -- How the full brain is assembled
- V2 Brain API -- Full brain endpoint reference
- Enrichment -- How items get their embeddings