Matryca Plumber

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

We are not building another "agentic memory"...

We are building the governed memory plane for humans and agents.

Human-owned memory. Agent-native access. Governed evolution.

Matryca Plumber does not define or require a graph database, vector database, embedding model or retrieval algorithm.

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.

Published maintenance prerelease: v2.0.1-rc.1 remains available for opt-in evaluation as an exact historical artifact. It adds a bounded, canonical journal_day handler that reads Markdown directly without querying Shadow or mutating a graph, alongside provider-free evidence tooling. Stable v2.0.0 remains the default recommendation. The current development branch has advanced beyond that prerelease, so any later candidate or stable release requires its own exact-source qualification. See the release record and historical qualification plan.

RC2 terminal history; RC3 published; RC4 superseded: v2.0.1-rc.2 failed before GitHub Release creation and PyPI publication; its signed tag and workflow evidence are immutable but are not a public artifact, Gate B result, or stable-promotion credit. v2.0.1-rc.3 is a published historical prerelease. v2.0.1-rc.4 / 2.0.1rc4 remains unpublished. An earlier exact candidate (74884c38) has source, build, and installed-resource evidence, but later changes require their own exact-source qualification. No RC4 tag, public artifact, Gate B result, or stable promotion exists. See the RC2 failed-publication record, RC3 publication record, and historical RC4 preparation and qualification plan.

Current development: experimental 2.1.0a2 preparation. Alpha.1's failed publication remains immutable; its earlier source evidence does not qualify alpha.2. The active qualification plan prioritizes an offline OG graph-identity and complete content-free topology producer. Linux x86_64 and macOS arm64, CPython 3.12/3.13, and wheel/sdist paths form eight planned rows; none is qualified by this preparation. The supersession record preserves RC4 history and transfers unfinished Windows, full Stage A and dual-profile Gate B obligations. No alpha publication, installed-runtime, Trama-admission or stable-support result is claimed; v2.0.0 remains the default.

Local-first human/agentic memory inspired from Logseq OG and maintenance for Logseq. 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.

Video Overview: Watch this to learn how Matryca Plumber works, how it connects to the wider Matryca ecosystem, and where it fits in shared human/agentic memory.

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

Evaluators may still install the published RC1 historical artifact explicitly without changing the stable recommendation:

uv tool install matryca-plumber==2.0.1rc1

2.0.1rc2 was not publicly released and must not be installed. 2.0.1rc3 is a published historical prerelease and may be installed only for evaluation:

uv tool install matryca-plumber==2.0.1rc3

2.0.1rc4 is not published and must not be installed. The experimental 2.1.0a2 track is preparation, not an installation recommendation or publication record. Neither RC3 availability nor alpha preparation proves Gate B or stable qualification.

The ordinary quick start above is not the experimental OG gateway bootstrap. That gateway requires a dedicated environment with the complete hash-locked Parser 1.9.0 dependency profile, followed by installation of the verified public wheel with --no-deps. The broad application dependency range and an ordinary uvx resolution do not qualify this exact profile. Follow the alpha plan only after its public artifacts and profile pass the declared gates.

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.
• Qualified parser baseline and supported range: v2.0.0 was qualified with logseq-matryca-parser 1.7.1; package metadata accepts >=1.7.1,<2.0.0, so a fresh install can resolve a newer parser within that declared range. The experimental 2.1.0 track qualifies only its declared exact Parser profile; a metadata range is not gateway qualification for other resolved versions.

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.

Experimental OG producer direction

The active 2.1.0 alpha programme adds an isolated, offline process boundary for graph identification and complete ordered, content-free OG topology. Its planned installed matrix, exact dependency profile and public-artifact handoff are defined in the alpha qualification plan. Preparation and static contracts do not prove installed support or a usable Trama adapter. Text/properties, Logseq DB, writes, events, sync and active-desktop coexistence are not included. Windows gateway refusal is a negative control, not Windows qualification; full qualification obligations remain separate.

Historical v2.0.1 RC4 candidate scope

This section preserves the superseded, unpublished RC4 scope. It does not define the current alpha scope or claim that no historical RC4 candidate was selected.

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 handler neither initializes nor queries a Shadow cache. Ordinary CLI or MCP process startup may still prepare the configured Shadow profile before dispatch; that separate bootstrap is unchanged. The feature is useful when an operator or agent needs one day of context without widening retrieval to the surrounding graph.

The proposed candidate does not change the default-on Shadow contract, Read Only boundaries, or write plane. It adds an internal, session-bound OG topology projection and packages only static public contract/TCK bytes; it does not expose a Python adapter, transport, CLI/MCP route, Logseq DB feature, consumer wiring, UI, or LENS surface. Its evidence tooling remains provider-free and is not a benchmark, a real-agent evaluation, or a release result. RC4 preparation has no tag, public artifact, Gate B result, or stable-promotion decision. RC2 and RC3 historical evidence cannot qualify RC4.

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.