raglocal

NOTE – Any legacy ragkit or rag-local configuration has been removed. Use the new raglocal settings in ~/.config/raglocal/config.toml.

Local-first RAG (Retrieval-Augmented Generation) toolkit designed as an MCP server. Index your code, journals, books, and docs once — query them from Claude, OpenCode, or any MCP-capable AI tool with minimal tokens per session.

• Zero daemons — embedded LanceDB, no Docker, no Qdrant
• Local embeddings — three size profiles, no API key required
• Two MCP tools — search returns ranked 250-char snippets; expand fetches full text on demand
• Heterogeneous content — code, markdown, PDFs, EPUB, DOCX, JSON/YAML, journal entries
• Portable corpora — bundle and share an indexed corpus as a single zip file

Installation

pip install raglocal[local-embed]   # recommended — includes sentence-transformers

Optional extras:

pip install raglocal[local-embed,books]    # adds EPUB/MOBI/PDF book parsing
pip install raglocal[local-embed,office]   # adds DOCX/ODT support

Requires Python 3.12+.

Quick start

rag init                        # interactive wizard — picks embedder profile, sets paths
rag index ~/journals/ ~/code/   # index your content (incremental, re-run any time)
rag stats                       # verify chunks were indexed
rag mcp                         # start the MCP server

Then point your AI tool at the server (see MCP setup below).

Embedder profiles

Chosen once during rag init. To switch profiles later, edit ~/.config/raglocal/config.toml and run rag reindex — raglocal detects the mismatch via the on-disk manifest and refuses to mix incompatible vectors. See DESIGN.md §11 Hot-swap for details.

Indexing content

# Index a directory (all supported file types, recursive)
rag index ~/notes/

# Index multiple paths
rag index ~/code/myproject ~/journals ~/books/

# Target a specific collection
rag index ~/books/ --collection books

# Check what was indexed
rag stats

Indexing is incremental — files are skipped if unchanged since last run (mtime + content hash).

Supported file types

MCP setup

OpenCode

Add to ~/.config/opencode/config.json:

{
  "mcp": {
    "raglocal": {
      "command": "rag",
      "args": ["mcp"],
      "type": "stdio"
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "raglocal": {
      "command": "rag",
      "args": ["mcp"]
    }
  }
}

Restart your AI tool after editing. The search and expand tools will appear automatically.

MCP tools

search

Semantic + keyword hybrid search. Returns up to top_k ranked snippets (≤250 chars each) with chunk IDs for use with expand.

{
  "query": "rust ownership model",
  "top_k": 10,
  "filter": {
    "collection": "code",
    "type": "code",
    "language": "rust",
    "since": "2025-01-01"
  }
}

Response includes hits array — each hit has id, snippet, score, source, collection.

expand

Fetch full text of specific chunks by ID. Use on hits from search that look worth reading in full.

{
  "ids": ["abc-123", "def-456"],
  "before": 1,
  "after": 1
}

before/after include neighbouring chunks for context. Response includes full text per chunk.

Note: chunk ID resolution was broken prior to v0.2.0 and is now fixed.

Token cost

A typical session costs ~1,200–2,000 tokens for retrieval, vs. ~4,000+ for full-chunk RAG.

CLI reference

rag init                    Interactive setup wizard
rag index <path...>         Index files/directories into the store
rag reindex [--collection]  Rebuild index after switching embedder profile
rag stats                   Show chunk counts per collection
rag mcp                     Start the MCP server
rag debug "<query>"         Debug search — print results to stderr
rag export <output.zip>     Bundle corpus for sharing
rag import <input.zip>      Import a shared corpus
rag models                  List configured model aliases
rag collections             List collections and chunk counts
rag doctor                  Health check (config, store, Ollama, model)

Configuration

rag init writes ~/.config/raglocal/config.toml. See config.toml.example for all options.

Key sections:

[store]
backend = "lance"
path = "~/.local/share/raglocal/lance"

[embedder]
profile = "balanced"       # lean | balanced | powerful

[collections.docs]
chunk_size = 800
chunk_overlap = 100
chunk_strategy = "token"   # token | sentence | code-aware | chapter

[collections.code]
chunk_size = 500
chunk_overlap = 50
chunk_strategy = "code-aware"

Portable corpora

Share an indexed corpus without requiring re-indexing on the recipient's machine:

# Export
rag export ~/my-corpus.zip

# Recipient imports
rag import ~/my-corpus.zip
# or: unzip and run the self-contained bootstrap script
bash run.sh

Development

git clone https://github.com/gpid007/raglocal
cd raglocal
uv sync --all-extras --dev
uv run pytest
uv run rag --help

Further reading

• Hot-swap embedder — switching profiles on an existing index
• OpenCode integration guide
• Troubleshooting
• Architecture & design