quicksilver/echo-memory.plugin.src/skills/echo-memory/references/vault-layout.md

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)
│   ├── weekly/  monthly/
│   └── 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/  source-material/
│   └── people/        ← <name>.md
├── decisions/
│   ├── by-date/       ← YYYY-MM-DD-<slug>.md (ADR-style) — the canonical home
│   └── decision-template.md
│   (decisions/by-project/ exists in the legacy scaffold but is not used —
│    mirror an ADR into a project's `## Decisions` heading instead)
├── reviews/           ← weekly / monthly / quarterly / annual
├── archive/           ← notes / projects / imports
└── _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-<slug>.md
    ├── templates/     ← canonical note templates
    ├── outputs/       ← briefs / drafts / summaries / synthesis
    ├── 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 (<session-log-path> @ <ISO-timestamp>). 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.

---
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/<slug>.md

---
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-<slug>.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-<slug>.md form.

decisions/by-date/YYYY-MM-DD-<slug>.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/<name>.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.