← All work
AI · Local RAG

docs-rag

Standalone local RAG agent — point it at a folder of Markdown docs, it builds a vector index and answers questions with Ollama. No cloud, no API keys.

Standalone local RAG (retrieval augmented generation) agent for querying a directory of Markdown/MDX docs with Ollama.

Prereqs

  • Ollama running locally
  • An embedding model (default: nomic-embed-text)
  • A chat model (default: minimax-m2.5:cloud)

Setup

Quick setup:

cd ~/Projects/docs-rag
./scripts/run.sh setup

Manual setup:

cd ~/Projects/docs-rag
python3 -m venv .venv
source .venv/bin/activate
pip install -r agent/requirements.txt

Pull models:

ollama pull nomic-embed-text
ollama pull minimax-m2.5:cloud

Build an index for a docs folder

You can index any folder of .md/.mdx.

cd ~/Projects/docs-rag
./scripts/run.sh index --docs /absolute/path/to/your/docs --name mydocs

By default the index is stored under:

  • ~/.cache/docs-rag/indexes/<name> Override via --index ... or DOCS_RAG_INDEX=....

Run the agent server

cd ~/Projects/docs-rag
./scripts/run.sh serve --name mydocs --port 8787

All-in-one (index + serve):

cd ~/Projects/docs-rag
./scripts/run.sh up --docs /absolute/path/to/your/docs --name mydocs

Endpoints:

  • GET /health
  • POST /api/ask { "question": "...", "k": 10, "k_per_query": 8 }

Reusing the React sidebar components

This repo also includes:

  • web/DocsChat.tsx
  • web/DocRightSidebar.tsx They’re plain TSX components you can import into a Vite/React app (you’ll likely need a Vite alias and server.fs.allow if importing from outside the app’s root).