Find Your Way Around The Vault - alexherrero/agentm GitHub Wiki

How to find your way around the vault

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.

Steps

  1. List the root. ls <vault> prints the seven spaces โ€” agent, calendar, personal, projects, resources, standards, systems โ€” and the two root notes, index.md and Ideas.md. Ideas.md is rebuilt every night; index.md is yours, kept by hand.

  2. 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. Today agent/ holds the two directories above.

    Nothing else sits loose in agent/ except the data runs' dot-named markers, which the shape gate tolerates.

  3. Look inside calendar/. One YYYY/ directory per year, holding facet notes, plus a generated moc-calendar-YYYY.md beside each year. _daily-template.md sits at the calendar root permanently โ€” Obsidian's own daily-notes setting names it there (agentm-vault plan 15; plan 10 had left this open).

  4. 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, and Ideas.md is rebuilt from the folder (agentm-vault part 13) โ€” see Manage your ideas list.

  5. Look inside projects/. One tree per project: charter.md, tracker.md, decisions/, designs/, research/, drafts/, docs/, desk/, tasks/, completed/, and a generated moc-<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.md and its siblings) moved to desk/ 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's harness-dirs row flags, not a place anything writes. A finished project's tree lives under projects/completed/ instead.

    A closed task's folder moves too. Open work sits in tasks/<task>/; 14 days after a task's tracker reads done or dropped, the night moves the whole folder, under its own name, to completed/tasks/<task>/ and rewrites every link into it (task 177). A task is found by its name in either folder, so /work and 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 to tasks/ and set its tracker active.

  6. Look inside standards/. The four always-load files, plus voice/ for the on-demand voice rules. Nothing else lives here.

  7. 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 export MEMORY_VAULT_PATH by hand anywhere, confirm it ends in /agent โ€” that's the memory root it names, never the vault root.

  8. 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

    ls is the filesystem's own answer. agentmd status prints a vault line naming the path the daemon resolved at its last start โ€” compare it against ls by eye. check-memory-root-consistency.py confirms the Go daemon's daemon.spaces and the Python stack's own space config resolve to the same directories. check-no-title-case-roots.py confirms 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.

Verify

  • ls <vault> lists exactly agent, calendar, personal, projects, standards, index.md, and Ideas.md at the top level.
  • agentmd status's vault line names the vault root, not <vault>/agent.
  • check-memory-root-consistency.py and check-no-title-case-roots.py both read clean.

Troubleshooting

  • 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's vault line and ls <vault> disagree. The daemon resolved a stale vault_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.

Related

โš ๏ธ **GitHub.com Fallback** โš ๏ธ