Vexor

Vexor is a semantic search engine that builds reusable indexes over files and code. It supports configurable embedding and reranking providers, and exposes the same core through a Python API, a CLI tool, and an optional desktop frontend.

Featured In

Vexor has been recognized and featured by the community:

• Ruan Yifeng's Weekly (Issue #379) - A leading tech newsletter in the Chinese developer community.
• Awesome Claude Skills - Curated list of best-in-class skills for AI agents.

Why Vexor?

When you remember what a file does but forget its name or location, Vexor finds it instantly—no grep patterns or directory traversal needed.

Designed for both humans and AI coding assistants, enabling semantic file discovery in autonomous agent workflows.

Install

Download standalone binary from releases (no Python required), or:

pip install vexor  # also works with pipx, uv

Quick Start

0. Guided Setup (Recommended)

vexor init

The wizard also runs automatically on first use when no config exists.

1. Search

vexor "api client config"  # defaults to search current directory
# or explicit path:
vexor search "api client config" --path ~/projects/demo --top 5
# in-memory search only:
vexor search "api client config" --no-cache 

Vexor auto-indexes on first search. Example output:

Vexor semantic file search results
──────────────────────────────────
#   Similarity   File path                       Lines   Preview
1   0.923        ./src/config_loader.py          -       config loader entrypoint
2   0.871        ./src/utils/config_parse.py     -       parse config helpers
3   0.809        ./tests/test_config_loader.py   -       tests for config loader

2. Explicit Index (Optional)

vexor index  # indexes current directory
# or explicit path:
vexor index --path ~/projects/demo --mode code

Useful for CI warmup or when auto_index is disabled.

Desktop App (Experimental)

The desktop app is experimental and not actively maintained. It may be unstable. For production use, prefer the CLI.

Download the desktop app from releases.

Python API

Vexor can also be imported and used directly from Python:

from vexor import index, search

index(path=".", mode="head")
response = search("config loader", path=".", mode="name")

for hit in response.results:
    print(hit.path, hit.score)

By default it reads ~/.vexor/config.json. For runtime config overrides, cache controls, and per-call options, see docs/api/python.md.

AI Agent Skill

This repo includes a skill for AI agents to use Vexor effectively:

vexor install --skills claude  # Claude Code
vexor install --skills codex   # Codex

Skill source: plugins/vexor/skills/vexor-cli

MCP Server

Vexor ships a built-in MCP stdio server, so any MCP-capable agent can use semantic file search as a native tool:

claude mcp add vexor -- vexor mcp   # Claude Code
codex mcp add vexor -- vexor mcp    # Codex

Or configure manually in any MCP client, optionally supplying the API key and any config overrides via env (no vexor init needed):

{
  "mcpServers": {
    "vexor": {
      "command": "vexor",
      "args": ["mcp"],
      "env": {
        "VEXOR_API_KEY": "sk-...",
        "VEXOR_CONFIG_JSON": "{\"provider\": \"gemini\", \"rerank\": \"bm25\"}"
      }
    }
  }
}

The server exposes two tools: vexor_search (semantic file search) and vexor_index (explicit index warm-up). No extra dependencies are required. Vexor is listed on the official MCP registry as io.github.scarletkc/vexor. See docs/mcp.md for tool schemas, environment variables, and client setup details.

Configuration

vexor config --set-provider openai          # default; also supports gemini/voyageai/custom/local
vexor config --set-model text-embedding-3-small
vexor config --set-provider voyageai        # uses voyage defaults when model/base_url are unset
vexor config --set-batch-size 0             # 0 = single request
vexor config --set-embed-concurrency 4       # parallel embedding requests
vexor config --set-extract-concurrency 4     # parallel file extraction workers
vexor config --set-extract-backend auto      # auto|thread|process (default: auto)
vexor config --set-embedding-dimensions 1024 # optional, model/provider dependent
vexor config --clear-embedding-dimensions    # reset to model default dimension
vexor config --set-auto-index true          # auto-index before search (default)
vexor config --set-update-check false       # disable the daily update notice (default: on)
vexor config --rerank bm25                  # optional BM25 rerank for top-k results
vexor config --rerank flashrank             # FlashRank rerank (requires optional extra)
vexor config --rerank remote                # remote rerank via HTTP endpoint
vexor config --set-flashrank-model ms-marco-MultiBERT-L-12  # multilingual model
vexor config --set-flashrank-model          # reset FlashRank model to default
vexor config --clear-flashrank              # remove cached FlashRank models
vexor config --set-remote-rerank-url https://proxy.example.com/v1/rerank
vexor config --set-remote-rerank-model bge-reranker-v2-m3
vexor config --set-remote-rerank-api-key $VEXOR_REMOTE_RERANK_API_KEY  # or env var
vexor config --clear-remote-rerank          # clear remote rerank config
vexor config --set-base-url https://proxy.example.com  # optional proxy
vexor config --clear-base-url               # reset to official endpoint
vexor config --show                         # view current settings

Rerank defaults to off. It is highly recommended to configure the Reranker in advance to improve search accuracy. FlashRank requires pip install "vexor[flashrank]" and caches models under ~/.vexor/flashrank.

Config stored in ~/.vexor/config.json.

Configure API Key

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

Or via environment: VEXOR_API_KEY, OPENAI_API_KEY, GOOGLE_GENAI_API_KEY, or VOYAGE_API_KEY; VEXOR_API_KEY takes precedence over a stored key. Any config field can also be injected as a JSON object via VEXOR_CONFIG_JSON (useful for MCP client configs and CI), merged over ~/.vexor/config.json.

Rerank

Rerank reorders the semantic results with a secondary ranker. Candidate sizing uses clamp(int(--top * 2), 20, 150).

Recommended defaults:

• Keep off unless you want extra precision.
• Use bm25 for lightweight lexical boosts; it is fast and lightweight.
• BM25 uses a multilingual tokenizer (Bert pre-tokenizer), so it can handle CJK better.
• Use flashrank for stronger reranking (requires pip install "vexor[flashrank]" and downloads a model to ~/.vexor/flashrank).
• Use remote to call a hosted reranker that accepts {model, query, documents} and returns ranked indexes.
• For Chinese or multi-language content, set --set-flashrank-model ms-marco-MultiBERT-L-12.
• If unset, FlashRank defaults to ms-marco-TinyBERT-L-2-v2.

Providers: Remote vs Local

Vexor supports both remote API providers (openai, gemini, voyageai, custom) and a local provider (local):

• Remote providers use api_key and optional base_url.
• voyageai defaults to https://api.voyageai.com/v1 when base_url is not set.
• custom is OpenAI-compatible and requires both model and base_url.
• Local provider ignores api_key/base_url and only uses model plus local_cuda (CPU/GPU switch).

Embedding Dimensions

Embedding dimensions are optional. If unset, the provider/model default is used. Custom dimensions are validated for:

• OpenAI text-embedding-3-*
• Voyage voyage-3* and voyage-code-3*

vexor config --set-embedding-dimensions 1024
vexor config --clear-embedding-dimensions

If you change dimensions after an index is built, rebuild the index:

vexor index --path .

Local Model (Offline)

Install the lightweight local backend:

pip install "vexor[local]"

GPU backend (requires CUDA drivers):

pip install "vexor[local-cuda]"

Download a local embedding model and auto-configure Vexor:

vexor local --setup --model intfloat/multilingual-e5-small

Then use vexor search / vexor index as usual.

Local models are stored in ~/.vexor/models (clear with vexor local --clean-up).

GPU (optional): install onnxruntime-gpu (or vexor[local-cuda]) and use vexor local --setup --cuda (or vexor local --cuda). Switch back with vexor local --cpu.

Index Modes

Control embedding granularity with --mode:

Cache Behavior

Index cache keys derive from: --path, --mode, --include-hidden, --no-recursive, --no-respect-gitignore, --ext, --exclude-pattern.

Keep flags consistent to reuse cache; changing flags creates a separate index.

vexor config --show-index-all    # list all cached indexes
vexor config --clear-index-all   # clear all cached indexes
vexor index --path . --clear     # clear index for specific path

Re-running vexor index only re-embeds changed files; >50% changes trigger full rebuild.

Command Reference

Common Flags

Porcelain output fields: rank, similarity, path, chunk_index, start_line, end_line, preview (line fields are - when unavailable).

Documentation

See docs for more details.

Contributing

Contributions, issues, and PRs welcome! Commit messages and PR titles follow Conventional Commits (e.g. feat(mcp): add stdio server). Star if you find it helpful.

Star History

Star History Chart

License

MIT