Vexor

Vexor resolves configuration using the following priority (highest to lowest):

1. Explicit function arguments (e.g., provider, model, api_key)
2. Per-call override via config=... parameter
3. In-memory runtime config set by set_config_json(...)
4. Environment overrides (e.g., VEXOR_CONFIG_JSON, OPENAI_API_KEY)
5. The nearest project .vexor/config.json
6. Global ~/.vexor/config.json
7. Built-in defaults

To ignore on-disk configuration files in a library context, pass use_config=False and provide explicit arguments or a config dict.

Vexor uses a hierarchical configuration system.

1. Global Config: Stored at ~/.vexor/config.json. This is where mutating vexor config commands write data.
2. Project Config: A config.json file located in the nearest .vexor/ directory relative to your target path. This acts as a restricted overlay on the global config.

Key Rules

• Restrictions: Project-level config.json files can only override settings; they cannot define new credentials or endpoints.
• Resolution: When running search, index, config --show, or doctor, Vexor walks upward from the target path to find the nearest .vexor/ marker.
• Inspection: Use vexor config --show to see the effective configuration and identify which file (global or project) provided each value.

Choose a --mode based on your search intent and the type of files you are targeting:

• auto: Routes by file type (default).
• name: Searches filenames only (fastest).
• head: Searches only the first lines of files (fast).
• brief: Uses keyword summaries (best for PRDs).
• code: Uses code-aware chunking for .py, .js, and .ts files (best default for codebases).
• outline: Uses Markdown headings and sections (best for documentation).
• full: Chunks full file contents (slowest, but provides highest recall).

A Collection is a named, persistent set of caller-owned text records. Unlike file indexes (which use vexor index to discover files on a filesystem), Collections are intended for use when your source of truth is an external system like a database or message store that already has stable record IDs.

Collections are accessed via the Python API and store data in collections.db, separate from file indexes.

Key Constraints:

• The provider, model, and vector dimension are fixed upon the first successful non-empty write.
• Subsequent writes or searches that attempt to use a different configuration (different model or dimension) will be rejected with an error. You must recreate the collection to change these settings.

Vexor uses specific locations for global and project-specific data:

• Global Cache/Config: Located in ~/.vexor.
• Project-specific Index: If a project contains a .vexor/ directory, the index is kept there. This directory may also contain a config.json overlay (see docs/configuration.md).
• Index Database: index.db contains index metadata, paths, BM25 postings, and query caches.
• Dense Vectors: Stored as vectors/*.npy sidecars next to the database to allow NumPy mmap loading.
• Text Embedding Strategy: The text embedded for each chunk is constructed by mode strategies in vexor/modes.py. You can adjust the strategy label construction in that file to encode additional context.

For clients that use a JSON configuration file, add the following entry to your mcpServers configuration. If vexor is not in your system PATH, use an absolute path or run via python:

{
  "mcpServers": {
    "vexor": {
      "command": "vexor",
      "args": ["mcp"]
    }
  }
}

Alternative (via Python):

{
  "mcpServers": {
    "vexor": {
      "command": "python",
      "args": ["-m", "vexor", "mcp"]
    }
  }
}

Vexor supports multiple ways to provide credentials.

API Keys

You can set a key via CLI:

vexor config --set-api-key "YOUR_KEY"

Or use environment variables (in order of precedence):

1. VEXOR_API_KEY (takes precedence over stored keys)
2. OPENAI_API_KEY
3. GOOGLE_GENAI_API_KEY
4. VOYAGE_API_KEY

Configuration via Environment

• VEXOR_CONFIG_JSON: Allows injecting a JSON object of non-secret configuration fields. This is useful for CI or MCP clients. Note: Credential fields (like api_key) are rejected in this variable; use the dedicated environment variables above.
• VEXOR_NO_UPDATE_CHECK=1: A hard switch to disable automatic update checks, overriding all other layers.

Use VexorClient as a context manager to handle scoped configuration, reusable indexes, and custom data directories without mutating global state. This is recommended for library usage where you want to isolate settings like data_dir or api_key.

from vexor import VexorClient

with VexorClient(data_dir="/tmp/vexor", use_config=False) as client:
    client.set_config_json({"provider": "openai", "api_key": "YOUR_KEY"})
    response = client.search("config loader", path=".", mode="name")