My knowledge layer started as a single file

The simplest knowledge layer in the world is a single file.

If you know what you’re doing at all, you’ve probably already got one. A CLAUDE.md, an AGENTS.md, a .cursorrules, whatever your platform calls it. A page that agents find which proclaims “Here’s the stack, here’s how I want you to work, don’t do the dumb thing again.” Once you have one, agents suddenly stop guessing about the stuff you’ve already decided and make fewer mistakes.

That’s the whole idea, in one file. Everything I’ve built is just that idea, refusing to stop growing.

Where one file stops being enough

One file works. For a while. Until it doesn’t. Mine got long. It started carrying rules for my personal stuff, rules for two different kinds of code projects, rules for when I’m planning versus when I’m heads-down building, rules for fire-and-forget tasks. All in one page the agent had to choke down whole, every session, whether the rules applied to that session or not.

So I split it. I refactored it the same way I would a monolithic method or class.

The single “always loaded” file became a thin router. Its only job now is to figure out what kind of session this is and point at the right rulebook. Personal session, dev session on a specific project, or even heavier delegation mode. Think main() that does nothing but dispatch. From there the agent loads the role’s rules, and reads the slice of the vault that matters to the work in front of it. Profile, project notes, journal, whatever the task touches.

It’s still the same move as the one-file version. Read the right context first. There’s just more of it now, and the router makes sure the agent only loads what actually matters.

Every session launches from here

This part matters more than the structure. Every session I run, personal or code, starts in this one directory.

It’s homebase. The agent boots, reads the router, takes on a role, and it already knows the room. I’m not re-explaining my projects or my preferences at the top of every conversation. The directory is the memory the model doesn’t have.

One session runs the show

At any given time I’ve usually got a few sessions open, and they’re not equal. One is the main session, and its whole job is to stay available. Like a personal assistant, or a producer.

The main session is the throughline that automates all the details that happen between tasks. It plans and decides with me, captures those decisions to the right files, and then ships the heavy or focused work off to other sessions instead of doing it itself. When one of those focused sessions wraps, the main session reviews what came back as an extra sanity check. Then it either accepts it or calmly flags any issues. It’s the only session allowed to call a task completely done.

The reason it refuses to do the heavy work is the same reason you don’t run a long job on the main thread. The trap with a capable agent is that it’ll try to do everything. The context window fills up with the guts of one big task, everything spirals. The session gets dumber and watered down right when you need it sharp. So the main session hands the expensive work to a specialized worker session built for exactly that one thing. That session launches from the same homebase, takes a role, does its job, writes its log, works with me, and wraps. The control plane stays responsive. The expensive work happens somewhere it can’t clog the part that has to stay quick.

That split is what makes running several at once workable instead of chaos. There’s one place I think and decide, and the rest is labor I farm out and review.

The sessions write back, and the agent keeps the log

Reading from homebase is only half of it. Sessions also write to it. As the agent works, it narrates what it did into dated log files: a personal timeline, and a separate progress log per project. I don’t write these. The agent does as it works. The value is higher than I expected, in two ways.

Concurrency. The main session and dedicated sessions never talk to each other directly. They coordinate entirely through the logs. Each project writes to its own dated file, so two sessions aren’t fighting over the same page (an early version had everything landing in one note, and concurrent sessions clobbered each other constantly until I split it). When I hand a task from one session to another, the brief and its activity log are the channel: one session stamps what it changed and where it stopped, the next one reads that and continues. Nothing is shared between them except files. The files are the truth, and a continuing session is told in so many words not to trust any earlier session’s memory, only what’s written down.

History. Months later, the logs are the record of what I tried, when I changed course, and why. A commit message tells you the code changed. The log tells you the reasoning that moved it. And because a future session reads those same logs, it reconstructs context I’d otherwise be re-explaining from scratch. The history isn’t nostalgia, it’s load-bearing. The agent generating it as a side effect of doing the work, instead of me writing it up after, is the only reason it actually gets written.

Three rules that keep it from rotting

A knowledge layer that drifts out of sync with reality is worse than none. You trust it and it lies. We mitigate this in the following ways:

It’s portable between platforms. None of this is locked to one agent or platform. It’s plain markdown in a plain git repo. The entry file happens to be named for the tool I use most, and the layer underneath it is just files any agent can read. If I switch tools, or run two, the knowledge comes with me. I’m not rebuilding my entire workflow because a new company makes a better agent.

It’s all intentionally hand-curated. No embeddings, no auto-summarized memory, no background process quietly deciding what’s important. I review changes and direct updates to every file myself. That sounds like more work, and it is. That’s the point. Anything generated in the background automatically drifts beneath you. A summary that’s subtly ambiguous, a hallucinated detail that is hidden in an auto-generated memory store. Hand-maintained means when it’s stale, it’s stale because I let it go stale, and I can see exactly where.

Everything is diffable. It’s markdown in git, so every change is a diff. I can see what I changed, when, and why. The agent’s “knowledge” isn’t a black box I have to trust. It’s a folder I can read and a history I can scroll. When the agent knows something, I can point at the line that told it.

The RAG question, quickly

People hear “knowledge layer for my agents” and ask if it’s RAG. It isn’t, and the three rules above are why.

RAG embeds a big pile of documents and retrieves the chunks that sound closest to your question. It’s the right tool when you’ve got an unknowable, static haystack you can’t read yourself. I don’t have that. I have a small, curated workspace I built and know cold. I don’t want the agent to retrieve what’s similar. I want it to navigate to what’s correct, the same way you’d cd to a directory instead of running a similarity search against your own filesystem. Different problem, different tool. The two can even stack, this curated layer on top routing to a retrieval index beneath, when there’s a more durable haystack of knowledge to sift through.

The short version

Start with one file that tells the agent how you work. When it gets too big, split it: a router that dispatches, roles that scope, a vault it reads from. Keep it portable, keep it hand-maintained, keep it diffable. Launch everything from it.

It’s not a clever system. It’s a directory I own, organized so an agent walks in already knowing where things are. We can do better than that someday. For now it just works.