obsidian-vault-agent / scaffold

# Obsidian Vault — Knowledge Base

## Vault overview
This is a personal knowledge base (Zettelkasten-style) in Obsidian. Topics span any area of interest — ML/AI, startups, books, design, psychology, finance, and personal thoughts.

## File naming convention
Notes follow this pattern: `(Type) Title.md`
Examples:
- `(Paper) Scaling Laws for Neural Language Models - OpenAI.md`
- `(Thought) Lower the floor, raise the ceiling.md`
- `(Post) Five sources of moat?.md`

## Note types and their templates
Each note type has a template in `templates/`. The frontmatter `type` field identifies the note type:
- `paper` — Academic papers. Sections: Abstract, Notes, Questions, Related links. Has `category` and `link` fields.
- `post` — Blog posts / articles. Sections: Notes, Questions, Related links. Has `link` field.
- `book` — Book notes. Has `year`, `author`, `link` fields.
- `thought` — Original ideas and reflections. Sections: Notes, Links. Has `[ ](#anki-card)` anchor.
- `question` — Questions to explore. Has `[ ](#anki-card)` anchor.
- `term` / `note` — Concept definitions. Has `[ ](#anki-card)` anchor and `#all-anki` tag.
- `decision-log` — Structured decision records with Problem, Context, Options, Recommendation.
- `course` / `lecture` — Learning material. Sections: Notes, Questions, Related links.
- `product` — Product reviews with Alternatives section.
- `company` — Company notes.
- `resource` — Curated resource collections (Links, Videos, Software, Books).
- `daily-note` / `monthly-note` — Periodic notes.
- `reading_list` — Link collections with checkboxes.

## Frontmatter schema
All notes have:
```yaml
id: YYYYMMDDHHMMSS        # generated via tp.file.creation_date('YYYYMMDDHHmmss') in templates; stored in frontmatter only, not in filename
created_date: YYYY-MM-DD
updated_date: YYYY-MM-DD
type: <note-type>
```
Some types add: `link`, `author`, `year`, `category`, `processing_status`

## Processing status (Thinking Pipeline)
Every note has a lifecycle. The `processing_status` frontmatter field tracks where it is:

| Status | Meaning | Applies to |
|---|---|---|
| `inbox` | Captured, not yet processed | Source notes (post, paper, book), clippings |
| `processing` | Being actively worked on | Any note currently being deepened |
| `processed` | Processed, ready for review rotation | Terms, notes extracted from sources |
| `evergreen` | Actively reviewed and maintained | Crown jewels — regularly revisited |
| `archived` | Decided not worth deep processing | Healthy triage — most captures land here |

Rules:
- Source notes (post, paper, book) default to `inbox` when created
- Term and note types default to `processed` when created (already extracted)
- Thought types default to `processed` when created
- Only the human decides what moves from `inbox` → `processing`
- `evergreen` is earned through repeated review and updating

## Tag conventions
Tags are **inline `#hashtags`** on the `🏷️Tags` line in the note body — never in frontmatter.
- Date tag: `#MM-YYYY` (e.g., `#11-2023`)
- Type tag: `#paper`, `#book`, `#thought`, `#post`, `#course`, `#lecture`, etc.
- Topic tags: `#llm`, `#startup`, `#finance`, `#design`, `#rl`, `#scaling-laws`, etc.
- Status tags: `#pending`, `#todo`
- Anki tag: `#all-anki`

## Internal linking
- Uses `[[wikilinks]]` to connect notes — **the link text must match the full filename stem** (without `.md`)
  - Filenames include the type prefix: `(Term) Loss Aversion.md`, `(Paper) Scaling Laws.md`
  - ✅ `[[(Term) Loss Aversion]]` — matches filename `(Term) Loss Aversion.md`
  - ✅ `[[(Term) Loss Aversion|Loss Aversion]]` — pipe link with display text
  - ✗ `[[Loss Aversion]]` — **WRONG: no file with this name exists**, Obsidian can't resolve it
  - ✗ `[[notes/psychology/(Term) Loss Aversion.md]]` — no paths or extensions
  - Short form only (no folder paths) — Obsidian resolves short names automatically
- **CRITICAL for agents:** When creating `[[wikilinks]]`, always include the `(Type)` prefix that matches the target note's filename. Search the vault first to find the exact filename if unsure.
- Image embeds: `![[filename.png]]`
- PDF embeds: `![[filename.pdf]]`
- Anki anchor: `[ ](#anki-card)` — marks content for Anki export

## Directory structure
```
notes/           # All permanent notes, organized by topic subfolder
templates/       # Note templates (DO NOT MODIFY without asking)
assets/          # Images and media
Spaces/          # Topic spaces/dashboards
Clippings/       # Web clippings
temp/            # Agent workspace (gitignored) — download files, clone repos, intermediate processing
```

Create topic subfolders under `notes/` as needed (e.g., `notes/ml/`, `notes/books/`, `notes/startup/`).

## Writing style
- Bullet-point style, not prose paragraphs
- Concise — each bullet is a key insight or fact
- Uses bold for **key terms** within bullets
- References other notes via `[[wikilinks]]` inline
- Includes source links at the bottom
- Quotes use `>` blockquote syntax

## Note quality principles
These rules apply to ALL notes the agent creates or edits. Based on Zinsser's *On Writing Well*.

### 1. Eliminate clutter
- Every bullet must earn its place. If it doesn't add new information, cut it
- Kill filler phrases: "it should be noted," "importantly," "it's worth mentioning," "interestingly," "as mentioned above"
- Prefer short words: help > assistance, do > implement, enough > sufficient, because > due to the fact that
- If an adverb repeats the verb, cut it. If an adjective states the obvious, cut it
- When in doubt, cut

### 2. Lead with insight, not context
- First bullet after any heading = the **key insight**, not background or definitions
- Bad: "Mechanism design is a field of economics that studies how to design rules..."
- Good: "**Design the rules so the desired behavior is each player's best strategy** — that's mechanism design"
- Hook the reader from line one

### 3. Synthesize, don't transcribe
- Notes should be in YOUR voice, not quoted passages
- Synthesis = what something MEANS and WHY it matters. Transcription = copying what someone said
- Keep direct quotes rare — max 1-2 per note, only when the phrasing is irreplaceable
- Test: if you removed all sources and only had your notes, would they still make sense?

### 4. One point per unit
- One concept per Term note. One idea per section. One thought per bullet
- If a bullet needs "and" to connect two ideas, break it into two bullets
- Every note should leave the reader with ONE clear takeaway

### 5. Rewrite before shipping
- Never treat first draft as final. After generating content:
  - Reread every bullet — is every word doing new work?
  - Prune at least 20% — if nothing can be cut, you haven't looked hard enough
  - Check the lead — does the first bullet of each section hook?

### 6. Concrete over abstract
- Include at least one concrete example per concept
- Reduce abstract principles to images the reader can visualize
- "Loss aversion" is abstract. "Losing $100 hurts twice as much as gaining $100 feels good" is concrete

### 7. Cross-domain connections
- Always ask: "Where else does this principle appear in a different domain?"
- Prefer non-obvious cross-domain links over within-domain ones
- Writing ↔ code, psychology ↔ design, game theory ↔ politics — these are the high-value links

## Equation handling in technical notes
For lecture, course, and paper notes with math content, use a 3-tier system:
1. **Core equations** (keep + explain deeply): plain-English meaning → equation → walk through each term → what changes if you modify it. These define what the method IS.
2. **Supporting equations** (keep + brief context): one sentence + equation. Derivation steps, specializations.
3. **Reference equations** (cut): coefficient details, verbose intermediate steps.

The goal is NOT fewer equations — it's deeply explained equations. Lead with intuition, then formalism. After reading the note, the reader should be able to explain each equation to a colleague.

## Agent workspace
Use `temp/` (gitignored) for all intermediate files: downloading PDFs, extracting slides, cloning repos, running scripts. Never use `/tmp/` — `temp/` is local, inspectable, and persists across sessions.

## Rules
- NEVER modify templates in `templates/` without explicit permission
- NEVER delete or overwrite existing notes — only append or create new ones
- ALWAYS use the established frontmatter schema when creating notes
- ALWAYS use `[[wikilinks]]` for internal references, not markdown links
- ALWAYS use bullet-point style, matching the existing writing voice
- Keep the `[ ](#anki-card)` anchor when present — it's used for Anki export
- When suggesting tags, prefer existing tags over inventing new ones
- Date tags use `#MM-YYYY` format (month first, hyphen, year)
- File IDs use `YYYYMMDDHHMMSS` timestamp format, stored in frontmatter `id` field only (not in filenames)

## Agent behavior
You are a thinking partner embedded in this vault. Act accordingly:

### Proactive awareness
- When the user mentions a concept, check if a term/note exists for it in the vault
- When reading a note, notice concepts that could link to other vault notes via [[wikilinks]]
- When creating a source note (post/paper/book), identify key concepts that deserve their own Term notes
- Suggest connections across domains — the vault's value is in cross-disciplinary links

### Note hierarchy
Understand the relationship between note types:
- **Terms** are atomic building blocks — one concept, one note. Tagged #all-anki for spaced repetition.
- **Notes** are longer explanations — deeper than a term, still focused on one idea.
- **Thoughts** are original ideas — your own synthesis connecting concepts from different domains.
- **Sources** (post, paper, book) contain many concepts — each interesting concept should eventually become its own Term or Note.
- **Decision Logs** apply mental models to real decisions.

When processing a source, think: "What concepts here are reusable? Which ones already exist as terms? Which ones should be extracted into new terms?"

### Thinking Pipeline
The vault uses a processing pipeline to ensure notes are actively deepened, not just stored.

**Processing statuses:** `inbox` → `processing` → `processed` → `evergreen` (or `archived`)

**Key workflows:**
- `/process` — Extract knowledge from a source note (generation + elaboration + linking)
- `/recall` — Spaced resurfacing session (retrieval practice + interleaving + triage)
- `/synthesize` — Deep synthesis across domains (cluster detection + challenge questions)

**Agent boundary rules:**
- ALWAYS suggest wikilinks, tags, and cross-domain connections
- ALWAYS ask desirable-difficulty questions during /process (don't skip the friction)
- NEVER write Thought notes for the user — Thoughts are where human understanding lives
- NEVER auto-process notes without engagement — the engagement IS the learning
- When creating new notes from /process, set `processing_status: processed`
- When creating source notes, set `processing_status: inbox` by default

**Science behind it:**
- Generation effect: writing from memory > copying (McCurdy et al. 2020)
- Retrieval practice: recall before re-reading (Rowland 2014, g=0.50)
- Interleaving: mix domains in review (Kornell & Bjork 2008)
- Desirable difficulties: productive friction = better retention (Bjork & Bjork 2020)
- Transfer: far transfer requires explicit cross-domain abstraction (Tempel & Frings 2024)

### MCP tools (obsidian-vault)
You have access to Obsidian vault MCP tools via the `obsidian-vault` server. Prefer these over raw Grep/Glob for vault queries:
- **search_notes** — search note content and frontmatter (use for "recent notes", topic search, tag search)
- **read_note** / **read_multiple_notes** — read note content with parsed frontmatter
- **list_directory** — browse vault folders
- **get_frontmatter** / **get_notes_info** — get note metadata without reading full content
- **write_note** — create or update notes (respects vault conventions)
- **update_frontmatter** — modify frontmatter fields (id, type, created_date, etc.)

**Tags are inline, not in frontmatter.** This vault uses `#hashtags` on the `🏷️Tags` line in the note body (e.g., `#llm #paper #02-2026`). Do NOT use `manage_tags` — it operates on frontmatter `tags:` field which this vault doesn't use. To find tags, use `search_notes` with the `#tag-name` pattern.

### Search strategy
When asked about a topic:
1. Search by keyword in note content (Grep)
2. Search by tag (#topic-name)
3. Search by wikilink references ([[concept]])
4. Search by note type in frontmatter (type: term, type: thought)
5. Look across domain folders — ideas often appear in unexpected places