>_ContextOS

Configuration

Configuring the ContextOS retrieval engine via .contextos/config.json.

Implementation Sourcesrc/config/defaults.ts

The config file

ContextOS works out of the box with zero configuration. To fine-tune the engine, add a .contextos/config.json file in your repository, or a global ~/.contextos/config.json. Repo config overrides global, which overrides the built-in defaults in src/config/defaults.ts.

{
  "ignorePatterns": ["**/tests/fixtures/**", "**/*.generated.ts"],
  "maxTokenBudget": 1200,
  "maxRetrievalResults": 25,
  "graphExpansionDepth": 2,
  "graphExpansionMaxNodes": 20,
  "embeddingsEnabled": true,
  "embeddingsRetrieval": false,
  "pipeline": {
    "graphExpansion": true,
    "containmentDedup": true,
    "diversityFilter": true
  }
}

Configuration options

ignorePatterns

Glob patterns for files/directories to skip during indexing. Noisy directories (node_modules, .git, dist, __pycache__, …) are always excluded, so use this only for repo-specific noise. Use an ignorePatterns! key (trailing !) to replace the defaults instead of merging.

Token & retrieval budgets

  • maxTokenBudget (number): default compile budget. Default 1200; a per-call get_context max_tokens accepts up to 8000.
  • maxRetrievalResults (number): cap on scored chunks before compile. Default 25.
  • ftsLimit (number): per-query FTS5 hit limit. Default 15.
  • maxChunkTokens / maxSymbolChunkTokens (number): soft caps when creating chunks. Defaults 1500 / 900.

Graph expansion

  • graphExpansionDepth (number): relationship walk depth. Default 2.
  • graphExpansionMaxNodes (number): cap on expanded entities. Default 20.

Embeddings

ContextOS uses a local MiniLM model (@xenova/transformers) — there is no external/OpenAI provider and no API key.

  • embeddingsEnabled (boolean): generate index-time embeddings. Default true.
  • embeddingsRetrieval (boolean): fuse embedding kNN into query-time retrieval. Default false — the keyword/RRF path is the accuracy baseline; embeddings act as a confidence-gated fallback.

pipeline

Toggle individual query-time stages.

  • graphExpansion (boolean, default true)
  • embeddingFusion (boolean): when unset, follows embeddingsRetrieval; set true/false to force.
  • containmentDedup (boolean, default true)
  • diversityFilter (boolean, default true)

execAllowRepoScripts

Whether the ctx_execute tool may run the indexed repository's own scripts (npm test, npm run build|lint, npx vitest|jest). Default true. Set to false (or export CONTEXTOS_EXEC_ALLOW_SCRIPTS=0) when indexing untrusted repositories, since those scripts execute repo-controlled code.

Environment variables

  • CONTEXTOS_EMBEDDINGS=0: disable index-time embeddings.
  • CONTEXTOS_EMBEDDINGS_RETRIEVAL=1: enable embedding fusion at query time.
  • CONTEXTOS_EXEC_ALLOW_SCRIPTS=0: disable ctx_execute script execution.
  • CONTEXTOS_REPO_ROOT: the repository root the MCP server operates on.
  • CONTEXTOS_WORKSPACE: workspace name for multi-project isolation.
PreviousCLI CommandsNext Architecture