# Vault Layout & Frontmatter Conventions **This document is canonical.** The ECHO vault holds data only — there are no `CLAUDE.md` / `STRUCTURE.md` / `BOOTSTRAP.md` / `index.md` control docs in it. Layout, taxonomy, and frontmatter conventions live here in the plugin; the bootstrap procedure (`references/bootstrap.md`) builds the tree below into any empty vault. ## Folder Map (root-addressed) ``` /vault/ ├── README.md ← thin human signpost (NOT read for routing) ├── inbox/ │ ├── captures/ ← quick captures (inbox.md), date-prefixed lines │ ├── imports/ ← raw imported material │ └── processing-log/ ├── journal/ │ ├── daily/ ← YYYY-MM-DD.md (has an "Agent Log" section) │ └── templates/ ├── projects/ ← lifecycle: incubating → active → on-hold/archived │ ├── active/ ← current work (status: active) │ ├── incubating/ ← idea captured, not yet started (status: incubating) │ ├── on-hold/ ← paused but kept (status: on-hold) │ ├── archived/ ← done / abandoned (status: archived) │ └── project-template.md ├── areas/ ← business / personal / learning / systems ├── resources/ │ ├── concepts/ references/ meetings/ │ └── people/ ← .md ├── decisions/ │ ├── by-date/ ← YYYY-MM-DD-.md (ADR-style) — the canonical home │ └── decision-template.md │ (decisions/by-project/ is retired and not created — │ mirror an ADR into a project's `## Decisions` heading instead) ├── reviews/ ← weekly / monthly / quarterly / annual └── _agent/ ├── echo-vault.md ← bootstrap marker: schema_version + bootstrap date (plugin-owned; the "is this vault set up?" probe) ├── context/ ← current-context.md and task bundles ├── memory/ │ ├── working/ ← transient, time-boxed │ ├── episodic/ ← what happened, when │ └── semantic/ ← durable facts/patterns (operator-preferences.md) ├── sessions/ ← YYYY-MM-DD-HHMM-.md ├── templates/ ← canonical note templates ├── skills/ ← active / archived └── heartbeat/ ← single-line pointers (e.g. last-session.md → most-recent session log path) ``` **Heartbeat:** `_agent/heartbeat/last-session.md` is a one-line pointer file an agent MAY write at session end (` @ `). Reading it at session start is cheaper than listing the sessions directory; use it as a hint, not a source of truth — fall back to the directory listing if it's missing or stale. **Slug rules:** kebab-case, ASCII only, truncate to ~40 chars. --- ## Canonical Frontmatter Every note starts with this block. Fill what applies; leave the rest empty rather than guessing. ```yaml --- type: # see Note Types below status: # active | draft | done | archived | complete created: # YYYY-MM-DD (or YYYY-MM-DDTHH:mm for sessions) updated: # YYYY-MM-DD tags: [] agent_written: false source_notes: [] # plain relative paths as strings — NEVER [[wikilinks]] --- ``` `agent_written: true` + a populated `source_notes` is the key signal separating agent-managed content from human-authored content. When appending with POST, do not rewrite frontmatter — the append goes after existing content. To change `updated:` or `status:`, use PATCH with `Target-Type: frontmatter`. **Frontmatter field semantics:** - `created:` is the **earliest known date** the entity was tracked in the vault — *not* "today". When merging notes (e.g. promoting an `on-hold/` project into `active/`), preserve the earliest `created:` from any merged source and only update `updated:`. - `source_notes` is a **backward link** — the note(s) that triggered or supplied content for this one (e.g. the session log a project update came from). Forward links go in the `## Related` body section, never here. - `status:` for a project MUST match its folder under `projects/` (`active`, `incubating`, `on-hold`, `archived`). Moving the file and updating `status:` are the same operation. > **No `[[wikilinks]]` in frontmatter.** YAML parses `[[...]]` as nested lists, so wiki > links there break and never render as clickable links in reading view. Put all > cross-references in a **`## Related`** section in the note **body** (bulleted `[[links]]`). > Frontmatter holds scalar/string metadata only; `source_notes` values are plain relative > paths, not links. ## Note Types `daily-note`, `weekly-note`, `monthly-note`, `project`, `project-update`, `area`, `concept`, `reference`, `person`, `meeting`, `decision`, `review`, `session-log`, `working-memory`, `episodic-memory`, `semantic-memory`, `context-bundle`, `skill`, `draft`, `inbox-item`. --- ## File-Specific Conventions ### operator-preferences.md (`_agent/memory/semantic/`) The profile analog. Canonical headings: - `## Operator` — who Jason is (one paragraph) - `## Fact / Pattern` — **promoted, deduped rules.** No date prefix. Timeless. - `## Observations` — **timestamped raw observations.** Date-prefixed lines (`- 2026-06-06: ...`). Default landing zone for new evidence. - `## Evidence` — citations/links supporting the rules - `## Recommendation or Implication` — how the rules should shape behavior - `## Review Notes` — confidence / last review date Append observed facts under `## Observations` by default. Promote to `## Fact / Pattern` (dropping the date) once a pattern stabilizes. "The operator" is Jason — he is both operator and architect of this vault. ### projects/active/\.md ```markdown --- type: project status: active created: 2026-06-05 updated: 2026-06-05 tags: [] agent_written: false source_notes: [] --- # Project Name ## Current status One paragraph, kept fresh via PATCH replace. ## Decisions - [[YYYY-MM-DD-decision-slug]] — one-line summary ## Open threads - [ ] unresolved thing ## Log - 2026-06-05: observation or update ## Related - [[areas/business/business-ops]] ``` ### sessions/YYYY-MM-DD-HHMM-\.md See `session-log-template.md`. ECHO uses an **HHMM time component** in the filename — this is **canonical, not optional**. The four-digit local-time component makes filenames lex-sort in true chronological order, which the loading procedure relies on. Older session logs without HHMM exist; leave them alone, but every new one must use the full `YYYY-MM-DD-HHMM-.md` form. ### decisions/by-date/YYYY-MM-DD-\.md ADR-style: Context → Decision → Consequences. If the decision belongs to an existing project, PATCH-append the wikilink into that project's `## Decisions` heading. Don't use `decisions/by-project/` — it's legacy scaffolding that's intentionally left empty. ### people/\.md `type: person`. Use lowercase kebab-case for the slug (e.g. `jason-stedwell.md`). --- ## Cross-References Use Obsidian wiki links freely: `[[note-name]]` or `[[folder/note]]`. The REST API doesn't resolve them, but Obsidian does when the operator browses the vault.