What to move out of Obsidian, and what to leave in it
Move the notes other people rely on being true — conventions, decisions and their reasons, and anything an agent would act on. Leave everything that is thinking in progress. The test is per note, not per vault: if being wrong about this note would mislead somebody else, it has outgrown a personal tool.
The previous post argued that an Obsidian vault cannot be your AI agents’ knowledge base: it is private to one machine, its claims carry no provenance, and nothing marks a note as expired.
That argument gets agreed with and then not acted on, because “move your knowledge” is not a task anybody can start on a Tuesday. This post is the practical half. What actually moves, what stays, and what the replacement looks like once it is running.
The line, applied per note
If being wrong about this note would mislead somebody else, it has outgrown a personal vault.
Per note, not per vault. That distinction is the whole thing, and it is why this is a smaller job than it sounds. Most vaults are mostly thinking — half-formed connections, meeting scraps, things you wrote to work out what you thought. None of that moves. What moves is the minority that other people, or an agent, would act on.
In practice that has been under a fifth of the notes for everyone I have watched do it. The rest stays exactly where it is.
What moves?
Conventions. “We do migrations in two steps.” “Handlers return the error, they do not log it.” Anything phrased as we do X is a claim about the team, and a claim about the team belongs where the team can see and correct it.
Decisions, with their reasons. Not just what was chosen, but what was rejected and why. This is the highest-value category and the one most often lost, because the reasoning lives in someone’s head and the vault records only the conclusion. An agent handed the conclusion without the reason will cheerfully undo it the first time the conclusion is inconvenient.
Anything an agent would act on. If a note would change what gets written when an agent reads it, it is operational, not personal. This is the newest category and the one vaults were never designed for.
The boundaries. “We deliberately do not do X, and here is why.” Nobody writes these down and everybody rediscovers them the expensive way.
What stays?
Everything else, and that is not a consolation prize.
Half-formed ideas. Notes that are allowed to be wrong. The connection you have not made yet. Reading notes, meeting scraps, the thing you wrote at 2am that made sense at 2am. Obsidian is better at all of it than anything you would replace it with, and it is better because it has no review, no approval and no audience — the exact properties that disqualify it for the other category.
A vault that only holds this is a vault doing its job.
What about the notes that are half thinking, half convention?
The common awkward case, and the one that stalls people, because the line looks clean until you meet an actual note that is two thousand words of working-something-out with one real decision buried at the bottom.
Split it, and it is easier than it sounds. The thinking stays in the vault. The claim moves, on its own, as one sentence. Link back if you like.
What you must not do is move the whole thing. A note that is eighty per cent exploration and twenty per cent decision, sitting in the repository, teaches an agent that your team’s conventions are tentative — and an agent that thinks a rule is tentative will negotiate with it the first time the rule is inconvenient. Leaving the whole thing in the vault has the opposite failure: the twenty per cent that other people need is invisible, indistinguishable from the musing around it.
The test for whether a note is ready: can you extract a sentence that starts “we do” or “we do not”? If not, there is nothing to move yet, and the note is still doing its job where it is.
Where should the moved notes live?
Into the repository they describe. Not a wiki, not a second tool: the repo, reviewed in the same pull request as the code they are about.
That placement is doing the work. A note in the repo gets read at the moment somebody changes the thing it describes, because it is in the diff. A note in a wiki gets read when somebody goes looking for it, which is the failure mode you are leaving.
It also means the note is reviewed like code. Somebody approves it. Somebody is accountable for it. Two engineers cannot hold two contradictory versions without one of them showing up in a diff.
What does a moved note actually look like?
Format matters less than four properties, and each one answers a way the vault version failed:
- One claim per note. “We do migrations in two steps” is a note. “Notes on our backend” is a folder wearing a note’s name, and nothing in it can be confirmed, contradicted or archived independently.
- It says where it came from. The decision, the incident, the pull request. A claim you cannot trace is a claim you cannot weigh, and moving an untraceable claim into the repository relocates the problem rather than fixing it.
- It says what was rejected. The conclusion without the reasoning gets undone the first time the conclusion is inconvenient — usually by an agent, cheerfully, in a diff that looks like a simplification.
- Present tense, and specific enough to be wrong. “Be careful with migrations” is not a note, it is a mood. Nobody can act on it and nobody can ever prove it stale.
And short. The reason wiki pages go unread is that they are two thousand words when the claim is one line, and a note nobody reads is a note that does not exist — which is the same outcome as leaving it in the vault, after more work.
What does this not fix?
Moving notes into the repo fixes discovery and review. It does not fix decay, and any post that told you otherwise would be selling you something.
A note in a repository goes stale exactly as fast as a note in a vault. What changes decay is not location, it is a trigger — something that forces knowledge to be written while the person still remembers why, and something that lets a wrong note be removed by a mechanism rather than by somebody’s memory.
Those are the two properties to look for in whatever you use, and they are the two properties CommitCycle builds on: knowledge is fed at the close of a unit of work, one line at a time, when the reason is still fresh; and archived is a real state, which is what lets the corpus shrink instead of only growing more confident.
How do I start without a migration?
Do not migrate. Migrations of knowledge fail for the same reason migrations of anything fail — the effort is up front and the payoff is diffuse.
Instead: the next time you write a note that other people would rely on, write it in the repo instead of the vault. Then the next one. The vault stops growing in the category that hurts, and the corpus that matters starts accumulating in the place where it gets reviewed. Nothing is moved and nothing is lost.
For the notes whose readers are agents rather than people, the destination has a shape: a skill is a folder in the repository that gets loaded when it becomes relevant and ignored when it does not, which is the closest thing to a vault note that an agent can actually use.
After a few weeks, whatever is still in the vault and still load-bearing is a short list, and by then you will know exactly which notes are on it.
How do I know it is working?
Four signals, roughly in the order they show up:
- You stop re-explaining the same thing to each new session. This one arrives first and is the most immediately satisfying.
- Somebody corrects a note during a code review. That is the placement paying off: it means the note was read at the moment the thing it describes was being changed, which is the entire reason it went in the repository.
- An agent cites one back to you — proposing something and naming the note it came from, rather than proposing something plausible.
- Somebody archives one. This is the real signal, and it is the one that takes longest. A corpus that has only ever grown is being accumulated, not maintained, and it will end up exactly where the vault was: more confident every month and less accurate.
The counter-signal is the mirror of that last one. If the notes in the repository are growing and nothing has ever been removed, you have rebuilt the vault with extra ceremony, and the staleness is on its way back.
Where CommitCycle actually is
Worth stating plainly, because the point of this post is a line you can apply with or without us: the enforcement installs today as a plugin, and the commitcycle package on npm installs the CLI beside it. The hosted board is invitation-only while this is small.
So take the line and use it. It costs nothing, it applies to whatever tools you have, and the argument underneath it is in the previous post if you want to check the reasoning before you trust the conclusion.