The problem
The standard way to give an AI agent context is to paste it. You dump a doc into the prompt, or point the agent at a file, and hope the relevant part is in there somewhere. It works until your knowledge outgrows a single file. Then you are back to copy-pasting, and the agent only ever sees the slice you happened to remember.
I have a vault of around 1,500 notes in Obsidian, built up over years. The whole point of keeping them is that they connect to each other. Pasting one note at a time throws away the part that makes the collection valuable: the structure. If an agent is going to work with my notes, it should navigate them the way I do, not treat each one as an isolated blob.
That turned out to be less about giving the agent access and more about teaching it the conventions.
What is Zettelkasten?
Zettelkasten (“slip box”) is a note-taking method built on three rules.
One idea per note. Each note is small and atomic. Not “everything I know about caching,” but a single claim or observation you can link to. In my vault these are tagged idea, and there are around 1,250 of them.
Link generously. Notes reference other notes. The value is not in any single note; it is in the web of connections between them. Over time you get a graph of how your own thinking fits together.
Use index notes to navigate. When a topic accumulates enough notes, you make a Map of Content (a MOC): a hub note that points to the cluster around a subject. It is a table of contents you grow over time, so you can find your way back into a topic months later. I have about 200 of these, tagged MOC.
The result is less a folder of documents and more a personal knowledge graph. Which is exactly the thing an agent should be able to walk.
What I did not expect is how well the method fits an agent specifically. The same properties that make Zettelkasten good for a human turn out to be exactly what an agent needs. Atomic notes are retrieval-sized: one note is one idea, so a search returns a clean unit instead of a sprawling document the agent has to skim. Explicit links give it a graph to traverse instead of a keyword guess. And MOCs are ready-made entry points, a short list of doors into a topic. A human navigates this structure out of convenience. An agent needs it, because it cannot hold my whole vault in its head and has to find its way in from somewhere.
How my system actually works
Two pieces make my vault navigable: a small, consistent shape on every note, and a query that turns that shape into structure.
Every note carries a block of frontmatter at the top. The fields that matter are tags (is this an idea, a MOC, a piece of literature?), a status I track with a colored square, and related, a list of links to other notes. That related field is the load-bearing one. It is where a note declares what it belongs to.
The MOCs are where it pays off. A MOC does not contain a hand-maintained list of links. It runs a live query that, in plain terms, says: list every note that links to me. So when a note puts [[Caching MOC]] in its related field, it shows up on the caching MOC automatically. I never edit the MOC. I just point notes at it and the index assembles itself.
That is the system I wanted an agent to participate in. Not “read my files,” but “add to this graph the same way I do, and find your way around it the same way I do.”
How my agents reach the notes
There are two ways an agent could touch the vault. It could read the raw markdown files off disk, or it could go through the Obsidian CLI. I went with the CLI, and the choice matters more than it looks.
The CLI talks to the running Obsidian app, so it speaks the graph’s language instead of the filesystem’s. It can search across the vault, read a note by its name the way a link does, list what points back to a given note, and patch a single frontmatter field without rewriting the file. Reading raw files gives you text. The CLI gives you the graph: backlinks, properties, resolved links.
The agent reaches that CLI through a small skill I wrote: a document that tells the agent when to use the vault, which commands exist, and the conventions to respect. So the loop is: I ask a question, the agent decides the answer lives in my notes, and it runs CLI commands to search, read, and follow links until it has what it needs. It is not grepping a folder. It is navigating.
The one rule the skill is firm about: if Obsidian is not running, the agent should say so, not quietly fall back to scraping files off disk. The whole point is to go through the graph, not around it.
Access is the easy part
Wiring up the CLI was the simple half. The hard part is that the tools alone do not tell the agent how the graph works. The CLI will happily read a note, but it does not know that a note tagged idea is atomic and a note tagged MOC is a navigation hub. It does not know that the connections live in the related field, or that a note joins a topic by linking to its MOC. Left to its own devices, an agent will use the commands to read files like documents and miss the structure entirely, which defeats the reason the graph exists.
So the real work was writing down the conventions an agent has to follow to be a good citizen of the graph:
- How to tell the note types apart.
- Where the links live, and how to add one without breaking the existing web.
- How to explore the graph when it needs more context than one note holds.
None of that is exotic. It is the same etiquette I follow when I add a note by hand. The agent just has to be told, because the conventions are in my head, not in the files.
One concrete pattern: linking instead of duplicating
Here is the kind of convention that matters. When the agent writes a new note about, say, a caching strategy, it should not also go edit my caching MOC to add a link back. It just records the connection on the new note:
related:
- "[[Caching MOC]]"That one line is enough. Because the MOC’s query is “list everything that links to me,” the new note shows up there on its own. If the agent also tried to hand-edit the MOC, it would be duplicating a link the system already maintains, and probably formatting it slightly wrong. The convention is: state the relationship once, in one place, and let the graph do the rest.
The flip side is navigation. Those live queries are an Obsidian feature; the agent cannot run them through the CLI. So instead of pretending it can, the agent approximates the same answer with the commands it does have: it asks the CLI for the backlinks to a MOC and walks outward from there. The query and the backlink lookup arrive at the same set of notes from opposite directions, and the agent has to know to take the other road.
Takeaway
The instinct with agents is to focus on access. Give it the files, give it the API keys, give it the CLI, and assume capability follows. But a knowledge graph is not just a set of files, and the CLI that reads it is not enough on its own. It is a set of files plus the conventions that make them a graph, and those conventions are usually undocumented because you never had to explain them to yourself.
A personal knowledge graph beats dumping context into every prompt because the structure is the value. But an agent can only use that structure if you give it a way in and teach it the rules you have been following without thinking. The notes were never the hard part. The conventions were.