AGENTS.md

Entry point for Codex, and for any agent that reads AGENTS.md rather than CLAUDE.md. Claude Code reads the same rules through notes.md and .claude/.

This folder is a vault: durable markdown notes plus the engine that searches and indexes them. Nothing here loads on its own. Fetching context is your job, and so is putting it back.

Before you read or write a note

Read notes.md. It is the full convention: the five folders and what each one holds, frontmatter, linking rules, how to decide between editing an existing note and adding one, and when writing nothing is the right outcome. The rest of this file is the mechanical layer.

Search first, always

python3 .scripts/notes.py -m "the question you actually have"

Ask in your own words. The ranking fuses BM25 with local embeddings, so a plain question works and does not need the vault's jargon. -m returns one line per note: score, last-updated, path, description, and the body line that earned the hit. Twenty rows is roughly 1,400 tokens, cheap enough to search several times before writing.

Each ranker fails at what the other is for. BM25 cannot find am i well positioned for this, because that query and the note answering it share no word. Embeddings cannot find CGSSetWindowShape, because no model has seen the symbol. Search wide before writing: several phrasings, the jargon and the plain words. A near-duplicate that scores 8 when you expected 20 is still a near-duplicate.

Following a link

[[stem]] names a file by stem, never by path. The target is the note whose filename is stem.md, wherever it sits.

find . -name '<stem>.md' -not -path '*/.*'

Strip the decorations first: [[stem|display text]], [[stem#Heading]], and [[folder/stem]] all target stem.md.

Close the turn once, not once per file

python3 .scripts/reindex.py

Rewrites every index from frontmatter, then prints only what it will not guess at, each line naming its own fix. dangling and orphan are worth stopping for. A dangling link is fine when it marks a note worth writing and a hole when its target was deleted.

Then, whenever a turn added, deleted, or edited a note, in this order:

python3 .scripts/notes.py -m "warm embeddings"   # then
python3 .scripts/colorize.py

colorize.py skips any note with no cached vector rather than embedding it. Editing a note invalidates its vector, so running the colouriser alone after a writing turn leaves exactly the notes you just touched grey. The search call is what warms them; its output is discardable.

Colour is not decoration. Hue, lightness, and chroma come from the embedding, the link neighbourhood, and distance from the vault centroid, and they are rank-normalised across every note, so adding or deleting notes shifts all of them. A partial run makes new notes read as unrelated to everything.

What you must not write

compass/ holds the vault owner's standing goals and principles. It is read-only to every agent, enforced by .claude/hooks/notes-immutable.py. A note carrying immutable: true in its frontmatter is the same. Propose changes in chat; never make them.

sources/ is read-only once written. A source that turns out wrong gets contradicted in the note citing it, never corrected in place.

Every index.md is generated. Editing one by hand is work the next reindex overwrites.

Scope

Touch the note you changed and the notes that directly cite it. Do not follow those notes' links onward, re-fold every topic they touch, or start closing gaps in the graph. Each of those opens two more, and a one-line memory write becomes an hour of rewriting. When a change clearly wants a deeper pass, say so in one line and let the owner call it.