Configuration

vecgrep resolves configuration from environment variables, project files, and global defaults.

Resolution Order

Highest priority wins:

1. Environment variables
2. Project root vecgrep.yaml or vecgrep.yml
3. Project .config/vecgrep.yaml
4. Legacy project .vecgrep/config.yaml
5. Global project entry in ~/.vecgrep/config.yaml
6. Global defaults in ~/.vecgrep/config.yaml
7. Built-in defaults

Use OpenAI by default

Set the complete embedding profile in your global defaults:

vecgrep config set --global embedding.provider openai
vecgrep config set --global embedding.model text-embedding-3-small
vecgrep config set --global embedding.dimensions 1536

Provide OPENAI_API_KEY or VECGREP_OPENAI_API_KEY in the process running vecgrep, including your MCP launcher. OpenAI receives the source chunks sent for embedding. Initialization uses the resolved provider and model in both CLI and MCP.

Project settings still take priority. If vecgrep config show reports Nomic, check the listed project config files for embedding.provider, model, and dimensions overrides. Remove those overrides to inherit your global profile. After changing an existing index's embedding profile, run vecgrep index --full to rebuild it. Vectors from different models cannot share an embedding space.

Default Storage

New projects use global storage by default:

~/.vecgrep/
  config.yaml
  projects/
    <project-name>/
      vectors.veclite
      embedding_profile.json

This keeps generated vector indexes out of source repositories.

Use local storage only when required:

vecgrep init --local

Project Config

Create vecgrep.yaml in your project root for checked-in settings:

embedding:
  provider: ollama
  model: nomic-embed-text
  dimensions: 768
  ollama_url: http://localhost:11434
  # Optional Ollama request controls:
  ollama_context: 0
  ollama_options: {}
  query_template: ""
  document_template: ""

indexing:
  chunk_size: 512
  chunk_overlap: 64
  max_file_size: 1048576
  source_buffer_bytes: 8388608
  sync_interval: 50
  sync_interval_duration: 30s
  ignore_patterns:
    - ".git/**"
    - "node_modules/**"
    - "vendor/**"

search:
  default_mode: hybrid
  vector_weight: 0.7
  text_weight: 0.3

vector:
  veclite:
    m: 16
    ef_construction: 100  # Memory-bounded default; use 200 for higher build quality
    ef_search: 100

codemap:
  # auto = use fresh symbol records and fall back per file; off = local
  # chunker only; required = fail indexing if any export file is unusable.
  structural_chunks: auto

Configure From CLI

Set project-local config:

vecgrep config set search.default_mode keyword
vecgrep config set embedding.provider voyage
vecgrep config set embedding.model voyage-code-3
vecgrep config set embedding.dimensions 1024
vecgrep config set codemap.structural_chunks required

Set global defaults:

vecgrep config set --global embedding.provider ollama

Apply a complete local embedding profile atomically:

vecgrep config preset                   # List presets
vecgrep config preset fast-local        # Project config
vecgrep config preset --global quality-code

Preset changes require the model pull and full rebuild printed by the command. They leave provider endpoints, credentials, throttling, caching, and unrelated configuration unchanged.

Inspect resolved config:

vecgrep config show
vecgrep config show --global

Environment Variables

Variable	Description
VECGREP_EMBEDDING_PROVIDER	ollama, openai, cohere, or voyage
VECGREP_EMBEDDING_MODEL	Embedding model name
VECGREP_EMBEDDING_DIMENSIONS	Embedding vector dimensions
VECGREP_OLLAMA_URL	Ollama API URL
VECGREP_OLLAMA_CONTEXT	Ollama num_ctx; 0 uses the model/server default
VECGREP_OLLAMA_OPTIONS	YAML/JSON map passed to Ollama's options object
VECGREP_EMBEDDING_QUERY_TEMPLATE	Query template containing
VECGREP_EMBEDDING_DOCUMENT_TEMPLATE	Document template containing
VECGREP_INDEXING_SOURCE_BUFFER_BYTES	Maximum queued source bytes before chunking
VECGREP_INDEXING_SYNC_INTERVAL	Files processed between periodic full-store syncs
VECGREP_INDEXING_SYNC_INTERVAL_DURATION	Maximum duration between periodic syncs
VECGREP_OPENAI_API_KEY	OpenAI API key
VECGREP_OPENAI_BASE_URL	OpenAI-compatible base URL
VECGREP_COHERE_API_KEY	Cohere API key
VECGREP_COHERE_BASE_URL	Cohere-compatible base URL
VECGREP_VOYAGE_API_KEY	Voyage AI API key
VECGREP_VOYAGE_BASE_URL	Voyage-compatible base URL
VECGREP_CODEMAP_STRUCTURAL_CHUNKS	auto, off, or required structural indexing mode

Provider-standard API key aliases are also supported: OPENAI_API_KEY, COHERE_API_KEY, and VOYAGE_API_KEY.