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. Built on Andrej Karpathy's LLM-Wiki vision. Current: v1.13.1 — CHANGELOG.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)
• 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

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"
matryca import tana --file ~/Downloads/workspace.json   # dry-run; add --apply to write

Eight MCP tools (five mega-tools + store_fact + ingest_document + import_tana) — MATRYCA_MCP_ENABLED=true when you trust the host. Spec: llms.txt · docs/openspec/agent-dx.md · docs/openspec/tana-import.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, import_tana, link verification, LLM OS Soft Gate. OpenSpec: docs/openspec/README.md.

Advanced .env — copy .env.example; T