ravel

Find the function, passage or note you need. Give your coding agent the evidence that fits.

The local workspace, with real results. Interface guide · First-release demo and provenance.

ravel is a compact local context engine for code repositories, Markdown, text and optional PDF/DOCX documents. Exact identifiers use SQLite BM25 without loading an embedding model. Harder questions can use local semantic retrieval. A cost-aware planner decides how much work to do, while a bounded int8 vector cache trades storage for recomputation.

No accounts, paid APIs, telemetry or always-running daemon. One small core dependency. The optional model stays on your machine. v0.1.1 is an experimental alpha, with measured strengths, failures and limits documented below.

Search in a minute

Python 3.10+ and Git are required for this installation route. uv is optional; ordinary pip works too.

uv tool install 'git+https://github.com/nazeeh111/ravel@v0.1.1'

ravel index /path/to/your/repository
ravel search 'retry_with_backoff' --root /path/to/your/repository --tokens 2048
ravel inspect --root /path/to/your/repository

Prefer pip? Install the release wheel in your virtual environment:

python -m pip install https://github.com/nazeeh111/ravel/releases/download/v0.1.1/ravel_index-0.1.1-py3-none-any.whl

Try a public sample with no personal-data indexing:

git clone https://github.com/nazeeh111/ravel.git
cd ravel
ravel index examples/sample
ravel search 'retry_with_backoff' --root examples/sample --tokens 2048
ravel symbols ExpiringCache --root examples/sample

Search returns source paths and exact line spans, a SHA-256 source hash, the current Git revision when available, and actual retrieval evidence. Editing, deleting, renaming or ignoring a file refreshes the next default search automatically. Source files are never changed by ravel.

Related MCP server: semantic-code-intelligence

Add local semantic search

The core needs no model. Semantic support is an explicit extra and a separate, one-time public model download, approximately 67.2 MB excluding the runtime.

python -m pip install 'ravel-index[semantic] @ git+https://github.com/nazeeh111/ravel@v0.1.1'
ravel index examples/sample --semantic --download-model --materialize
ravel search 'How can I wait longer between temporary failures?' \
  --root examples/sample --tokens 2400

The pinned BGE-small model runs locally through ONNX on CPU. Later queries use local model files only. --materialize precomputes vectors up to the saved cache quota; omit it for lazy computation. --cache-mb 1 sets a persistent vector payload quota. Models, metadata, source text, SQLite pages and process memory are separate costs. Inspect them with ravel stats --root examples/sample.

Put ravel in your coding agent

codex mcp add ravel -- ravel mcp --root /absolute/path/to/repository
claude mcp add --transport stdio ravel -- ravel mcp --root /absolute/path/to/repository

Ask your agent to use ravel_search to find the relevant implementation and cite its source lines. The server fixes one approved root and exposes search/status, with no source-editing or network tool. Configuration, Python API and verification.

from ravel import Index

with Index("/path/to/repository") as index:
    answer = index.search("retry_with_backoff", token_budget=2048)
    for hit in answer["results"]:
        print(hit["path"], hit["start_line"], hit["end_line"], hit["text"])

Spend context deliberately

ravel search 'ExpiringCache.get' --root examples/sample --mode lexical --json
ravel search 'expire old entries' --root examples/sample \
  --latency-ms 300 --memory-kib 1024 --tokens 1800 --json

The planner selects lexical search, semantic reranking or compressed-vector scanning from query shape, lexical evidence, cache coverage and observed cost. It preserves lexical candidates when a cold semantic scan would be incomplete. The cache prioritizes vectors by access frequency and measured regeneration cost per byte. A small learned selector is included for reproducible experiments and explicit opt-in, rather than silently learning from private queries.

--tokens conservatively charges serialized evidence UTF-8 bytes as a token upper bound. It is not an exact model tokenizer count. Provenance counts toward that budget; protocol/metrics overhead is separate. --latency-ms is a soft target and --memory-kib is a candidate-work allowance, not a total-process memory cap.

The interactive inspector shows the actual selected strategy, source evidence, cache hits, index storage and elapsed time. No external UI assets, JavaScript framework or hosted service is required.

Measurements, including where ravel loses

The repository includes raw runs and reproducible harnesses for:

• A separately authored 48-query code/document experiment with subject-disjoint training and held-out test queries, heuristic versus learned routing, cache quotas, fixed-strategy ablations, source freshness, CPU time and peak memory.

• A shared 32-file/32-query fixture run with LEANN, QMD, Codanna, grepai, exact FAISS and ravel, including a model-matched MiniLM cohort.

• One full-repository ContextBench diagnostic, with the original issue as the query and gold paths used only for scoring. This exposed a cold-routing failure and motivated the lexical-preserving fallback.

These are small, local experiments, not leaderboard results. Several competitors score perfectly on the shared fixture. LEANN and FAISS have smaller indexes than ravel there. A smaller ravel cache can be slower and less accurate. The learned policy did not establish an advantage and is not the default. CLI startup, warm API calls, embedding models and tool capabilities are disclosed separately. Concurrent local workloads limit latency comparisons.

Full methodology and held-out results · Head-to-head configurations and results · Raw measurements · Current-source research and prior art

Adaptive routing, BM25, AST chunking, incremental indexing and MCP already exist in other tools. ravel's experimental contribution is a minimal, inspectable joint policy for retrieval depth, context allowance and frequency/cost-aware vector retention. It is not a claim to have invented those individual techniques.

Freshness and privacy are part of retrieval

Default searches hash eligible source bytes, so same-size edits with preserved modification times are detected. SQLite transactions prevent concurrent indexing from mixing source text, hashes and vectors. Removed, denied or newly ignored files lose old entries. This costs O(source bytes) per search. --snapshot is a consciously unchecked mode, labeled in every returned evidence object.

ravel honors hierarchical Git ignores and .ravelignore, skips hidden directories, symlinks, common secret names/patterns, unreadable files and files over 2 MiB. Exclusions are best effort; keep sensitive material outside the approved root or explicitly exclude it. The index contains readable source excerpts and is not encrypted. Privacy boundaries.

Limits worth knowing

• Full source verification and a cold model load can exceed the latency target.

• Vector search uses a streaming linear scan, not an ANN index. Cold lazy scans may be partial; hybrid reranks lexical candidates rather than recovering all lexical misses. Large-corpus quality and scale are not established.

• Python has AST symbols and call observations. Other languages currently have line chunks, not resolved symbol graphs. PDF/DOCX locations are extracted-text lines; image-only PDFs need external OCR. Install .[documents] for these parsers.

• The public diagnostic is one task. Full ContextBench/Agent Retrieval Bench and end-to-end coding-agent success rates have not been replicated. Claude Code configuration follows its documentation; no installed Claude client was available.

Build and contribute

python -m pip install -e '.[dev,documents]'
python -m pytest -q
ruff check src tests
python -m build

Architecture · Contributing · Independent review · Licenses and attribution

MIT licensed.