My Obsidian vault as an agent's memory

The first two sessions after the reorg both ended the same way. The agent finished whatever I’d asked for and then, politely, suggested I put the vault in git. Both times I said no, and both times it had no way of knowing I’d already said no, because the session before it had ended and taken the conversation with it. So the third thing I added to the vault’s CLAUDE.md that week was a line saying git had been offered and declined, with the date, and not to pitch it again.

That line is a good summary of what the file is for, which I didn’t understand when I wrote the first version last summer.

The reorg

A year ago I pointed Claude Code at my notes and mostly used it to find things. The structure underneath was the one I described in 2022, a handful of numbered folders borrowed from Tiago Forte’s PARA idea and simplified, which in practice meant five numbered folders and a lot of notes that had ended up in whichever one I had open when I wrote them.

At the end of July I finally fixed it, over one weekend, with an agent doing most of the moving. The vault now has an inbox, projects (things with an outcome and an end), areas (ongoing, no finish line), ideas, resources, people, a journal, an archive and a meta folder for templates and such. They’re numbered 00 to 09 with a gap at 06, which used to be meetings. By July that folder held zero notes, because I’d moved my work notes into a separate vault last year, so we retired it. The gap stays, because renumbering would break every path that mentions a folder.

Last year’s rule was that the agent needs my approval for every edit to an existing note, and a reorg edits every note. So I made a full copy of the vault into a scratch folder first, and then the agent proposed the changes in numbered batches and I picked which to apply, which is how I review nearly all agent work now. It took most of Saturday and part of Sunday.

A schema, and views on top of it

Every note now has front matter with a required type: project, area, idea, resource, person, daily, and a few more. Projects have a status and a priority, ideas have a 1–5 score for how much they pull at me and a rough effort, and daily notes have a handful of numbers I want to see over time. (Yes, daily notes are back. The 2022 version of me gave up on them after three weeks. The difference is that now they feed something.)

The front matter matters because of Bases, the database views Obsidian added last year, which take a filter over properties and show the matching notes as a table or a list. There are ten of those views now, and the home note is mostly a dashboard of them: active projects, the inbox, ideas sorted by pull, areas I haven’t touched in a while.

We also deleted properties. A lot of notes had title, updated and tags, and nothing read any of them. The file name is the title and the file’s modified time is the modified date, so they went.

What the CLAUDE.md says

It’s about a page and a half. The first part is hard constraints, the things that would hurt if they went wrong. The vault syncs to my phone within seconds and has no git and no undo, so anything destructive starts with a copy to a scratch folder. No credential ever gets written into a note, and if the agent finds one, it replaces it with a callout saying it’s in the password manager. Don’t rename notes from the shell, because Obsidian only rewrites links when the rename happens inside the app, and a plain mv quietly breaks every link to that note. Don’t read or touch the workspace layout files, which change every time I click something.

The second part is decisions, each with a date. The 06 gap is on purpose. The deleted properties stay deleted. Git was declined. The weekly review lives in one note, and only one, which is there because the agent’s instinct is to helpfully copy it into the manual and the home note so it’s “easier to find”, and then there are three versions that drift.

An agent with no memory between sessions will reopen every decision you’ve made, forever, in good faith, unless something tells it the decision was made. Most of the file is that something. The full spec for the schema is in a separate manual note, and the CLAUDE.md points at it rather than repeating it.

The silent failures

The third part is the ways the system can break without telling anyone, which I learned mostly by having them happen.

A property that links to a note has to be quoted, like area: "[[Tech]]". Leave the quotes off and YAML reads the [[ as the start of a list, the parse fails, and Obsidian behaves exactly as if the property weren’t there. A Bases filter on a property that no note has returns zero rows, which looks exactly like nothing matching. And filters at the top of a base are combined with each view’s own filters, so a top-level type == daily makes a view of logs impossible. That one had my journal views showing nothing for about a day before I noticed.

The one I like best is about time. The reorg rewrote every file in the vault on the same weekend, so every note’s modified date is late July. The “areas I’ve neglected” view, which works by looking for old modified dates, returns nothing by construction, and will until about the end of October. It renders a perfectly normal empty table, which is what makes it dangerous, so the CLAUDE.md says so in bold.

There are also four skills, for capturing a note, a status summary, the weekly review and tidying up, which encode all the conventions above so the agent doesn’t reinvent them each time. Their source lives in the vault’s meta folder, which syncs, and gets copied into the hidden folder the agent reads, which might not.