graphmark
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 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 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_orphans: 14 exceeds limit 10
{"pass": false, "checks": [{"name": "max_orphans", "limit": 10, "actual": 14, "pass": false}, {"name": "max_unresolved_links", "limit": 0, "actual": 0, "pass": true}]}
$ 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.
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.
gaps — link suggestions with injected similarity
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 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,
)
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]}
Configuration
root = "." # required unless --root is passed
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.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| graphmark-0.3.1.tar.gz | 72.0 kB | Without provenance | Details for graphmark-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| graphmark-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for graphmark-0.3.1-py3-none-any.whl |
Total release size: 96.3 kB
Release files / graphmark-0.3.1.tar.gz
| Download URL | graphmark-0.3.1.tar.gz |
|---|---|
| Size | 72.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
efa392a983718f75b7ad92c6b0ae9ab8645c5f3b29428e749d6672e382fcda47
|
|
BLAKE2b-256 checksum How to use checksums |
99f7f058547ff10d991e1ae696df2f1b30db5b8067aef898e84f6913d507359d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","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.3.1-py3-none-any.whl
| Download URL | graphmark-0.3.1-py3-none-any.whl |
|---|---|
| Size | 24.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5412c8bd410d2a3b56e2e115a03b3836b136ec842a7ead47b76e16eae47625a3
|
|
BLAKE2b-256 checksum How to use checksums |
7adabba48c2cb7d8dc6f11afed754c84633dfa9e1db0b0b4282064b91490ddf2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","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.3.1
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.