A file, a wiki, or a shared ledger?
The most common thing people say to us is that they can already do this with a markdown file, or Notion, or a small RAG stack they wired up themselves. Often they are right. Here is how to tell which case you are in.
The objection, stated properly
It usually arrives in one of three forms, and all three are reasonable.
- I have a CLAUDE.md and it works. It does. It costs nothing, it is reviewed in the same pull request as the code, and it works in any tool that can open a file.
- We keep this in Notion already. Also true. Notion is better at long-form writing than anything we will ever build, and your team is already in it.
- I could build this in a weekend with pgvector. The retrieval part, yes, genuinely. That part is not hard any more.
A sales page would now explain why all three are wrong. They are not wrong. They fail in specific circumstances, and if you are not in those circumstances the honest advice is to keep what you have. What follows is the actual dividing line, which is narrower and more concrete than the pitch usually suggests.
Three questions that decide it
Forget the storage format. Every option here stores text and every option here retrieves it. The differences that matter are three properties that have nothing to do with where the bytes sit.
1. Does anything read it without being asked?
This is the one that quietly disqualifies the wiki. Your coding agent does not open Notion before it answers you. It does not open Notion before it edits a file. If retrieval requires a human to remember that the relevant page exists and go and paste it in, the wiki is a reference library for people, which is a fine thing to be, but it is not agent memory.
The in-repo file does better here, because harnesses load it automatically. That is exactly why the pattern caught on. The catch arrives at scale: what gets loaded is the whole file, every turn, whether or not any of it bears on what you asked. That works at 40 lines and stops working somewhere around 600, when the model starts skimming your instructions the same way you would.
2. Does anything keep it true?
A file does not know when it has gone wrong. Neither does a wiki page. Neither does a vector store, which will happily return a chunk about a decision you reversed last quarter, with high confidence, because semantically it is an excellent match for your question.
Retrieval quality and truth are independent. A perfect retriever over a stale corpus returns exactly the wrong answer, quickly.
This is the failure people underestimate when they estimate the weekend build. Embedding and cosine similarity are the easy half. The half that takes real work is everything that decides whether a chunk still deserves to be returned: when the fact was last confirmed rather than last edited, whether the decision it describes has since been reversed, whether the risk it warns about was resolved by work that has already shipped.
3. Can two agents coordinate through it?
A file is a broadcast channel. Nothing in it can express somebody is already doing this. If you run one agent at a time and you are the only person on the project, that costs you nothing and this question is irrelevant to you.
It stops being irrelevant the moment there are two. Two agents on the same repository will both read the same file, both conclude the same work needs doing, and both do it. What prevents that is not better notes. It is a piece of shared state that can be claimed, where the claim is atomic and the second agent gets told no.
What the weekend build actually contains
The pgvector answer deserves a straight response rather than a dismissal, because it is correct about the part it names.
Chunk, embed, store, query by cosine distance: a weekend, and it will work. What it gives you is a store. What a project record has to be is a loop. Here is the rest of the list, which is where the time actually goes:
read something has to pull relevant context in before every prompt,
without being asked, and without flooding the window
write the agent has to record what it learned mid-task, at the moment
it learns it, not in a summary nobody reads at the end
claim concurrent agents need atomic claim on units of work, or two of
them do the same thing and one of them wins the merge conflict
age facts need to expire, retire when their task closes, and step
aside when a decision replaces them, with the old one still
readable and clearly marked
reach the same record has to be readable from a second agent, a second
machine, a review on your phone, and a tool that is not a coding
agent at all
trust somebody has to be able to ask "is this still true?" and get an
answer that is not just "it was edited recently"None of these are hard individually. All of them together are a product, and it is a product that is not the one you were trying to ship. That is the entire argument for buying rather than building, and it is the only argument we would make: not that you cannot do it, but that you would be doing it instead of your actual work.
So which one
Read this as a decision aid rather than a scoreboard. The left column wins more often than you would expect from a page on our own site.
| If this is you | Use |
|---|---|
| One person, one project, notes you can hold in your head | A file in the repo. Genuinely. Do not add infrastructure. |
| Long-form docs written for humans: onboarding, architecture essays, RFCs | A wiki. Keep it. It is better at that than a knowledge graph will ever be. |
| Retrieval over a large static corpus that does not change | Your own vector store. Staleness is not your problem, so you are not paying for a solution to it. |
| Facts that go out of date, more than one agent, and a need to know which parts still hold | A maintained shared record. This is the case we build for. |
Notice that the first three rows are not consolation prizes. Most projects are one of the first three rows, and the honest thing to say is that most projects do not need us yet.
The answer is usually both
The framing of this post is a lie of convenience. Almost nobody picks one. What actually happens is that different kinds of writing settle into different homes, and the useful question is which kind goes where.
The split that has held up for us is by shape, not by topic.
- Long-form, written for a human to read start to finish belongs in a document. Onboarding guides, architecture essays, proposals with diagrams and comment threads. A knowledge graph is a bad book.
- Small, atomic, and load-bearing belongs in a record. A single decision with its reason. A single lesson with the error string in it. A risk that expires when a specific piece of work lands. These are the things an agent needs one of, at a precise moment, and they are the things that go out of date individually.
- Instructions to the agent about how to work in this repo belongs in the repo. Build commands, conventions, the test runner. That file should be short and it should be the first thing you prune.
The unit size is the real distinction. A wiki page called Authentication can be current in three sections and wrong in a fourth, and nothing about a page can express that. When a fact is its own object, it can be retired on its own, and the rest of what you know about authentication stays standing.
What you give up by moving
Two real costs, and pretending otherwise would be the kind of thing that makes a comparison page worthless.
You take on a hosted backend. An in-repo file needs nothing, works offline, and survives any vendor going away. A hosted record does not have those properties. An open, SQLite-backed version for self-hosting is planned, and we will say so on this page when it ships rather than before.
You lose review-in-the-same-diff. When knowledge lives in the repo, a change to it shows up in code review next to the change it describes. That is a genuinely good property, and moving the record out of the tree gives it up. What you get back is that the record is reachable from things that are not the checkout, which is the trade, and which one is worth more depends entirely on how your team works.
A carefully pruned notes folder that one person keeps honest beats any system that person resents. We would rather you used the folder for another year and came back when it stopped working than pay us for something you did not need.
The signal to watch for
There is a specific moment when the folder stops being enough, and it is easy to miss because it does not look like a crisis.
It is the day you open your notes to check something and find yourself reading them the way you would read a stranger's code: not what does this say but is this still true, and how would I even tell. When that question becomes routine, you have stopped having notes and started having archaeology, and no amount of reorganising the folder fixes it, because the missing thing was never organisation.
That is the point a maintained record starts earning its keep, and what it does about it is concrete rather than aspirational. A reversed decision is retired the moment it is replaced, and it comes back marked, carrying its reason, ranked below whatever replaced it. A lesson anchored to a file arrives when somebody edits that file, in whichever agent they happen to be using. A risk bound to the task that resolves it retires itself when that task closes. Two agents cannot claim the same work.
None of that requires you to keep the record honest by hand, which is the job that quietly stopped being possible somewhere between the fortieth note and the four hundredth.