haiku.rag

What it does

haiku.rag is a retrieval toolkit for your own documents, and its `haiku-rag mcp` command serves an existing haiku.rag database to an MCP client. The assistant can run hybrid (vector plus full-text) searches, search by image when a multimodal embedder is configured, list documents, read a whole document, fetch its heading outline with page numbers, or pull a single section. Search results come back as text with rank, document ID, title, headings and the passage expanded to its section, followed by any pictures as image blocks.

A seventh tool, `execute_code`, runs a short Python program over the documents and returns what it printed, which suits counting and aggregating across many files. The program runs in pydantic-monty, a restricted Python interpreter written in Rust, in a worker subprocess; documents appear inside it as a virtual file system under /documents/{id}/. In version 0.97.0 each call is cut off after 60 seconds (`sandbox.code_timeout`) and its output is capped at 50,000 characters (`sandbox.max_output_chars`), per the config models in the source.

The server opens the database read-only. Documents are added beforehand with the haiku-rag CLI (`add`, `add-src`) or the separate `haiku-ingester` service. It speaks Streamable HTTP on 127.0.0.1:8001 by default, or stdio with `--stdio`, and can cover several databases at once, naming which one each result came from.

What it needs

Python 3.12 or newer and the haiku.rag package (`pip install haiku.rag`) so that `haiku-rag` is on PATH. A database built first with `haiku-rag add` or the ingester. The default configuration embeds queries with Ollama (`qwen3-embedding:4b` at http://localhost:11434), so Ollama must be running with that model, unless a haiku.rag.yaml points to another provider such as OpenAI or VoyageAI, which then needs that provider's key. The published Docker image (ghcr.io/ggozad/haiku.rag-slim) serves HTTP on port 8001 rather than stdio.

Limits

It cannot add, change or delete documents: ingestion happens outside the server. `search_documents_by_image` is registered only when a multimodal embedder is configured. The `filter` parameter narrows searches and listings but does not restrict the three document read tools, so the docs say content that must stay hidden belongs in a database the server does not cover. Each `execute_code` call is a fresh program with no state carried over, stopped after 60 seconds and cut at 50,000 characters of output by default. Search scores are not comparable across queries. Claude Desktop does not show the server's instructions to the model.

Who it suits

Suits someone who already keeps, or is willing to build, a local haiku.rag index of PDFs and office files and wants an assistant to search and quote it with page numbers, without sending documents to a hosted service when Ollama is used. The read-only design fits shared or sensitive collections. Less suited to anyone wanting the assistant itself to save notes or memories, since nothing can be written through the server, or to anyone who does not want to run a local model or an indexing step first.