193 lines
8.2 KiB
Markdown
193 lines
8.2 KiB
Markdown
---
|
|
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 "<path>"
|
|
```
|
|
|
|
### 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]]
|