StashBase: a local-first Markdown wiki that agents can read over MCP
Turn your local files into a Wiki for your agents. Open-source and local-first.
At a glance
- What is it?
- StashBase turns folders of notes, PDFs and recordings into linked Markdown wiki pages and exposes them to Claude Code, Codex or any MCP client. It is early alpha, the strongest features depend on a hosted model gateway, and the licence question is the one to settle before you point it at a work folder.
- Who is it for?
- Adopt StashBase if your material is already a folder of Markdown, PDFs and transcripts and you want the wiki pages to stay as files you can open in any editor; try it on a copy of one folder before trusting it with anything else.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap between giving an agent a folder and giving it usable context
Pointing an agent at a directory is the easy part. The hard part is that the answer is often buried in a forty-page PDF, phrased with different words than the question, or sitting in a scan or a recording that no text search will reach. StashBase's stated goal is to close that gap by turning a folder into a linked wiki and then letting agents read the wiki instead of re-reading raw files on every turn. The README frames the audience as people with personal notes, research libraries, project docs and knowledge bases, which in practice means anyone whose working memory is a folder rather than a database. The output is deliberately unglamorous: Markdown pages that live in a wiki/ directory next to your sources, which you can open in any editor without StashBase installed.
What a Build Wiki request actually produces
The mechanism is an agent turn, not a background indexer. The README is explicit that a Build Wiki request creates or improves wiki/index.md and, when useful, pages beside it, and that sources outside wiki/ are preserved. It also states that building or updating pages is an explicit Agent request and that opening a folder does not schedule automatic Wiki maintenance. That is a meaningful design decision: there is no watcher quietly rewriting your notes when a file changes. The prompt the README suggests is plain English, asking for an overview, an organisation of the main topics, and links back to the source files. Because the pages are ordinary Markdown, the linking structure is whatever the model produces, not a fixed schema. That gives you freedom and also means two runs over the same folder can produce differently shaped wikis.
Search, extraction and the two providers you have to choose between
Search runs in two modes. Keyword search needs no account. Search by meaning is offered during the first folder setup, and the README says it can use StashBase sign-in with included monthly credits or your own OpenAI or OpenRouter key, with a Not now option that leaves you on keyword search. The setup is independent of building wiki pages and can be done later in Settings. Text extraction covers PDFs, DOCX files, images and recordings, and the README states that OCR and optional audio and video transcription run locally, while hosted search by meaning sends relevant text to the selected embedding provider for indexing and sends queries for retrieval. That split is the honest core of the local-first claim: your files stay in place, but the moment you turn on semantic search, text from those files travels to a third party.
Installing it, and running it from source
The packaged path is Homebrew on macOS, with a cask published from the liliu-z tap. The README gives brew install --cask liliu-z/stashbase/stashbase, and direct downloads named StashBase-*-mac-arm64.dmg, StashBase-*-win-x64.exe, and either a .deb or an .AppImage for Linux x86_64. macOS 12+ on Apple Silicon and Windows 10+ x64 are described as the primary platforms; Linux on Debian 12+ or Ubuntu 22.04+ is community-supported, which is a polite way of saying it is not the path the maintainers exercise first. Building from source needs Node.js 24+, pnpm and Python 3.10+, with a native toolchain installed first on Ubuntu or Debian, then git clone, pnpm install, pnpm setup:python, pnpm build:web, and env -u ELECTRON_RUN_AS_NODE pnpm electron. The env prefix is not decorative; Electron misbehaves when ELECTRON_RUN_AS_NODE is set in the environment, which is why the README spells it out.
MCP wiring, and the fact that the agent runs somewhere else
For Claude Code and Codex used inside the built-in Chat, StashBase configures the MCP connection automatically, and the app shows tool calls and file edits for review. For anything else you keep StashBase running and copy the connection configuration from Settings, MCP into the external client. The README describes the exposed surface as searching the library, reading prepared source content, and bounded file operations within the authorized folders. The word bounded is doing real work there, and the material does not spell out the exact limits, so treat the authorized folder boundary as the thing to verify in docs/mcp-configuration.md rather than assume. The second thing to note is that Wiki Agent runs locally but sends prompts and necessary model context through StashBase's hosted model gateway. Claude Code and Codex bill against your own provider accounts instead. If your reason for choosing a local-first tool is that no prompt leaves the machine, the included agent does not satisfy that.
Where the design gets in your way
The wiki is generated text, and generated text drifts. Nothing in the README describes a rebuild policy, a diff against a previous index.md, or what happens to a page you edited by hand before the next Build Wiki request. Since builds are manual agent turns, the practical risk is that the wiki quietly becomes a stale summary that later agents treat as ground truth. The second limitation is platform. There is no headless mode, no server binary, no Docker image and no CI story in the material; this is an Electron desktop app, and the Linux build is community-supported. If you wanted a shared wiki that a team queries from a build runner, StashBase is the wrong shape. The third is that the semantic layer depends on an external embedding provider, so an offline machine degrades to keyword search, which is exactly the case the README's own framing says is insufficient.
How this differs from pointing an MCP server at a directory
The obvious alternative is a general-purpose filesystem MCP server, which exposes read, write and search operations over a folder and lets the agent decide what to read. The difference in approach is where the synthesis happens. A filesystem server hands the agent raw files every time and the agent re-derives structure on each question, spending context on material it has already seen. StashBase front-loads that work into Markdown pages that persist, so subsequent questions can start from a document shaped for reading rather than from a directory listing. The cost is that the front-loaded summary can be wrong or out of date, and you have added a second artifact to maintain. A filesystem server has no such artifact and no drift. If your folder is small enough to fit in context, the plain server is the better tool.
Licence, upkeep and what early alpha means here
The repository is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant, with the usual requirements around notices and stating changes. That covers the code. It does not cover the hosted model gateway, the embedding allowance behind StashBase sign-in, or the Gallery content, none of which the material places under the repository licence. The README labels the project early alpha, and the release cadence shown is three versions in roughly two weeks during August and September 2026, which is fast enough that config keys and the MCP settings layout can move between releases. Upgrading on macOS goes through the Homebrew cask; on Windows and Linux you replace the installer. The upkeep that actually costs time is not the upgrade, it is re-running Build Wiki over folders whose sources have changed, and that work is manual by design.
Editorial conclusion
Adopt StashBase if your material is already a folder of Markdown, PDFs and transcripts and you want the wiki pages to stay as files you can open in any editor; try it on a copy of one folder before trusting it with anything else. Skip it if you need a headless server, a Linux-first deployment, or a guarantee that no document text leaves the machine, because search by meaning routes extracted text through the selected embedding provider and Wiki Agent routes prompts through StashBase's hosted gateway. Before you rely on it, build the wiki twice on the same folder and diff the two versions of wiki/index.md, since the README states that page creation happens only when an Agent is asked to do it and nothing in the material describes how a rebuild treats pages you have edited by hand.
Community notes