ResearchZosho
研究蔵書, the research holdings. The Research Harness For The Rest Of Us.
ResearchZosho is an open-source deep research assistant. Give it a question and it searches the web and scholarly papers, or only your own PDFs, and writes a report in which every claim points at a source. It runs on your own computer with a local LLM (llama.cpp, Ollama, LM Studio) or a hosted API.
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 → FAMILY_HISTORY.md: researching your family, from a relative's notes to records and a family tree → YOUTUBE.md: researching what is on YouTube — channels, what is said in a video and when, channels like one you know — without an API key
→ BEDROCK.md: using the models in your own AWS account (Amazon Bedrock) with your own AWS sign-in
→ MODELS.md: which model to run, from what we measured: the local models by your graphics card's VRAM first, then the hosted ones by what they got right, how long a run took and what it cost
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, and when the question calls for them the web archives, the Internet Archive, digitised historical newspapers, the National Diet Library's digitised Japanese books, the archives of source code and the video sites beside YouTube. A page that is gone is read from its archived copy. 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.
Get book recommendations. Ask for a book to read first on a subject, what a book covers, or what to read next. The recommendations come from the library catalogues (Open Library, Japan's National Diet Library and others), never from the model's memory, so every book named is a real one with a link to its record. It looks past the bestseller lists and says what each book covers and who it is for.
Use your own shelf. Point it at your Calibre library and it learns what you go for: the
subjects, the authors you come back to, the decades and languages. researchzosho myshelf like "<title>" recommends books on your shelf like one by what the texts say, not by who wrote them. A
nightly reading of your books builds a card for each, which describes the book and nothing about
you. Say which rows you liked and disliked, and the next lists move.
Know what you own. Import your purchase records (the zip Amazon sends you, a mailbox of order confirmations, a card statement) and the library can tell what you already have. Every night it checks the open product-safety feeds against them, and a recall that may concern you waits in the inbox.
Research a purchase. Ask what to buy and the run looks only at what shops list right now in your country, with the price, the datasheet, recall notices, repairability and what owners say. The table judges fit against your need, not popularity. For used, vintage or out-of-print things it asks eBay and gives you ready search links for the marketplaces no program may read.
Ask how to do or make something. A craft, a hobby, a sport, a martial art or a trade. The answer comes with the kit: every material and tool, what it is for, what stands in for it, and where to get it. For a sport or a martial art, the gear in the order you need it and where to learn. For a community you want to join, such as the SCA or a reenactment society, how to join and what its rules ask of your equipment.
Podcasts and videos. A question about a podcast, a host or an episode reads what was said, with the time it was said, and cites the episode. Follow a show and its new episodes are noted as they arrive. A question about videos searches YouTube and the sites beside it and cites the moment.
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.
Reach it from outside your home. researchzosho share makes the library reachable now, behind an
encrypted relay (a Cloudflare quick tunnel at first, Tailscale Funnel for an address that lasts),
free, with no port opened at home: anyone with the link sees the sign-in page, and only a person you
invited gets in, with their name and password, a passkey, or a one-time code as a second step. Invite
a person with one link; they choose their password when they open it.
Sign in simply. No tokens to paste. You make your account once, with a name and a password, and sign in from any phone or computer. On the library's own computer your browser needs no sign-in. Add a passkey, so your fingerprint or face signs you in, or a one-time code from an authenticator app as a second step. Programs still use tokens.
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>"
researchzosho reader token <did> makes the token: programs sign in with tokens, people with a name and
password. Every session can then use the library.
What to use it with
Nothing to buy. In this order:
- A browser. Open
http://127.0.0.1:4649/once the service runs. Search, ask, read a claim with its sources, have it explained, see the map, send a question, download a write-up. Nothing to install. This is also how the rest of the house uses the library. - Obsidian or SoloMD. Open the folder that
researchzosho vaultwrites. codezaiku chat, to talk to the library on a local model, for free. It connects to the service. What the library holds is pushed into each turn,/librarianasks it, and/researchfiles runs with it.- Claude Code, Codex or Gemini CLI, if you have one.
setupconnects it. Every session then has the library's tools. Any other program that speaks MCP connects the same way.
For programs there are two clients. Both follow LIBRARY_PROTOCOL.md. Its sections 1 to 6 are the contract and keep working across releases.
- Python (
sdk/python, no dependencies):pip install researchzosho, thenLibrarian("http://127.0.0.1:4649", token=…). - Java (
client/):org.researchzosho:client, thenLibrarianClient.
The family
ResearchZosho is part of Wyrdsekai. Its sibling is
CodeZaiku, a coding and development harness that runs on local models or
hosted APIs: code, review, research and guarded ops. codezaiku install researchzosho installs this
library beside it. The two share a model server, so one on-demand model on a machine serves both.
Licence
Apache 2.0. See LICENSE. ResearchZosho includes no model. You supply a model server and accept its licence separately.