--- type: reference status: active created: 2026-06-02 updated: 2026-06-02 tags: [agent, bootstrap, system] agent_written: true source_notes: [] --- # BOOTSTRAP.md ## Purpose This is the **first file any agent reads** when operating against this vault. It does three things, in order: 1. **Checks** that the required files and folders exist. 2. **Generates** anything that is missing, using the templates and conventions below. 3. **Instructs** the agent on how to use the memory system once the vault is healthy. Run the bootstrap check at the start of every session before following the Session Protocol in [[CLAUDE]]. The check is cheap, idempotent, and safe to repeat. --- ## 1. Preflight Check Verify the following exist. Treat each as `[ ]` until confirmed, then `[x]`. If a path is missing, jump to the matching entry in section 2 (Repair) before continuing. ### Root control docs - [ ] `CLAUDE.md` — operating contract and session protocol - [ ] `BOOTSTRAP.md` — this file - [ ] `STRUCTURE.md` — layout, taxonomy, frontmatter standard - [ ] `spinup.md` — one-time setup walkthrough - [ ] `index.md` — navigation hub - [ ] `README.md` — human-facing overview - [ ] `.env.example` — config template for REST/API clients ### Required folders - [ ] `inbox/` (with `captures/`, `imports/`, `processing-log/`) - [ ] `journal/` (with `daily/`, `weekly/`, `monthly/`, `templates/`) - [ ] `projects/` (with `active/`, `incubating/`, `on-hold/`, `archived/`) - [ ] `areas/` (with `business/`, `personal/`, `learning/`, `systems/`) - [ ] `resources/` (with `concepts/`, `references/`, `people/`, `meetings/`, `source-material/`) - [ ] `decisions/` (with `by-date/`, `by-project/`) - [ ] `reviews/` (with `weekly/`, `monthly/`, `quarterly/`, `annual/`) - [ ] `archive/` (with `notes/`, `projects/`, `imports/`) - [ ] `_agent/` (see agent subtree below) ### Required `_agent/` subtree - [ ] `_agent/context/` — active context bundles - [ ] `_agent/memory/working/` — short-lived working memory - [ ] `_agent/memory/episodic/` — event/session-derived memory - [ ] `_agent/memory/semantic/` — durable facts, patterns, preferences - [ ] `_agent/sessions/` — session logs - [ ] `_agent/templates/` — note templates - [ ] `_agent/heartbeat/` — liveness / scheduled-run markers - [ ] `_agent/skills/` (with `active/`, `archived/`) - [ ] `_agent/outputs/` (with `briefs/`, `drafts/`, `summaries/`, `synthesis/`) ### Required templates - [ ] `_agent/templates/session-log-template.md` - [ ] `_agent/templates/context-bundle-template.md` - [ ] `_agent/templates/working-memory-template.md` - [ ] `_agent/templates/semantic-memory-template.md` - [ ] `journal/templates/daily-note-template.md` - [ ] `journal/templates/weekly-review-template.md` - [ ] `projects/project-template.md` - [ ] `decisions/decision-template.md` ### Anchor notes (recommended, not blocking) - [ ] `_agent/context/current-context.md` - [ ] `_agent/memory/semantic/operator-preferences.md` - [ ] today's daily note in `journal/daily/YYYY-MM-DD.md` A quick way to list the tree for comparison: ```bash find . -type d | sort # folders find . -type f -name '*.md' | sort # notes ``` --- ## 2. Repair (generate what's missing) Only create what is missing. **Never overwrite an existing file** during bootstrap — that violates the additive-update principle in [[CLAUDE]]. If a file exists but looks malformed, flag it in the session log instead of replacing it. ### Missing folders Create the folder and add a one-line `README.md` inside any leaf folder that would otherwise be empty (Obsidian and git both ignore empty dirs): ```bash mkdir -p "" ``` ### Missing root control docs - `STRUCTURE.md`, `spinup.md`, `README.md`, `.env.example` — if absent, note it and reconstruct from the conventions in this file and [[STRUCTURE]]. Do not invent secrets in `.env.example`; use placeholders only. - `index.md` — rebuild as a link hub pointing at the Start Here docs, current daily note, active context, latest session log, and active projects. ### Missing templates Recreate from the canonical frontmatter (section 4). Each template is just frontmatter plus the section headings its note type uses. ### Missing anchor notes - `_agent/context/current-context.md` — create an empty context bundle (type `context-bundle`) scoped to the current task. - today's daily note — create from `journal/templates/daily-note-template.md`. - `operator-preferences.md` — only create if you have evidence to record; do not fabricate preferences. ### After repair Append a line to the daily note's **Agent Log** and write/refresh a session log in `_agent/sessions/` recording what was generated. --- ## 3. How to Use the Memory System Once preflight passes, operate as follows. ### Session start 1. Read this file (bootstrap), then [[CLAUDE]]. 2. Read today's daily note in `journal/daily/`. 3. Read the most recent log in `_agent/sessions/`. 4. Read active bundles in `_agent/context/`. 5. Scan `inbox/` for unprocessed material relevant to the task. 6. Review active projects in `projects/active/` and open loops. ### During the session - Put short-lived state in `_agent/memory/working/` (expires; safe to prune). - Promote durable, reusable facts and patterns into `_agent/memory/semantic/`. - Record notable events and outcomes in `_agent/memory/episodic/`. - Keep task-scoped context in `_agent/context/` and refresh it as focus shifts. - Capture raw, unprocessed input in `inbox/captures/`; log processing in `inbox/processing-log/`. - Record meaningful choices as decision notes in `decisions/` (mirror by-date and by-project as needed). ### Session end 1. Write or update a session log in `_agent/sessions/` (`YYYY-MM-DD-HHMM-slug.md`). 2. Record what changed, decisions made, and what remains open. 3. Update durable notes if the session produced lasting knowledge. 4. Add a concise entry to the daily note's **Agent Log**. 5. Leave the vault cleaner and more queryable than you found it. ### Memory model (where things live) - **Working** → `_agent/memory/working/` — transient, time-boxed. - **Episodic** → `_agent/memory/episodic/` — what happened, when. - **Semantic** → `_agent/memory/semantic/` — durable facts, patterns, preferences. - **Context bundles** → `_agent/context/` — task-focused reading lists and state. ### Safety rules (from [[CLAUDE]]) - Do not fabricate facts, relationships, or prior decisions. - Do not mass-restructure the vault unless explicitly asked. - Do not delete notes unless deletion is explicitly requested and clearly safe. - Do not store secrets or API keys inside the vault. - Default to additive updates and explicit status changes. --- ## 4. Canonical Frontmatter Every note carries this block. Fill what applies; leave the rest empty rather than guessing. ```yaml --- type: # one of the note types in STRUCTURE.md status: # active | draft | done | archived created: # YYYY-MM-DD updated: # YYYY-MM-DD tags: [] agent_written: false source_notes: [] # plain relative paths as strings — NEVER [[wikilinks]] --- ``` Agent-generated notes set `agent_written: true` and list their `source_notes`. This is the key signal that separates agent-managed content from human-authored content. > **No `[[wikilinks]]` in frontmatter.** YAML interprets `[[...]]` as nested lists, so wiki > links in frontmatter break — they do not render as clickable links in Obsidian's reading > view. Put every cross-reference in a **`## Related`** section in the note **body** as a > bulleted list of `[[links]]`. Frontmatter holds scalar/string metadata only; `source_notes` > values are plain relative paths, not links. (The older `related:` frontmatter field has > been retired for this reason.) --- ## 5. REST / API Readiness Future clients (Obsidian Local REST API, CoWork plugin) may operate without filesystem access. Keep the bootstrap contract portable: stable paths, parseable frontmatter, durable titles, and all state stored in notes rather than hidden conversation memory. Config for those clients lives in a local `.env` derived from `.env.example` — never committed with real values. --- _This file is the entry point. If you change folder conventions or required files, update both this manifest and [[STRUCTURE]] so they stay in sync._ ## Related - [[CLAUDE]] - [[STRUCTURE]] - [[index]] - [[spinup]]