repolore

Ask why your code is the way it is, and get back the PR, review thread or issue that says so.

Lore: what a team knows about its own code. Most of it was written down once, in a PR or a review thread, and then buried.

RAG over your own engineering history on GitHub: PRs, review threads, issues, commits and docs, searchable from a CLI and from Claude Code over MCP. It answers questions like "why did we drop the retry middleware?" with the passages that explain it and links to them.

Why this one

• The history, not just the code. PR descriptions, review threads, issues, commits that never had a PR, the repos' markdown, and the .plans/ folders in your local checkouts. The reasons behind code live there.
• Everything stays on your machine. It uses your own GitHub token and embeds locally, so no model API key is needed, and nothing leaves your machine except GitHub API calls and the one-time model download from GitHub.
• Made for Claude Code. Sessions get search, read, list_repos and refresh tools and answer with links to the sources. Codex and other MCP clients work too.
• One model for every session. Each session runs a small relay, about 70 MB; one shared server holds the model.
• Stays current cheaply. A refresh fetches only what changed on GitHub and embeds only the chunks that changed.
• Every default was measured. Each retrieval choice went through repolore eval against a fixed question set, and EXPERIMENTS.md logs every result.
• Hand-built. No RAG or eval framework: fetching, chunking, embedding, retrieval and evaluation are each written out, so every stage stays visible.

Install

You need uv and a GitHub login. It runs on Linux, Windows and macOS 14+ on Apple Silicon.

uv tool install --managed-python --python 3.12 repolore-mcp   # the repolore and repolore-mcp commands
repolore setup                                                # pick repos, register with Claude Code, first refresh

The package is repolore-mcp: PyPI's repolore is a different project.

For GitHub access, being logged in with the GitHub CLI (gh auth login) is enough. Otherwise set REPOLORE_GITHUB_TOKEN to a classic token with the repo scope, plus read:org for organization repos. Organizations with SSO also need the token authorized for them.

repolore setup checks the GitHub token, lists the repos it found and asks which to index, writes your pick to repolore.toml, registers repolore with Claude Code and Codex when they're on PATH, and starts the first refresh in the background. It finds the repos you own or can read as a collaborator or organization member, plus your own PRs and issues in other people's repos. Every question has a flag, which repolore setup --help lists, so it can run without asking: repolore setup --include "you/*" --register --refresh (plus --replace-config when repolore.toml exists).

The first refresh downloads the embedding model from GitHub, about 1.4 GB, and embeds everything on your machine, which takes a while for a large account, so start with a few repos. As a rough guide, 3,713 chunks took 22 minutes to embed on a 12-core desktop CPU, after a 9-minute download. On Apple Silicon it embeds on the GPU through MLX; set REPOLORE_DEVICE=cpu to keep it on the CPU. repolore doctor shows how far it has got and which engine a build uses.

Use it

repolore search "why did we drop the retry middleware?"
repolore search "rate limit handling" --repo you/some-repo --kind pr -k 10
repolore refresh          # fetch what changed and rebuild the index with its recorded settings
repolore doctor           # check every part of the setup, with the fix for each failure
repolore server status    # the shared MCP server; `repolore server stop` stops it

Or ask Claude Code in a new session. It gets search, read, list_repos and refresh tools and can answer questions about your history with links to the sources. search cuts each passage at 1,500 characters, and read returns a source's whole text from the index, plans and private repos included, a page at a time.

{
  "hooks": {
    "SessionStart": [
      { "matcher": "startup", "hooks": [{ "type": "command", "command": "repolore refresh", "async": true }] }
    ]
  }
}

Other MCP clients

repolore-mcp is a standard stdio MCP server, so other clients can run it too. Most take a JSON entry in the portable mcpServers format (VS Code's own mcp.json calls the object servers):

{ "mcpServers": { "repolore": { "command": "repolore-mcp" } } }

A client can also launch it through uvx, without a tool install:

{ "mcpServers": { "repolore": { "command": "uvx", "args": ["--managed-python", "--python", "3.12", "repolore-mcp"] } } }

The first launch downloads about 190 MB, which can take longer than a client waits for a server to start (30 seconds in Claude Code), so run uvx --managed-python --python 3.12 --from repolore-mcp repolore setup --no-register once first: it fills uv's cache and sets repolore up.

[mcp_servers.repolore]
command = "repolore-mcp"
startup_timeout_sec = 60
tool_timeout_sec = 300

What the experiments found

Every retrieval choice was measured with repolore eval against 35 questions about the author's public repos, each with the sources expected to answer it. EXPERIMENTS.md has the full log. In short:

• Plain vector search won. Keyword search (BM25) alone was worse on every metric, because questions use plain words rather than the exact identifiers. Fusing the two rankings and reranking with a cross-encoder both gave gains within the noise and moved some first-place hits down.
• Bigger chunks were better. One chunk per markdown section, never split, beat 800, 400 and 200-token caps. No section in that corpus came near 8,192 tokens, which is now the most a chunk holds by default: on larger corpora, the few longer sections were slow to embed and were cut off at the model's 32K-token window (#17), so they are now split instead.
• The model matters most. bge-small (33M parameters) lost a third of the first-place hits compared with voyage-4-nano (340M), the default.
• Less can be more. Indexing every commit instead of only those without a PR lowered MRR: the commits restate their PR and push its passages down.
• One passage per source. Plain search spent the top 5 on 3.3 sources on average, the rest being more sections of the same document. Keeping each source's best section raised recall@5 from 0.857 to 0.904 and lowered no question, so Claude Code's search does that by default (--distinct on the CLI).
• "Not found" is the open problem. Cosine scores of answerable and unanswerable questions overlap. The reranker's scores separated them much better on the 3 unanswerable questions so far, which makes them the most promising way to say "nothing indexed covers this".

A search takes a median of 308 ms over 2,587 chunks on a desktop CPU, query embedding included. With 35 questions, one question moves recall by about 3%, so these numbers show direction, not precision. The biggest limit is the question set itself: several "misses" are valid answers that weren't listed as expected.

Development

uv sync
uv run repolore --help
uv run pytest

To have Claude Code use your checkout instead of the installed tool:

claude mcp add --scope user --transport stdio repolore -- uv run --directory /path/to/repolore --no-sync repolore-mcp

main only changes through PRs. After cloning, enable the hooks that block direct commits and pushes to it:

git config core.hooksPath .githooks

Documentation

• EXPERIMENTS.md: every retrieval experiment and its numbers
• AGENTS.md: the architecture, stage by stage, and the conventions for working on it
• SECURITY.md: reporting a vulnerability

License

MIT