Matryca Plumber：AI agent に Logseq のローカル知識庫を安全に読ませる
AI agent を personal knowledge base につなぐとき、本当に怖いのは「notes を読めるか」ではなく、「ついでに notes を壊さないか」だ。
Logseq OG の良さは、content が local Markdown files として残ることにある。version control、backup、offline use と相性がいい。一方で agent から見ると、application semantics を通らずに text file を直接編集できてしまう。indent が一段ずれる、block property が消える、id:: line が上書きされる。その程度でも、長く育てた graph はかなり戻しにくくなる。
今日メモしておきたい MarcoPorcellato/matryca-plumber は、このリスクを扱う project だ。Logseq OG vault を AI agent に開く。ただし agent に Markdown を勝手に parse させるのではなく、CLI、MCP server、background daemon、Sovereign UI を通す。read/write は structured interface に寄せ、mutation の前に OCC check を入れ、background semantic indexing や link hygiene も local-first の範囲に置く。
2026-07-18 時点で GitHub repository page、README、Tags page、公開 commit history、LICENSE、raw README、local git clone から確認できる公開情報では、MarcoPorcellato/matryca-plumber は 82 stars、11 forks。主言語は Python で、GitHub language breakdown は Python 89.5%、TypeScript 6.9%、Shell 3.1%、Makefile 0.2%、CSS 0.2%、JavaScript 0.1%。license は Apache-2.0。GitHub page の embedded data にある repository creation time は 2026-05-17 04:05:01 UTC。公開 Git history の initial commit は d90d01a、commit time は 2026-05-17 04:55:29 UTC。候補取得時の GitHub search が記録した最近 push は 2026-07-17 15:39:30 UTC。default branch main の最新 commit は 490961c、commit time は 2026-07-17 15:39:29 UTC。GitHub Releases block の current latest release は v1.14.0 で、公開日表示は 2026-07-16。Tags page では v1.14.0 の commit は 895884a、commit time は 2026-07-16 06:05:57 UTC。README に書かれている current version も v1.14.0 だ。
プロジェクト概要
| 項目 | 内容 |
|---|---|
| リポジトリ | MarcoPorcellato/matryca-plumber |
| 位置づけ | Logseq OG の local-first AI daemon、CLI、MCP server |
| Stars | 82 |
| Forks | 11 |
| 主言語 | Python |
| ライセンス | Apache-2.0 |
| GitHub 作成時刻 | 2026-05-17 04:05:01 UTC |
| 公開 Git history 起点 | 2026-05-17 04:55:29 UTC、initial commit d90d01a |
| 最近 push | 2026-07-17 15:39:30 UTC |
| 最新 main commit | 490961c、2026-07-17 15:39:29 UTC |
| Latest GitHub release | v1.14.0、2026-07-16 |
| キーワード | Logseq OG、local-first、MCP、OCC safety、semantic indexing、Tana import |
痛点は検索より安全な書き戻し
多くの「AI が notes を読む」tool は、まず vector index と Q&A から始まる。もちろん便利だ。ただ、長く notes を保守している人にとっては、search より write-back の方が危ない。search が外れても答えが悪いだけだが、write-back が外れると、何年も育てた vault を汚す可能性がある。
Matryca Plumber の README は、Logseq-native writes と OCC safety をかなり強調している。logseq-matryca-parser で frontmatter、block properties、namespace encoding など Logseq の細部を扱い、agent が Markdown patch を手で書く状況を避ける。mutation には st_mtime snapshots と page locks を使う。agent が考えている間にあなたが同じ page を直していたら、commit は silent overwrite せず abort する。
これは地味だが重要だ。personal knowledge base は temporary code branch ではない。完全な test suite があるわけでもない。agent に書き込ませるなら、最低でも二つの保証がほしい。agent が普通の Markdown ではなく Logseq block tree を扱っていること。そして、古い context で user の変更を上書きしないことだ。
agent の入口は CLI と MCP
Matryca Plumber は、人間向けの desktop app だけではない。README には agent 向け entry point として matryca --json read、context load、read subtree のような CLI command と FastMCP stdio tools が出てくる。つまり agent は .md files を直接読みにいくのではなく、page、subtree、context を structured JSON として受け取れる。
MCP server という置き方も自然だ。Cursor、Claude Desktop、Claude Code、その他 MCP-compatible client が、同じ tool set に接続できる。knowledge base では、これは client ごとに prompt を増やすより扱いやすい。prompt は preference や task instruction を書く場所として残す。実際の read/write capability は controlled tool に寄せる。
README には MATRYCA_MCP_ENABLED=true という switch もある。これは project が「MCP なら常に安全」とは考えていないことを示している。MCP は capability boundary であり、trust boundary でもある。現在の host と agent を信頼できるときだけ、write capability を開くべきだ。
background daemon は notes hygiene 向き
明示的な read/write 以外に、project には background daemon がある。semantic summaries、dangling [[link]] repair、entity consolidation、link hygiene、Journey Log などを扱う。価値は、agent に一度で knowledge base を書き換えさせることではない。小さな maintenance action を checkable loop にすることだ。
Logseq を長く使うと、link drift、同義 entity の分散、密度の高い page、split したい block が増える。Matryca Plumber の README は、これらの action を trust tier に分けている。Safe Mode は read-only と side cache 寄り、Augmented Mode は side-blocks、Surgeon Mode で初めて inline edits を許す。
この分け方は大事だ。AI notes tool が最初から「全部自動整理します」と言うと、危険な black box になりやすい。まず observe し、side structure を作り、checklist を出し、それから徐々に強い write action を許す方が現実的だ。
Sovereign UI は設定と確認の場所
project には browser 上の Sovereign UI もある。README の quick start は uvx --from matryca-plumber matryca-plumber status で、UI から Logseq Graph Path、local LLM、engine start を設定する。uv tool install matryca-plumber の後に background service を install する流れもある。
この UI は Logseq を置き換えるためのものではない。risk configuration を見えるようにするためのものだ。Graph path、local LLM、daemon state、trust tier、telemetry、Bearer auth がすべて environment variables に隠れていると、普通の user は現在の agent が何をできるのか判断しにくい。UI に置くことで、「write を許すか」が明示的な操作になる。
developer にとっても試しやすい。最初から MCP config を書かなくても、status で UI を開き、どの vault を読むのか、daemon が起動するのか、pre-flight check が何を見ているのかを確認してから、自分の agent client につなげられる。
Tana import も現実的な使い道
README の大きな部分は Tana から Logseq OG への migration に割かれている。command は matryca import tana --file export.json で、default は dry-run。--apply を付けて初めて write する。Tana workspace JSON、journal routing、depth split、wikilink resolution、tana-id idempotent property などを扱う。
これは agent memory と同じ底の問題だ。外部構造を local outliner に書き込むとき、string concatenation だけでは足りない。importer は page、journal、nested block、property、idempotency を理解する必要がある。失敗すると単一 file の error ではなく、相互参照を持つ dirty data が残る。
Matryca Plumber は、この migration と agent write-back を同じ Logseq-native mutation plane に置いている。考え方は一貫している。agent 生成であれ Tana import であれ、最終的には Logseq の file semantics と block semantics を尊重しなければならない。
向いている人
第一に、Logseq を work memory として本気で使っている人。notes が toy demo ではなく、projects、meetings、research、journals が混ざった long-lived vault になっているなら、AI には読んでほしいが、勝手には直してほしくないはずだ。
第二に、local knowledge base を coding agent につなぎたい人。project を直すときに decision records、architecture notes、runbooks を読ませたり、新しい fact を固定 page に戻したりする場面がある。CLI と MCP は、「この folder を読んで」と頼むより boundary を制御しやすい。
第三に、Tana や他の outliner、散らばった Markdown から migration している人。Matryca Plumber がすべての migration need を満たすわけではないが、dry-run、idempotent property、Logseq parser を前面に置いている点は、手書き script より安心しやすい。
第四に、local-first toolchain が好きな人。README は vault が disk に残ること、local LLM が使えること、cloud API key が不要なことを繰り返し強調している。private notes では、これは feature count より重要な方向性だ。
注意したいところ
第一に、Matryca Plumber は Logseq OG の Markdown graph を対象にしている。主な knowledge base が Obsidian、Notion、Logseq DB 形態なら、適用範囲を先に確認した方がいい。
第二に、実際に local files を書く tool である。OCC と parser は risk を下げるが、backup の代わりにはならない。README も、まず graph を copy し、test clone で試してから main vault に戻ることを勧めている。
第三に、MCP write capability は慎重に開きたい。MATRYCA_MCP_ENABLED=true は現在の agent host を信頼するという意味になる。personal knowledge base では、read-only と dry-run から始める方がよい。
第四に、project は若い。GitHub creation time は 2026-05-17 で、iteration はかなり速く、release 数もすでに多い。活発なのは良いが、interface や architecture はまだ変わり続ける可能性がある。daily workflow に入れる前に、non-critical vault でしばらく試したい。
まとめ
Matryca Plumber が面白いのは、「AI notes」をまた別の chat box として扱っていないところだ。local files、Logseq block semantics、OCC conflicts、MCP permissions、background maintenance loop という、実際に壊れやすい部分を中心に据えている。
model に記事を一つ要約させるだけなら、少し重く見えるかもしれない。しかし agent に自分の Logseq vault へ長期的に触らせたいなら、MarcoPorcellato/matryca-plumber は観察する価値がある。AI agent を knowledge base につなぐ最初の一歩は、もっと話せるようにすることではなく、knowledge base を壊しにくくすることかもしれない。