jason/goldbrain

Fork 0

Files

T

jason 392ae7bbe3 first push

2026-06-04 16:20:56 -05:00

8.2 KiB

Raw Blame History

type, status, created, updated, tags, agent_written, source_notes

type

status

created

updated

BOOTSTRAP.md

Purpose

This is the first file any agent reads when operating against this vault. It does three things, in order:

Checks that the required files and folders exist.
Generates anything that is missing, using the templates and conventions below.
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:

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):

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

Read this file (bootstrap), then CLAUDE.
Read today's daily note in journal/daily/.
Read the most recent log in _agent/sessions/.
Read active bundles in _agent/context/.
Scan inbox/ for unprocessed material relevant to the task.
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

Write or update a session log in _agent/sessions/ (YYYY-MM-DD-HHMM-slug.md).
Record what changed, decisions made, and what remains open.
Update durable notes if the session produced lasting knowledge.
Add a concise entry to the daily note's Agent Log.
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.

---
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.

8.2 KiB Raw Blame History