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.
Status: v0.1.1 on PyPI. The engine is complete and pinned by a frozen differential oracle — structural outputs reproduce a proven reference implementation exactly (shape, ordering, tie-breaking). See
CLAUDE.mdfor the architecture and the reference-parity contract.
Install
pip install graphmark # or: uv pip install graphmark
Dev setup:
uv pip install -e ".[dev]"
Test
uv run --extra dev ruff check . && uv run --extra dev ruff format --check . && uv run --extra dev pytest -q
CLI
Every command takes --config PATH (TOML) and/or --root PATH (vault root; overrides the config's
root). Output is deterministic JSON (DOT for export dot).
graphmark stats --root /path/to/vault
graphmark orphans --config configs/my-brain.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 gaps --root /path/to/vault
Note: gaps is a library-first metric — it ranks and filters link-gap candidates over a
similarity function you inject (metrics.gaps(graph, similar_fn, ...)); the package itself ships no
embeddings. The CLI subcommand has no similarity source to inject, so graphmark gaps prints
guidance to stderr and exits 2 rather than silently returning []; use the library API (below).
Library
from pathlib import Path
from graphmark.config import VaultConfig
from graphmark.graph import NormalizeResolver, VaultGraph
from graphmark.metrics import gaps, hubs, stats
from graphmark.parse import WikilinkExtractor
config = VaultConfig(root=Path("/path/to/vault"))
graph = VaultGraph.build(config, WikilinkExtractor(), NormalizeResolver())
print(stats(graph))
print(hubs(graph, n=10))
# gaps: you supply similarity — graphmark owns the deterministic ranking/filtering.
print(gaps(graph, similar_fn=my_similarity, threshold=0.6, k=8))
dismiss.py provides a content-hash dismissal store for gap suggestions: a dismissed pair stays
suppressed only while both notes exist with unchanged content.
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).
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.2.0
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.2.0.tar.gz | 34.2 kB | Without provenance | Details for graphmark-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| graphmark-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for graphmark-0.2.0-py3-none-any.whl |
Total release size: 50.4 kB
Release files / graphmark-0.2.0.tar.gz
| Download URL | graphmark-0.2.0.tar.gz |
|---|---|
| Size | 34.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a026e2170a89e112adc9abc62a5a184c308aa9ead915436ff4c8ad24f610a3f2
|
|
BLAKE2b-256 checksum How to use checksums |
a761c9950ce38827b83e814147df8b7dd81f7b1380b44f05f0372c451c5e0c1f
|
| 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.2.0-py3-none-any.whl
| Download URL | graphmark-0.2.0-py3-none-any.whl |
|---|---|
| Size | 16.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
34900f5a0d99fe70acdd4ffe30909d7f104881e6fc841abd805c824586b1cf69
|
|
BLAKE2b-256 checksum How to use checksums |
afa747f64db09f5739da851889a1e32fa01761778e924d9989f3b035a5f722e0
|
| 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.2.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.