source-recall

Fast code and document search. Indexes repositories with tree-sitter parsing, embeds chunks with a local model, and retrieves via hybrid BM25 + vector search with reciprocal rank fusion.

Requirements

• Python ≥ 3.12 (3.13 recommended)
• uv for installs (or any PEP 517 installer)
• mise optional but recommended — pins Python, uv, and just to known-good versions (run mise install after cloning)

Install

From PyPI (the distribution is dungle-scrubs-source-recall):

# FTS-only: no model download, instant startup, keyword search only
uv tool install dungle-scrubs-source-recall

# Full: vector search and reranking, ~2 GB model deps
uv tool install "dungle-scrubs-source-recall[embed]"

From a checkout (development):

uv tool install -e .[embed]

This gives you the sr CLI globally.

Quick Start

# Index a repository
sr index ~/dev/my-project

# Search
sr ask "how does authentication work" ~/dev/my-project

# Start persistent server (typically <100ms warm queries vs ~12s cold)
sr serve ~/dev/my-project

CLI Commands

sr index [PATH]

Build or rebuild the full index. Parses source files with tree-sitter, splits into semantic chunks, embeds with CodeRankEmbed, and stores in SQLite.

sr index .                        # index current directory
sr index ~/dev/project            # index a specific repo
SR_EMBED_ENABLED=false sr index . # skip embeddings (FTS only)

sr ask QUESTION [PATH]

Search the index. Returns ranked code chunks.

sr ask "payment processing"
sr ask "UserModel" ~/dev/api
sr ask --json "auth"              # JSON output
sr ask --plain "config" | llm     # pipe to LLM
sr ask --files "database"         # file paths only

sr serve [PATHS...]

Start a persistent HTTP query server. Loads the embedding model once on startup (~12s), then serves warm queries in <100ms.

sr serve .                                    # single repo
sr serve ~/dev/api ~/dev/frontend             # multiple repos
sr serve ~/dev/api --port 7249 --host 0.0.0.0 # custom bind

Endpoints:

When serving multiple repos, include "repo": "name" in query requests. With a single repo, the repo field is optional.

# Query the server
curl -X POST http://localhost:7249/query \
  -H "Content-Type: application/json" \
  -d '{"question": "authentication", "top_k": 5}'

sr status [PATH]

Show index metrics: file count, chunk count, vector coverage, database size.

Configuration

Configuration is resolved in order (first wins):

1. Environment variables (SR_ prefix)
2. Repo-local .source-recall.toml
3. Built-in defaults

Environment Variables

TOML Config

Create .source-recall.toml in your repo root:

[source-recall]
top_k = 10
max_file_size = 200000
embed_enabled = true
rerank_enabled = true
exclude_patterns = ["node_modules/", "dist/", ".git/"]

Config Reference

Default excludes: node_modules/, dist/, build/, .git/, __pycache__/, *.pyc, .venv/, venv/, .tox/, .mypy_cache/, .pytest_cache/, .ruff_cache/.

Supported Content

Retrieval Pipeline

Query
  → FTS5 BM25 search (top 30)
  → Vector cosine search (top 30)
  → Symbol exact match (if query looks like a symbol)
  → RRF merge (k=15)
  → Cross-encoder rerank (if enabled, top 3x top_k candidates)
  → Graph expansion (top 5 → follow refs → resolve symbols)
  → Return top_k

Reranking uses cross-encoder/ms-marco-MiniLM-L-6-v2 (22M params, ~90MB). It scores query-document pairs jointly, which is more accurate than bi-encoder cosine similarity. Adds ~100ms. Enable with SR_RERANK_ENABLED=true.

Graph expansion follows cross-references (imports, inheritance, decorators) from the top results and pulls in the referenced definitions. This surfaces related code without the user explicitly asking for it.

Embedding Model

CodeRankEmbed (nomic-ai/CodeRankEmbed, 137M params, 768d, MIT license). Runs locally via sentence-transformers + ONNX Runtime. Downloads ~522MB on first run (cached in ~/.cache/huggingface/).

Disable with SR_EMBED_ENABLED=false for pure FTS keyword search (no model download, instant startup).

Auto-Start (macOS)

The daemon can run as a launchd service that auto-starts at login and restarts on crash. sr daemon start generates a plist dynamically (with resolved paths from your environment) and loads it — no manual editing required:

# Configure which repos the daemon serves
sr add ~/dev/my-project

# Generate the plist and start the service
sr daemon start

# Check status
sr daemon status

# View logs
sr daemon logs

# Stop
sr daemon stop

Other platforms (systemd on Linux, Task Scheduler on Windows) are not yet automated; run sr daemon run in your platform's service manager.

Justfile

just test          # run tests
just t             # run tests (short output)
just lint          # check lint + format
just fix           # auto-fix lint + format
just serve         # start server (current dir)
just query "auth"  # query running server
just health        # server health check
just repos         # list served repos
just status        # server index status
just install       # install sr globally

Dependencies

Development

See CONTRIBUTING.md for the full guide. The short version:

# Setup
mise install
uv sync

# Run tests (fast, skips model-loading tests)
uv run pytest -m "not slow"

# Run all tests including slow model tests
uv run pytest

# Lint
uv run ruff check src/ tests/

This repo uses mise to pin the local Python, uv, and just versions. Run mise install after cloning, then use the existing uv and just commands normally.

Support

• Bugs and feature requests: GitHub Issues
• Security vulnerabilities: see SECURITY.md — do not open a public issue; use a private GitHub Security Advisory.
• Code of conduct: CODE_OF_CONDUCT.md