Matryca Plumber

I gave my AI access to my notes. It corrupted them.
I built Matryca Plumber so that never happens again.

CLI · MCP · background daemon · Sovereign UI · Logseq OG · OCC-safe · local-first

Install · Architecture · Compare · Agents · Docs · Contributing

_{AI agents: read llms.txt — run uvx matryca-plumber --help; do not parse Markdown manually.}

Matryca Plumber is the definitive bridge between your trusted AI agent and your Logseq OG vault — a headless CLI and MCP server for safe read/write on Logseq's block tree (no raw Markdown parsing, no Logseq API, no silent overwrites), plus a background daemon and Sovereign UI. Built on Andrej Karpathy's LLM-Wiki vision. Current: v1.10.6 — CHANGELOG.md.

Developed by Marco Porcellato · Matryca.ai — the product name is Matryca Plumber (not “Matryca” alone). See docs/BRANDING.md.

What it does

• Agent CLI — matryca --json read, context load, read subtree — structured access to pages and block trees without hand-parsing .md
• MCP server — FastMCP stdio tools for Cursor / Claude Desktop; query and mutate the graph headlessly (MATRYCA_MCP_ENABLED=true when you trust the host)
• Logseq-native writes — logseq-matryca-parser AST compliance: line-0 frontmatter, +2 block properties, namespace encoding — agents stop breaking vaults
• OCC safety — st_mtime snapshots + page locks; if you edited while the model was thinking, the commit aborts — your typing always wins
• Background daemon — semantic summaries, dangling [[link]] healing, entity consolidation while you sleep (local LLM via LM Studio / Ollama)
• Sovereign UI — browser dashboard at :8500; pre-flight checklist, trust tiers, live telemetry — configure everything without terminal env vars
• Link hygiene — background URL/asset checks, Journey Log in today's journal — no per-cycle journal spam
• 100% local-first — vault stays on disk; no cloud API key required

How it works (30 seconds)

CLI, MCP, daemon, and Sovereign UI converge on one OCC-protected mutation plane — same vault on disk, no Logseq HTTP API.

flowchart TB
  subgraph operators [Operators and agents]
    Human[Human · Logseq optional]
    UI[Sovereign UI :8500]
    Daemon[Maintenance daemon]
    CLI[matryca CLI --json]
    MCP[FastMCP stdio optional]
  end

  subgraph plane [Shared headless mutation plane]
    GD[graph_dispatch]
    Lock[OCC + page_rmw_lock\n+ platform_lock flock]
    Parser[logseq-matryca-parser]
    GD --> Lock
    GD --> Parser
  end

  subgraph local [Local inference — 100% offline]
    LLM[LM Studio / Ollama]
  end

  subgraph vault [LOGSEQ_GRAPH_PATH — single source of truth]
    Pages[pages/ · journals/ · templates/]
    Meta[.matryca_* cache & ledgers\nmatryca-l1/ session rules]
  end

  Human <-->|co-edit Markdown| Pages
  UI -->|start · stop · config · telemetry| Daemon
  Daemon -->|Phase 1 harvest · Phase 2 lint| GD
  Daemon <-->|structured JSON| LLM
  CLI --> GD
  MCP --> GD
  Lock -->|atomic UTF-8 writes| Pages
  Meta -.-> GD

Loading

• Single mutation plane — graph_dispatch + OCC locks; CLI, MCP, and daemon share the same write contract
• Phase 1 → Phase 2 — catalog harvest, then cognitive lint against a local LLM
• Parser-first — agents never touch raw Markdown; the AST layer handles Logseq quirks
• One vault path — LOGSEQ_GRAPH_PATH (set in the Sovereign UI or .env)

→ docs/ARCHITECTURE.md

Get started (60 seconds)

# 1 — Try instantly (opens Sovereign UI in your browser)
uvx --from matryca-plumber matryca-plumber status

# 2 — Configure in the browser — no terminal env vars needed
#    Pre-flight → Settings (gear) → Logseq Graph Path → local LLM → Start Engine

# 3 — Optional: install globally + background service
uv tool install matryca-plumber
matryca service install

The first command opens the Sovereign UI at http://127.0.0.1:8500. Use the pre-flight wizard to point at your vault, pick a local LLM, and click Start Engine. The daemon does not run until you confirm.

Command	What it starts	Browser / :8500	Maintenance daemon
matryca plumber status (recommended)	Sovereign UI + local API	Yes	No — use Start Engine or plumber start
matryca plumber ui	Same as status	Yes	No
matryca plumber start	Background daemon only	No	Yes
matryca plumber stop	—	—	Stops daemon

Common mistake: matryca plumber start does not open the dashboard — run matryca plumber status (or use Start Engine from the UI).

How it compares

Feature	Matryca Plumber	Official Logseq AI Plugin	Obsidian LLM Plugins
Local-only	Yes — vault stays on disk	Typically cloud-backed	Mixed (local + cloud options)
No API Key required	Yes — local LLM endpoint	Usually requires provider API key	Often requires API key
OCC Safety (no corruption)	Yes — st_mtime + page locks	No comparable write guard	No standard OCC layer
MCP Support	Yes — FastMCP stdio tools	No	Varies by plugin
Agent CLI (structured graph access)	Yes — matryca --json	No	Varies by plugin

Matryca Plumber targets Logseq OG (Markdown on disk); Obsidian comparisons refer to common community plugins, not a single product.

Clone your graph first

Matryca Plumber edits local .md files directly. OCC prevents silent data loss, but test on a clone first:

1. Duplicate your graph folder (e.g. MyGraph → MyGraph_Test) and add it in Logseq via Add new graph.
2. If you use Logseq Sync: do not enable Sync on the test graph.
3. In the Sovereign UI: Settings → Logseq Graph Path → point at the clone → Save.

Once comfortable, switch to your main graph in Settings.

Trust & Safety

You are in control. Nothing mutates your prose unless you explicitly enable it in the UI.

Mode	Risk	What it allows
🟢 Safe Mode	Read-only	Semantic cache, entity consolidation (alias::), property hygiene — never edits bullet text.
🟠 Augmented Mode	Side-blocks	Heal Dangling Links, Backpropagate Links — original bullets stay intact.
🔴 Surgeon Mode	Inline edits	Inline Semantic Corrections, Auto-Split Dense Blocks — strictly opt-in.

"Logseq is building the best local outliner database. But AI Agent memory is at the very bottom of their roadmap. Matryca Plumber gives you that future today, safely bridging your local agents to your Logseq graph without waiting years." — Marco Porcellato, Matryca.ai

Agent CLI & MCP

Point the vault in the Sovereign UI (or .env) — agents inherit LOGSEQ_GRAPH_PATH.

matryca --json read page "My Project"
matryca context load "My Project"

Seven MCP tools (store_fact, ingest_document, …) — MATRYCA_MCP_ENABLED=true when you trust the host. Spec: llms.txt · docs/openspec/agent-dx.md · docs/openspec/agent-onboarding.md

Sovereign UI, configuration & full capabilities

UI (:8500) — pre-flight checklist, live telemetry, trust tiers, Bearer auth (SECURITY.md). Recommended LLM: Gemma 4-E4b Instruct (gemma-4-e4b-it) on 16 GB RAM.

Daemon — semantic indexing, dangling links, entity consolidation, auto-split, ingest_document, link verification, LLM OS Soft Gate. OpenSpec: docs/openspec/README.md.

Advanced .env — copy .env.example; edge profile for large vaults: docs/v1.8-OPTIMIZATION-PLAN.md. Release history: CHANGELOG.md.

Developer setup

git clone https://github.com/MarcoPorcellato/matryca-plumber.git && cd matryca-plumber
make install
cd frontend && npm install && npm run build && cd ..
make test-fast    # fast loop (~5s)
make check        # full CI gate before PR

Documentation

Start here	Go deeper
SUPPORT.md	docs/ARCHITECTURE.md
CONTRIBUTING.md	docs/openspec/README.md
llms.txt	SECURITY.md
ROADMAP.md	CHANGELOG.md
SYSTEM_PROMPT.md	docs/integrations/hermes-agent.md
Good first issues	good_first_issues_blueprints.md

License

Apache-2.0 — see LICENSE.

Star History