vault-naming-convention

Vault Naming Convention

Every file in the {{AGENT_NAME}} vault is a node in the knowledge graph. Filename uniqueness ensures wikilinks resolve deterministically. P-layer prefix preserves priority identity. Exclusion boundaries keep operational noise out of the graph.

Why This Matters (The SEO of Knowledge)

Duplicate filenames waste "resolution budget" — the same way duplicate content wastes search engine crawl budget:

• [[SOUL]] with 4 SOUL.md files → Obsidian guesses, possibly wrong
• [[SCHEMA]] with 3 SCHEMA.md files → ambiguous reference
• Agent reading the vault must resolve ambiguity → compute waste

From NeuronFS: the P-layer prefix (P0-P6) is structural IDENTITY, not just a folder. Losing it in a short-name link loses priority information.

Rule: Unique Basenames in Structural Zones

Structural zones = paths that form the knowledge graph:

• P0-brainstem/ through P6-prefrontal/
• skills/ (each skill has its own SKILL.md)
• YOUR_SITE/

Non-structural zones (excluded from Obsidian, can have duplicates):

• source/ — {{AGENT_NAME_LOWER}}-agent upstream code
• cron/output/ — operational logs
• .trash/ — recovery staging
• _agent/ — runtime state
• node_modules/, archive/

Enforcement

Every .md file in structural zones must have a unique basename (case-sensitive):

find ~/.{{AGENT_NAME_LOWER}} -name '*.md' \
  -not -path '*/cron/*' -not -path '*/.trash/*' \
  -not -path '*/source/*' -not -path '*/_agent/*' \
  -not -path '*/node_modules/*' -not -path '*/archive/*' \
  2>/dev/null | while read f; do basename "$f"; done \
  | sort | uniq -c | sort -rn | awk '$1 > 1 {print $1, $2}'

Wikilink Convention by Scope

Scope	Recommended Style	Example
Unique filename	Short name [[Slug]]	[[SELF_MODEL]], [[rules]]
Non-unique filename	Full path [[P-layer/path/Slug]]	[[@identity/persona/SOUL]] (not bare [[SOUL]])
Skill file	[[skills/category/name/SKILL]]	[[skills/devops/kanban-worker/SKILL]]
Neuron file	[[@identity/禁/slug]]	[[@identity/禁/禁task_qa_gate.neuron]]