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 · Tana import · Architecture · Compare · Agents · Docs · Community · 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. v1.11.0 adds Tana → Logseq OG migration; v1.11.1 aligned logseq-matryca-parser 1.4.0; v1.11.2 refactors the graph layer boundary; v1.12.0 applies Clean Architecture to Tier-1 prompts, L0 write safety, and fragment-assembled SYSTEM_PROMPT.md; v1.12.1 adds contributor Clean Code docs and a v2.0 preparation index; v1.13.0 ships daemon/dispatch modularization (#58, #59) and GraphReadPort (v2 Phase 1); v1.13.1 pins logseq-matryca-parser 1.6.0 with headless newline parity; v1.14.0 hardens MasterCatalog write-safety, the file watcher, and leaf-module dependency direction after the 2026-07-16 code audit. Built on Andrej Karpathy's LLM-Wiki vision. Release candidate: v2.0.0-rc.1 — CHANGELOG.md. The RC moves Shadow to a per-user external cache, makes healthy Shadow reads default-on with explicit MATRYCA_SHADOW_DB_ENABLED=false opt-out, and supports independent Strict Read Only and Shadow controls while Logseq Markdown remains authoritative. Gate A is qualified; the public RC begins the separate Gate B observation required before stable v2.0.0. The published v2.0.0-beta.1 / 2.0.0b1 wheel remains the historical default-off, graph-local baseline. Readiness record: docs/quality/issue-bodies/v2-rc-stable-readiness.md.

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

What it does

• Tana → Logseq OG import — matryca import tana --file export.json [--apply] and MCP import_tana stream Tana workspace JSON into your vault: ijson anti-OOM parsing, logseq/config.edn journal routing, depth-split, catalog wikilink resolution, tana-id idempotent OCC writes — dry-run by default (docs/openspec/tana-import.md)
• Agent CLI — matryca --json read, context load, read subtree — structured access to pages and block trees without hand-parsing .md
• MCP server — eight 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
• L0 write safety — semantic index commits abort when an LLM diff would delete id:: lines or edit protected zones (graph/safety/validators.py)
• Tier-1 prompt architecture — domain */prompts.py builders + DI on InstructorLLMClient; SYSTEM_PROMPT.md assembled from OpenSpec fragments (make build-system-prompt)
• Shadow DB (unreleased v2 RC-target source, default-on external cache) — derived shadow.sqlite read cache outside the Logseq graph: FTS5 BM25 + recursive CTE subtree while health is ready, with generational BM25 + parser fallback otherwise. MATRYCA_READ_ONLY=true can protect the graph while Shadow remains enabled; MATRYCA_SHADOW_DB_ENABLED=false explicitly disables the cache. The Sovereign UI exposes both independent controls and reports bounded fallback reasons. The published 2.0.0b1 wheel remains historically opt-in and graph-local. See llms.txt §2.6.
  • Over-budget pages are quarantined, not fatal. If a page exceeds the page-parse budget (MATRYCA_PAGE_PARSE_TIMEOUT_S, default 15 s), it is parked instead of aborting the rebuild: the rest of the graph is cached and reads for that page use Markdown, which stays authoritative. Health remains READY and the Sovereign UI shows how many pages are parked. On a measured daily-use vault of 1,014 graph pages, 3 pages (0.30%) exceed the default and consume the large majority of total parse time — parse cost tracks page structure, not size (the largest page measured, 650 KB, parses in 0.54 s while a 336 KB page does not finish in a minute), so quarantine removes almost all of the rebuild cost. A parked page is released automatically as soon as it parses within budget; raising MATRYCA_PAGE_PARSE_TIMEOUT_S (2–120 s) parks fewer pages at the cost of slower rebuilds, and MATRYCA_SHADOW_QUARANTINE_ENABLED=false restores the strict fail-the-rebuild behaviour. Full analysis: docs/quality/SHADOW_DB_PARSE_BUDGET_TRIZ_2026-07-27.md.
• 100% local-first — vault stays on disk; no cloud API key required

Tana → Logseq OG migration

Export your Tana workspace as JSON (Export workspace as JSON in Tana), then import into a clone of your Logseq graph first:

export LOGSEQ_GRAPH_PATH=/path/to/your/logseq/graph

# Dry-run (default) — JSON report on stdout; stderr warns no writes
matryca import tana --file ~/Downloads/workspace.json | jq '.write'

# Commit after reviewing counters
matryca import tana --file ~/Downloads/workspace.json --apply | jq '.write.pages_created'

Full pipeline spec: docs/openspec/tana-import.md · MCP: import_tana(export_path, dry_run=True)

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

• 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.

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

How it compares

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 — especially before import tana --apply:

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.

"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

matryca --json read page "My Project"
matryca context load "My Project"
matryca import tana --file ~/Downloads/workspace.json   # dry-run; add --apply to write

Community

Code of conduct: report concerns to marco@matryca.ai — see CODE_OF_CONDUCT.md.

New contributors: start with docs/FIRST_CONTRIBUTION.md, then CONTRIBUTING.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 ci           # full CI gate before PR (format-check + lint + types + tests)

Documentation

License

Apache-2.0 — see LICENSE.

Star History