StashBase：local folders を Agent が検索できる context library にする
AI coding agent でよくぶつかる制約の一つは、tool を呼べないことではなく、本当に必要な local material を見つけられないことだ。code repository は workspace に入れられるが、project notes、contracts、papers、meeting recordings、screenshots、design docs、PDF manuals は別の folder に散らばっている。ファイルを一つずつ chat window に投げることはできるが、それは継続的な context management ではないし、team や長期 project が頼れる workflow とも言いにくい。
今日見たいのは liliu-z/stashbase。位置づけは明快で、local files を Agent が検索できる context に変える tool だ。local folder を開くと、StashBase は対応する content を text と index に準備し、local MCP server 経由で Claude、Codex、その他 MCP client に渡す。新しい chat model ではなく、local material に再構築可能で検索可能な Agent 接続 layer を追加する project である。
GitHub repository API、repository page、README、Latest Release、tags、package.json、default branch commit を 2026-08-01 時点で確認すると、liliu-z/stashbase は 172 stars、11 forks。主要言語は TypeScript、license は Apache-2.0。repository は 2026-05-19 05:21:06 UTC に作成され、最近の public push は 2026-08-01 09:46:42 UTC。default branch main の現在の HEAD は 4c3527d、commit time は 2026-08-01 09:10:54 UTC。最新 GitHub Release は v1.3.2、published time は 2026-07-22 11:57:50 UTC。root package.json の package name は stashbase、version は 1.3.2、必要な Node.js は >= 22.12.0、package manager は pnpm 11.5.1。
プロジェクト概要
| 項目 | 内容 |
|---|---|
| リポジトリ | liliu-z/stashbase |
| 位置づけ | local file library、search index、MCP context layer |
| Stars | 172 |
| Forks | 11 |
| 主要言語 | TypeScript |
| ライセンス | Apache-2.0 |
| GitHub 作成時刻 | 2026-05-19 05:21:06 UTC |
| 最新 push | 2026-08-01 09:46:42 UTC |
| 現在の default branch commit | 4c3527d、2026-08-01 09:10:54 UTC |
| 最新 GitHub Release | v1.3.2、2026-07-22 11:57:50 UTC |
| package | stashbase 1.3.2、Node.js >= 22.12.0、pnpm 11.5.1 |
| キーワード | local files、semantic search、MCP、PDF、DOCX、OCR、transcription、Electron |
扱うのは code だけではなく file material
StashBase の README は入力範囲をはっきり示している。Markdown、HTML、PDF、DOCX、images、audio、video が preparation flow に入る。Format ごとに経路は異なる。Markdown は source text をそのまま index できる。HTML は clean text を抽出する。PDF は derived Markdown になる。DOCX は derived HTML になる。Images は OCR、audio と video は local transcription によって timestamped transcript になる。
この角度は一般的な code search tool と少し違う。Code repository にはすでに rg、LSP、symbol index、Agent 向け tool がある。本当に扱いづらいのは、その横にある「code ではないが判断に効く」資料だ。たとえば Agent に compliance 関連機能を直してもらうなら、contract clauses や customer mails が必要かもしれない。Docs generation なら古い PDF manual を参照したい。Product behavior の調査なら meeting recording の transcript や screenshot note が効くこともある。
StashBase の価値は、そうした local material を同じ search surface に置くところにある。README の core flow は、local files -> prepared text -> search index -> MCP -> Agents。Original files は source of truth のままで、index は folder から再構築できる derived layer だ。この点は実務的で、資料を新しい cloud knowledge base に移すことを要求しない。
MCP が Agent との接続面になる
StashBase の実行中は local MCP server が立ち上がる。README にある core tools は library_info、search_library、reindex。外部 Agent は、現在開いている folder、embedder status、library の状態を確認したうえで検索し、必要なら index の再構築を走らせられる。
さらに、opened folders 向けの bounded file helpers もある。list_directory、read_file、write_file、edit_file、move_file、delete_file だ。README は、これらが sandbox 内で動く Agent client のためのもので、general-purpose filesystem API ではないと説明している。この境界は重要だ。StashBase は OS の file permission を置き換えるのではなく、user が明示的に開いた folder の中で Agent に制御された入口を渡す。
Claude や Codex のような CLI / desktop client にとって、この設計は「document を prompt に貼る」より安定している。Library は更新でき、Agent は検索してから関連 file を読むことができる。毎回人間が context を選ぶ必要はない。長期 project にも向いている。今日追加した PDF が、数週間後にも同じ local library から見つかるからだ。
Local-first だが semantic search には選択が残る
README は local boundary をかなり丁寧に説明している。Folder は元の場所に残り、library から削除しても StashBase の app-owned state が消えるだけで、disk 上の files は削除されない。Audio と video transcription は local speech model で走り、Settings から Tiny、Base、Small の model を download できる。
ただし semantic search は完全な zero-config ではない。README によると、embedding API key がなくても app 内の keyword search は使える。Semantic search を使う場合は OpenAI または OpenRouter API key を追加できる。つまり StashBase は file preparation、index、MCP、local transcription を手元で扱うが、semantic embedding を外部 provider に渡すかどうかは user の選択になる。
だからこそ、まず小さく試すのが合っている。Non-sensitive material と keyword search で workflow を確認してから、どの folder に semantic search を使うか、どの資料は local 処理だけに留めるかを決められる。Team で評価すべきなのは、単に「検索できるか」ではなく、data scope、API key、derived text、vector store、Agent write permissions の境界だ。
Desktop app と built-in Agent panel は現実的な選択
StashBase の primary platforms は macOS 12+ Apple Silicon と Windows 10+ x64。Linux x86_64 Debian 12+ / Ubuntu 22.04+ build も community-supported として用意されている。Install path は macOS Homebrew cask、Windows installer、Linux .deb。Source build は普通の TypeScript / Electron project に近い。
git clone https://github.com/liliu-z/stashbase
cd stashbase
pnpm install
pnpm setup:python
pnpm build:web
pnpm electronBuilt-in Agent panel もある。Current folder の横で Claude Code や Codex のような local Agent CLI を走らせるための panel だ。この panel は別の knowledge base ではなく、同じ MCP server の client である。README では、Agent CLI 自身の session history を維持し、tool calls や file edits を app 内で review できると説明されている。
この設計は document-driven tasks に向いている。PRD、user interviews、PDF specs、old screenshots が入った folder を開き、Agent にまず資料を検索させ、その同じ folder 内の Markdown や code を編集させる。資料の場所と work directory を二つの tool に分ける必要がない。
注意したい境界
第一に、project は early alpha だ。172 stars、11 forks、2026 年 5 月作成で、更新は活発だが、多くの organization に検証された knowledge infrastructure ではまだない。Personal project、research folder、小さな team trial に向いている。
第二に、index quality は preparation flow に依存する。OCR、PDF extraction、DOCX to HTML、audio/video transcription は format、language、scan quality、model capability の影響を受ける。Search results は Agent に clues を渡せるが、すべての資料を完璧に理解する保証ではない。
第三に、MCP file helpers の permission は慎重に扱うべきだ。対象は opened folders に限られるが、Agent に接続すれば、その Agent が files を読んだり変更したりできる。Sensitive materials、write access、automated workflow を同時に置く前に、folder、permission、client を分けて試したい。
第四に、semantic search は external embedding provider を含む可能性がある。StashBase の local-first model は資料を集中 upload する圧力を下げるが、OpenAI や OpenRouter key を設定した場合、どの text が embedding request に入るかは自分の risk boundary に照らして確認したい。
まとめ
liliu-z/stashbase が面白いのは、Agent context の問題を「もっと長い prompt」に単純化していないところだ。Local folder、format preparation、search index、MCP interface をつなぎ、Agent が人間に file を渡されるのを待つのではなく、自分で資料を探せるようにしている。
仕事がほぼ code repository の中で完結するなら、通常の code search で足りるかもしれない。しかし判断に PDF、DOCX、screenshots、recordings、research notes、散らばった documents が頻繁に関わるなら、StashBase は watchlist に入れてよい。まだ早い project だが、摩擦はかなり現実的だ。価値のある context の多くは、最初から local folder の中に眠っている。