witt3rd/zk-memory/zettelkasten-maintenance

zettelkasten-maintenance

Repo AGENTS.md is the contract. This file is the maintenance surface.

Link integrity — tend

zk-memory --root <root> tend check
zk-memory --root <root> tend mint --write
zk-memory --root <root> tend repair --write
zk-memory --root <root> tend robustify --write

Dry-run without --write. Actions: check / repair / mint / robustify. tend walks up from the corpus root to find linlink.toml. linlink is the tool; darnlink is the old name.

Gardener — tend-writes (needs an LLM)

Reconciles recent writes (by mtime): fold a duplicate into an existing note (append-only) and retire the original to <root>/.archive/ (reversible, never deleted), or append out-links. decision notes never merge. Capture fast, integrate later.

De-merge — split (needs an LLM)

split_note is the inverse of merge: summary parent + atomic children, original retired to .archive/. Not the authoring "branch a new sibling and keep the old note." split-candidates is a mechanical size sweep (no LLM). tend-writes --split-sweep N may split only notes that sweep listed.

Sidecar

Everything planted besides notes lives under <root>/.zk/ (lock, FTS index, vector pin, ingest, trace). Never beside the corpus in the parent. Retired notes: <root>/.archive/.

Vector pin

<root>/.zk/index/vector/meta.json records model + dims. A later search with a different embedder raises EmbedderMismatch unless --rebuild-index. The index is derived and rebuildable. Committing it is a corpus policy (embeddings cost money), not a library rule.

CLI embedder is injected, not a backend string:

zk-memory --root <root> --embed-model <id> --embed-base <url> --embed-key <key> search "…"

Env: ZK_MEMORY_EMBED_MODEL / ZK_MEMORY_EMBED_BASE / ZK_MEMORY_EMBED_KEY. Any OpenAI-compatible /embeddings endpoint.

Ingest vs maintenance

ingest skips any source path whose components start with . (so .meta/ never inventories). That is an ingest limitation, not a tend rule — write those notes with write / merge. See the ingest skill.