Deeprepo

DeepRepo — Local RAG Engine for Codebases

A production-grade Python library for performing RAG (Retrieval Augmented Generation) on local codebases. No heavy frameworks, no external vector DBs, no cloud required.

What It Does

DeepRepo ingests a codebase and builds three things simultaneously:

A smart query router classifies every question and picks the cheapest context strategy, reducing LLM token usage by 5–50x compared to naive RAG.

---

Features

• Zero dependencies on heavy frameworks — pure Python, SQLite-backed
• Multiple AI providers — Ollama (free/local), OpenAI, Anthropic, Gemini, HuggingFace
• CLI-first — deeprepo ingest . / deeprepo serve / deeprepo query "…"
• Wiki viewer — browsable, searchable HTML wiki with in-page chat (deeprepo serve)
• 7 focused MCP tools — drop DeepRepo into Cursor / Claude Desktop as an MCP server
• Branch isolation — per-branch SQLite databases with copy-on-write from base branches
• 3-tier retrieval — Embeddings → FTS → Graph fallback for resilient search
• Incremental ingestion — unchanged files are skipped; only deltas re-processed

---

Quick Start

1. Install

cd deeprepo_core

pip install -e .

For MCP server support:

pip install -e ".[mcp]"

2. Install Ollama (free, local — recommended)

# macOS

brew install ollama ollama serve # keep this running

ollama pull nomic-embed-text # embedding model ollama pull llama3.1:8b # LLM

3. Ingest your codebase

cd /path/to/your/project

deeprepo ingest .

4. Browse the wiki

deeprepo serve                        # opens http://localhost:8080

5. Ask questions

deeprepo query "how does authentication work?"

deeprepo query "what breaks if I change auth.py?"

---

CLI Reference

deeprepo <command> [options]

Common flags (all commands)

--llm ollama|openai|anthropic|gemini|huggingface   # LLM provider

--embed ollama|openai|huggingface # embedding provider (default: same as --llm) --branch-isolation # enable per-branch databases --base-branch main # seed feature-branch cache from main --wiki-dir .deeprepo/wiki # override wiki output directory

ingest flags

--chunk-size N      # chars per text chunk (default: 1000)

--overlap N # overlap between chunks (default: 100) --workers N # wiki parallel workers (default: 3) --no-wiki # skip wiki generation

serve flags

--port N            # HTTP port (default: 8080)

Examples

# Ollama (free, fully local)

deeprepo ingest .

OpenAI embeddings + Anthropic LLM

deeprepo ingest . --embed openai --llm anthropic

Branch isolation for a feature branch

deeprepo ingest . --branch-isolation --base-branch main

Serve wiki with chat on a custom port

deeprepo serve --llm openai --port 9000

Query with specific top-k results

deeprepo query "where is AuthService defined?" --top-k 3

---

Python API

from deeprepo import DeepRepoClient

Single provider (backward-compatible shorthand)

client = DeepRepoClient(provider_name="ollama")

Split providers — Anthropic LLM + OpenAI embeddings

client = DeepRepoClient( embedding_provider_name="openai", llm_provider_name="anthropic", )

Branch isolation (team workflow)

client = DeepRepoClient( provider_name="ollama", branch_isolation=True, base_branches=["main"], )

Ingest (incremental — unchanged files are skipped)

result = client.ingest("/path/to/your/code") print(f"Files: {result['files_scanned']}, Wiki pages: {result['wiki_generated']}")

Query — smart routing selects the cheapest context strategy

response = client.query("How does authentication work?") print(response['answer']) print(f"Intent: {response['intent']}, Strategy: {response['strategy']}") print(f"Sources: {response['sources']}") # list of file paths

Browse the generated wiki

print(f"Wiki at: {client.get_wiki_dir()}")

query() return shape

{

"answer": str, # LLM-generated answer "sources": list[str], # file paths used as context "intent": str, # navigate | impact | explain | debug | review | general "strategy": str, # e.g. symbol_lookup, blast_radius, wiki_plus_skeleton, … "retrieval": str, # embeddings | fts | graph "token_estimate": int, # estimated tokens consumed "history": list[dict], # conversation history (last N exchanges) }

---

Supported AI Providers

Note: Anthropic has no embeddings API. Pair it with another provider:

`python

client = DeepRepoClient(embedding_provider_name="openai", llm_provider_name="anthropic")

`

---

Architecture

deeprepo_core/src/deeprepo/

├── client.py # Main facade — branch isolation, freshness, provider wiring ├── graph.py # SQLite store: graph nodes/edges, embeddings, wiki index, state ├── graph_builder.py # Tree-sitter AST parser → code knowledge graph ├── wiki.py # Hierarchical wiki engine — bottom-up LLM synthesis ├── router.py # Intent classifier + 6 context strategy selectors ├── ingestion.py # File scanner, chunker, language detection ├── interfaces.py # Abstract base classes (EmbeddingProvider, LLMProvider) ├── registry.py # @register_embedding / @register_llm decorator system ├── ui.py # Wiki viewer (HTTP server + mermaid renderer + chat) ├── mcp/ │ └── server.py # 7 MCP tools for AI assistants (Cursor, Claude Desktop) └── providers/ ├── ollama_v.py ├── openai_v.py ├── anthropic_v.py ├── gemini_v.py └── huggingface_v.py

.deeprepo/ # Generated (gitignore this) ├── default.db # SQLite: graph + embeddings + wiki index + state ├── .db # Per-branch database when branch_isolation=True └── wiki/ # Browsable .md wiki files ├── overview.md # Whole-repo narrative overview └── *.md # One page per module

Storage

Everything lives in a single SQLite file per branch — no Redis, no Postgres, no Chroma.

Design Patterns

• Facade — DeepRepoClient is the single entry point; internals are hidden
• Strategy — LLMProvider / EmbeddingProvider abstract interfaces; providers are swappable
• Registry — @register_llm("ollama") decorator auto-registers providers at import time
• Bottom-up synthesis — wiki pages generated leaves-first; parent pages consume child summaries
• 3-tier fallback — Embeddings → FTS → Graph; queries work even when embeddings are cold
• Copy-on-write branching — feature branches start from base-branch cache, then delta-update

---

MCP Server (AI Assistant Integration)

Connect DeepRepo as an MCP server so Cursor, Claude Desktop, or any MCP-compatible AI assistant can call it directly — without ever reading raw files.

Setup

pip install deeprepo[mcp]

Cursor — create ~/.cursor/mcp.json:

{

"mcpServers": { "deeprepo": { "command": "python", "args": ["-m", "deeprepo.mcp.server"], "env": { "LLM_PROVIDER": "ollama" } } } }

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{

"mcpServers": { "deeprepo": { "command": "deeprepo-mcp", "env": { "EMBEDDING_PROVIDER": "openai", "LLM_PROVIDER": "anthropic", "OPENAI_API_KEY": "sk-...", "ANTHROPIC_API_KEY": "sk-ant-..." } } } }

Available MCP Tools (7 tools)

Token Reduction vs Naive RAG

CLAUDE.md tip

Add this to your project's CLAUDE.md so Claude automatically uses DeepRepo:

## Code navigation

Before reading any source file directly, use these MCP tools:

• find_symbol(name) to locate a class or function
• get_file_structure(filepath) to see a file's API without reading it
• explain_file(filepath) to understand what a file does
• find_change_impact(filepath) before editing any file
• ask_codebase(question) for open-ended questions
• get_project_overview() at the start of a new session

Only call Read/Grep on a file after the above tools have been tried.

---

Configuration

Environment Variables

---

Testing

# Full end-to-end test suite (runs ingest + all checks)

python3 test_deeprepo_flow.py

Skip ingest, use cached index (faster iteration)