Quickstart

Install the package and scan a Logseq graph:

uv pip install logseq-matryca-parser
matryca-parse scan /path/to/logseq/graph

The scan reports pages, blocks, references, and graph diagnostics without changing the vault. Continue with the CLI and Python examples, or use the Cookbook for RAG, graph-query, watcher, and agent recipes.

Parsing and scanning are read-only. Source-vault writes are explicit, opt-in, confined, and reviewable; exporters write derived artifacts to destinations selected by the caller.

Choose your workflow

• Parse and query: load one page or a complete vault as a typed AST and graph.
• Build RAG context: export LangChain documents, LlamaIndex nodes, or enriched chunks.
• Move knowledge: generate JSON, clean Markdown, or an Obsidian vault.
• Visualize: render an interactive reference-topology graph with the transitional, feature-frozen LENS adapter.
• Use an AI agent: start from AGENTS.md or the concise llms.txt index.

🌐 The Vision: Virtual Centralization vs. Binary Lock-in

The PKM (Personal Knowledge Management) world is currently forcing users to make a painful choice between Data Longevity and AI Power.

• Vanilla Logseq / Obsidian is a "Forest" of decentralized Markdown files. It guarantees the Lindy effect (plain-text lasts forever) and perfect Git versioning, but standard AI chunkers treat it like a blender, destroying the outliner hierarchy.
• Tana is a centralized "Tree". It offers incredible semantic power, but traps your brain in a proprietary cloud database.
• The new Logseq DB (SQLite) uses a local database and provides official export paths. Its primary working state is not line-diffable Markdown, however, and the semantic fidelity of exported Markdown remains a separate interoperability question. Matryca does not currently claim to read or replace Logseq DB graphs.

🔱 The Matryca Solution: The Best of Both Worlds

Logseq Matryca Parser is the ultimate bridge. It allows you to keep your sovereign, future-proof Markdown files, while synthesizing a Virtual Global Graph in RAM at runtime.

It acts as the strict File System Driver for your LLM OS. By using a deterministic Stack-Machine to parse your outliner topology, it feeds LangChain or LlamaIndex with the exact parent-child context of every single block.

You get the reasoning power of a centralized relational database, without sacrificing the plain-text soul of your Second Brain in Logseq.

⚖️ The PKM Landscape

🧭 Matryca vs. naive framework loaders

🚀 The Problem

Standard RAG pipelines treat your notes like a blender. They chop Markdown into random shards, destroying the parent-child hierarchy that makes Logseq powerful.

graph TD
    Raw[(Logseq Markdown\nFiles)]

    subgraph Standard RAG
        Blender[Standard Text Splitter\n'The Blender']
        Chunk1[Chunk 1: Orphan text]
        Chunk2[Chunk 2: Lost context]
        Blender --> Chunk1 & Chunk2
    end

    subgraph Matryca Parser
        Architect[Logos Engine\nStack-Machine]
        Parent[Parent Node\n+ Properties]
        Child[Child Node\n+ Task State & Time]
        Architect --> Parent --> Child
    end

    Raw --> Blender
    Raw --> Architect

    classDef bad fill:#fee2e2,stroke:#ef4444,color:#000;
    classDef good fill:#dcfce7,stroke:#22c55e,color:#000;
    class Chunk1,Chunk2 bad;
    class Parent,Child good;

🔱 The Solution

Logseq Matryca Parser is a deterministic Stack-Machine engine that acts as the File System Driver for your LLM. It preserves the true topology of your thoughts, ensuring AI understands spatial hierarchy, time, and block-lineage—including structured task state and first-class temporal attributes you can query in downstream graph databases and GraphRAG engines without re-parsing raw Markdown.

🏗️ Core capabilities

The base parser is local-first and has zero telemetry. Optional AI, watcher, and visualization dependencies remain lazy. See the architecture and API stability reference for exact boundaries. For cross-product Logseq OG use, Plumber is the gateway to Trama and Brain; Parser remains the deterministic parsing stage. LENS stays compatible while a future Trama graph-intelligence migration is separately designed and released. Stage 0 marks LENS as transitional and feature-frozen: GraphVisualizer, matryca-parse visualize, and matryca-parse demo remain available without a deprecation warning. Matryca Trama is the destination for future user-facing graph intelligence.

Data model — LogseqNode task fields

Each AST block is a LogseqNode. Alongside task_status, the parser surfaces priority and schedule metadata as typed fields (epoch integers are seconds since Unix epoch, UTC):

{
  "uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "task_status": "TODO",
  "task_priority": "A",
  "scheduled_at": 1641600000,
  "deadline_at": 1641772800,
  "clean_text": "Cut v0.3.2 release"
}

Marker syntax ([#A], SCHEDULED: <...>, DEADLINE: <...>) is stripped from clean_text so embeddings stay clean; the promoted fields carry the structured signal for downstream graph databases and GraphRAG engines.

Usage

# Optional: filesystem watcher for live incremental graph updates
uv pip install 'logseq-matryca-parser[watch]'

# Or clone and sync all extras locally
uv sync --all-extras

# 1. Visualize your local graph (LENS: transitional, feature-frozen)
matryca-parse visualize /path/to/logseq/graph my-map.html

# 2. Export for AI / RAG (SYNAPSE)
matryca-parse export /path/to/logseq/graph output --format langchain

# 3. Context-enriched LangChain JSON (graph + inheritance + embed expansion)
matryca-parse export /path/to/logseq/graph output --format langchain-enriched

# 4. Obsidian vault (YAML frontmatter + ^ block ids)
matryca-parse export /path/to/logseq/graph output --format obsidian

# Global options (all subcommands): --verbose, --graph /path/to/vault
matryca-parse --graph /path/to/logseq/graph --verbose export output --format json

Python API

Prefer the package root for stable imports (see __all__ in logseq_matryca_parser):

from logseq_matryca_parser import (
    LogseqGraph,
    LogosParser,
    SynapseAdapter,
    SessionAliasRegistry,
    discover_graph_files,
)

# Parse a single page to AST (YAML or native frontmatter; utf-8-sig BOM-safe)
page = LogosParser().parse_page_file("page.md")
if page.root_nodes[0].assets:
    absolute = page.resolve_asset_path(page.root_nodes[0].assets[0])

# Load the whole vault (pages, backlinks, node registry)
graph = LogseqGraph.load_directory("/path/to/logseq/graph")
page_obj = graph.get_page("My Page")  # case-insensitive
effective = graph.get_effective_properties(page_obj.root_nodes[0].uuid)

# Build the same in-memory indexes from caller-captured Markdown without filesystem access.
from logseq_matryca_parser import SnapshotPage

snapshot_graph = LogseqGraph.from_snapshot_pages(
    "/path/to/logseq/graph",
    [SnapshotPage("pages/Project.md", "- Captured block\n")],
)

# Export to LangChain with lineage metadata
docs = SynapseAdapter.to_langchain_documents(page.root_nodes, source_name=page.title)

# Optional strict same-page block-ref validation at parse time
from logseq_matryca_parser import StackMachineParser

strict_page = StackMachineParser(strict_refs=True).parse_page_file("page.md")

🤖 Agentic Write Access (Append-Only)

Agents such as Hermes or OpenClaw can record structured notes into a Logseq graph without rewriting existing pages. The helper logseq_agent_write only opens the weekly agent page in append mode ("a"), writes a new bullet (journal link + optional tag links + body), and never truncates or replaces prior content—so routine logging cannot wipe blocks that already live in that file.

Point it at your graph’s pages directory and config.edn so journal titles match Logseq’s :journal/page-title-format (including ordinal days when you use do in the pattern).

from logseq_matryca_parser import logseq_agent_write

result = logseq_agent_write(
    "Summarized user intent and proposed next steps.",
    config_path="/path/to/logseq/config.edn",
    pages_dir="/path/to/logseq/pages",
    context_tags=["agent/hermes", "#session"],
)
assert result["status"] == "success"
# result["path"] → e.g. .../pages/2026-18-agent.md

🗺️ Roadmap

• Graph-intelligence UI: A future Matryca Trama surface may succeed the compatible Parser LENS workflow after a separately reviewed migration; Parser does not commit to a standalone GUI. (Track the historical RFC)
• Obsidian Adapter: Native CLI export (--format obsidian) with YAML frontmatter and ^ block anchors.
• Ollama Integration: One-click local RAG setup. (RFC draft) · (Track progress #34)

☕ Support & Enterprise

Logseq Matryca Parser is open-source. If it powers your pipeline, consider a star ⭐ or a sponsorship!

💖 Sponsor me on GitHub

Need custom RAG integrations or consulting? Contact: marco@marcoporcellato.it

🤝 Contributing & Community

We welcome issues, pull requests, and constructive feedback.

📦 Release history

Read the complete release highlights, the exhaustive changelog, or the signed artifacts on GitHub Releases.

• v1.9.0 — Adds the stable in-memory snapshot graph factory, clarifies the Parser-Plumber boundary, and governs the temporary optional-NLTK advisory exception.
• v1.8.2 — Adds SHA-pinned hosted assurance, portable Windows local assurance, corrected cookbook recipes, consistent optional-AI guidance, and Path | str graph loading.
• v1.8.1 — Hardened deep-outline parsing, coherent incremental graph mutations, bounded assurance cleanup, and stable provenance for optional NLTK.
• v1.8.0 — Added bounded privacy-safe local graph assurance, source-location contracts, and the first internal parser line-classification phase.
• v1.7.1 — Added the runnable offline SYNAPSE RAG example and tightened release-note and optional-dependency security checks.
• v1.7.0 — Hardened parser correctness, graph diagnostics, writer safety, API stability, documentation governance, and release provenance.
• v1.6.0 — Clean Architecture v1 structural slices, new public graph APIs, layer-boundary CI, and documentation SSOT.
• v1.5.0 — Added opt-in CLI detection of unresolved block references for vault and CI hygiene.
• v1.4.2 — Fixed agent-write newline handling, controlled corrupt-state failures, and cyclic SYNAPSE page embeds.
• v1.4.1 — Expanded contributor tests and refreshed the good-first-issue onboarding path.
• v1.4.0 — Strengthened graph integrity, live reloads, serialization, path safety, strict references, and parser edge cases.
• v1.3.1 — Aligned examples and skill installation instructions with the repository's uv workflow.
• v1.3.0 — Expanded the stable API and improved graph reloads, strict references, SYNAPSE metadata, CLI behavior, and optional imports.
• v1.2.2 — Restored CodeQL workflow reliability and documented its supported configuration.
• v1.2.1 — Added the Python 3.12/3.13 CI matrix, security gates, release pre-flight, and contributor infrastructure.
• v1.2.0 — Added graph parity, assets, round-trip serialization, Obsidian export, live watching, agent X-Ray mode, and headless writes.
• v1.1.1 — Established title and alias indexing, backlinks, incremental reload, parser shields, property parsing, and broader task markers.

Architected by Marco Porcellato | Powered by Matryca.ai