Skip to main content

graphmark

PyPI Python versions License

Deterministic knowledge-graph analysis for markdown / [[wikilink]] vaults — orphans, hubs, clusters, bridges, siloed notes, neighborhoods, PageRank, and link-gap suggestions over your notes, driven by a small config so it works on any Obsidian-family vault.

Structural outputs are pinned by a frozen differential oracle: they reproduce a proven reference implementation exactly, down to ordering and tie-breaking. See CLAUDE.md for the architecture and the reference-parity contract.

Install

pip install graphmark        # or: uv pip install graphmark

Runtime dependency: networkx only. The package ships a py.typed marker, so mypy and pyright see its annotations.

Quickstart

import graphmark

graph = graphmark.build("/path/to/vault")

print(graphmark.stats(graph))            # {'notes': 6, 'edges': 5, 'orphans': 2, ...}
print(graphmark.hubs(graph, n=10))       # [['brain/hub.md', 3], ...]
print(graphmark.orphans(graph, graphmark.VaultConfig(root="/path/to/vault")))

build() accepts a vault root (str or Path) or a fully configured VaultConfig. To drive it from a TOML file, pair it with load_config:

graph = graphmark.build(graphmark.load_config("vault.toml"))

CLI

Every command takes --config PATH (TOML) and/or --root PATH (vault root; overrides the config's root). Output is deterministic JSON on stdout (DOT for export dot); errors and warnings go to stderr, so stdout is always safe to pipe.

graphmark stats                          --root /path/to/vault
graphmark orphans                        --config vault.toml
graphmark hubs --n 10                    --root /path/to/vault
graphmark clusters                       --root /path/to/vault
graphmark bridges                        --root /path/to/vault
graphmark siloed                         --root /path/to/vault
graphmark neighborhood --note a/b.md --depth 2  --root /path/to/vault
graphmark pagerank --n 10 --alpha 0.85   --root /path/to/vault
graphmark export dot                     --root /path/to/vault > graph.dot
graphmark links                          --root /path/to/vault
graphmark check                          --config vault.toml

Exit codes: 0 success, 1 a check threshold breach, 2 a usage or config error. Nothing else uses 1, so CI can trust it.

$ graphmark --root /path/to/vault links
{"total": 6226, "counts": {"resolved": 6169, "ambiguous": 0, "non-note-file": 17, "out-of-scope-note": 0, "missing": 0, "intra-note": 40}, "alias_resolved": 23}
resolved 6169 · ambiguous 0 · non-note-file 17 · out-of-scope-note 0 · missing 0 · intra-note 40 · alias-resolved 23

JSON on stdout, the one-line summary on stderr, so the output stays pipeable.

Every wikilink lands in exactly one bucket and the buckets sum to total — nothing is silently dropped. All six reasons are always present, because a zero is a finding: the line above with missing 23 · alias-resolved 0 instead is what a real defect looked like before frontmatter aliases resolved, on the same vault with the same 6226 total. Reading the distribution is the fastest way to notice the tool is wrong about your vault.

The same block appears in check's report under links, as context for the verdict. It never changes the verdict.

graphmark reads [[wikilinks]] by default. A vault written in markdown link syntax — [text](note.md), what most non-Obsidian markdown gardens use — would otherwise produce an empty graph, so set link_syntax:

root = "."
link_syntax = "both"   # "wikilink" (default) | "markdown" | "both" | "markdown-autolinks"

The two resolve differently, and the difference is not cosmetic:

  • a wikilink names a note — [[Note]] finds Note.md anywhere in the vault, and two notes with that name make it ambiguous;
  • a markdown link is a path relative to the linking note — [x](../other/b.md) means that file and nothing else, so the same filename in two folders is not ambiguous at all.

markdown-autolinks is markdown with the mkdocs-autolinks plugin's rule for bare targets: [tdd](tdd.md) names a note anywhere in the tree, not a sibling file. Set it only if your site actually runs that plugin — it is never applied as a fallback, because a second rule tried after the first fails is how a link ends up pointing at a note it does not name. A target that contains / keeps the relative rule in this mode too.

If your links are in a syntax graphmark is not reading, it says so on stderr rather than reporting a confidently empty graph:

graphmark: warning: 39 wikilinks extracted but 10149 markdown-style [](.md) links found;
graphmark only reads [[wikilinks]] — this graph is probably not your vault

graphmark check — vault health as a CI gate

Declare thresholds in the config's [check] table, then run graphmark check as a build step. It exits non-zero when the vault drifts past them.

root = "."

[check]
max_orphans = 10
max_unresolved_links = 0
max_siloed = 3
$ graphmark check --config vault.toml
max_unresolved_links: 1 exceeds limit 0
  notes/decisions.md → [[datasheet]]
{"pass": false, "checks": [{"name": "max_orphans", "limit": 10, "actual": 2, "pass": true, "offenders": ["inbox/stray.md", "notes/scratch.md"]}, {"name": "max_unresolved_links", "limit": 0, "actual": 1, "pass": false, "offenders": [["notes/decisions.md", "datasheet"]]}, {"name": "max_siloed", "limit": 3, "actual": 0, "pass": true, "offenders": []}], "links": {"total": 512, "counts": {"resolved": 496, "ambiguous": 0, "non-note-file": 9, "out-of-scope-note": 2, "missing": 1, "intra-note": 4}, "alias_resolved": 6}}
$ echo $?
1

The JSON report is byte-stable — key order is fixed and checks appear in policy-declaration order — so two runs over an unchanged vault diff to nothing. Thresholds are inclusive (actual == limit passes), and only thresholds you set are reported. Every check lists its offenders (note paths for orphans and siloed notes, [source, target] pairs for unresolved links, one per occurrence), and actual is that list's length, so the count and the names cannot disagree. stderr prints each breach followed by its offenders, so a failing gate says what to fix.

Unknown keys inside [check] are a hard error rather than being ignored, and a config with no thresholds at all exits 2 instead of reporting a meaningless green: a gate that can't fail is worse than no gate.

Deprecated. The gap policy now lives in ragmark v0.2.0, in its ragmark.gaps module; install ragmark from that release page. That module is not a drop-in for graphmark.gaps(): ragmark.gaps.rank_pairs takes an injected similarity function as this section describes, while ragmark.gaps.gaps ranks against ragmark's own index. graphmark.gaps() and graphmark gaps are deprecated but still work: gaps() emits a DeprecationWarning on every call and returns exactly what it always did, and the CLI verb prints a deprecation line to stderr and still exits 2. The dismissal store below (weaklink_sig, record_dismissal, active_dismissed_sigs, load_dismissed) is unchanged.

gaps is library-first. graphmark owns the deterministic ranking and filtering — already-linked pairs, self-pairs, thresholds, prefix exclusions, dismissed pairs, reciprocal dedup, novelty-first ordering — while you supply the similarity source. No embeddings ship in this package, and the test gate stays free of them.

import graphmark

graph = graphmark.build("/path/to/vault")

def my_similarity(rel_path: str, k: int) -> list[tuple[str, float]]:
    """Return up to k (rel_path, score) pairs. Any embedding backend you like."""
    ...

# The band validated on a live ~340-note vault, as one keyword bundle.
suggestions = graphmark.gaps(graph, my_similarity, **graphmark.GAPS_DEFAULT_BAND)

GAPS_DEFAULT_BAND bundles threshold=0.6, max_score=0.92, k=8, hub_degree=40 (also available individually as GAPS_DEFAULT_THRESHOLD and friends). The Similarity protocol in graphmark.interfaces types the callable you inject.

Because the CLI has no similarity source to inject, graphmark gaps prints guidance (and the deprecation notice above) to stderr and exits 2 rather than silently returning [].

Dismissing a suggestion

dismiss is a content-hash store: a dismissed pair stays suppressed only while both notes still exist with unchanged content, so a rewrite re-opens the question.

Function Purpose
weaklink_sig(a, b) Stable, order-independent signature for a pair — the same one gaps() emits as sig
record_dismissal(root, a, b, *, path=...) Persist a dismissal, hashing both notes' current content
active_dismissed_sigs(root, *, path=...) The signatures still valid (both notes present, unchanged)
load_dismissed(root, *, path=...) Raw store contents; a corrupt store reads as empty, never raises
graphmark.record_dismissal(root, "a/one.md", "b/two.md")

# Feed the live set back in, and that pair stops being suggested.
suggestions = graphmark.gaps(
    graph, my_similarity,
    dismissed=graphmark.active_dismissed_sigs(root),
    **graphmark.GAPS_DEFAULT_BAND,
)

A signature has two formats. When neither path contains |, it is weaklink| plus the two paths, sorted and joined with |, with no escaping; this is the format existing stores already hold, so they stay valid. When either path contains |, it is weaklink2| plus the two paths escaped (\ becomes \\, then | becomes \|), sorted and joined with |, so a pipe in a path cannot make two different pairs collide. The prefixes differ, so the formats never overlap. active_dismissed_sigs recomputes each signature from the stored pair, so a pipe-path entry written before the second format existed is still honoured.

The store lives under the vault root at .claude/data/connect-dismissed.json; pass path= to put it elsewhere.

Other metrics

graphmark.pagerank(graph, n=10, alpha=0.85)   # importance ranking; matches networkx
graphmark.clusters(graph)                     # connected components, largest first
graphmark.bridges(graph)                      # articulation points
graphmark.siloed_notes(graph)                 # reachable only through a single bridge
graphmark.neighborhood(graph, "a/b.md", depth=2)
graphmark.to_dot(graph)                       # Graphviz DOT
graph.unresolved                              # {rel_path: [broken link displays]}
graph.catalog                                 # {normalized stem: [rel_paths]} — 2+ means ambiguous
graph.out_of_scope                            # same, for markdown outside the configured scope
graph.aliases                                 # {normalized alias: rel_path} — frontmatter aliases
graph.link_counts                             # {reason: occurrences} — every link, one bucket each
graph.alias_resolved                          # how many resolutions came via an alias

link_counts accounts for every display the extractor produced, one bucket each, and always carries all six DIAGNOSIS_REASONS — a zero is a finding, not a non-event. The buckets sum to the extraction count, so nothing is silently dropped. Reading the distribution is the fastest way to notice the tool is wrong about your vault:

resolved 6169 · ambiguous 0 · non-note-file 17 · out-of-scope-note 0 · missing 0 · intra-note 40 · alias-resolved 23

versus the same vault with alias resolution disabled — the shape of a real defect that once shipped:

resolved 6146 · ... · missing 23 · ... · alias-resolved 0

Same total, 23 links in the wrong bucket.

catalog and out_of_scope are the resolution state the build consulted. They are what you need to explain a link rather than just resolve it — which notes a bare [[link]] collided with, or whether a link that failed to resolve points at a real file you deliberately excluded. Value lists are sorted by rel_path.

graph.unresolved conflates two different problems. A link that matched nothing needs its target created or deleted; a link that matched too much needs disambiguating against the notes it collided with. diagnose separates them, and names the three cases that are not broken at all.

d = graphmark.diagnose(graph, "2026-W27-tasks|W27 tasks")

d.reason      # 'ambiguous'
d.candidates  # ('personal/archive/tasks/2026-W27-tasks.md', 'work/archive/2026/tasks/2026-W27-tasks.md')
d.target      # None — set only when reason == 'resolved'
d.display     # echoed verbatim: what a human has to go and fix
reason meaning candidates
resolved names exactly one note; target is its rel_path —
ambiguous names several notes, so the resolver refused to pick the colliding notes
non-note-file targets a .canvas / .base / image / PDF — not indexed here —
out-of-scope-note targets real markdown outside the configured scope the unindexed paths
missing names nothing that exists — a genuine broken link —
intra-note [[#Heading]] / [[#^block]] — a same-note reference —

DIAGNOSIS_REASONS holds that set in decision order, so a consumer can switch on it exhaustively. Alias, anchor and .md forms all diagnose identically to the bare form.

VaultGraph.build classifies its own links through this same function, so a diagnosis can never contradict the graph it describes: unresolved is exactly the displays diagnosing as ambiguous or missing, and the edges are exactly the resolved non-self targets.

Near-miss suggestions

Pass suggest=k to turn a missing verdict into an actionable one. Suggestions are computed only for missing — every other reason already carries the rel_paths in play — so the default of 0 costs nothing on the check hot path.

graphmark.diagnose(graph, "Jordan", suggest=5).candidates
# ('people/Jordan Ellis.md',)

Matching is directional, which is what separates a suggestion from a wrong answer:

  • a display inside a candidate name is an abbreviation — [[Jordan]] → Jordan Ellis, or [[Mood Tracker]] → 2026-04-11-mood-tracker (pure-digit tokens are filing metadata, not content);
  • a candidate inside a display is offered only when it covers at least SUGGEST_MIN_COVERAGE of it — [[fable-prompt-technique-reference]] → fable-prompt-technique is the answer, while [[Dagster PJM InSchedules]] → Dagster is a real note that is not the target;
  • partial overlap in neither direction is rejected;
  • a display matching more than SUGGEST_MAX_MATCHES notes names a topic, not a typo, and gets nothing at all.

Notes whose stem is generic (SKILL.md, README.md) are matched on their parent folder, where their name actually lives.

Both constants were calibrated against a human-annotated baseline of a real vault's broken links rather than chosen by taste — see tests/fixtures/suggest/README.md for the method and the measured result.

Frontmatter aliases

Obsidian's aliases: property declares additional real names for a note, so links written against one resolve like any other link. Block, inline and scalar forms all work:

---
aliases:
  - Mood Tracker
  - mood-tracker
---

[[Mood Tracker]] now resolves to 2026-04-11-mood-tracker.md and produces a real edge. On a 521-note vault this was the difference between 23 reported broken links and 0 — every one of the 23 a false positive, plus 17 edges that were silently missing.

Three rules keep it conservative:

  • A real note name always wins. An alias can never hijack a link to a note that actually bears that name.
  • An alias that collides with any real note name is dropped entirely — not merely outranked, so an already-ambiguous basename can't be rescued into resolving by someone's alias.
  • An alias claimed by two notes resolves to nothing, the same refusal applied to colliding basenames.

Set resolve_aliases = false for strict basename-only resolution. graph.aliases exposes the resolved map.

Configuration

root = "."                                    # required unless --root is passed
resolve_aliases = true                        # resolve frontmatter aliases: (default true)
scoped_folders = ["brain", "work"]            # limit the vault to these top-level folders
excluded_dirs = [".git", "templates"]         # skip notes under these directories
rules_files = ["CLAUDE.md", "CLAUDE.local.md"]  # agent-rules files, not vault content
transient_prefixes = ["daily/"]               # excluded from orphan reports

Unknown top-level keys are ignored; unknown keys inside [check] are an error.

Development & releases

Two long-lived branches: dev is the integration branch (open PRs against it); main is the release branch. Both are gated by CI — ruff check + ruff format --check + pytest -q on Ubuntu and macOS across Python 3.11, 3.12, and 3.13.

uv pip install -e ".[dev]"
uv run --extra dev ruff check . && uv run --extra dev ruff format --check . && uv run --extra dev pytest -q

Releases are automated by conventional commits. When dev is promoted to main, .github/workflows/release.yml runs python-semantic-release: it reads the commit history since the last tag, bumps the version, updates CHANGELOG.md, tags v<version>, cuts a GitHub release, and publishes to PyPI via OIDC Trusted Publishing. So the version is a function of your commit messages — feat: bumps the minor, fix:/perf: the patch (pre-1.0, breaking changes bump the minor, not the major). No manual version edits, no tokens.

Metadata

Release files for graphmark 0.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for graphmark 0.11.0
File Size Uploaded Provenance Actions
graphmark-0.11.0.tar.gz 236.0 kB Without provenance Details for graphmark-0.11.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for graphmark 0.11.0
File Interpreter ABI Platform Actions
graphmark-0.11.0-py3-none-any.whl Python 3 none any Details for graphmark-0.11.0-py3-none-any.whl

Total release size: 289.1 kB

Release files / graphmark-0.11.0.tar.gz

Download URL graphmark-0.11.0.tar.gz
Size 236.0 kB
Tags Source
SHA-256 checksum
How to use checksums
20d91fd8b5977c4c350eb3c920b89d2af496f28fb0f64ff9ca610e7d02bd5dd5
BLAKE2b-256 checksum
How to use checksums
95bd4f8de498776da4ccfbf398640c3082a8bc99d60c0ecf52753b570f7e9984
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / graphmark-0.11.0-py3-none-any.whl

Download URL graphmark-0.11.0-py3-none-any.whl
Size 53.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1856929a0fb66f42ed46f34385f88adbb1c5e4dc68aa668f4f041c5b83ab0d97
BLAKE2b-256 checksum
How to use checksums
6f51cfc3a93091da62834fffd66ca0413ccf1eec1384ad4bb35637f51584fde1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for graphmark 0.11.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page