Everyone handing a model their own material for the first time asks the same seven questions. All of them come back to one fact, and once that fact lands, the answers stop being matters of taste and become arithmetic you can move with a slider.
This is the misunderstanding most first implementations run aground on. People say "we'll give the AI our documentation" as though the model has it somewhere and goes to look. It does not have it and it does not look.
A model sees only the text someone handed it at the moment you asked. Everything else, the whole knowledge base, the folders, the semantic search, the vectors, is machinery for deciding what that text should be.
Once that lands, arguments about organising knowledge stop being arguments about style. They start being countable. Which is why most of what follows is a knob you can turn and watch the recommendation move.
The worked example is a real one: someone has a few hundred events from their own life and wants a base a model can genuinely use. Company documentation, an archive of proposals, meeting notes, a procedures library, all obey exactly the same laws.
The model's context window is a desk, not a library. Everything it reasons about has to be lying on that desk at once. Your entire documentation on the desk means there is no room left for the actual work, and it means every question pays for the whole archive.
A knowledge base is not about tidiness. It is about being able to put eight cards on the desk instead of the whole drawer.
What falls out of that bar: loading the whole base at once is not catastrophic on a large window. It is merely expensive on every single question, and it buries the relevant page among six hundred irrelevant ones. A good retrieval, the eight to twelve pages that actually bear on what you asked, costs almost nothing.
The real trade is not file count, it is grain: how much unrelated material rides along whenever retrieval pulls the relevant material out.
Your archive is a roughly fixed amount of writing. Splitting it does not shrink it. It changes how sharply you can cut a piece out. Coarse pages are cheap to maintain and drag noise into every answer. Fine pages retrieve cleanly and multiply the things that can drift out of date.
Where the numbers come from: this is a toy model. It assumes about 150 words of a page bear on a typical question, and that one retrieval pulls six pages. The shape of the curve is right. The exact values are illustration.
The curve has a wide flat floor somewhere around 200 to 500 words per page: one event, a few paragraphs, told once. On an archive of a few hundred thousand words that lands you at several hundred files, and that is the right order of magnitude.
Filed by year, an event has exactly one home, and every other way you will ever want to reach it, by person, by client, by theme, by the thing it caused, has just ceased to exist. That is the cost nobody sees at the moment they choose the folder tree.
Links have no such limit. A page can sit under 2016/ and still be reachable from a client note, from the person who introduced you, and from the decision it later explains. Folders are for a human skimming. Links are for finding.
| Index | Good at | Fails at | Costs |
|---|---|---|---|
| Folders by year | Human browsing, obvious ordering | Anything that is not chronology | One dimension only |
| Dated filenames | Sorting, glancing, text search | Recall by meaning | Naming discipline |
| Frontmatter | Slicing by person, place, theme | Unnamed concepts | Vocabulary drift |
| Links between pages | Neighbourhood, causation, story | Pages nobody linked | Attention while writing |
They are not rivals so much as two different answers to how do I find the right page without reading them all. Worth seeing the mechanics of both, because the mechanics decide which one fails you and when.
It cuts your writing into chunks, runs each chunk through a model that turns text into a list of numbers, and stores the result. Your question gets the same treatment, and the system returns the chunks whose numbers sit nearest yours. Nearness in that number space approximates nearness in meaning. That is the magic and also the whole problem.
Where it quietly goes wrong is the cutting. Too fine and the answer straddles the seam. Too coarse and every hit drags a paragraph of unrelated material along with it.
How to read it: the bold sentences are the two that together answer "why did this happen". The green chunk holds both, the amber one holds only half.
No numbers. A page has a name, the name appears on other pages, and the agent simply walks: read the index, open the page whose name matches, follow its links one hop out. It is what a person does in a library, done quickly. Retrieval you can read, argue with, and repair by editing one line of text.
Below, the same four questions run through three methods: plain filename search, semantic search, and the link graph.
The pattern that emerges: naming beats meaning when the thing has a name, and meaning beats naming when it does not. Questions about a person, a place, a date land the graph cleanly. Questions phrased in feelings, "the hardest year", "when I was drifting", land nowhere in a graph unless you happened to write those words down. That is the one case where vectors earn their keep.
| Link graph | Semantic search | |
|---|---|---|
| Built from | Names, links, frontmatter | Chunks and vectors |
| Setup | Writing discipline | Model, store, a whole pipeline |
| Why this hit | Readable: a name, a link | Opaque: a distance |
| Fixing a bad result | Rename, add a link | Re-chunk, re-embed, tune |
| Breaks when | You never wrote the word | The answer spans chunks |
| Scales to | Thousands of pages | Millions |
--- lines. Where date, people, place and tags live, so they can be filtered rather than read.A lint pass is worth having early: it is what catches the link you typed to a page you never created. That is the quiet way a graph hollows out from the inside.
Chat hands you text, you paste it somewhere, and every future correction is another round of copying. That is the difference and it is the whole difference: chat gives you output, an agent with file access gives you an archive it can return to.
| Surface | Reads your files | Writes them | Right for |
|---|---|---|---|
| Chat | Only what you paste | No | Thinking, settling the shape |
| Agent with file access | Yes | Yes | Converting hundreds of files, in batches |
| Agent in the terminal | Yes | Yes, plus version history | Anything you want reversible |
| Notes editor | You read | You write | Reading and writing it afterwards |
A notes editor is not a competing system, which is usually the real worry underneath this question. It is a text editor over a folder of plain files. The agent writes the files, the editor shows them to you with the links clickable, and neither owns anything. If you dropped both tomorrow the folder still opens.
The two halves of this project are not the same kind of work. Settling the taxonomy, what counts as an event, which tags exist, what a page looks like, is judgement, done once, and every mistake there is multiplied by six hundred. Turning event number 340 into a file is transcription against a settled spec.
The units are relative, these are not prices. The point is the ratio: the decisions are a sliver of the turns and nearly all of the consequences.
One mechanical caveat: switching models switches the whole conversation, not the next message. The new model inherits the transcript and carries on. That is fine going into execution, because the plan is written down by then. Going back to designing, switch back up first, because the thinking that produced a good taxonomy is not in the transcript. Only its conclusions are.
The trick is to make the agent declare its own doubt as it works, rather than leaving you to find it afterwards. Concretely: one field in the frontmatter and one queue file.
That is the shape worth insisting on, in this project and every one after it: the work is autonomous, the uncertainty is escalated, and each ruling gets written down as policy. Your attention goes only where it changes an outcome.
The last point matters most. The archive is the asset: plain files, yours, portable, readable in forty years. Every retrieval scheme built on top is replaceable machinery, and machinery is far easier to add to a good archive than an archive is to rescue from good machinery.
I build AI into small and mid-sized companies: automations, agent systems, knowledge bases a model actually uses. Things that subtract repetitive work instead of adding another tool. I also run workshops for teams, after which it is clear what can be built and what is an expensive promise.
We usually start with a short conversation about where the repetitive work sits in your week.
Get in touch