Find Your Way Around The Vault - alexherrero/agentm GitHub Wiki
Note
Goal: Find where something lives in the vault, and confirm the CLI, the daemon, and the consistency gates all read the layout the same way. Prereqs: A configured vault (Choose a storage backend). Shell access to the machine it lives on.
The vault is seven lowercase root spaces beside two root notes. Every space is spelled the way the code spells it, since the root casing migration (agentm-vault plan 08 โ see Run the root casing migration). Read every name on this page exactly, case included: the disk is case-insensitive, so a stale Title Case directory still opens if you type its name by hand โ that's the only thing the case-insensitivity hides. Every exact-string comparison in the codebase, and Linux CI's case-sensitive disk, see the mismatch and refuse it.
-
List the root.
ls <vault>prints the seven spaces โagent,calendar,personal,projects,resources,standards,systemsโ and the two root notes,index.mdandIdeas.md.Ideas.mdis rebuilt every night;index.mdis yours, kept by hand. -
Look inside
agent/, the agent's own half.Directory Holds agent/memory/The six memory classes: semantic/,procedural/,episodic/,entities/,crystallized/,mocs/.agent/diagnostics/Scorecards and digests. agent/archive/Not yet there: the retention plan (agentm-vault plan 11) creates it, mirroring memory/'s own tree. Todayagent/holds the two directories above.Nothing else sits loose in
agent/except the data runs' dot-named markers, which the shape gate tolerates. -
Look inside
calendar/. OneYYYY/directory per year, holding facet notes, plus a generatedmoc-calendar-YYYY.mdbeside each year._daily-template.mdsits at the calendar root permanently โ Obsidian's own daily-notes setting names it there (agentm-vault plan 15; plan 10 had left this open). -
Look inside
personal/. Your own filing, Title Case inside and untouched by the root casing migration โ that migration renamed only the four root spaces themselves, never anything below them.personal/Home/,personal/Church/, and the rest of your tree read exactly as you left them. One folder there is also read by the machinery:personal/ideas/, lowercase, is where an idea card lives once you file it. The night may add its thoughts to a card there, andIdeas.mdis rebuilt from the folder (agentm-vault part 13) โ see Manage your ideas list. -
Look inside
projects/. One tree per project:charter.md,tracker.md,decisions/,designs/,research/,drafts/,docs/,desk/,tasks/,completed/, and a generatedmoc-<slug>.md(the design's skeleton).docs/holds the project's living documents โfollowups.md,roadmap.md,conventions.md, and others โ moved off the project root by task 176 step 3 (2026-09-25); config and source lists (auto-orchestration-config.mdand its siblings) moved todesk/in the same step. No code reads a_harness/tree any more (agentm-vault plan 15 retired the last fallback that did) โ a project that never ran the projects migration and still carries one is a leftover the doctor'sharness-dirsrow flags, not a place anything writes. A finished project's tree lives underprojects/completed/instead.A closed task's folder moves too. Open work sits in
tasks/<task>/; 14 days after a task's tracker readsdoneordropped, the night moves the whole folder, under its own name, tocompleted/tasks/<task>/and rewrites every link into it (task 177). A task is found by its name in either folder, so/workand the resolver still reach one that has moved, and a new task is numbered past both. To reopen a closed task, move its folder back totasks/and set its trackeractive. -
Look inside
standards/. The four always-load files, plusvoice/for the on-demand voice rules. Nothing else lives here. -
Confirm the memory root. The agent's own tree begins at
<vault>/agent, not at the vault root itself. Two config keys say so:python3 scripts/agentm_config.py --get memory_root python3 scripts/agentm_config.py --get daemon.spaces
The first prints
agent. The second prints the vault-relative directory for every logical space the daemon writes,{"memory": "agent/memory", "projects": "projects"}among them. If you exportMEMORY_VAULT_PATHby hand anywhere, confirm it ends in/agentโ that's the memory root it names, never the vault root. -
Confirm every tool agrees. Four different readers of the same layout, checked against each other:
ls <vault> agentmd status # the "vault" line python3 scripts/check-memory-root-consistency.py python3 scripts/check-no-title-case-roots.py
lsis the filesystem's own answer.agentmd statusprints avaultline naming the path the daemon resolved at its last start โ compare it againstlsby eye.check-memory-root-consistency.pyconfirms the Go daemon'sdaemon.spacesand the Python stack's own space config resolve to the same directories.check-no-title-case-roots.pyconfirms nothing in the codebase still names a root space by its retired Title Case spelling. A tool that disagrees with the other three is the one that's wrong.
-
ls <vault>lists exactlyagent,calendar,personal,projects,standards,index.md, andIdeas.mdat the top level. -
agentmd status'svaultline names the vault root, not<vault>/agent. -
check-memory-root-consistency.pyandcheck-no-title-case-roots.pyboth read clean.
- A root space shows up Title Case. Something wrote to the old path after the root casing migration ran. See Run the root casing migration ยง Troubleshooting.
-
agentmd status'svaultline andls <vault>disagree. The daemon resolved a stalevault_pathโ check what set it (a plist, a shell profile) and restart the daemon once it's fixed. -
A directory opens fine by hand but the tools act like it's missing. You're looking at the case-insensitive disk hiding a case mismatch. Check the exact spelling with
ls, not by opening the folder.
- AgentM Vault design โ "The root spaces are lowercase," the ruling this layout follows.
- Run the root casing migration โ the migration that got the vault here.
- Set up Obsidian on the vault โ reading this same layout through Obsidian's graph and backlinks.
-
Manage your ideas list โ
personal/ideas/, the one code-recognized folder insidepersonal/. -
CI gates reference โ
check-no-title-case-rootsandcheck-memory-root-consistency, the two gates step 8 runs by hand.