StashBase: a local-first Markdown Wiki that your coding agents can read

The gap StashBase targets: a folder is not context

Pointing an agent at a directory is easy. Getting useful evidence out of it is not. The README frames the problem plainly: relevant material may sit inside a long document, may use different words than the question, or may only exist as a scan or a recording. StashBase's answer is to convert sources into linked Markdown Wiki Pages that sit beside the originals and can be reused as context later.

The intended user is not a RAG engineer. It is someone with a research library, project documents or personal notes who already works with Claude Code, Codex or another MCP client and wants those tools to see the same material. The app is an Electron desktop application written in TypeScript, and the README describes it as early alpha, so the audience is people willing to run pre-1.0 desktop software on their own machine.

How the Wiki, the search index and the MCP server fit together

Three mechanisms are visible in the repository layout and the README. The first is the Wiki build: a Chat request such as "Build a Wiki from the sources in this folder" creates or improves wiki/index.md and, when useful, pages beside it, while sources outside wiki/ are preserved. The second is retrieval: keyword search works without any account, and search by meaning uses an embedding provider, either StashBase sign-in with included monthly credits or your own OpenAI or OpenRouter key. OCR and optional audio and video transcription run locally; the README states that hosted search by meaning sends relevant text to the selected embedding provider for indexing and queries for retrieval.

The third is the agent surface. StashBase configures its MCP connection automatically for the built-in Wiki Agent and for Claude Code or Codex used inside Chat. External clients are pointed at the same library by copying the connection configuration from Settings, MCP. The repository reflects this split with separate top-level directories for electron/, renderer/, server/, mcp/, shared/ and python/, and package.json exposes an mcp script that runs mcp/server.ts. The python/ tree and a build:python-sidecar script in package.json line up with the README's statement that OCR and transcription run locally through packaged sidecars.

Installing StashBase and building a first Wiki

The README gives macOS 12+ on Apple Silicon and Windows 10+ on x64 as the primary platforms. Linux x86_64 on Debian 12+ or Ubuntu 22.04+ is described as community-supported. On macOS the documented install is a Homebrew cask:

brew install --cask liliu-z/stashbase/stashbase

Windows and Linux users download from the releases page instead; the README lists StashBase-*-win-x64.exe, StashBase-*-linux-amd64.deb and the .AppImage variant as the artifacts.

Once the app is open, the README's first-Wiki flow has three steps. Open your own folder or pick a Gallery entry and choose Make a copy. Choose an agent: Wiki Agent is included and selected initially and needs a StashBase sign-in for its model allowance, while Claude Code and Codex use your own provider account. Then, in a Chat scoped to the folder, send the prompt the README quotes:

Build a Wiki from the sources in this folder. Create an overview, organize
the main topics, and link back to the source files.

What you should see afterwards is wiki/index.md plus any focused pages the agent decided to write, with links back to the original files. The README is explicit that this is an explicit agent request: opening a folder does not schedule automatic Wiki maintenance. The first folder also prompts for search by meaning setup, which can be deferred with Not now and configured later in Settings.

Contributors build from source instead. The README requires Node.js 24+, pnpm and Python 3.10+, and on Ubuntu or Debian it lists the native build packages:

sudo apt install build-essential binutils cmake curl git nasm pkg-config python3 python3-venv xz-utils

git clone https://github.com/liliu-z/stashbase
cd stashbase
pnpm install
pnpm setup:python
pnpm build:web
env -u ELECTRON_RUN_AS_NODE pnpm electron

The package.json engines field pins node >=24.11.0 and the packageManager field pins [email protected], so a mismatched toolchain is a plausible first failure point rather than a documented one.

What stays local, and what does not

The local-first claim is narrower than the tagline suggests, and the README says so. Browsing, editing, preview, keyword search, OCR and audio or video transcription run locally. Search by meaning does not: indexing sends relevant text to the embedding provider you selected. Wiki Agent runs locally, but prompts and necessary model context pass through StashBase's hosted model gateway. Claude Code and Codex use their own provider accounts, which means their data path is whatever those tools already do.

So the honest reading is that your files and your Wiki Pages stay in ordinary folders you own, and you choose which folders join the Library, but model-backed features still reach cloud services. If your material cannot leave the machine at all, only the keyword-search path and local OCR and transcription are available, and you should expect retrieval quality to drop on material that uses different vocabulary than your question.

A second constraint is state ownership. Extracted text and search indexes are app-managed data, not files you edit. The README states that removing a folder from the Library clears StashBase's state for it without deleting your files. That is a reasonable boundary, but it also means the index is disposable and rebuilding it is a cost you should be prepared to pay.

Where StashBase is the wrong tool

Three cases stand out. The first is a team that needs a shared, always-on knowledge service. StashBase is a desktop app; the README's external-client instructions start with keeping StashBase running and copying the connection configuration from Settings, MCP. There is no documented headless deployment or multi-user server mode, so a shared wiki with concurrent editors is outside what the material describes.

The second is anyone on Linux who needs first-class support. The README labels Linux x86_64 Debian 12+ and Ubuntu 22.04+ as community-supported, and the build-from-source notes include a list of native packages that must be installed before the sidecars will build. That is not the same as a supported platform.

The third is a workflow that expects the Wiki to stay current on its own. The README is blunt: building or updating pages is an explicit agent request, and opening a folder does not schedule automatic Wiki maintenance. If your sources change daily and you will not send a build request, the Wiki Pages will drift from the sources they point at.

How it differs from a plain RAG pipeline or a note-taking app

A conventional RAG setup embeds chunks and returns passages at query time. StashBase also does semantic search, but its distinctive move is the intermediate artifact: Markdown Wiki Pages that are linked to each other and back to the sources, and that you can open and use outside the app. That artifact is inspectable and editable in a way a vector store is not. You can read the overview, notice it is wrong about a topic, and fix it in the editor rather than debugging retrieval.

The trade-off is maintenance. A RAG index rebuilds itself when the corpus changes; a Wiki is documentation, and documentation goes stale unless someone asks the agent to revise it. StashBase makes that request cheap, but it does not make it automatic.

The other comparison worth drawing is with note-taking tools that have added AI features. Those tend to own the note format and the storage. StashBase's README states that sources keep their original layout and that Wiki Pages are visible Markdown, which means the exit cost is low: you keep the folder. Whether that matters depends on how much you trust a pre-1.0 app with your library's index.

Licence, maintenance and the upgrade bill

StashBase is Apache-2.0, with a NOTICE file in the repository root, which is the usual arrangement for a permissively licensed project that wants attribution handled explicitly. The practical implication for adopters is that you can read, modify and redistribute the code under those terms; it says nothing about the hosted model gateway or the embedding credits, which are separate services rather than part of the licensed source. Nothing here is legal advice, and anyone embedding StashBase in a product should read the licence text and NOTICE themselves.

On maintenance, the repository is not archived and the last push was on 2026-09-08, with v2.4.0 released on 2026-09-04, v2.3.2 on 2026-08-28 and v2.3.1 on 2026-08-27. That is a recent cadence, but the README still carries an early alpha status badge, and package.json reports version 2.7.0 while the newest listed release is v2.4.0, so the published release and the source tree are not on the same number.

Upgrade cost is mostly re-indexing. Because extracted text and search indexes are app-managed, a schema change in how text is stored or embedded can force a rebuild of the state for a folder, and the README offers no documented migration path for that. Building from source adds a second kind of cost: Node.js 24+, pnpm, Python 3.10+ and, on Ubuntu or Debian, the native build packages listed in the README.

Editorial conclusion

Adopt StashBase if you keep research, notes or project docs in ordinary folders and want an agent to read them without moving the files, and if macOS Apple Silicon or Windows x64 matches your machine. Skip it if you need a supported Linux desktop, if you cannot send text to an embedding provider for search by meaning, or if you expect the Wiki to maintain itself. Verify first that the folder you point it at can be re-indexed from scratch, because the README states that removing a folder from the Library clears StashBase's state for it.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. liliu-z/stashbase on GitHub
3. Project website
4. README
5. Releases