Context System

Every user message drives a context pipeline. It classifies the question, gathers relevant code in parallel from four sources, budgets against the active model’s window, and hands the result to the prompt assembler.

Note: this page and Prompt Pipeline overlap. This page focuses on what goes into context; the pipeline page focuses on how the prompt is assembled around it.

Pipeline

sequenceDiagram participant User participant QC as Classifier participant CG as Gatherers participant Sel as SmartContextSelector participant PA as Prompt assembly participant CW as Window compactor User->>QC: Message + @-files QC->>QC: Classify (isCodebase? categories? confidence?) alt Not codebase-related QC-->>PA: Raw message (skip gather) else Codebase-related par @-files CG->>CG: Load user-selected file contents and AST CG->>CG: Tree-sitter symbol scan from search terms and Semantic CG->>CG: Hybrid BM25 + vector via HybridSearchService and Arch + memory CG->>CG: Architecture context + core memories + team graph end CG->>Sel: All gathered snippets Sel-->>PA: Selected within budget end PA->>CW: Assembled prompt alt > 90% window CW->>CW: 5-tier progressive compaction end CW-->>User: Final prompt to LLM

Gathering — 4 parallel sources

1. @-mentioned files — always included at highest priority. Active editor is auto-added if not already mentioned.

2. AST scan — AnalyzeCodeProvider uses Tree-sitter to locate relevant symbols. Search terms come from @-file keywords (fast path) or a SecondaryLLMService call (~200 ms).

3. Hybrid semantic search — ContextRetriever runs a 4-tier cascading query:

1. Hybrid: vector similarity + BM25 via HybridSearchService
2. Keyword-only: FTS4 fallback if embedding fails
3. Legacy vector: brute-force cosine scan
4. Legacy keyword: term counting

Broad/architectural questions get README, package.json, and entry points auto-appended. Results deduped by file path, capped at 15.

4. Architecture + memory + team — persistent codebase analysis (patterns, frameworks), manage_core_memory entries, TeamGraphStore data if available. All passed through sanitizeForLLM() before injection.

Non-codebase questions (general knowledge, small talk) skip gathering entirely — saves tokens and latency.

Selection — SmartContextSelectorService

Token budgets

Model	Budget
Claude 3 Opus	50 000
GPT-4o	20 000
Qwen 2.5 Coder	4 000
Default fallback	4 000

Estimation: 1 token ≈ 4 chars.

Scoring

Source	Score
User-selected (@ mention)	1.0 — always included first
Auto-gathered	0.1–0.9 by keyword density + name matches

extractSmartSnippets() pulls functions, classes, interfaces, types, and variables using per-language regex (TypeScript, JavaScript, Python). Prefer signatures over full bodies when the budget is tight.

Selection

1. Dedupe by filePath:startLine.
2. Sort by score descending.
3. Greedy pack until the next snippet would exceed the budget.
4. Return ContextSelectionResult — snippets, total tokens, wasTruncated, droppedCount.

Window compaction

When the assembled prompt approaches the active model’s context window, ContextWindowCompactionService progressively compresses history.

Known windows:

Model family	Window
Gemini 1.5/2 Pro	1–2 M tokens
Claude Sonnet 4/5, Opus 4	200 K
GPT-4o	128 K
DeepSeek	64 K
Fallback	16 K

Effective window: codebuddy.contextWindow setting → model-family lookup → 16 K default.

5-tier compaction (kicks in progressively; 4 most-recent messages never touched):

Tier	Strategy	Effect
1	NONE	No compaction
2	TOOL_STRIP	Drop large tool results (>200 chars) from older turns
3	MULTI_CHUNK	Summarize message batches with overlapping windows
4	PARTIAL	Summarize the oldest half
5	PLAIN_FALLBACK	Plain-text compression when LLM summarization fails

Warning at 80% of the window, auto-compact at 90%.

See Self-healing Layer 4 for the compaction integration with the safety guard.

Inline completion context

A separate lighter pipeline via ContextCompletionService:

Component	Budget
Prefix	2 000 tokens
Suffix	500 tokens
Imports	Extracted via Tree-sitter

FIMPromptService wraps these in Fill-in-the-Middle tokens appropriate for the model family (DeepSeek, CodeLlama, StarCoder/Codestral, Qwen). See Inline Completion.

Settings

Setting	Default	Meaning
codebuddy.contextWindow	"16k"	Cap the window: 4k, 8k, 16k, 32k, 128k
codebuddy.includeHidden	false	Include hidden files during gathering
codebuddy.maxFileSize	"1"	Max file size (MB) considered during gathering
codebuddy.hybridSearch.vectorWeight	0.7	Semantic similarity weight
codebuddy.hybridSearch.textWeight	0.3	Keyword weight
codebuddy.hybridSearch.topK	10	Max search results returned

Related

• Prompt pipeline — assembly steps around the gathered context
• Semantic search — hybrid BM25 + vector detail
• Memory — how memories get injected
• Self-healing §Layer 4 — compaction as part of the safety layers