Matryca Plumber

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

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 audit; v2.0.0-alpha ships an opt-in Shadow DB read cache (MATRYCA_SHADOW_DB_ENABLED, default off) with FTS5 BM25 + recursive CTE subtree reads and Markdown/BM25 fallback; v2.0.0-alpha.1 hardens Axis 1 concurrency (#262) and meta/pages health (#264). Built on Andrej Karpathy's LLM-Wiki vision. Current: v2.0.0-alpha.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)
• Shadow DB (v2.0.0-alpha.5, opt-in) — daemon-owned shadow.sqlite read cache: FTS5 BM25 + recursive CTE subtree when MATRYCA_SHADOW_DB_ENABLED=true and health is ready; CTE depth-truncation status (#289); state API path redaction (#293); FTS query length bound (#279); hyphenated FTS query fix (#277); incremental rename stale-owner fix (#272); cross-process writer flock + meta/pages validation; generational BM25 + parser fallback otherwise — see llms.txt §2.6
• 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

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

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; Tana knobs: MATRYCA_TANA_IMPORT_NAMESPACE, MATRYCA_TANA_DEPTH_LIMIT; edge profile for large vaults: docs/v1.8-OPTIMIZATION-PLAN.md. Release history: CHANGELOG.md.

Community

Code of conduct: report concerns to [email protected] — 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