Configuration Reference

Complete environment variable reference for Context Engine.

Documentation: README · Getting Started · Configuration · IDE Clients · MCP API · ctx CLI · Memory Guide · Architecture · Multi-Repo · Observability · Kubernetes · VS Code Extension · Troubleshooting · Development

On this page:

• Core Settings
• Embedding Models
• Indexing & Micro-Chunks
• Query Optimization
• Watcher Settings
• Reranker
• Learning Reranker
• Decoder (llama.cpp / OpenAI / GLM / MiniMax)
• Git History & Commit Indexing
• ReFRAG
• Pattern Search
• Lexical Vector Settings
• Ports
• Search & Expansion
• info_request Tool
• Memory Blending

Core Settings

Tool Description Customization

Override default MCP tool descriptions (useful for agent tuning).

Embedding Models

Context Engine supports multiple embedding models via the EMBEDDING_MODEL and EMBEDDING_PROVIDER settings.

Default (BGE-base)

The default configuration uses BAAI/bge-base-en-v1.5 via fastembed:

Qwen3-Embedding (Experimental)

Qwen3-Embedding-0.6B offers improved semantic understanding with instruction-aware encoding. Enable via feature flag:

Setup:

# In .env
QWEN3_EMBEDDING_ENABLED=1
EMBEDDING_MODEL=electroglyph/Qwen3-Embedding-0.6B-onnx-uint8
QWEN3_QUERY_INSTRUCTION=1
# Optional: customize instruction
# QWEN3_INSTRUCTION_TEXT=Instruct: Find code implementing this feature\nQuery:

Important: Switching embedding models requires a full reindex:

make reset-dev-dual  # Recreates collection and reindexes

Dimension comparison:

Indexing & Micro-Chunks

Query Optimization

Dynamic HNSW_EF tuning and intelligent query routing for 2x faster simple queries.

Watcher Settings

Reranker

Cross-encoder reranking improves search quality by scoring query-document pairs directly. Context Engine supports two configuration methods:

FastEmbed Model (Recommended)

Set RERANKER_MODEL to use FastEmbed's auto-downloading cross-encoder models:

Popular models:

• jinaai/jina-reranker-v2-base-multilingual - Multilingual, good quality
• BAAI/bge-reranker-base - English-focused, fast
• Xenova/ms-marco-MiniLM-L-6-v2 - Lightweight, fast inference

Example:

RERANKER_MODEL=jinaai/jina-reranker-v2-base-multilingual
RERANKER_ENABLED=1

Manual ONNX Paths (Legacy)

For custom models or explicit control, set both ONNX path and tokenizer:

Note: If both RERANKER_MODEL and RERANKER_ONNX_PATH are set, RERANKER_MODEL takes priority.

Reranker Tuning

Learning Reranker

The learning reranker trains a lightweight neural network (TinyScorer) to improve search rankings over time. See Architecture for details.

This feature is optional and enabled by default. To disable:

# Disable learning scorer in search results
RERANK_LEARNING=0

# Disable event logging (no training data collected)
RERANK_EVENTS_ENABLED=0

# Or simply don't run the learning_worker container

Enable/Disable

Weight Management

Learning Rate

Event Logging

Learning Worker

Decoder (llama.cpp / OpenAI / GLM / MiniMax)

Runtime Selection

Set REFRAG_RUNTIME explicitly to choose a decoder backend:

• llamacpp: Local llama.cpp server (requires REFRAG_DECODER=1)
• openai: OpenAI API (GPT-4.1, GPT-4.1-mini, o1, etc.)
• glm: ZhipuAI GLM models (GLM-4.5, GLM-4.6, GLM-4.7)
• minimax: MiniMax M2 API

No auto-detection is performed to avoid surprise API calls. If REFRAG_RUNTIME is unset, it defaults to llamacpp.

Git History & Commit Indexing

Settings for indexing git commit history and enabling commit-aware search.

Note: Git history indexing stores commit messages and metadata as searchable points. Use search_commits_for MCP tool to query.

ReFRAG (Micro-Chunking & Retrieval)

LLM-Based Pseudo/Tags (REFRAG_PSEUDO_DESCRIBE):

When enabled, the indexer uses the configured decoder (via REFRAG_RUNTIME) to generate semantic descriptions and tags for each code chunk. This enriches the lexical vectors with natural language terms, improving NL→code retrieval.

# Enable LLM pseudo/tags generation (requires decoder configured)
REFRAG_PSEUDO_DESCRIBE=1
REFRAG_RUNTIME=glm  # or openai, minimax, llamacpp

Note: This significantly increases indexing time and API costs. Best used with batch concurrency (PSEUDO_BATCH_CONCURRENCY=4).

Pseudo Backfill Worker

Deferred pseudo/tag generation runs asynchronously after initial indexing.

Adaptive Span Sizing

Expand search hits to full symbol boundaries for better context.

Context Answer Shaping

Controls output formatting for context_answer responses.

Mini Vector Gating

Compact 64-dim vectors for fast candidate filtering before full dense search.

Pattern Search

Structural code pattern matching across languages. Disabled by default.

Enable:

# In .env or docker-compose
PATTERN_VECTORS=1

When enabled, the indexer extracts control-flow signatures (loops, branches, try/except, etc.) and stores them as pattern vectors. The pattern_search MCP tool allows finding structurally similar code across languages—e.g., a Python retry loop can match Go/Rust equivalents.

Note: Enabling requires reindexing to generate pattern vectors for existing files.

Lexical Vector Settings

Controls the sparse lexical (keyword) vectors used for hybrid search.

Sparse Vector Settings (Experimental)

True sparse vectors for lossless lexical matching (no hash collisions).

Note: Enabling LEX_SPARSE_MODE requires the collection to have a sparse vector index configured. Use --recreate flag when switching modes. If sparse query fails or returns empty, the system automatically falls back to dense lexical vectors.

Note: Changing LEX_VECTOR_DIM requires recreating collections (--recreate flag).
To use legacy settings (pre-v2): LEX_VECTOR_DIM=4096 LEX_MULTI_HASH=1 LEX_BIGRAMS=0

Ports

Search & Expansion

Note: REPO_AUTO_FILTER=0 disables automatic repo scoping, useful for benchmarks or cross-repo searches.

Caching

Semantic Expansion

Synonym/related term expansion for improved recall on natural language queries.

LLM Query Expansion

Query expansion uses the decoder infrastructure (set via REFRAG_RUNTIME):

• openai: Uses OpenAI API when REFRAG_RUNTIME=openai and OPENAI_API_KEY is set
• glm: Uses GLM API when REFRAG_RUNTIME=glm and GLM_API_KEY is set
• minimax: Uses MiniMax API when REFRAG_RUNTIME=minimax and MINIMAX_API_KEY is set
• llamacpp: Uses local llama.cpp when REFRAG_RUNTIME=llamacpp and REFRAG_DECODER=1

Set LLM_EXPAND_MAX=4 to enable LLM-assisted query expansion (generates up to 4 alternate phrasings).
EXPAND_MAX_TOKENS controls the response length budget for the LLM call.

Filename Boost

The search engine can boost files whose paths match query terms—production-grade algorithm for real-world codebases.

Naming convention support:

• snake_case, camelCase, PascalCase, kebab-case, SCREAMING_CASE
• Acronyms: XMLParser → xml, parser; HTTPClient → http, client
• Prefixes stripped: IUserService → user, service; _private → private
• Dot notation: com.company.auth → com, company, auth

Abbreviation normalization:

• auth ↔ authenticate/authentication
• config ↔ configuration/cfg/conf
• repo ↔ repository, util ↔ utility, impl ↔ implementation, etc.

Scoring tiers:

• Exact token match: 1.0 × factor
• Normalized match (abbreviation/plural): 0.8 × factor
• Substring containment: 0.4 × factor
• Filename bonus: 1.5× multiplier for filename vs directory matches
• Common token penalty: 0.5× for tokens like "utils", "index", "main"

Example: Query "authenticate user handler" matching auth/UserAuthHandler.ts:

• "user" exact match in filename (1.0 × 1.5 = 1.5)
• "authenticate" → "auth" normalized (0.8 × 1.5 = 1.2)
• "handler" exact match in filename (1.0 × 1.5 = 1.5)
• Total: 4.2 × 0.15 = 0.63 boost

Set FNAME_BOOST=0 to disable, or increase (e.g., 0.25) for stronger path weighting.

info_request Tool

Simplified codebase retrieval with optional explanation mode.

Output Formatting

TOON (Token-Oriented Object Notation)

Compact output format that reduces token usage by 40-60%.

Set output_format="toon" per-call, or enable globally via TOON_ENABLED=1.

Memory Blending

Exclusions (.qdrantignore)

The indexer supports a .qdrantignore file at the repo root (similar to .gitignore).

Default exclusions (overridable):

• /models, /node_modules, /dist, /build
• /.venv, /venv, /__pycache__, /.git
• *.onnx, *.bin, *.safetensors, tokenizer.json, *.whl, *.tar.gz

Override via env or flags:

# Disable defaults
QDRANT_DEFAULT_EXCLUDES=0

# Custom ignore file
QDRANT_IGNORE_FILE=.myignore

# Additional excludes
QDRANT_EXCLUDES='tokenizer.json,*.onnx,/third_party'

CLI examples:

docker compose run --rm indexer --root /work --ignore-file .qdrantignore
docker compose run --rm indexer --root /work --no-default-excludes --exclude '/vendor' --exclude '*.bin'

Scaling Recommendations

For large monorepos, set INDEX_PROGRESS_EVERY=200 for visibility.