An Obsidian vault as agent memory: fewer tokens, better answers

Most of the tokens I used to burn weren't spent writing code. They were spent getting the agent back up to speed: re-explaining a decision from last week, having it re-read docs it already summarized once, or watching it explore half the repo to rediscover something I already knew.

An agent has no memory between sessions. The fix that has worked best for me is boring: a folder of small markdown notes that the agent can search, plus a short skill that tells it how the folder is organized. I keep mine in Obsidian, because Obsidian is a good editor for exactly that kind of folder.

Where the tokens actually go

Re-discovery is the expensive part. Reading a 40-page doc to answer one question costs the whole doc. Searching ten files for a convention costs ten files. Doing that again the next day costs it all again.

A vault changes what the agent has to read:

The savings come from three properties: notes are small, they're findable by search (so the agent reads matching lines instead of whole files), and they're linked (so it can follow one or two links instead of loading everything).

The skill

Matt Pocock published an obsidian-vault skill that captures this setup in about 50 lines. It's listed on skills.sh, and you can install it with:

npx skills add https://github.com/mattpocock/skills --skill obsidian-vault

The rules it gives the agent are worth copying even if you never install it:

• Keep the vault mostly flat. Organize with links and index notes, not folders.
• Use title case for every note name.
• Index notes (Skills Index, RAG Index…) are just lists of [[wikilinks]].
• Each note links to its related notes at the bottom.
• Search before you read: by filename, by content, and by backlink.

Here's my version, with the path pulled into one place:

---
name: obsidian-vault
description: Search, create and update notes in my Obsidian vault. Use when I ask what I know about a topic, or to save something worth remembering.
---

# Obsidian vault

Vault: `~/Vault/Dev/` (flat; no folders for organization).

## Read
1. Start from the matching index note: `find ~/Vault/Dev -name "*Index*"`.
2. Search before opening: `grep -ril "keyword" ~/Vault/Dev --include="*.md"`.
3. Open at most 3 notes. Follow a [[wikilink]] only if the note says it matters.

## Write
- One idea per note. Title Case filename.
- First line: a one-sentence summary. Last lines: [[related notes]].
- Add the note to its index. Update a note instead of writing a duplicate.

Set it up in ten minutes

1. Pick a folder and keep it flat. Something like ~/Vault/Dev/. Open it as a vault in Obsidian so you get the graph, backlinks and quick switcher for free.
2. Create two or three index notes for the topics you work on most. An index is only a list of links. That's the point: it's cheap to read.
3. Write notes the agent can skim. Put the answer in the first line, so a search hit or the first few lines of a file is often enough.
4. Add the skill (or two lines in your AGENTS.md/CLAUDE.md pointing at the vault and the rules above).

A note looks like this:

# Cloudflare D1 Migrations

Use `wrangler d1 migrations apply <db> --remote`; it is idempotent and tracks applied files in `d1_migrations`.

- Create: `wrangler d1 migrations create <db> <name>`
- SQLite can't alter a CHECK constraint: rebuild the table, and copy child rows aside first
  because DROP TABLE runs the foreign-key cascade.
- Test locally with `--local` before `--remote`.

Related: [[Cloudflare Workers Index]] · [[SQLite Gotchas]]

What a session looks like

> Add a column to the subscribers table

- reads wrangler docs (web)
- greps the repo for migrations
- reads 4 migration files
- tries ALTER on a CHECK constraint, fails
- reads SQLite docs (web)
- writes the migration

> Add a column to the subscribers table

- finds [[Cloudflare Workers Index]]
- opens [[Cloudflare D1 Migrations]]
- writes the migration
- appends one line to the note about the new column

The second session is shorter, and it skips the failed attempt, because the gotcha is already written down.

Keep it from rotting

A stale note is worse than no note, because the agent will trust it. Three habits keep the vault honest:

• Update, don't append. When something changes, fix the note it lives in.
• Delete what's wrong. Research notes that were only true on the day you wrote them should go when the task is done.
• Link to the source. A note that points at the doc or the file can be checked in one hop.

Measure it yourself

Don't take my word for the savings. Pick a task you do every week, run it once without the vault and once with it, and compare the token counts your tool reports. Count the follow-up corrections too. In my experience that's where the vault pays for itself: fewer “no, we decided against that” messages.