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:
| setting | what it is |
|---|---|
RESEARCHZOSHO_DRIVE | the model server, for example http://localhost:8080 or https://api.openai.com/v1 |
RESEARCHZOSHO_MODEL | the model name to ask for |
RESEARCHZOSHO_JUDGE_DRIVE / RESEARCHZOSHO_JUDGE_MODEL | a second, stronger model for the judgment steps (planning, the critic, the write-up, the citation check), while a local model does the reading |
RESEARCHZOSHO_EMBED | an embeddings server (OpenAI embeddings call), so search works by meaning as well as by words; off for words only. researchzosho embed start runs one with Docker (Text Embeddings Inference, about nine times faster than llama.cpp on the same model) |
RESEARCHZOSHO_LIBRARY | where the library folder is (default ~/researchzosho-library) |
research.workers / research.pause / research.window | how research runs share the model: how many questions at once, a pause switch, the hours it may work. Set with researchzosho research …; they take effect at once |
RESEARCHZOSHO_VISION_DRIVE / RESEARCHZOSHO_VISION_MODEL | a separate model for reading pictures (a photographed page, a scanned PDF); by default your own model reads them, when it reads images |
RESEARCHZOSHO_RECORDS | record_search goes to research runs in genealogy mode and to software questions; always gives it to every run, off to none |
RESEARCHZOSHO_BRAVE_KEY / RESEARCHZOSHO_SEARXNG | the web search backend: a Brave Search API key (used first), a SearXNG address (default http://localhost:8888; researchzosho search start runs one with Docker); with neither, the built-in fallback, Wikipedia plus Crossref and OpenAlex (RESEARCHZOSHO_FALLBACK_SEARCH=off turns it off) |
RESEARCHZOSHO_API_KEY | the key for a hosted API; it is sent only to that server |
RESEARCHZOSHO_UPDATE | check (default): say when a newer release exists; auto: the service updates itself after the housekeeping when idle; off |
RESEARCHZOSHO_EXPLORER_PER_NIGHT / RESEARCHZOSHO_EXPLORER_TYPES | how many open questions the housekeeping researches a night (default 2), and of which types (default report, asked, person) |
RESEARCHZOSHO_PODCASTINDEX_KEY / RESEARCHZOSHO_PODCASTINDEX_SECRET | the Podcast Index key and secret (api.podcastindex.org/signup, free): the open podcast directory and search by person. Apple's directory answers without them. researchzosho podcast index download keeps the directory's weekly file on the machine (1.8 GB) for searching and browsing shows by word, category and language without the API; RESEARCHZOSHO_PODCASTINDEX_LOCAL=on has the housekeeping refresh it. |
RESEARCHZOSHO_YAHOO_JP_CLIENT_ID, RESEARCHZOSHO_RAKUTEN_APP_ID + RESEARCHZOSHO_RAKUTEN_ACCESS_KEY, RESEARCHZOSHO_ICECAT_USER, RESEARCHZOSHO_REDDIT_CLIENT_ID + RESEARCHZOSHO_REDDIT_CLIENT_SECRET | the shops and catalogues a shopping question may ask, all free: Yahoo!ショッピング and 楽天市場 listings with prices (Japan), Open Icecat datasheets, what owners wrote on Reddit through an app of your own. Without them the run uses the open sources and points at shops. |
calibre | your Calibre library, its folder or its metadata.db, read and never changed: researchzosho settings set calibre "~/Calibre Library". Your shelf, the books' cards and "like this one" come from it |
market | the country you buy in, as two letters; setup asks for it. A shopping run uses that country's shops, currency and recall notices |
ebay_client_id + ebay_client_secret | eBay listings and auctions in your market, for used, vintage and out-of-print things; free from eBay's developer program |
cinii_appid | Japanese books across the university libraries, with how many hold each; free from NII |
dna_minutes / dna_share | how long a night the library reads your books for their cards (20 unless set, 0 for none), and whether a pack of the cards, with nothing of you in it, is written once a week for you to share (off unless set) |
recalls | off stops the nightly check of the product-safety feeds against what you own |
RESEARCHZOSHO_WHISPER | a transcription server on another machine (an OpenAI-style /v1/audio/transcriptions); the local container when unset. RESEARCHZOSHO_TRANSCRIBE_EPISODES and RESEARCHZOSHO_TRANSCRIBE_MINUTES cap what one run transcribes (2 episodes, 120 minutes); RESEARCHZOSHO_TRANSCRIBE_FOLLOWED_MINUTES caps a night's transcription for followed podcasts (unset: none). researchzosho settings reads and changes every setting. |
RESEARCHZOSHO_TROVE_KEY / RESEARCHZOSHO_DIGITALNZ_KEY / RESEARCHZOSHO_EUROPEANA_KEY / RESEARCHZOSHO_DPLA_KEY | keys for the archives that want one: Trove (Australian newspapers), DigitalNZ (a higher rate for Papers Past), Europeana and DPLA (heritage items). The rest of the archives need none. |
RESEARCHZOSHO_FETCH_PRIVATE | deny to stop it fetching addresses on your own network |
RESEARCHZOSHO_FETCH_MAX_BYTES | the largest document it will download (default 25 MB) |
RESEARCHZOSHO_STALL_MINUTES | after how many minutes without progress a research run is marked "no progress since" and the service writes where the run waits into its log (default 15) |
RESEARCHZOSHO_FETCH_MIN_BYTES_PER_SECOND | the slowest a page may come, on average, before the download is given up (default 4,096 bytes a second); a page that keeps coming faster is read to its end however long it takes |
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.