zettel-builder

zettel-builder is a Python tool for turning raw reading material into a network of short, atomic note cards that can eventually be assembled into articles. It is designed to run inside AI coding assistants such as Claude Code, OpenClaw, Codex, or Hermes as an installable skill, meaning you invoke it through slash commands rather than running it as a standalone program.

The core idea comes from the Zettelkasten method, a note-taking philosophy where each card captures a single idea that can stand alone even months later without needing its surrounding context. zettel-builder adds a required step on top of that: after splitting source material into cards, an AI agent must write a brief value judgment on each one, recording whether the author agrees, disagrees, or partially agrees with the idea and where the boundaries of that position lie. Cards without this judgment are considered unfinished.

The tool provides four main commands. The ingest command takes a piece of source material and produces a batch of atomic cards, each with a value-realignment note and a list of candidate links to existing cards. The scan command works through a queue folder of accumulated material in one pass. The inspect command reviews the entire card pool to find clusters that are dense and varied enough to become an article, flagging orphan cards and gaps in coverage and optionally sending a Telegram notification when a cluster is ready. The write command takes a cluster and arranges it into a draft outline that can then be handed off to a separate writing skill.

Linking between cards is handled by a combination of embedding-based recall (using fastembed with a lightweight Chinese-language model by default) and a TF-IDF fallback, but the final decision on whether two cards are genuinely connected is always made by the AI agent reading the full card text, not by a similarity threshold alone. The author describes this as intentionally expensive but necessary for accuracy.

The repository ships with a voice-snapshot template that users must fill in with their own values and style rules before the value-realignment step works as intended. Scripts for embedding, clustering, and link candidates are included. The license is MIT.