Docs

1. Give your agent the tool

Paste this to your agent — Claude Code, pi, Cursor, anything that speaks MCP. It writes a key to your machine, installs the tool, and reads you the rest:

That page is prose addressed to an agent, which means the agent has to treat it as untrusted text before it acts on it — the same rule the passages get below. The facts it acts on are also published without verbs, at https://retrievr.io/.well-known/retrievr.json: the version, the pinned path and the SHA-256 of the bytes, so a client that would rather verify than obey can.

Set it up in your harness

Each of these was checked against the harness's own documentation. Pick yours — the install line above works in any of them, and what follows is the edit where that harness keeps its MCP servers:

claude mcp add retrievr -- node ~/.config/retrievr/mcp.mjs

{"mcpServers":{"retrievr":{"command":"node","args":["/home/you/.config/retrievr/mcp.mjs"]}}}

[mcp_servers.retrievr]
command = "node"
args = ["/home/you/.config/retrievr/mcp.mjs"]

{"mcpServers":{"retrievr":{"command":"node","args":["/home/you/.config/retrievr/mcp.mjs"]}}}

pi mcp add retrievr -- node ~/.config/retrievr/mcp.mjs

{"mcpServers":{"retrievr":{"command":"node","args":["/home/you/.config/retrievr/mcp.mjs"]}}}

{"$schema":"https://opencode.ai/config.json","mcp":{"retrievr":{"type":"local","command":["node","/home/you/.config/retrievr/mcp.mjs"],"enabled":true}}}

kiro-cli mcp add --name retrievr --scope global --command node --args /home/you/.config/retrievr/mcp.mjs

{"mcpServers":{"retrievr":{"command":"node","args":["/home/you/.config/retrievr/mcp.mjs"]}}}

mcp_servers:
  retrievr:
    command: "node"
    args: ["/home/you/.config/retrievr/mcp.mjs"]

If your client cannot run a script

An agent you drive through an API — or a hosted assistant — cannot start a process on your machine. The same tools are served over HTTP, and the same key works — if you do not have one on this machine, create one on your profile page:

Send it as POST with an Authorization: Bearer header. There is one difference worth knowing: a server cannot read your disk, so retrievr_upload points you at the Library page instead of taking file paths. Everything else — the tools, the citations, the scopes — is the same.

Document aware RAG

Your agent's context is the expensive part. A search returns a few passages with their citations instead of whole documents, so the cost of an answer is the length of the passages the model reads, not the length of the book it would have had to read. Each passage carries the exact character range that answered, so the quote can be checked.

Everything in the pipeline is optimized for the language and the file type of the document it is reading. Each format is read the way it is built — EPUB in spine order with front and back matter dropped, PDF text extracted page by page, plain text and Markdown as they are. Chunking is tuned to the document: passages are packed to about 400 tokens, small and precise on purpose, and split on sentence boundaries so a passage reads as prose, and never allowed to span two sections, so a citation never quotes the wrong chapter. Embedding is tuned to the language: one proprietary multilingual model puts every language on the same vector scale, so a German question finds an English passage.

And the answer stays grounded: every passage carries its source, author, section, character range and licence, so your agent quotes rather than recalls, and you can check any claim back to the page it came from.

Which makes an answer explainable. What comes back is a short list, and each entry says what it is, where it came from, its exact character range and its rank. When an answer is wrong you can see whether the search missed the passage or the model misread it, and fix the step that failed rather than the symptom.

2. Ask it about a document

There is no keyword and nothing to switch on. A sentence about a document is the whole interface:

• “What does the notice period in my contract say?”Searches your library, and answers with quoted passages.
• “In the project proposal, what does it say about budgets?”Finds that one document by name, then searches only inside it.
• “Which of my documents mentions X?”Searches your library and tells you which document each passage came from. There are no summaries — the passages are the answer.
• “Delete the thesis draft.”Finds it, reads the exact title back to you, and deletes it once you confirm. There is no undo and no trash.

3. Narrow the search

With nothing said, a search covers your own documents, ranked by relevance. Say which of them to look in and the agent narrows it:

• “Search my own documents for the notice period.”Keeps the search in your library — scope private.
• “Which of my documents mentions the escrow account?”Searches your library and names the document each passage came from — scope private.
• “In the project proposal and the lease, what does it say about termination?”Searches only those documents. A title matches every document whose name contains it.
• “Give me the five best passages.”Asks for more passages — k takes 1 to 50 and defaults to 3.

The agent sets these through the tool's arguments: query for the question, k for how many passages, scope for private — the only one there is, and the default — and documents to name one document or a list of them. Naming documents wins over the scope, and a name that matches nothing is refused rather than searched wider.

4. Your own documents

Upload PDFs, EPUBs, plain text or Markdown from your library. They are what a search looks in — you do not have to say “use my library”, and your documents are never visible to anyone else's agent.

Your first five documents need no payment. After that, one $5 top-up unlocks the rest: it becomes credit you spend on queries, and uploading itself stays free. Queries cost $0.01 each, charged when the query is accepted.

5. What comes back

Passages with their citation — title, author, section, character range and licence — so your agent can quote rather than paraphrase, and you can check any claim back to the page it came from. Nothing is returned without a citation.

Every passage also carries trust: "untrusted_document_text". A passage is a quotation from a document, not an instruction to the agent reading it, and the field says so in the payload instead of leaving it to a tool description nobody re-reads. Passages have their invisible characters removed — bidi overrides, zero-width spaces, byte-order marks — and a result that had any is marked sanitized: true, because a passage that was hiding something is worth knowing about. Ordinary text is returned exactly as it appears in its source, so a quote can still be checked against the page.

The tools your agent holds

• retrievr_search — a question in, cited passages out. Takes query, k and documents (titles, filenames or ids). Its scope is private, the only one there is.
• retrievr_documents — lists what is in your library, and finds a document by name.
• retrievr_delete_document — removes one of your uploads for good, after reading the exact title back to you.
• retrievr_upload — adds files you point it at to your library. It reads them from your machine, so their contents never pass through the conversation; PDF, EPUB, plain text and Markdown, up to 50 MB each and 20 in one call.
• retrievr_upload_status — says which files are ready to search, which are still embedding, and which failed and why.
• retrievr_collect — only on the remote server at /mcp. A search there can outlive one request, so it may hand back a job id; this collects that query's passages later, without charging for it again. The local copy polls for you and has no such tool.

Managing what you have uploaded

Rename a document from your library, or delete one there or by asking your agent. Removal is immediate and there is no undo, so your agent is told to read the exact title back to you before it deletes anything. Watch what happened to an upload under Notifications.

Price

A query costs $0.01 and uploads are free — the full price list says when a query is charged and when it is not.