ResearchZosho

研究蔵書, the research holdings. The Research Harness For The Rest Of Us.

Three people, one problem.

Your vet mentions a new drug for your dog's cancer. The follow-up is in three days. You want to know what the studies say: how well it works, for which breeds, and what the side effects are. The answer is spread across twenty papers, a regulator's review, and many pages that only look like medical advice.

You are tracing your family. Your great-grandfather is in the 1911 census in Osaka. By 1921 he is gone from every record the family knows about. Somewhere there are ship manifests, a prefecture's emigration lists, and an old newspaper notice. Most of them are in Japanese. None of them are on the first page of a search.

You are writing one chapter of a thesis on the influence of the Soviet-Afghan War on 1990s British science fiction. You have forty papers and articles saved, in three languages. You have one week to work out what they agree on, where they disagree, and what nobody has looked at yet.

None of that can be read in one evening. That is the job ResearchZosho does. You give it the question. It reads and notes each fact with the source it came from. When it is done, a write-up is waiting: what it found, where the sources disagree, and what it could not resolve. Every claim in it points at a source you can check. It keeps what it found, so the next question on the same subject does not start from zero. If a paper you used gets a new version, or two of your own findings contradict each other, it tells you.

Nothing counts as valid until you have reviewed it.

It runs on your own computer with a model you pick, local or hosted. It is free and open source. It is for anyone who needs reliable research done.

This is The Research Harness For The Rest Of Us.

→ LIBRARIAN_HOWTOUSE.md: how to use it day to day → LIBRARY_PROTOCOL.md: for programmers, how a program talks to it → MODELS.md: which model to run, by your graphics card's VRAM, from what we measured

What you can do with it

Send it a question. It works out what needs answering. It reads in parallel: the web, and the scholarly literature by DOI through Crossref and OpenAlex. It writes the answer up in sections. It keeps going until the job is done, or for as long as you allow. It also reads sources in other languages, especially when the question points at a non-English language. The write-up says which languages its sources were in.

Check the answer. Every write-up ends with a table of the facts it used. Each fact has its source and a quote. A numbered list of unique sources follows. Before the write-up is shelved, each sentence that cites a source is checked against that source. A problem is called out. If it cannot read a source, because of a paywall, a login or another issue, it lists that source so you can supply the text yourself.

Keep bad sources out. A claim with one source stays a draft until a second, independent source backs it. A retracted paper disputes the claims that cite it. A site you ban is not used. A site you trust counts as a primary source.

Decide what stands. Each claim starts as a draft. You accept it, dispute it or retire it. The library uses what you accept next time.

Talk to it. researchzosho chat is a conversation with the Librarian. Ask what the shelves hold, ask a follow-up, say "find out …" to start a research run, ask "how did that go?", or go through the inbox. Every reply cites a look-up you can open. A figure it cannot back is marked as its guess. The same conversation is on the pages at /chat.

Ask what you already know. researchzosho ask "…" shows what the library has on a question: each claim, where it came from, and whether it is accepted or still in dispute.

Bring your own documents. A PDF, a web page, or a whole folder. Point it at a folder and every document in it is shelved as a collection. Then ask a question that searches only those documents, or one that starts there and goes to the web afterwards for more.

Ongoing research, every night. Every night it runs the searches you have declared ongoing. It looks into questions it could not answer before. It re-reads a few accepted claims against their sources. It notices new versions of papers you cite. It keeps a dated backup. On Sundays it leaves you two lists: claims that look like duplicates, and documents you might clean out. It never merges, deletes or decides for you.

See how things connect. When a claim says a person lived in a place, or an author wrote a work, the library keeps the connection. researchzosho map "Arthur Ellis" shows everything around a name. The service draws it in your browser. This connects the research you have built up.

Open it in a browser. The service has basic pages: search, ask, read a claim with its sources, walk the subjects, see what changed and what is running, send a question, and download any write-up as Markdown or PDF. For a desktop editor, researchzosho vault writes a folder that Obsidian, SoloMD or SilverBullet can import.

Let other programs use it. Claude Code, Codex, Gemini CLI and any other MCP host can ask the library directly. A small HTTP service with Python and Java clients covers everything else.

Getting started

Research runs need a model server that speaks the OpenAI chat API. That can be a local one (llama.cpp, Ollama, LM Studio) or a hosted API with a key (OpenAI, DeepSeek, Gemini, OpenRouter and others). You also need Java 21 or newer, unless you take a build that carries its own runtime. The installer picks that build for you when Java is missing.

Research runs also need a web search backend. It matters as much as the model. Use a Brave Search API key (free plan), or SearXNG (setup starts one with Docker). With neither, the built-in fallback searches Wikipedia and the scholarly literature only. Asking what the library already has works without a model.

git clone https://github.com/Wyrdsekai/researchzosho.git
cd researchzosho
bin/researchzosho setup

When it is done, open http://127.0.0.1:4649/ in a browser.

setup asks a few questions. Each has an answer already filled in:

• where the library installs
• which model it uses, and which it checks for
• which web search backend
• whether search is by meaning, by keyword, or both
• whether to run it as a service
• which programs to connect

Then it shelves a document you name and answers a question about it. Run it again any time to change one thing. --yes takes every default.

The release installs on Linux, macOS and Windows. If you already use CodeZaiku, codezaiku install researchzosho fetches the release, checks it, and runs setup.

Settings live in ~/.researchzosho/config as key = value lines, or in the environment. These are the ones you are most likely to change:

As a service

bin/researchzosho service install           # Linux, macOS or Windows; a user service, no administrator rights

The service listens on 127.0.0.1:4649. It does the housekeeping at 03:00 and runs the questions you send. service install --host 0.0.0.0 opens it to your own network. The pages are open as shipped: anyone who can reach them can read and send questions. researchzosho web signin on turns on access control.

From Claude Code, Codex or Gemini CLI

claude mcp add --transport http librarian http://127.0.0.1:4649/rpc --header "Authorization: Bearer <token>"
codex mcp add librarian -- researchzosho mcp
npx -y @wyrdsekai/researchzosho-mcp        # any client that runs npm packages; installs the release if needed
gemini mcp add -t http librarian http://127.0.0.1:4649/rpc -H "Authorization: Bearer <token>"