>_ContextOS

Configuration

Configuring the ContextOS retrieval engine via contextos.json.

Implementation Sourcesrc/core/parser/config-parser.ts

The contextos.json File

ContextOS is designed to work out of the box with zero configuration. However, if you need to fine-tune the engine's behavior, you can create a contextos.json file in the root of your repository (next to your package.json or .git folder).

{
  "ignorePatterns": [
    "**/tests/fixtures/**",
    "**/*.generated.ts"
  ],
  "retrieval": {
    "maxDepth": 3,
    "maxNodes": 40
  },
  "embeddings": {
    "enabled": true,
    "provider": "openai",
    "model": "text-embedding-3-small"
  }
}

Configuration Options

ignorePatterns

An array of glob patterns specifying files and directories that should be skipped during the init and watch indexing phases.

Note: ContextOS inherently ignores standard noisy directories via a hardcoded SAFETY_IGNORE list (e.g., node_modules, .git, dist, __pycache__). You do not need to specify these. ignorePatterns is strictly for repository-specific noise (like generated API clients or large mock data files).

retrieval

Overrides the default parameters for the Graph Expansion and Context Compilation engines.

  • maxDepth (number): How deep the Breadth-First Search will traverse dependency edges. Default is 2.
  • maxNodes (number): The absolute upper limit on the number of entities pulled into the LLM context window. Default is 20.

embeddings

Configures the semantic vector generation layer.

  • enabled (boolean): Set to false to completely disable embeddings and rely 100% on the BM25 (FTS5) engine. This drastically speeds up initial indexing.
  • provider (string): The inference provider. Supported values: openai, local (ONNX), ollama.
  • model (string): The specific model string to use for the specified provider.

Environment Variables

For secure values like API keys, ContextOS reads from your environment variables or a local .env file.

  • OPENAI_API_KEY: Required if using the OpenAI embeddings provider.
  • CONTEXTOS_HOME: Overrides the global storage directory (defaults to ~/.contextos).
PreviousCLI CommandsNext Architecture