Matryca Plumber

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

v2.0.0 is stable and available now. Matryca Plumber's default-on external Shadow DB, Strict Read Only protection, Markdown authority, and fail-closed fallback contract are now published on GitHub Releases and PyPI. Read the release record and changelog for the exact scope and upgrade notes.

Maintenance candidate: v2.0.1-rc.1 is the next patch candidate. It adds a bounded, canonical journal_day read without invoking Shadow or mutating a graph, alongside provider-free evidence tooling. It is qualified separately from v2.0.0: see the release qualification plan.

Local-first agentic memory and maintenance for Logseq OG. Matryca Plumber gives humans and agents one safe, structured interface to a Markdown knowledge graph—without turning an opaque database or a model provider into the owner of that knowledge.

Quick start · Why Matryca · Memory model · Architecture · Shadow DB · v2.0.0 release · Agent guide · Documentation

Quick start

Requires Python 3.12 or newer and a Logseq OG graph.

# Run the UI without installing anything permanently
uvx matryca-plumber status

Open http://127.0.0.1:8500, select a cloned Logseq graph, review the pre-flight checks, and start the engine when ready.

# Optional: install the command and its background service
uv tool install matryca-plumber
matryca service install

Start with a clone of your graph, especially before enabling writes or applying an import. See the operator contract, security policy, and support guide.

To install the stable release explicitly:

uv tool install matryca-plumber==2.0.0

Once the candidate is published, evaluators may install it explicitly without changing the stable recommendation:

uv tool install matryca-plumber==2.0.1rc1

The candidate is not a claim that the final patch has been published or qualified.

What v2.0.0 changes

The stable v2 release makes the Shadow read path a practical default while keeping ownership and mutation boundaries explicit:

• External Shadow DB by default: healthy FTS5 and subtree reads use a disposable cache outside the Logseq graph; set MATRYCA_SHADOW_DB_ENABLED=false to opt out.
• Strict Read Only remains useful: MATRYCA_READ_ONLY=true blocks graph-local mutation while validated external Shadow maintenance remains available.
• Markdown remains authoritative: Shadow never replaces Logseq Markdown, OCC, or the parser-aware write plane. Unavailable, stale, or unhealthy Shadow state falls back to Markdown-backed BM25 reads.
• Stable parser baseline: the release uses logseq-matryca-parser 1.7.1.

Biological memory, native Logseq DB Safe-Sync writes, content-aware Tana merge, and proactive adaptive runtime remain future work; they are not silently included in the v2.0.0 contract.

What the v2.0.1 candidate adds

journal_day is a narrow read target for one canonical ISO-dated Logseq journal. It keeps the same ownership model as v2: Markdown is authoritative, the response carries bounded provenance and a source digest, malformed dates and pagination requests fail closed, and the read neither initializes nor depends on a Shadow cache. The feature is useful when an operator or agent needs one day of context without widening retrieval to the surrounding graph.

The candidate does not change the default-on Shadow contract, Read Only boundaries, write plane, or any experimental graph-native projection. Its evidence tooling remains provider-free and is not a benchmark, a real-agent evaluation, or a release result.

Why Matryca Plumber

Most agent memory systems ask you to trust an internal store. Matryca Plumber starts from the opposite premise: your human-readable Logseq Markdown remains the system of record.

This makes Matryca Plumber more than a vector store or chat-history database. It is a controlled memory plane where humans keep custody of knowledge and agents receive the structure, speed, and safety they need to work with it.

A different model of agentic memory

Mem0 and many other service-centric memory layers solve an important problem: they extract, store, and retrieve scoped memories so an application can personalize an agent across sessions. Matryca Plumber solves a different problem: how humans and agents can safely maintain the same durable body of knowledge.

Why block granularity matters

Logseq's outliner gives Matryca Plumber a natural unit of memory that is both machine-addressable and human-readable. A block can have a durable id:: UUID, properties, children, links, and a precise place in the graph.

When an agent already knows that anchor, Matryca can:

• retrieve only the block and its descendants instead of placing the entire page in the model's context;
• narrow the result again to one heading, or bound a Shadow query by depth, node count, and output bytes;
• append beneath a specific parent or edit only the permitted property lines inside that block's span;
• preserve the surrounding page and reject a stale write through dry-run, page locks, and OCC.

This reduces prompt tokens and irrelevant context, makes retrieval more focused, and shrinks the area in which an agent can make a mistaken edit. A Markdown fallback may still read the page locally to locate the block, and an atomic commit persists the page file, but the model does not need to ingest or regenerate the whole document.

Page-centric Markdown integrations often lack this boundary and must provide a much larger document to the model for a small read or update. Not every agent-memory system is page-centric—Mem0 also stores granular extracted memories. Matryca's distinction is that its granular unit remains the same canonical block the human reads and edits, not a separate derived memory record. See the targeted subtree contract for the exact read surface.

The decisive distinction is not merely local versus cloud, or Markdown versus a database. It is which representation remains authoritative. Matryca Plumber uses a database where it is valuable—for fast derived reads—without moving ownership away from the documents a human can inspect, edit, link, version, and keep independently of any agent.

This is an architectural comparison, not a claim that one category replaces every other. Mem0 supports both hosted and self-hosted deployments and is optimized for a different integration boundary. For the longer argument and the design philosophy behind Matryca Plumber, read The Agentic Memory Dilemma: Mem0 vs. Matryca Plumber and the Future of Human-AI Collaboration.

What it provides

• Agent-native CLI and MCP for pages, blocks, search, context, ingestion, and guarded mutation.
• Derived Shadow DB with SQLite FTS5 and subtree reads, external cache isolation, health checks, fallback, and quarantine behavior.
• Background maintenance for semantic indexing, link hygiene, entity consolidation, and other explicitly enabled operations.
• Logseq-aware writes through the parser and one shared OCC-protected mutation plane.
• Sovereign UI for setup, trust controls, health, and runtime telemetry.
• Tana to Logseq OG migration, streamed and dry-run by default.

For the complete and current behavior, use the documentation paths rather than this overview.

Choose how much gardening you want

Matryca separates the permission to write from the kind of maintenance it may perform. Strict Read Only is the hard boundary: while it is enabled, every graph-writing control is unavailable. Reads still work, and Shadow DB Acceleration may independently maintain its disposable cache outside the Logseq graph.

When writes are allowed, the traffic-light levels let you choose how actively Matryca Plumber tends the graph:

This means Matryca can remain a fast, read-only memory layer, or become an opt-in knowledge gardener that consolidates entities, improves properties, repairs missing link targets, and strengthens connections between notes. Start with Strict Read Only, then enable only the smallest gardening level that matches your needs.

See the architecture trust levels and Shadow DB operator contract for the exact boundaries.

How it works

flowchart LR
  Human["Human in Logseq"] <--> Markdown[("Logseq Markdown\nsystem of record")]
  Agents["Agents"] --> Access["CLI + MCP"]
  UI["Sovereign UI"] --> Runtime["Maintenance runtime"]
  Access --> ReadPlane["Structured read plane"]
  Access --> WritePlane["OCC-protected write plane"]
  Runtime --> ReadPlane
  Runtime --> WritePlane
  ReadPlane --> Shadow[("External Shadow DB\ndisposable cache")]
  ReadPlane --> Markdown
  WritePlane --> Parser["Logseq-aware parser"]
  Parser --> Markdown
  Markdown -. "rebuild / reconcile" .-> Shadow

The read and write paths have deliberately different authority:

• Reads may use the Shadow DB when it is enabled, healthy, and fresh; otherwise they fall back to Markdown-backed indexes.
• Writes always pass through the shared mutation plane and parser. Shadow maintenance cannot roll back an authoritative Markdown write.
• Strict Read Only blocks graph-local mutation while permitting validated external derived-cache writes.

Current defaults and exact fallback semantics live in the canonical Shadow DB operator contract.

Common workflows

Give an agent structured graph access

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

Agent hosts should start with llms.txt. MCP is disabled until explicitly trusted and enabled by the operator.

Import a Tana workspace

export LOGSEQ_GRAPH_PATH=/path/to/a/cloned/logseq/graph

# Inspect first; no graph writes by default
matryca import tana --file ~/Downloads/workspace.json

# Apply only after reviewing the dry-run report
matryca import tana --file ~/Downloads/workspace.json --apply

See the Tana import contract for mapping, idempotency, and large-export behavior.

Run the local services

Documentation

Project and community

• Issues — bugs and trackable feature work
• Discussions — design proposals and questions
• Contributing — development setup and quality gates
• Code of Conduct — community expectations
• Security — private vulnerability reporting
• Sponsor — support continued work

Matryca Plumber is developed by Marco Porcellato and Matryca.ai. Product naming and identity are defined in the branding guide.

License

Apache-2.0 — see LICENSE.