diff --git a/skills/goldbrain-memory/references/vault-layout.md b/skills/goldbrain-memory/references/vault-layout.md new file mode 100644 index 0000000..cbde5a7 --- /dev/null +++ b/skills/goldbrain-memory/references/vault-layout.md @@ -0,0 +1,155 @@ +# Vault Layout & Frontmatter Conventions + +Mirrors the canonical conventions defined in the vault's own `STRUCTURE.md` and `BOOTSTRAP.md`. If those change, they are the source of truth. + +## Folder Map (root-addressed) + +``` +/vault/ +├── CLAUDE.md ← operating contract + session protocol +├── STRUCTURE.md ← layout, taxonomy, frontmatter standard +├── BOOTSTRAP.md ← preflight/repair manifest (read first) +├── spinup.md index.md README.md +├── 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/ ← .md +├── decisions/ +│ ├── by-date/ ← YYYY-MM-DD-.md (ADR-style) +│ ├── by-project/ ← mirror by project +│ └── decision-template.md +├── reviews/ ← weekly / monthly / quarterly / annual +├── archive/ ← notes / projects / imports +└── _agent/ + ├── 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 + ├── outputs/ ← briefs / drafts / summaries / synthesis + ├── skills/ ← active / archived + └── heartbeat/ +``` + +**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`. + +> **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 Bryan is (one paragraph) +- `## Fact / Pattern` — **promoted, deduped rules.** No date prefix. Timeless. +- `## Observations` — **timestamped raw observations.** Date-prefixed lines (`- 2026-06-07: ...`). 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 Bryan; do not attribute Jason's design preferences to Bryan without evidence — Jason's preferences live in the ECHO vault. + +### projects/active/\.md + +```markdown +--- +type: project +status: active +created: 2026-06-07 +updated: 2026-06-07 +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-07: observation or update + +## Related +- [[areas/business/business-ops]] +``` + +**Lifecycle / status agreement:** a project's folder under `projects/` (`active`, `incubating`, `on-hold`, `archived`) and its `status:` frontmatter MUST match — moving the file and updating `status:` are the same operation. A note in `projects/active/` with `status: on-hold` is broken state; fix it when you see it. Keep heading text ASCII (plain hyphens, no em dashes/parentheses) so headings stay PATCH-targetable. + +### sessions/YYYY-MM-DD-HHMM-\.md + +See `session-log-template.md`. goldbrain 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 may 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. Mirror a project-relevant ADR as a `[[wikilink]]` under that project's `## Decisions` heading, and optionally into `by-project/` per the vault's `STRUCTURE.md`. The by-date ADR is always the canonical record. + +### people/\.md + +`type: person`. Use lowercase kebab-case for the slug (e.g. `bryan-gilliom.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.