VaultKG v0.5.0

Release Notes -- v0.5.0

Released: 2026-10-14

VaultKG can now bring source documents into a vault. vaultkg add converts a
PDF, an office document, a LaTeX or HTML file, or a Markdown or text file into
a note under the vault's sources folder, with a record of exactly where it
came from, ready for a person or an agent to write wiki pages from.

What changed

vaultkg add. Give it files or folders and a --kind (for example
articles or documents). Each file becomes RAW/<kind>/<slug>.md, with
frontmatter that records the source's path, its SHA-256, the converter and
version that produced the text, when it was added, its title and its word
count. The original is copied beside it under files/. Conversion uses the
fleet's shared converters: pymupdf4llm for PDF, anydoc for office
formats, and pandoc, when installed, for LaTeX and HTML.

Collisions are decided by content. Adding the same file again does
nothing. Adding a different file under a name that is already taken writes
nothing and exits with an error; --prefix keeps the two apart. Notes made
before this release, which carry no recorded hash, are matched through their
copied original. A scanned PDF or a file pandoc cannot read is reported as
failed, never written as an empty note.

The graph is untouched. add only places sources; run vaultkg build
afterwards. No model is involved, so the same files always produce the same
notes.

A configurable sources folder. raw_dir in .vaultkg/config.yaml sets
where add writes (default RAW).

Upgrading

uv tool install --force --refresh "vault-kg[semantic,viz,viz3d,ingest]==0.5.0"

vaultkg add needs the new ingest extra. Nothing else changes.

---

Full changelog: CHANGELOG.md

VaultKG v0.4.0

Release Notes -- v0.4.0

Released: 2026-10-14

Rebuilding a vault after an edit is now quick. vaultkg build still rebuilds
the whole graph from the notes on disk, but it re-embeds only the notes and
sections whose text changed instead of every note.

What changed

Incremental embedding. vaultkg build calls the SDK's new
KGModule.sync(). Each note and section's index text is compared with what
was embedded last time; only new or changed text is embedded, and the vectors
of deleted notes are removed. The graph itself is rebuilt in full, so the
same vault still always gives the same graph. On a 310-note vault, an
unchanged rebuild took 2.8 seconds and embedded nothing, against 8.2 seconds
for the first build.

--full for the old behavior. vaultkg build --full re-embeds every note,
as every build did before. The first build of a vault, and the first after a
--full build, embeds everything once either way.

Current SDK. VaultKG now requires kgmodule-utils 0.27.0, which provides
sync().

Upgrading

uv tool install --force --refresh "vault-kg[semantic,viz,viz3d]==0.4.0"

Nothing else changes. The next vaultkg build embeds everything once while
it records what it embedded; builds after that are incremental.

---

Full changelog: CHANGELOG.md

VaultKG v0.3.0

Release Notes -- v0.3.0

Released: 2026-10-14

This release lets a vault remember what to leave out. Build excludes now live
in the vault, in .vaultkg/config.yaml, and every way of building or serving
the graph reads them: the vaultkg CLI, the MCP server, viz3d and the
KGRAG adapter. A private folder listed there stays out of the graph no matter
which tool builds it.

What changed

Persistent build config. Create <vault>/.vaultkg/config.yaml with an
exclude list of folder names or globs, the same values --exclude takes.
VaultKG reads it when it is constructed, so a plain vaultkg build uses
it with no flags. --exclude still works and adds to the stored list for
that one build. A file that is not a mapping, has an unknown key, or has a
malformed list is an error rather than being silently ignored.

Why it matters. VaultKG does not read .gitignore. Before this release,
excludes existed only as command-line flags, so a build run without them
indexed every folder, including gitignored ones. In a real vault that put a
folder of private notes into the graph, and the MCP server then served them.
Keeping the list in the vault closes that gap for every entry point at once.

Current fleet dependencies. VaultKG now requires kgmodule-utils 0.26.0
and, for the 3-D views, quiltwright 0.16.0.

Upgrading

uv tool install --force "vault-kg[semantic]==0.3.0"   # or: pip install -U vault-kg

Nothing changes until you add a config file; existing --exclude flags keep
working. To make your excludes permanent:

# <vault>/.vaultkg/config.yaml
exclude:
  - templates
  - _inbox

The file is safe to commit; only the .sqlite files in .vaultkg/ need
ignoring. Rebuild once after adding it.

---

Full changelog: CHANGELOG.md

VaultKG v0.2.0

Release Notes -- v0.2.0

Released: 2026-09-22

This release makes the vault's structure easier to read at a glance. In the
3-D tree, a note's leaf now grows with the number of notes that link to it,
so the hubs of a vault stand out without reading a label. In the 2-D link
graph, relations move off the canvas and onto hover, which keeps a note's
neighbourhood legible when nearly every edge is a plain link.

What changed

Leaves sized by backlinks. vaultkg quilt and vaultkg viz3d size each
leaf by its note's backlinks: an unlinked note is 0.6 times the base size,
one backlink is 1.0 times, and hubs grow with the square root of their count
up to 2.5 times. --size-by none draws every leaf one size. Both the organic
and the schematic renders honour it.

Edge labels on hover. vaultkg viz no longer prints each relation across
the canvas; it shows it on hover and in the edge colour. --edge-labels
prints them all again.

A newer SDK. VaultKG now requires kgmodule-utils 0.24.0, which added both
rendering options and a way to drop a stale vector index. vaultkg build --no-index removes an index from an earlier build through the SDK rather
than deleting the files itself; what it does is unchanged.

Upgrading

uv tool upgrade vault-kg --reinstall

No rebuild is needed; existing .vaultkg/ stores work as they are. To keep
the previous look, pass --size-by none to quilt and viz3d and
--edge-labels to viz. KGRAG federates vaults from kg-rag 0.17.0, with the
kg-rag[vault] extra.

---

Full changelog: CHANGELOG.md

VaultKG v0.1.0

Release Notes -- v0.1.0

Released: 2026-09-22

VaultKG turns an Obsidian-style Markdown vault into a knowledge graph built
from the links its author wrote. Notes, sections, tags and attachments become
nodes; wikilinks, embeds, tags and typed links such as supports:: [[X]]
become edges. Nothing is extracted by a language model, so the same vault
always builds the same graph, and every edge can be traced to the line it
was written on. This first release covers building, searching, analysing and
viewing a vault, and serving it to agents.

What's in it

A graph that follows Obsidian's rules. Links resolve the way Obsidian
resolves them: by path, then by file name, then by alias, with section
anchors pointing at the heading and ambiguous matches flagged rather than
guessed. Typed links, from Dataview inline fields or frontmatter keys, keep
their own relation names, so a vault's own vocabulary (SUPPORTS,
CONTRADICTS, UP) becomes part of the graph.

Search that stays grounded. vaultkg query uses embeddings only to find
where to start, then follows stored links from there; vaultkg pack returns
the matching notes and sections with their paths and line numbers, ready to
hand to a model. vaultkg links answers what a note links to and what links
back to it, section links included.

The vault's structure, measured. vaultkg analyze reports hubs, bridges,
wanted pages, orphans and islands from the graph alone, and snapshots record
those figures so you can compare a vault's shape over time.

Views. vaultkg viz writes the link graph as one interactive HTML page,
with notes sized by backlinks and coloured by folder. vaultkg quilt and
vaultkg viz3d grow the vault as a 3-D tree, its folders as limbs and its
notes as leaves, for the screen or a Looking Glass display.

For agents. vaultkg-mcp serves a vault to Claude Code, Cursor or any
MCP client, with bounded, validated arguments. KGRAG can federate a vault
with code, documents and its other knowledge graphs through its vault
kind, which ships in KGRAG's next release.

Installing

uv tool install "vault-kg[semantic,viz,viz3d]"
vaultkg build --vault ~/brain

The core install builds, analyses and serves a vault. The semantic extra
adds search, viz the link graph, and viz3d the 3-D views. The
documentation is at https://flux-frontiers.github.io/vault_kg/.

---

Full changelog: CHANGELOG.md