---
type: Document
---
# GitHub Release — v2.0.0 Stable

**Tag:** [`v2.0.0`](https://github.com/MarcoPorcellato/matryca-plumber/releases/tag/v2.0.0)  
**PyPI:** [`matryca-plumber==2.0.0`](https://pypi.org/project/matryca-plumber/2.0.0/)  
**Release commit:** `987446b8337f7abd308a9efe4abb834ce1acdc1b`  
**Published:** 2026-08-18

## Summary

Matryca Plumber v2.0.0 is the stable Shadow read-path release for Logseq OG.
It gives agents fast, structured reads through a daemon-owned external Shadow DB
while keeping human-readable Logseq Markdown as the system of record.

The release completes the transition from the opt-in, graph-local beta path to a
default-on, health-gated external derived cache. Strict Read Only is compatible with
Shadow acceleration: graph-local mutation is blocked while validated cache maintenance
remains available outside the graph.

## What is included

- **External Shadow DB by default** — SQLite FTS5 and recursive-CTE subtree reads use
  a disposable per-graph cache outside `LOGSEQ_GRAPH_PATH`.
- **Strict Read Only protection** — `MATRYCA_READ_ONLY=true` blocks every graph-local
  mutation while preserving validated external derived-cache writes.
- **Markdown authority** — Shadow never becomes the source of truth and never replaces
  the parser-aware OCC-protected write plane.
- **Fail-closed routing** — disabled, bootstrapping, stale, schema-mismatched, or
  unhealthy Shadow states fall back to Markdown-backed BM25 reads.
- **Stable parser baseline** — `logseq-matryca-parser` 1.7.1.
- **Governed outcome and retrieval contracts** — provenance-bound, content-free
  evidence surfaces for later benchmark and memory work without enabling those future
  capabilities in the stable runtime.

## Deliberately out of scope

The following remain future work for v2.1.0 or later:

- biological memory recall, decay, and consolidation as a shipped runtime path;
- native Logseq DB writes or Safe-Sync through internal SQLite;
- content-aware Tana merge;
- proactive adaptive runtime behavior.

## Qualification and publication proof

| Gate | Result |
| --- | --- |
| RC observation window | Passed the seven-day cutoff after the public RC2 publication |
| Default-on Shadow profile | Terminal `PASS` on the exact public RC2 artifact |
| Read Only + external Shadow profile | Terminal `PASS` on the exact public RC2 artifact |
| Upgrade and rollback matrix | Terminal `PASS` across the published 1.14.5, 2.0.0a5, 2.0.0b1, and RC baselines |
| Cross-platform CI | Linux, macOS, and Windows Shadow contract checks passed |
| Stable candidate CI | PR #515 passed the required CI, CodeQL, dependency, and platform checks |
| Release workflow | Build, changelog extraction, GitHub Release, and PyPI publication passed |

The complete readiness decision is maintained in the
[v2.0.0 readiness record](../quality/issue-bodies/v2-rc-stable-readiness.md). Historical
RC1 and RC2 documents remain preserved as evidence for their exact artifacts and are
not silently rebound to the stable wheel.

## Artifact digests

The GitHub Release and PyPI expose the same verified artifacts:

| Artifact | SHA-256 |
| --- | --- |
| `matryca_plumber-2.0.0-py3-none-any.whl` | `d3247aa1f4c2ea802c0bd94b180df61fef8d3f1faf62e0f3b920e483f74c4653` |
| `matryca_plumber-2.0.0.tar.gz` | `42b5fd0e6b1af874e91d74ebd4ecc339127130ea52cca8bae82bb97185238266` |

The tag is an annotated Ed25519-signed tag created by Marco Porcellato and bound to
the exact release commit above. The publication workflow is
[run 32118732567](https://github.com/MarcoPorcellato/matryca-plumber/actions/runs/32118732567).

## Upgrade

```bash
uv tool install matryca-plumber==2.0.0
```

For an existing installation:

```bash
uv tool upgrade matryca-plumber
```

Before enabling graph writes or maintenance, work on a clone of the graph and review
the [Shadow DB operator contract](../knowledge/architecture/shadow-db.md). Operators
who need the legacy discovery path can set:

```bash
MATRYCA_SHADOW_DB_ENABLED=false
```

## Related documentation

- [Main README](../../README.md)
- [Changelog](../../CHANGELOG.md)
- [Shadow DB architecture and operator contract](../knowledge/architecture/shadow-db.md)
- [v2.0.0 readiness decision](../quality/issue-bodies/v2-rc-stable-readiness.md)
- [Release process](../RELEASE_PROCESS.md)