percolate-kb

Percolate concepts and relationships

Keep the graph authored, local, and reviewable. kb percolate proposes candidates from deterministic evidence; it never changes a note. Backlinks, graph reports, and QMD results are derived views, while Markdown remains the authority.

Locate the vault

• Resolve <vault> to the directory containing its authored or managed index.md front door.
• Read the applicable repository and vault instructions before editing.
• Pass the resolved path to every --root.
• Identify the note or small neighborhood changed by the current task. Prefer a bounded review to a vault-wide cleanup during parallel work.

Inspect candidates

Run percolation on the changed note when possible:

kb percolate notes/example --root "$KB_ROOT" --limit 25 --json

Run it without a note only when reviewing the whole vault:

kb percolate --root "$KB_ROOT" --min-support 2 --limit 50 --json

Treat each result as a prompt to open the cited notes and read the relevant prose. Candidate kinds may include:

• a recurring tag with no maintained type: concept note;
• notes that share a concept or tag but have no explicit relationship;
• an exact title or alias mentioned without a contextual link;
• a self, reciprocal, malformed, broken, or ambiguous authored relationship.

For missing relationships, support counts independent shared tags or concept neighbors; the evidence array shows the participating notes. The default minimum of two therefore requires two shared signals, not merely both endpoints of one tag match. Other candidate kinds count their natural unit: supporting notes, mention occurrences, or authored hygiene evidence.

For a missing concept, use suggestedId. When collidesWith is non-null, the natural ID is already an ordinary note, so KB chooses an unoccupied *-concept ID. Read the occupied note before deciding whether to create the suggested concept or promote and improve the existing note instead.

Semantic search may help discover evidence, but similarity is never enough to author an edge.