Skip to main content

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.md for 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)

Source distribution for graphmark 0.2.0
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)

Table of built distributions (wheels) for graphmark 0.2.0
File Interpreter ABI Platform Actions
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.

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