TL;DR

• Graph engineering now means two different things, and both definitions shipped in 2026: a graph of what the system knows, and a graph of how work flows through agents.

• They fail differently. A knowledge graph fixes wrong answers. An agent graph fixes wrong steps. Building the wrong one buys you weeks of work that does not touch your actual failure.

• The test is four questions, at the bottom of this post. Answer them before you write a schema or a state machine.

Search for graph engineering today and you get two answers that do not agree.

One set of articles tells you it means modeling your data as entities and typed relationships so a language model can traverse facts instead of guessing at them.

Another set, most of it published in July, tells you it means designing your agent system as an explicit graph: nodes are agents and tools, edges are routes, and the whole thing has shared state.

Both camps are describing something real. They are not describing the same thing.

I wrote the field guide that defines the term and I have watched the second meaning arrive over the last six weeks. This post is not a referee call about who owns the word. It is the thing neither camp gives you: a way to tell which one your problem is, before you spend a month building the wrong grap

Definition one: a graph of what the system knows

In this version, the nodes are things. A person, a project, a decision, a document, a customer. The edges are typed relationships between them: this decision supersedes that one, this person owns that project, this bug blocks that release.

You build it because retrieval by similarity keeps failing you. Vector search finds text that reads like your question. It cannot follow a chain. Ask which decisions are now dead because of a call made in March and similarity search returns three notes that mention March.

A knowledge graph answers that by walking edges. The value is the walk, not the storage.

This is the definition with the longer history. Knowledge graphs predate language models by decades. What changed in 2026 is that the graph stopped being a database problem and became a retrieval problem, which is why GraphRAG turned into a common pattern rather than a specialist one.

Definition two: a graph of how work moves

In this version, the nodes are workers. An agent, a tool, an evaluator, a human approval step. The edges are routes: after this step, go there, unless the check fails, in which case go back.

You build it because a single agent loop stopped being enough. One agent with a long prompt and twelve tools works until it does not, and when it breaks you cannot say where. Turning the loop into an explicit graph gives you named steps, typed transitions, and a place to put a retry.

This is the definition that showed up loudly in July. It is close to what workflow engines have done for years, and several writers in this camp say so themselves. That does not make it empty. The new part is that the nodes are non-deterministic, so the edges carry more weight than they used to.

Subscribe now

Why one term ended up with two meanings

Two groups needed a word in the same year.

The retrieval people had a problem with knowledge: the model cannot find what it needs, so it makes something up. They reached for graphs to make knowledge walkable.

The orchestration people had a problem with control: the model does the wrong thing in the wrong order, so nobody can debug it. They reached for graphs to make control explicit.

Both problems get solved by drawing nodes and edges. So both got called graph engineering. Nobody did anything wrong here. New fields collide on vocabulary before they settle, and this one is still being settled in public. The pieces arguing for the second meaning are dated July and August of this year.

The cost is not linguistic. The cost is that a builder reads the wrong article, recognizes the shape of the diagram, and starts building.

The test: four questions

Answer these before you build anything. They take five minutes.

1. When it fails, is the output wrong or is the path wrong?

Wrong output means the system had bad or missing information. That is a knowledge problem. Wrong path means the system had the information and did the wrong thing with it. That is a topology problem.

Read your last ten failures and sort them into those two piles. The bigger pile picks your definition.

2. Does it fail the same way twice?

Run the failing case again. If it fails identically, something in what the system knows is wrong, and it will be wrong every time. If it fails differently, or works on the second run, the problem is in how the work moved: a timeout, an order, a tool that returned early.

Repeatable points at knowledge. Variable points at topology. This is the fastest of the four and most people never run it.

3. Which path can you not draw today?

Take one real failure. Try to draw the route the answer took through your data. Then draw the route the run took through your code.

Whichever one you cannot draw is the one you have not engineered yet.

4. What happens if you double one thing?

Double your documents. If quality drops, your problem is knowledge. Double your steps or your tools. If reliability drops, your problem is topology.

Most systems eventually need both. Almost nobody needs both first.

The same failure, run through the test

An agent answers questions about your own project history. Someone asks why a library got dropped last quarter. It returns a confident answer citing the document that argued for keeping it, because a later decision reversed that one and nothing in your store says so.

Output is wrong, not path. It fails the same way every time. You can draw the route the run took through your code and you cannot draw the route the answer took through your data. Double the documents and it gets worse.

Four for four on the knowledge side. The fix is one edge: the newer decision points at the older one and says it replaced it. No amount of orchestration would have helped.

Now change one detail. The agent finds the reversal, calls a summarizing tool that truncates it, and answers from half a decision with no error raised. Same question, different answer on a rerun, and you cannot say why the run continued after a short read. That is topology, and the fix is also one edge, this time a route: after that tool, verify, and stop if the check fails.

What each mistake costs

Building the wrong graph is not a small detour. Both mistakes are expensive in the same specific way: you get a working system that does not touch your failure.

Building a knowledge graph when the problem was topology. You spend weeks on an ontology. Entity resolution eats another week, because deciding that two names are the same person is genuinely hard. You ship it. Retrieval gets sharper. Your agent still calls the wrong tool at step four and still cannot recover from a timeout, because none of that was ever about knowing things.

Building an agent graph when the problem was knowledge. You split one loop into nine nodes with typed edges and a state schema. Every run is now traceable. You can see exactly where it went. It goes to the right node, retrieves the wrong context, and produces a confident wrong answer with a beautiful trace attached.

The second mistake is worse, because observability feels like progress. You can watch the failure in high definition for a month before admitting it never moved.

Where the two actually meet

They meet at state.

A knowledge graph is state at rest: what is true, how it connects, what replaced what. An agent graph is state in motion: what this run has done, what it holds now, where it can go next.

That is why the same drawing works for both, and why the confusion was inevitable.

In my own system the split is literal. The vault is the knowledge graph. Edges live in frontmatter as typed fields, so a machine reads them without parsing prose, and a superseded note points at the note that replaced it instead of quietly disagreeing with it. I wrote up the five steps I use to keep those edges honest separately.

The agent side is deliberately thin. A handful of scheduled agents, each with one narrow job, and nothing orchestrating between them. That is still a topology decision, just a very small one, because my failures were almost all knowledge failures.

The repo that runs it is obsidian-second-brain, MIT licensed, about 3,900 stars as of this week. Six months of running it produced the same lesson the test above encodes: I built structure where the failures were, and left the other side small until it earned the work.

Subscribe now

What I would tell you if you only read one line

Do not pick the definition that matches the article you found. Pick the one that matches your last ten failures.

The term will settle eventually. Your rebuild will not un-happen.

Frequently asked questions

What is graph engineering?

Designing the graph structure a language model system depends on. As of 2026 the word covers two structures: a graph of what the system knows (entities and typed relationships) and a graph of how the system works (agents, tools, and routes between them).

Is graph engineering the same as GraphRAG?

No. GraphRAG is one retrieval pattern that walks a knowledge graph and combines it with vector search. Graph engineering in the knowledge sense is the design work that makes such a graph worth walking. GraphRAG is a consumer of it.

Is graph engineering just workflow orchestration with a new name?

In the agent-topology sense, it borrows heavily from workflow engines and the people writing about it usually say so. The difference is that the nodes are non-deterministic, so edges carry retries, checks, and stopping rules that a deterministic pipeline never needed.

Do I need a graph database to do graph engineering?

No. My knowledge graph is markdown files with typed fields in frontmatter. A graph database earns its place when traversal is your bottleneck at scale, not when you are figuring out which edges matter.

How do I know which definition applies to my project?

Sort your last ten failures into wrong-output and wrong-path piles. Wrong output points at knowledge. Wrong path points at topology. The four questions in this post do this in more detail.

Can a system need both kinds of graph?

Yes, and mature systems usually do. Almost none need both at the start. Build the side your failures live on, keep the other side to a few rules, and let it grow when it earns the work.

Key takeaways

• Graph engineering has two live definitions in 2026: a graph of what the system knows, and a graph of how work moves through agents.

• Knowledge graphs fix wrong answers. Agent graphs fix wrong steps. The distinction is what your failures look like, not what your stack looks like.

• Sorting your last ten failures into wrong-output and wrong-path piles picks your definition faster than any article can.

• The expensive mistake is an agent graph built for a knowledge failure, because full traceability feels like progress while the failure sits untouched.

• Both graphs are about state, one at rest and one in motion, which is why the same diagram fits both and why the term split in the first place.

• Build the side where your failures live, keep the other side to a few rules, and let it grow when it earns the work.

Further reading

• What is graph engineering? A field guide for builders - the definition post this one builds on.

• How to do graph engineering in a markdown vault - the five steps, with the edge taxonomy I use.

• Karpathy’s LLM Wiki v2: what to keep, what to skip - where the knowledge-graph side of my vault came from.

• GraphRAG in its original form: the Microsoft Research paper From local to global and the project documentation.

• The agent-topology camp, in their own words: Graph engineering for AI agents and a complete guide in LangGraph.

About the author

Eugeniu Ghelbur builds production AI agent systems and the tooling around them. He maintains obsidian-second-brain, an open-source Claude Code skill that runs an Obsidian vault as a living knowledge system, starred by over 3,900 developers on GitHub and MIT licensed. He writes The AI Operator, where this post first appeared.

TL;DR

• An agent harness is everything around the model: instructions, tools, memory, feedback loops, and guardrails.

• Same model, different harness, different agent. The harness now explains more of the result than model choice does.

• Every part below is a general pattern first. My open-source second brain is the worked example, running in public.

Ask a builder which model runs their agent and you get a fast, confident answer. Ask what harness it runs in and you often get a pause.

That pause is closing fast. Anthropic’s own docs describe Claude Code as an agentic harness. OpenAI published a post titled “Harness engineering.” One line from the discourse stuck with me: 2025 was the year of agents, 2026 is the year of agent harnesses.

So the term is everywhere. What is missing is a real one you can open and read. Definitions are cheap. Working harnesses are not.

I have been doing harness engineering for six months without calling it that. This post is the definition, the five parts every working harness has, and the one I run in public so you can check every claim.

What an agent harness actually is

An agent harness is the execution layer wrapped around a language model. It decides what the model sees, which tools it can call, what it remembers between sessions, and what it may do without asking a human.

The formula that makes it click: agent = model + harness. The model provides reasoning. The harness provides everything else. Remove the harness and you do not have an agent, you have a chat window.

A harness is not a framework. A framework is where you write agent logic. A harness is the envelope your agent runs inside: state, permissions, tool access, recovery. Claude Code is a harness. Codex CLI is a harness. The layer you build on top of them is also a harness, yours.

One more boundary, because the term gets overloaded. Benchmark scaffolds like the ones behind SWE-bench are evaluation harnesses. This post is about runtime harnesses, the kind that do real work every day.

The five parts of a working harness

Strip any serious harness down and you find the same five parts. Here they are, each with the general pattern first and my public implementation second.

1. Instructions. The standing orders the model loads before any task: conventions, boundaries, definitions of done. In practice this is a CLAUDE.md or AGENTS.md file. Mine is public, and I wrote up what belongs in a CLAUDE.md after watching 3,000 developers run one.

2. Tools. The actions the model can take: scripts, commands, APIs. The pattern that holds up is a small, purposeful surface. A model with 400 tools picks badly. A model with 12 sharp ones picks well.

3. Memory. What survives the session. The general pattern: durable state in plain files the agent both reads and writes, not a black-box store. In my system that is an Obsidian vault, and the retrieval side is a recall budget, not a database: four notes per prompt, abstain when unsure, fail closed.

4. Feedback loops. Deterministic checks the model must pass before its output counts: linters, tests, structure gates. The model drafts, the gate rejects, the model fixes. This is where output quality actually comes from.

5. Guardrails. What the agent may never do without a human. Permission prompts, content firewalls, hard rules like “never publish, only draft.”

None of these parts is glamorous. Together they are the difference between a demo and a system.

What harness engineering looks like in practice

Harness engineering is the discipline of building and tuning that envelope. The core principle, now showing up in research papers: code owns the control flow, the model gets called at the reasoning steps.

The post you are reading came out of a harness. A research script pulled live sources and keyword volumes. A voice linter rejected every AI-tell phrase. A structure script checked the title length, the word count, and every section against a locked checklist before the draft counted as done.

Notice what the model did in that pipeline: it wrote prose. Everything else was code, written once, enforced every run. When the output misses, I do not tweak a prompt and hope. I tighten a gate, and the fix holds forever.

The same principle runs my vault. Search respects supersedes chains, so an agent asking for the current decision never retrieves a confidently stale one. Scheduled agents reconcile contradictions overnight. Six months of running it taught me what to keep and what to skip from the patterns everyone quotes.

That is harness engineering: fewer heroic prompts, more boring gates that compound.

Subscribe now

But the model is all that matters, right

The strongest counter-argument deserves a fair hearing: models improve so fast that harness work is a wrapper, obsolete by the next release.

Three things break that argument in practice.

First, the benchmark evidence points the other way. The same model scores differently depending on the scaffold around it. If harnesses were neutral wrappers, that variance would not exist.

Second, model upgrades raise the ceiling. The harness decides how much of the ceiling you reach. A stronger model in a harness with no memory and no gates just produces confident mistakes faster.

Third, and this is the part the wrapper argument misses completely: the harness is where your context lives. Your conventions, your history, your definitions of done. No lab will ever ship that, because it is yours.

To be fair to the other side: a weak model in a great harness is still a weak agent. The harness multiplies the model, it does not replace it. But you rent the model. The harness you own.

How to start building yours

You do not need a platform or a framework migration. You need five unglamorous moves, in this order.

1. Write the instructions file. One page: conventions, boundaries, what done means. This alone changes agent behavior more than any prompt trick.

2. Give it memory in plain files. A folder of markdown the agent reads and writes beats a vector store you cannot inspect.

3. Add one deterministic gate. A linter, a test suite, a checklist script. Make the agent pass it before output counts.

4. Set the guardrails. List what the agent must never do unattended, and enforce it in code or permissions, not in hopes.

5. Only then automate loops. Scheduled runs, background agents, self-checks. Loops amplify whatever exists, including the flaws.

And the boundary, so this stays honest: do not build a harness for a task you run twice. A good prompt in a bare CLI is the right tool for one-off work. The harness pays off on the tasks you repeat every week, because every gate you add keeps paying.

The model in my harness will be replaced many times. The harness is the part that compounds.

Frequently asked questions

What is an agent harness?
The execution layer around a language model that turns it into an agent: instructions, tools, memory, feedback loops, and guardrails. The model reasons; the harness decides what it sees, what it can do, and what persists.

What is the difference between an agent harness and an agent framework?
A framework is where you write agent logic, like LangGraph or the OpenAI Agents SDK. A harness is the runtime envelope the agent operates inside: state, permissions, tool access, recovery. You often use both, and the harness is the layer that touches production.

Is Claude Code an agent harness?
Yes. Anthropic’s own documentation describes Claude Code as an agentic harness: the tools, context management, and execution environment that turn the model into a coding agent. Codex CLI and similar tools sit in the same category.

What is harness engineering?
The discipline of designing that envelope: choosing tools, structuring context and memory, writing deterministic gates, and setting stop conditions. Code owns the control flow; the model is called at the reasoning steps.

Do I need to build my own agent harness?
If you use an agentic CLI, you already have one, and every CLAUDE.md rule or hook you add is you engineering it. Building your own layer on top pays off once you repeat the same class of work weekly and need memory and gates the stock harness does not ship.

What is the difference between a runtime harness and an evaluation harness?
A runtime harness runs real work every day, like Claude Code or the system in this post. An evaluation harness, like a benchmark scaffold, exists to measure a model on a fixed task set. Same anatomy, different purpose.

Key takeaways

• An agent is a model plus a harness. The model reasons; the harness supplies instructions, tools, memory, feedback loops, and guardrails.

• A framework is where you write agent logic. A harness is the envelope the agent runs inside. Claude Code itself is a harness, and you can build yours on top.

• Feedback loops are where quality comes from: deterministic gates the model must pass, written once, enforced on every run.

• The “just a wrapper” argument fails because the same model performs differently in different harnesses, and because your context lives in the harness, not the model.

• Build order matters: instructions file, plain-file memory, one gate, guardrails, and only then automated loops.

• You rent the model. You own the harness. Only one of them compounds.

Further reading

• The importance of agent harness in 2026 - a clear practitioner’s take on why the harness layer decides agent performance.

• What makes a harness a harness - the research paper pinning down necessary and sufficient conditions for an agent harness.

• Harness engineering, on the OpenAI blog - OpenAI’s post on the discipline from the lab side. (URL to verify: openai.com/index/harness-engineering/)

• How I gave Claude Code memory without a vector DB - the memory part of my harness, in full detail.

• obsidian-second-brain on GitHub - the open-source harness this post dissects, MIT-licensed.

Subscribe now

About the author

Eugeniu Ghelbur writes The AI Operator, a publication about practical AI systems. He maintains Obsidian Second Brain, an open-source system starred by over 4,000 developers on GitHub. The writing here comes from building and maintaining that public system.

TL;DR

• Graph engineering is making the relationships between your notes explicit enough that an AI agent can traverse them, not just read them.

• Plain wikilinks say two notes are related. They never say how. Typed edges, supersedes chains, a graph lint, and a bounded recall budget close that gap.

• Every step below is a general method first. My open-source vault system is the worked example, running in public.

In the graph engineering field guide I defined the term: structuring knowledge as nodes and explicit relationships so agents can answer chain questions. Who decided this. What replaced it. What broke because of it.

That post ended with a claim: a vault of linked markdown is already 80% of a graph index. This post is the missing 20%, as a build sequence you can copy.

One boundary first. “Graph engineering” also gets used for wiring multi-agent workflows, nodes as agents, edges as routing. That is a different discipline with its own tooling, and this post is not about it. This is about your knowledge.

Step 1: choose a small edge taxonomy

The principle: name the relationship types you will actually need to traverse, and keep the list small. Every type needs an inverse, or your graph only reads one direction.

Ask one question per candidate type: will an agent ever need to follow this to answer a real question? If not, it does not earn a place.

In my vault system, obsidian-second-brain, the answer settled at six types: supersedes, depends_on, caused, decided_by, contradicts, and a generic relates_to. Each carries an inverse (superseded_by, required_by, caused_by, decides). Six survived because agents kept needing them. A dozen others did not.

To pick your own set, work backwards from questions, not from ontology. Write down the five questions you actually ask your notes (”what is the current decision on X”, “what breaks if we change Y”), then keep only the edge types those questions traverse. A type you cannot attach a real question to is decoration.

And resist the generic type. Everything can be relates_to, which is exactly why it carries almost no signal. Use it only when nothing sharper is true.

Step 2: put edges where machines read them

The principle: a relationship buried in prose is invisible to traversal. Edges live in structured metadata, stated once, in a place a parser reaches without reading the whole note.

In markdown that place is frontmatter. This is the entire syntax in my system:

relations:
  supersedes: ["[[ADR-006 - Use Redis]]"]
  depends_on: ["[[Tide Gateway]]"]
  caused_by: ["[[Redis outage 2026-03]]"]

Nothing here needs a graph database. The nodes are files. The edges are three lines of YAML. Any tool that parses frontmatter can now walk decision chains in either direction.

Two traps to skip. First, relationships stated only in prose (”this replaces our earlier Redis decision”) feel recorded but are unreachable: an agent would have to read and correctly interpret every sentence in the vault to find them. Second, tags are not edges. A tag groups notes; it has no direction, no target, and no meaning an agent can follow.

You also do not need to retrofit the whole vault on day one. Start writing edges on new notes and on any old note you touch. The graph grows along the paths you actually use, which is also the order in which it pays off.

Subscribe now

Step 3: make truth supersede, not accumulate

The principle: in a knowledge graph that lives for months, the dangerous notes are not the wrong ones. They are the formerly right ones. Without an explicit “this replaces that” edge, an agent retrieves the old truth with the same confidence as the new.

So every decision that reverses an earlier one carries a supersedes edge, and retrieval must respect it: the superseded note steps back in search results instead of competing with its replacement.

This is the single highest-value edge type. In my vault, search honors supersedes chains and fades notes marked declined or archived, so an agent asking “what is our current approach” gets the current approach.

Step 4: lint the graph like code

The principle: a graph nobody validates rots quietly. Edges point at renamed notes. Cycles appear. Inverses go missing. None of it is visible while you write, all of it corrupts traversal later.

So the graph gets a linter, run the way you run tests. Mine flags five failure classes: unknown edge types, dangling targets, self-edges, supersedes cycles (A replaces B replaces A), and missing inverse edges. It runs inside the vault health check, and a typed edge pointing at a note that does not exist is an error, not a suggestion.

If you build only one piece of tooling from this post, build the lint. It is the difference between a graph and a pile of arrows.

Step 5: give agents a traversal budget

The principle: an agent with unlimited graph access does not get smarter, it drowns. Traversal needs a budget: how many nodes per question, what confidence justifies including one, and what happens on a miss.

My numbers: at most 4 notes injected per prompt, abstain when relevance is unsure, fail closed when retrieval errors. I wrote up the reasoning in how I gave Claude Code memory without a vector DB: memory as a recall budget, not a database. The graph makes the budget spend better, because a typed edge is a reason to include a note, not just a similarity score.

When a loop beats a graph

The strongest advice in the practitioner literature is also the least exciting: keep it a loop first. A vault with thirty notes does not need an edge taxonomy. A workflow that reads three files does not need traversal.

Graph engineering earns its cost when chain questions start failing. Three concrete signals, in the order they usually appear:

1. “What is the current approach” returns a superseded answer with full confidence.

2. “Why does this exist” needs more than one hop, and the agent stops at hop one.

3. Two notes contradict each other and nothing in the system knows they are even related.

I hit that wall around month four of running an AI-maintained vault, documented in Karpathy’s LLM Wiki v2: what to keep. Until you hit it, plain links are fine.

What is still missing

Honesty section. Two pieces of my own 20% are not finished. Multi-hop traversal queries (follow depends_on two levels out) work only as manual link-following, not as one retrieval call. And I have not yet published measured recall numbers for graph-aware retrieval against flat search on the same vault. The eval harness exists in the repo; the benchmark post is future work, and I would rather ship the method now and the numbers when they are real.

That is the practice: four buildable pieces, one boundary, one budget. The graph is not the product. The answers are.

Frequently asked questions

What is graph engineering?
Structuring knowledge as nodes and explicit typed relationships so AI agents can traverse chains (what replaced X, what depends on Y) instead of only matching similar text. The full definition is in the field guide linked above.

Do I need a graph database like Neo4j to do graph engineering?
No. Markdown files as nodes and frontmatter YAML as edges give you a working graph index. A dedicated graph database matters at a scale most personal and team vaults never reach.

What are typed edges in a knowledge graph?
Relationships with a named meaning and direction, like supersedes or depends_on, instead of a bare link. The type is what lets an agent follow the right edge for the question it was asked.

How is this different from GraphRAG?
GraphRAG extracts entity graphs from documents automatically at retrieval time. Graph engineering as practiced here writes the edges at authoring time, where the author still knows the relationship. The trade is a little discipline for much higher edge precision.

How do AI agents actually use a markdown knowledge graph?
Through retrieval that respects the edges: superseded notes step back, dependency chains resolve in order, and a bounded number of the most relevant notes gets injected into the agent’s context.

When should I not build a knowledge graph?
When chain questions are not failing yet. Small vaults and short-lived projects do better with plain links and a search tool. Add edges when the wrong-old-answer problem shows up.

Key takeaways

• A linked markdown vault is 80% of a graph index. The missing 20% is typed edges, supersedes chains, a graph lint, and a recall budget.

• A plain wikilink says two notes are related. A typed edge says how, and direction plus inverse is what makes traversal possible.

• The supersedes edge is the highest-value relationship type: it is the difference between retrieving current truth and retrieving confident stale truth.

• Lint the graph like code. Dangling targets, cycles, and missing inverses corrupt traversal silently until a validator makes them errors.

• Agents need a traversal budget, not unlimited graph access. Four notes per prompt with abstention beats a context window full of maybes.

• Do not graph-engineer three notes. Add the machinery when chain questions start returning stale answers.

Further reading

• What is graph engineering? A field guide for builders - part 1: the definition, the evidence, and the viral fake study that started the discourse.

• We are entering the graph engineering phase - the post that put the term in circulation.

• GraphRAG and multi-hop question answering - research grounding for where graphs beat vector retrieval.

• obsidian-second-brain on GitHub - the open-source implementation every step above ships in, MIT-licensed.

Subscribe now

About the author

Eugeniu Ghelbur writes The AI Operator, a publication about practical AI systems. He maintains Obsidian Second Brain, an open-source system starred by over 3,700 developers on GitHub. The writing here comes from building and maintaining that public system.

• After writing a test for a fix, I started deleting the fix and running the test again. If it still passes, the test is decoration. Five of mine were, in one sitting.

• The same habit caught a benchmark scoring 83% because every question was written inside its own answer, and a feature I had gated so carefully it would have run for nobody.

• The genuinely damaging bug was the one no benchmark caught: 29% of my notes had silently fallen out of the search index, and the score never moved.

I maintain obsidian-second-brain, an open-source tool with about 3,600 stars. It is the same project 1,374 strangers cloned before I had written a single test for it. I recently ran a full audit. Security, correctness, dead code, retrieval quality, all of it. 138 findings. I have closed 135.

The bugs themselves are ordinary. The interesting part is a habit I picked up partway through, which is that after writing a test for a fix, I revert the fix and run the test again.

It caught more than I expected. None of what follows shipped. All of it would have, with a green suite and a clear conscience, if I had trusted the green.

Reverting the fix

The rule is one line: if a test passes with its fix removed, the test is decoration.

I expected the occasional slip. I got five in the first session, in three distinct shapes.

The test asserted the wrong property. I had made a file write atomic. Write to a temp file, then os.replace. My test checked that the resulting file kept its original permission bits. It passed with the fix reverted, because a plain write_text preserves mode bits too. Real test, real assertion, nothing to do with atomicity.

The fixture never reached the code path. I fixed a freshness check meant to fire on notes with no “as of” date. My fixture note had an “as of” date in it. The check never ran. Green.

The code did not do what it reads like. path.lstrip("./") does not strip a leading ./. It strips any leading run of . and / characters in any order. My test used a path where the two happened to agree.

None of these survive a revert. None of them would have been caught by review either, because all three diffs look correct.

The benchmark that read its own answer key

This is the one I would most want someone to tell me about.

My project searches a folder of markdown notes, and I have a rule attached to it: no change to search ships without before-and-after numbers. Useful rule. It had also only ever run against my own private notes, which means every number I published was a claim nobody could reproduce.

So I built a synthetic corpus. 300 generated notes, fixed seed, a hash so two people can confirm they measured the same thing, and three query sets: exact keyword, English paraphrase, and the same descriptions in Spanish and Russian against English notes.

The paraphrase set is the hard one. The query deliberately avoids the words in the answer.

First run, pure keyword search scored 83% on it.

That is a suspicious number for a set built to defeat keyword search. The generator wrote each note’s summary as <title> is <description>, and the description was the exact text of that note’s paraphrase query. Every query was sitting inside its own answer.

Deleting one line dropped the score from 83% to 25%.

Both are real measurements of a real system. One is a measurement of the answer key.

The feature I built so carefully it would have run for nobody

Smaller, and it has stuck with me.

I added a prompt that asks once, ever, whether you might star the repo. It fires only after something good and visible happened. A vault gets created, or a health check comes back with zero issues. Once per machine. Suppressed under CI. Suppressed by an environment variable. Never on a machine-readable output path.

I also gated it on stdout.isatty(), so it would not fire into a pipe.

In this project the scripts are almost always run by an AI agent on the user’s behalf. Stdout is a pipe essentially every time. The person still reads every line, in their terminal, in the agent’s transcript.

So the careful version would have fired for exactly nobody, while looking thorough in review and passing its tests. The tty check felt like rigor. It was a way of doing nothing safely.

There is now a test asserting the prompt still fires with stdout captured. Strange-looking test until you know why it exists.

Subscribe now

The bug that was not the bug I named

One finding stayed open longest. On my multilingual query set, recall at 5 and recall at 10 were both exactly 0.625. Identical. Widening the window recovered nothing, so six of sixteen target notes were not ranked low. They were nowhere.

I called it the highest-value problem in the system and treated it as a cross-language failure. Three attempts to fix it by reweighting the ranking all failed, each costing something elsewhere.

Then I looked at what the six actually were. Not six failures. Three topics, each asked once in Russian and once in Spanish.

If cross-language alignment were the problem, Russian and Spanish would fail on different topics. So I translated the three into English and asked again.

Ranks 176, 22 and 38. No better. One materially worse than its Spanish version.

Never a language problem. Then I measured the thing I should have measured first: how much closer each target needed to be to reach the top ten. Between 0.009 and 0.071 in cosine distance. The entire spread between the first and tenth result is 0.02 to 0.04.

Four of the six need a correction larger than the whole visible range. Any weight big enough to rescue one scrambles the top ten of every other query in the vault.

That is not a bug I failed to fix. It is a bug that cannot be fixed the way I was trying, and one number would have said so on day one. I shipped the tool that prints that number, so the next person spends their afternoon somewhere better.

What was actually broken while I stared at rankings

The damaging bug was next door, and no benchmark caught it.

Semantic search reads a vector index. The index is built on demand and never invalidates itself. My README told people to build it once.

My vault had 1,828 notes. The index had 1,303. 29% had no vector at all, and nothing anywhere said so.

That sounds like a staleness nit and is worse than one. An unindexed note is still findable by literal word match, so on English queries the keyword half quietly covers the gap and you never notice. On a query in another language the keyword half contributes nothing, so those notes are not ranked low. They are unreachable. It is a quieter version of the problem I wrote about in your notes are a graveyard: the note is there, and nothing can reach it.

My benchmark scored exactly the same before and after I rebuilt the index, because every target in it happened to already be indexed.

A flat number is not evidence that nothing is wrong. It is evidence that your measurement did not look there.

What I would keep

None of this is about being careless. Every one was caught, by a cheap habit, before it reached anybody. The point is that a passing test is a much weaker signal than it feels like, and we have built almost no habits around checking the checkers.

Revert the fix, run the test. Cheap, fast, five fake tests in one sitting. If a test passes without its fix, delete it or rewrite it. A green assertion that proves nothing is worse than no test, because it occupies the space where a real one would go.

Be suspicious of a good first number. 83% on a set built to be hard was the loudest signal I got all month and I nearly banked it. A result that arrives easier than expected is a hypothesis about your instrument, not your system.

Ask what your measurement cannot see. A benchmark that does not move is not the same as a system that is fine. Mine was blind to a defect costing real users whole notes.

The audit is open at three items. Findings, dates and fixes are all in the repo, and the retrieval benchmark generates in one command if you want to point it at something of your own.

Subscribe now

Frequently asked questions

Is reverting the fix the same as mutation testing?
Same idea, done by hand at the one point that matters most. Mutation testing perturbs the code automatically and scores how much your suite notices. This is one deliberate mutation, the removal of the exact fix, run at the moment you are most likely to be fooled.

Is this not just test-driven development?
TDD gives you the same signal for free, if you actually watch the test fail first. These five all came from a fix written before its test, which is what most bug fixing looks like in practice. The revert is how you recover the red you skipped.

Does this not double the time to write a test?
It adds seconds. Revert, run, restore. Against that, all five of these would have shipped as permanent green assertions protecting nothing.

Why not just review the test more carefully?
All three shapes above look correct in review. That is what makes them dangerous. lstrip("./") reads exactly like the thing it is not.

Can I run the retrieval benchmark?
Yes. One command generates the corpus, the seed is fixed, and it prints a hash so you can confirm you measured the same thing I did.

Key takeaways

• If a test passes with its fix reverted, it is decoration. Delete it or rewrite it.

• The check costs seconds and it is the only one that tells you whether a test is load-bearing.

• A result that arrives easier than expected is a hypothesis about your instrument.

• A benchmark that does not move is not proof the system is fine. It may just not be looking.

• Publish measurements other people can reproduce, or they are claims.

Further reading

• obsidian-second-brain, the project and the full audit trail

• The retrieval benchmark, corpus generator, baseline and known limitations

• The AI-First note spec, 50 lines you can paste into any agent’s instructions

• I rebuilt Karpathy’s LLM Wiki, where the search this post measures came from

About the author

Eugeniu Ghelbur builds AI tooling and writes The AI Operator. He maintains obsidian-second-brain, an open-source AI second brain starred by over 3,600 developers, and writes up what holds and what breaks when these systems run against real work.

• Search “claude code second brain” and you get ten tutorials that all show the same setup: drop an Obsidian folder in, add a CLAUDE.md, done. It works, for about a week.

• The hard part is not the setup. It is what a second brain has to do to survive past a few hundred notes: retrieve across notes, stay current, and maintain itself.

• I maintain obsidian-second-brain, a Claude Code skill 3,400+ developers use for exactly this. Here is the part the tutorials skip.

Type “claude code second brain” into Google and you get a wall of how-to posts. They are not wrong. They all show the same thing: put your Obsidian vault in a folder, run Claude Code from it, write a CLAUDE.md, and now the model can read your notes.

That setup is real and it does work. For about a week.

Then you hit the part none of the tutorials cover, because they were written after a weekend, not after a year. I have run this daily for over a year and shipped the tooling for it in the open. This post is month six, not minute one.

The setup everyone shows

Credit where it is due, the basic loop is genuinely good.

Obsidian notes are plain markdown on your disk. Claude Code reads and writes files. Point one at the other and the model can create notes, edit them, and follow a CLAUDE.md instruction file. Cole Medin’s second-brain-starter and a dozen Substack guides all land here, and it is the right place to start.

The problem is that this is a demo, not a system. A demo answers “can Claude read my notes?” A system answers “will this still work when I have 3,000 notes and half of them are stale?”

Those are different questions. The gap between them is where every second brain quietly dies.

Where it breaks

Three things go wrong, and they all show up around the few-hundred-note mark.

Retrieval gets noisy. With 50 notes, Claude reading “everything” is fine. With 2,000, dumping the vault into context is impossible, and naive search pulls ten notes that mention a word but miss the one that answers the question. The tutorial setup has no real retrieval, just “read the files.”

Here is the kind of question that exposes it. Ask your vault “why did we drop the old billing provider?” The answer lives in three notes: the decision, the thing it replaced, and the incident that triggered it. Naive search pulls every note that mentions billing and misses the causal chain entirely. You get ten fragments and no answer.

The vault goes stale. You change jobs. A decision gets reversed. A tool you swore by gets dropped. The old note does not delete itself. Six months in, your second brain confidently cites the version of you from March, and you have no idea which half is current. This is the quiet failure, because it does not look broken. It looks like a confident answer that happens to be wrong.

Nothing maintains it. A real brain prunes, connects, and reconciles. A folder of markdown does none of that on its own. Without maintenance, entropy wins, and the thing you built to reduce your mental load becomes another mess you have to manage.

What a second brain actually has to do

Strip away the hype and a working second brain has four jobs, not one.

Capture with almost no friction, so you actually use it. Retrieve across notes, so it can answer questions whose answer lives in three places at once. Stay current, so it knows what is still true and what got superseded. And maintain itself, so it gets better while you sleep instead of rotting.

The tutorials give you job one and a weak version of job two. Jobs three and four are the entire difference between a note folder and a second brain. They are also the boring, unglamorous work nobody puts in a “build a second brain in 10 minutes” video, because they take longer than 10 minutes.

Subscribe now

Own it or rent it

There is a second question the tutorials skip: who holds your memory.

Claude now ships built-in memory, and it is genuinely convenient. But it has three properties I could not live with. It lives on someone else’s server. It lives inside one product. And I cannot open it, read it line by line, and correct a wrong fact.

A file-based second brain is the opposite trade. It is plain markdown on your disk. You can read every fact, fix the wrong ones, and move the whole thing to a different model next year when a better one ships. You give up the one-click convenience and you get ownership that outlives any single vendor. For something meant to hold years of your thinking, that trade is not close.

The part I built

I got tired of my own vault rotting, so I built the missing three jobs and open-sourced them as obsidian-second-brain, a Claude Code skill now starred by 3,400+ developers.

It is 45 slash commands, but they all serve those four jobs. Capture is one keystroke. Retrieval honors freshness and typed relationships between notes instead of blind similarity, so the billing question above returns the causal chain, not ten fragments. Scheduled agents run health checks, reconcile contradictions, and prune stale claims on their own. When a new note contradicts an old one, the old fact gets marked superseded, not silently left to lie.

That last part is the one people underestimate. A second brain that cannot tell you what is no longer true is worse than no second brain, because it launders stale facts as current ones. The maintenance layer exists to keep the vault honest with itself, which is exactly the work a folder of markdown will never do on its own.

This is also where the graph engineering work lives: typed edges in the markdown, so the vault is a real graph the agent can traverse, not just a pile of links. I wrote separately about what a working second brain needs that Karpathy’s LLM Wiki pattern does not, which is the same lesson from a different angle.

The point is not “use my thing.” The point is that the setup you see ranking for this search is the start line, and almost nobody writes about the actual race.

The one line to keep

A second brain is not a folder Claude can read. It is a system that maintains itself. The tutorials give you the folder. The maintenance is the whole job.

If you want to watch that maintenance layer get built in the open, with the benchmark numbers when they land, subscribe. Every post here documents a working build, including this one.

Subscribe now

Frequently asked questions

How do I use Claude Code as a second brain? Point Claude Code at a folder of markdown notes (an Obsidian vault works well), add a CLAUDE.md file with your rules, and it can read, write, and structure your notes. That is the starting setup. To make it survive past a few hundred notes you also need real retrieval, freshness tracking, and scheduled maintenance, which plain setup does not include.

Is Obsidian required for a Claude Code second brain? No. Any folder of markdown files works, because Claude Code operates on files, not on Obsidian specifically. Obsidian is a convenient viewer and gives you wikilinks and graph view for free, which is why most setups use it.

Why does my Claude Code second brain get worse over time? Because nothing maintains it. Notes go stale, decisions get reversed, and contradictions pile up. Without a maintenance layer that prunes, reconciles, and marks facts as superseded, the vault slowly fills with outdated claims the model then cites as current.

What is the difference between Claude’s built-in memory and a file-based second brain? Built-in memory lives on a server, inside one product, and you cannot open it and correct a wrong fact. A file-based second brain is plain markdown you own, can read line by line, and can move to any model. You trade convenience for ownership and control.

How many notes can a Claude Code second brain handle? The naive “read all the files” approach breaks around a few hundred notes, when the vault no longer fits in context and simple search gets noisy. With proper retrieval (freshness-aware, relationship-aware) it scales to thousands.

Key takeaways

• Every “claude code second brain” tutorial shows the same 20-minute setup and stops there. The setup is the easy part.

• A second brain has four jobs: capture, retrieve across notes, stay current, and maintain itself. Tutorials cover one and a half of them.

• The setup breaks around a few hundred notes: retrieval gets noisy, the vault goes stale, and nothing prunes or reconciles it.

• Claude’s built-in memory is convenient but sealed. A file-based second brain trades convenience for ownership you can read and correct.

• A second brain is not a folder Claude can read. It is a system that maintains itself, and the maintenance is the whole job.

Further reading

• obsidian-second-brain on GitHub - the open-source Claude Code skill this post describes (MIT, 3,400+ stars).

• What Is Graph Engineering? A Field Guide for Builders - how typed edges turn a vault into a real graph the agent can traverse.

• I Rebuilt Karpathy’s LLM Wiki. Here’s What’s Missing. - the same lesson from the knowledge-wiki angle.

• second-brain-starter by Cole Medin - a good starting-point skill if you want the minimal setup first.

• How to Use Claude Code as a Thinking Partner (Every) - a useful take on the daily-use side.

About the author

Eugeniu Ghelbur is an AI Automation Engineer and the creator of obsidian-second-brain, an open-source Claude Code skill starred by over 3,400 developers on GitHub. He builds production AI systems for marketing and sales workflows, and his personal research covers AI agent memory, AI-first knowledge management, and second brains that maintain themselves. He writes The AI Operator (theaioperator.io), a weekly systems newsletter where every post documents a working build, including this one. The fastest way to reach him is e.ghelbur@gmail.com, and his open-source work lives at github.com/eugeniughelbur.

• “Graph engineering” exploded on X this week with three competing definitions and a viral study that does not exist.

• The discipline underneath is real and measurable: graphs beat vector search on multi-hop and temporal questions, and lose on simple lookups and cost.

• A vault of linked markdown is already 80% of a graph index. I am building the missing 20% in the open.

Agents that read flat documents miss chains: who decided X, what replaced it, what broke because of it. Graph-shaped memory is the fix, and it is measurable. LinkedIn cut support resolution time 28% with it, and the best graph systems answer multi-hop questions 10 points better than vector search.

That is the business case. Now the story.

On July 18, Peter Steinberger posted twelve words on X: “Are we still talking loops or did we shift to graphs yet?” Thousands of likes. Within 48 hours, “graph engineering” had three competing definitions, a wave of copycat posts, and a viral claim about a “$3.1M Stanford and Anthropic study.”

I went looking for that study. It does not exist. Fabricated engagement bait.

But I kept digging, because under the noise there is a real discipline with a decade of research, working tools, and benchmark numbers that survived independent evaluation. I spent the weekend reading all of it so you do not have to.

By the end of this issue you will understand graphs better than most people posting about them this week.

The whole primitive in 60 seconds

Strip every buzzword away and a graph is two things.

Nodes: the things you know about. A person, a project, a decision, an incident.

Edges: the connections between them.

That is the entire primitive. The reason it matters for AI is retrieval. An agent answering a question has to find the right knowledge first, and there are only three ways to find things:

• Keyword search finds notes containing a word. Fails when the answer uses different words.

• Vector search finds notes that are about similar things. Fails when the answer is spread across notes that are individually not similar to the question.

• Graph traversal starts at one node and walks the connections. It is the only method that can follow a chain of reasoning.

The question that breaks vector search

Here is a synthetic example, the kind of question every real knowledge base gets asked:

“Why did we drop Redis for the job queue?”

Vector search embeds the question and pulls the ten chunks most similar to it. You get ten notes that mention Redis. None of them explains the decision, because the decision lives in the structure: a decision record, the thing it replaced, and the incident that triggered it. Three separate notes. Similarity search has no concept of “these three belong to one causal chain.”

Graph traversal walks it:

hop 1:  [[Job queue]] --decided_by--> [[ADR-007 Postgres queue]]
hop 2:  [[ADR-007]]  --supersedes--> [[ADR-003 Redis queue]]
hop 3:  [[ADR-003]]  --caused-->     [[Incident 2026-03-11]]

Three notes, about 1,000 tokens, causal chain intact.

Each step is a hop. Questions needing more than one hop are multi-hop questions, and they are where flat retrieval consistently breaks. “Who decided X and what broke because of it” is a two-hop question. Most interesting questions about any real body of knowledge are multi-hop.

One sentence to keep: vector search finds things that sound like your question. Graphs find things that are connected to your answer.

One bit versus meaning

Now the detail that decides whether a graph is useful or just pretty.

An untyped edge says “these two notes are related.” One bit of information. A typed edge says how: supersedes, depends_on, decided_by, caused.

Run the Redis example without types. The traversal becomes “the queue is related to a decision, which is related to another decision, which is related to an incident.” Did ADR-007 replace ADR-003, or the other way around? Did the incident cause the decision or the decision cause the incident? The chain survives. The meaning is gone, and the agent has to re-read every note and guess.

Typed edges turn a pile of links into something you can reason over. Hold onto that. It is the center of everything that follows.

Where the term actually came from

Know the history, so nobody can bluff you with it.

“Graph engineering” sits on a treadmill of terms. Each one described a real shift. Each one got turned into content slop within weeks:

• 2023: prompt engineering. Craft the words you send the model.

• Mid-2025: context engineering. Curate everything in the window.

• June 2026: loop engineering. Design the agent’s act-observe-retry cycle.

• July 2026: graph engineering. Design what happens between and across loops.

The receipts: a quiet blog post by Josh Simmons on July 4 is the earliest documented use I found. Steinberger's July 18 post lit the fuse (he was mocking the treadmill; the treadmill did not care). Carlos Perez published one of the first serious essays about ten hours later. The backlash started the same day.

Within 48 hours the term meant three different things:

• Orchestration graphs: design multi-agent systems as explicit graphs instead of loops. Typed nodes, typed transitions, checkpoints. This is LangGraph and Temporal territory.

• Graphs of loops: networks of self-improvement cycles watching each other. The most abstract meaning, and the least actionable today.

• Graph-structured knowledge and memory: the agent’s knowledge stored as typed nodes and edges it can traverse.

Only the third one has a decade of research, working tools, and real money behind it. Serious people were building it before the name existed, under different words: Foundation Capital called it “context graphs” in December 2025 and put a trillion-dollar label on it. Gartner predicts over half of enterprise agent systems will use graph-based context by 2028. SAP shipped a knowledge graph as its agent context layer.

The term is new. The substance is not.

How GraphRAG actually works

The umbrella name for graph-based retrieval is GraphRAG. Four systems matter, and each teaches one lesson.

Microsoft GraphRAG (2024) is the reference architecture:

1. An LLM reads every chunk and extracts entities plus relationships.

2. Community detection clusters related entities into neighborhoods.

3. An LLM writes a summary report for every community.

4. At query time, broad questions map-reduce over the reports; specific questions expand from a matched entity.

It works. It is also brutal on cost: an LLM call per chunk at index time. One widely cited estimate put it at around $33,000 to index a single large enterprise dataset. Lesson one: the naive version is too expensive, and its free-text edges do not compose.

LazyGraphRAG (Microsoft’s own correction) flips the design: build only a cheap structural graph at index time, and do the expensive thinking at query time. Indexing cost drops to about 0.1% of the original. Answer quality stays comparable.

Lesson two, and remember this one: you do not need to pre-compute the graph’s meaning. A cheap structural graph plus smart traversal at query time gets most of the value.

HippoRAG 2 (2025) is the benchmark king. It fuses graph structure with embeddings and ranks results by spreading importance along edges from wherever the query touched the graph. It spends about 1,000 tokens per query, wins on multi-hop, and, critically, does not get worse at simple questions to get better at hard ones. Most graph systems do. Lesson three: the winning retrieval is hybrid, never graph-only.

The 2026 trend line across the whole field: lazy indexing, agentic traversal (the agent decides which hops to take, live), small controlled edge vocabularies, and honest routing. Use the graph only for questions that need it.

Memory that knows what time it is

GraphRAG answers questions about a corpus. Agent memory is harder: knowledge that changes while the agent uses it. You change jobs. A decision gets reversed. A fact true in March is false in July.

This is where graphs do something vector stores structurally cannot.

Graphiti, the open-source engine behind Zep, tracks two timelines per edge: when the fact was true in the world, and when the system learned it. When new information contradicts an old edge, the old edge is not deleted. Its validity interval is closed, and the new edge takes over.

The agent can now answer both “where does she work?” and “where did she work in 2024?” from the same graph. Facts get superseded, not overwritten. A vector store can only overwrite or duplicate; it has no native concept of “this was true until May.”

Any long-lived knowledge base has this shape. Decisions supersede decisions. Claims go stale. A system that cannot represent “X replaced Y on this date” slowly fills with contradictions, and an agent reading it will confidently cite the stale half.

Notice the vocabulary this needs: supersedes, contradicts, valid_from, valid_until. Typed edges again.

The scoreboard, honestly

Half the numbers in this field are vendor-reported on their own benchmarks. Here is what independent evaluation actually shows, as of mid-2026:

Graphs win three things, by wide margins:

• Multi-hop reasoning: 53.4% vs 42.9% for vector RAG on GraphRAG-Bench; HippoRAG 2 beats a strong embedding model by 9.5 F1 points on 2WikiMultiHopQA.

• Temporal reasoning: the graph variant of Mem0 scores 58.1 where OpenAI’s memory scores 21.7. The most lopsided numbers in the field.

• Corpus-wide synthesis: 64.4% vs 51.3%.

Graphs lose two things:

• Simple fact lookup: 60.9% for plain vector RAG vs 60.1% for the best graph method. The graph adds redundant context and wins nothing.

• Cost: Microsoft GraphRAG’s global search burned 331,375 tokens per query in the benchmark. Vector RAG: 880. (HippoRAG 2: 1,008. Efficiency is possible.)

Two warnings worth the whole section. LightRAG posted huge wins on its own benchmark, then collapsed to 6.6 average F1 (versus 59.8 for HippoRAG 2) under independent evaluation. Never trust a system evaluated only by its authors. And in Mem0’s own paper, the graph variant lost to the non-graph variant on multi-hop questions. Graphs are a tool, not a religion.

The practitioner consensus: route by question type. Vector for lookups, graph for chains.

The math that kills graph projects

If graphs win benchmarks, why does not everyone run one? Because of one number almost nobody says out loud.

Entity resolution is deciding that “Dr. John Smith,” “J. Smith,” and “John” are one node, and that “Mercury the planet” and “Mercury the element” are two. Extraction pipelines get this wrong constantly, and the errors compound multiplicatively over hops.

At 95% per-hop accuracy, a 5-hop chain is 77% trustworthy. At 85%, it is 44%.

Your impressive multi-hop traversal is a coin flip.

Sit with that, because it flips the whole build order. The expensive part of graph engineering is not graph algorithms. It is deciding what is the same thing. And there is one place where that problem is already solved: human-curated wikilinks. When someone writes [[ADR-007]] in a note, entity resolution is done, by construction. No fuzzy merging, no compounding error.

Extraction pipelines spend most of their engineering budget trying to recover what a wikilink gives you for free.

The gap nobody has claimed

I maintain obsidian-second-brain, an open-source Claude Code skill that runs an Obsidian vault as an AI-first second brain (45 commands, MIT, starred by 3,400+ developers). I have written before about what a working second brain has to do that Karpathy’s LLM Wiki pattern does not. So the question I actually cared about all weekend: who has built graph engineering on plain markdown?

The answer surprised me. The space is five months old, moving fast, and every single player is missing exactly one leg of the tripod: typed edges in the files, graph rules and validation, agent retrieval.

• Basic Memory (3.5k stars) has typed relations in markdown and a real agent API. But the types are freeform strings: no vocabulary, no rules, no validation.

• Breadcrumbs, the veteran Obsidian plugin, has real graph engineering: typed links, automatic inverses, transitive rules. Built entirely for human navigation. No AI surface at all.

• Penfield is the only team articulating the full vision, and they route your graph into their cloud for $10 to 20 a month. Your markdown is an import source, not the store.

• Others (Rowboat at 13.1k stars, obra’s knowledge-graph, IWE) ship agent-facing graph tools over vaults with explicitly untyped edges.

And two things, as of this weekend, exist nowhere:

1. A linter for typed edges. Nothing validates a vault’s graph: unknown types, dangling targets, missing inverses, contradiction cycles. Zero tools.

2. An eval proving typing works. Nobody has published evidence that typed links measurably improve agent answers over plain links. Zero hits.

A well-kept vault is already 80% of a GraphRAG index. Entity resolution: solved by wikilinks. Indexing cost: zero, the graph is built at write time. The missing 20% is exactly those two lists above.

What I am doing about it

I am building the missing 20% into obsidian-second-brain, in the open, starting this week:

1. A small typed-edge vocabulary (10 to 20 verbs: supersedes, depends_on, decided_by, caused) written as plain inline fields, so notes stay human-readable and Obsidian-native.

2. The linter. The thing that exists nowhere, and the cheapest to ship.

3. The eval: same vault, same questions, typed versus untyped retrieval, published numbers.

Update (July 21): the typed-edge vocabulary and the linter shipped in the repo the day after this post went out. The eval is the piece still open.

The 2026 consensus from every serious system points the same way: small typed core, cheap indexing, hybrid retrieval, temporal supersession. All four of those are implementable on markdown files you own. That is the version of graph engineering that survives after the hype cycle moves on.

If you want to watch it get built (and get the benchmark numbers when the eval lands), subscribe. This is the kind of thing I ship here every two weeks.

Turns out the term everyone laughed at pointed at something real. The people laughing and the people building are not the same people.

Frequently asked questions

What is graph engineering? Graph engineering is designing AI systems around explicit graphs: knowledge stored as nodes (entities) and typed edges (relationships) that an agent can traverse, instead of flat documents searched by similarity. The term went viral in July 2026, but the underlying discipline (knowledge graphs, GraphRAG, graph-based agent memory) predates the name by years.

Is graph engineering the same as GraphRAG? GraphRAG is one part of it: retrieval-augmented generation where the retrieval step uses a graph. Graph engineering also covers agent memory graphs (like Zep’s Graphiti) and multi-agent orchestration graphs (like LangGraph).

Is GraphRAG better than vector RAG? It depends on the question type. Independent benchmarks show graphs win multi-hop reasoning (53.4% vs 42.9%), temporal reasoning, and corpus-wide synthesis, and lose on simple fact lookups and cost. The practitioner consensus is to route by question type.

What is a typed edge in a knowledge graph? An untyped edge only says two things are related. A typed edge names the relationship: supersedes, depends_on, decided_by, caused. Types are what let an agent reason over the graph instead of guessing what each link means.

Can I build a knowledge graph in Obsidian? Yes. Every note is a node and every wikilink is an edge, which solves entity resolution by construction. What Obsidian lacks out of the box is typed edges, graph validation, and an AI retrieval layer, which is the gap this article describes.

Why do knowledge graph projects fail in production? Entity resolution errors compound multiplicatively over hops: at 85% per-hop accuracy, a 5-hop chain is only 44% trustworthy. Stale graphs and indexing cost are the other two killers.

Key takeaways

• Vector search finds things that sound like your question. Graphs find things that are connected to your answer.

• “Graph engineering” was born on X on July 18, 2026 with three competing meanings. Only graph-structured knowledge and memory has benchmarks and production evidence behind it.

• Graphs win multi-hop, temporal, and synthesis questions by wide margins, and lose simple lookups and cost. Route by question type.

• An untyped link carries one bit. A typed edge (supersedes, depends_on, caused) is what turns a pile of links into something an agent can reason over.

• Entity resolution, not graph algorithms, is where graph projects die: at 85% per-hop accuracy, a 5-hop traversal is 44% trustworthy. Human-curated wikilinks solve it by construction.

• Typed edges plus graph rules plus agent retrieval on plain markdown exists nowhere as one local-first package. The linter and the typed-vs-untyped eval have never been shipped by anyone.

Further reading

• HippoRAG 2 (arXiv 2502.14802) - the benchmark-king paper; also the independent evaluation where LightRAG collapsed.

• Zep: temporal knowledge graphs for agent memory (arXiv 2501.13956) - the bi-temporal model behind “facts expire, not die.”

• GraphRAG-Bench (arXiv 2506.05690) - the honest scoreboard: where graphs win and lose by task type.

• We are entering the graph engineering phase - the July 4 post that quietly coined the term before the meme wave.

• I rebuilt Karpathy’s LLM Wiki. Here’s what’s missing. - my earlier piece on what a working second brain needs beyond the static wiki pattern.

About the author

Eugeniu Ghelbur is an AI Automation Engineer and the creator of obsidian-second-brain, an open-source Claude Code skill starred by over 3,400 developers on GitHub. He builds production AI systems for marketing and sales workflows, and his personal research covers AI agent memory, AI-first knowledge management, and second brains that maintain themselves. He writes The AI Operator (theaioperator.io), a weekly systems newsletter where every post documents a working build, including this one. The fastest way to reach him is e.ghelbur@gmail.com, and his open-source work lives at github.com/eugeniughelbur.

• Claude forgets everything between sessions, and the popular fixes are vector databases and memory frameworks.

• I shipped a bounded recall hook instead: at most 4 relevant notes from my Obsidian vault per prompt, and silence when nothing truly matches.

• Under roughly 50,000 notes, plain lexical search with a hard budget beats a vector database. Your notes are already the memory.

You can give Claude Code persistent memory with markdown files you already have. No vector database, no memory framework, no new service. Here is the version I run every day, and why the boring approach wins.

I run Claude Code all day. Every session used to start the same way: re-explaining who I am, what I decided last month, which approach I already rejected. The model is brilliant and amnesiac at the same time.

The standard advice for fixing this is heavy. Spin up a vector database. Add an embeddings pipeline. Install a memory framework. Mem0 alone has 48,000 GitHub stars and $24M in funding riding on that advice.

I took the opposite bet. My memory layer is a folder of markdown notes and one small hook. It has been running on my vault of 1,700+ notes, and it is free and open source.

The memory problem nobody names

Most “Claude memory” guides are feature tours. They list the layers, show the config flags, and stop.

The unsolved problems sit one level deeper. Context inflation: memory tokens crowd out task tokens until the model reads more about you than about the work. Memory poisoning: one bad write and the agent believes it forever. Stale beliefs: the note says X, reality moved to Y months ago.

Every one of these is a retrieval problem, not a storage problem. Storing knowledge is easy. Deciding what deserves to enter the prompt, and how much, is the hard part.

What Anthropic gives you out of the box

Claude ships three memory layers now. Chat memory in the apps, which reached free users earlier this year. Projects, which scope context to a workspace. And in Claude Code, Auto Memory: on by default, it writes a MEMORY.md per project and loads the first 200 lines, about 25KB, into the system prompt.

This is genuinely useful, and I keep it on. But it remembers the project, not you. It holds “this repo uses ruff with line-length 100”, not the decision you made in March, the person you met at that call, or the approach you already tried and killed.

That second kind of memory lives in my notes. I have written before about what belongs in a CLAUDE.md and the answer is: not this. Your accumulated knowledge does not fit in 200 lines.

Subscribe now

A recall budget, not a database

Here is the claim that made me build instead of install: below a threshold, vector databases are overhead.

One 2026 analysis puts the crossover near 50,000 stored items. Under that, lexical search (BM25 plus a simple index) beats a vector setup on latency and on operability. Even Anthropic’s own managed agents default to filesystem memory, not a vector store.

A personal vault sits far below 50,000 notes. Mine is around 1,700 after two years of daily use. At that scale the expensive question is not “can I find related notes”, it is “how much found material should I inject”.

So the design flips. The scarce resource is prompt space, not recall. What Claude Code needs is a recall budget.

Subscribe now

The hook: 4 notes, 900 characters, or silence

The implementation is one UserPromptSubmit hook. On every prompt, it searches the vault and injects a small brief of the most relevant notes. Four rules make it work:

Bounded. Hard cap of 4 notes, about 900 characters total. Memory can never crowd out the task. That is the whole answer to context inflation.

Abstaining. If confidence is low, it injects nothing. Silence beats noise. A memory system that always says something is a noise generator with a database attached.

Fail-closed. Any error and it exits silently. Recall must never break a prompt.

Observable. Every inject and every abstain decision is logged to a JSONL file, so I can audit what my agent was told and when.

There is a fifth rule hiding in the design: no per-prompt index rebuild. An earlier fork of this idea re-indexed the whole vault on every prompt, which means latency grows with vault size. The hook reuses the index the vault already maintains, so a prompt costs the same at 1,700 notes as it did at 200.

The search underneath is the same one my vault uses everywhere: lexical scoring with freshness and supersession reranking. When a note is superseded by a newer decision, the old one steps back automatically. That is the practical answer to stale beliefs, and it is why my Obsidian vault argues with me instead of parroting my past mistakes.

Memory poisoning gets the same structural answer. Writes into the vault go through validation, and because memory is notes, a bad memory is a file I can open, read, and fix. Try doing that with a corrupted embedding.

Nothing runs until you set two environment variables and register the hook. Memory that reads your private notes should be opt-in, twice.

Subscribe now

What changed in practice

The visible change is small and constant. I ask about a project, and the context of past decisions is just there. I mention a person, and the agent knows our history. No “as I mentioned before” theater, no re-pasting.

A concrete morning: I typed “draft the follow-up for yesterday’s call”. The hook matched three notes: the meeting note from the call, the person’s card, and a decision record from May that ruled out the approach I was about to suggest again. Four seconds of retrieval saved me from re-proposing something we killed two months ago.

One thing this system will not do is invent structure. The recall is only as good as the notes, and the notes stay good because the vault maintains itself: new information rewrites old pages, contradictions get flagged, and decisions carry dates. Retrieval and note quality are the same problem wearing two hats.

The invisible change matters more. Because the budget is 4 notes, I never wonder whether my prompt is drowning in memory. Because it abstains, unrelated prompts stay clean. Because everything is logged, I have caught bad matches and fixed the notes, not the model. The same pattern powered the LLM wiki experiment that this system grew out of: the notes are the product, the AI is the librarian.

Honest limits: this is personal-scale memory. If you are building agent memory for millions of users, the vector people are right, and you should hire them. For one builder with one vault, they are solving a problem you do not have.

The other limit is discipline-shaped. If you do not write things down, there is nothing to recall. The hook made my notes more valuable, which made me write more of them. That loop was the point all along.

Try it

The hook ships inside obsidian-second-brain, MIT licensed, on GitHub at github.com/eugeniughelbur/obsidian-second-brain. Point it at any folder of markdown notes, set the two variables, register the hook, and your next Claude Code prompt starts with your own knowledge behind it.

Frequently asked questions

How do I give Claude Code persistent memory?
Three options: Claude Code’s built-in Auto Memory (on by default, per-project MEMORY.md), a memory framework with a vector database, or a recall hook over your existing notes. This post covers the third: a UserPromptSubmit hook that injects up to 4 relevant notes per prompt.

Does Claude Code have built-in memory?
Yes. Auto Memory writes a MEMORY.md per project and loads the first 200 lines (about 25KB) into the system prompt. It captures project conventions well, but it is not designed to hold your accumulated decisions, people, and research.

Do I need a vector database for AI agent memory?
Below roughly 50,000 stored items, no. Lexical search with a hard injection budget is faster to run and easier to operate. A personal notes vault is far below that threshold.

What is a recall budget?
A hard cap on how much memory can enter a prompt. Mine is 4 notes, about 900 characters. The cap solves context inflation: memory can inform the task but never crowd it out.

Can Claude read my Obsidian vault?
Yes, locally. The hook searches the vault files on your machine and injects short excerpts into the prompt. Nothing is uploaded anywhere; the vault stays plain markdown on disk.

Is it safe to give an AI hook access to my notes?
The hook is double-gated (two environment variables must be set), fail-closed (any error exits silently), and logged (every inject or abstain is written to a JSONL audit file). You can read every decision it made.

Key takeaways

• Agent memory is a retrieval problem, not a storage problem. Your notes already store the knowledge.

• Below about 50,000 items, lexical search plus a hard budget beats a vector database on latency and operability.

• A recall budget (4 notes, ~900 characters) solves context inflation by construction.

• A memory system must be allowed to say nothing. Abstaining beats injecting noise.

• Supersession-aware search answers stale memory: replaced decisions step back automatically.

• Claude Code’s Auto Memory remembers the project. A vault recall hook remembers you. Run both.

Further reading

• Claude Code memory docs: https://code.claude.com/docs/en/memory

• The obsidian-second-brain repo (the hook ships in v0.13+): https://github.com/eugeniughelbur/obsidian-second-brain

• thedeepfeed.ai analysis (2026-04-30) on the lexical-vs-vector crossover near 50,000 items: https://www.thedeepfeed.ai/

• The launch story: I built this for myself. Then 1,374 strangers cloned it.

• Anthropic on managed agents and filesystem memory: https://www.anthropic.com/engineering/managed-agents

About the author

Eugeniu Ghelbur is an AI Automation Engineer and the creator of obsidian-second-brain, an open-source Claude Code skill starred by over 3,300 developers on GitHub. He builds production AI systems for marketing and sales workflows, and his personal research covers AI agent memory, AI-first knowledge management, and second brains that maintain themselves. He writes The AI Operator (theaioperator.io), a weekly systems newsletter where every post documents a working build, including this one. The fastest way to reach him is e.ghelbur@gmail.com, and his open-source work lives at github.com/eugeniughelbur.

• Ask AI to explain something and you get a wall of text you have to re-read three times.

• I built doceo, an open-source Claude Code skill that turns any topic, file, folder, or URL into a one-screen visual lesson: one answer, one diagram, one analogy, a quiz.

• It runs locally, remembers what you already know, and gets sharper after every lesson.

doceo is a free, open-source Claude Code skill that turns any topic, file, or URL into a one-screen visual lesson: one plain answer, one diagram, one analogy, and a quick quiz. Here is why I built it.

I ask AI to explain things all day. A new codebase, a config format I have not touched in a year, a concept three layers below what I actually work on.

The answer is almost always the same shape. A wall of text. Correct, thorough, and impossible to hold in my head. I read it, I get the gist, and an hour later I could not redraw it for you.

The problem is not the model. The model knows the thing. The problem is the format. A paragraph is how you store an explanation, not how you learn one.

So I built a tool that changes the format. It is called doceo, Latin for “I teach”, and it is a Claude Code skill I open-sourced. This is what it does and why it works.

A lesson is not a paragraph

Before I wrote any code I wrote down what a lesson should actually contain. Not an article. A lesson. The kind a good teacher gives you at a whiteboard in five minutes.

It has a shape:

• One sentence that answers the question directly, before anything else.

• One diagram, because a picture holds in memory where a paragraph does not.

• One analogy that maps the new thing onto something you already understand.

• Where it fits, so the idea has a place to live next to what you know.

• Baby steps, when the thing you asked is a task and not a concept.

• A short self-quiz, because you do not know a thing until you can answer a question about it.

• A couple of go-deeper links for when you want the full version.

That is the whole spec. One screen, seven parts. If it does not fit on one screen, it is not a lesson yet, it is reading.

What I built

doceo is a slash command. You type /doceo and point it at anything:

• a topic (”explain vector databases”)

• a file or a folder (”what does this script do”)

• a URL (”teach me this docs page”)

It produces two things. A one-screen visual lesson as an HTML artifact you can open in a browser, and a plain markdown note that lands in my vault so the lesson does not evaporate when I close the tab.

It is a Claude Code skill, so there is no app to install and no account to make. It is a folder of instructions Claude reads. It is public on GitHub under MIT. I built the first version and pushed it live the same day, which matters for a reason I will get to.

This is the same pattern I have used before with obsidian-second-brain: a small, sharp skill that does one thing, lives in the open, and improves in public.

The part that matters: it remembers you

A generic explainer treats every reader as the same blank person. That is why the answers are so long. The tool has no idea what you already know, so it explains everything, just in case.

doceo keeps a local memory of who is learning. On my machine it lives in a wiki/learning/ folder: a profile of what I already understand, a running file of things I have learned, my feedback, and a style file. It reads that at the start of every lesson.

So when I ask it to explain something adjacent to what I already know, it skips the part I know and spends the screen on the part I do not. The lesson gets shorter and sharper because it is calibrated to one specific person instead of everyone.

The memory is strictly local. Each machine keeps its own. Nothing personal ever ships in the repo. What is public is the skill. What is private is what it learned about me.

It gets sharper every time you use it

Here is the decision I am most sure about. I shipped doceo before it was good.

After every lesson it asks me exactly one question. Was this too long, too short, right? That answer goes into a feedback file. Then it gets distilled into rules in a learnings file, and those rules are read at the start of the next run.

So the tool corrects itself against my taste with every use. Lesson four is better than lesson one, not because I rewrote the prompt, but because it learned that my lessons were running too short and adjusted.

I could have polished it for a week first. I did not, on purpose. A tool with a feedback loop that ships today beats a perfect tool that ships in a month, because the today version starts learning today. This is the same bet behind what I keep in a CLAUDE.md: start rough, let real use file down the edges.

doceo vs NotebookLM, DeepWiki, and codebase walkthroughs

A fair thing to ask, since these tools sit next to each other. They do different jobs.

NotebookLM is a research surface. It summarizes and answers questions across sources you upload. DeepWiki and codebase-walkthrough tools map a repository into browsable docs. Diagram tools draw the structure of a system.

None of them teach. They summarize, map, or answer. doceo is aimed at the moment before that, when you do not yet understand the thing well enough to ask a good question about it. It hands you an analogy, a diagram, and a path, calibrated to what you already know. When I checked the field before building, that specific gap, teaching with analogy and a progressive path over mixed knowledge, was the part nothing else was doing.

Try it

The skill is public: github.com/eugeniughelbur/doceo. Clone it, drop it into your Claude Code skills, and point /doceo at the next thing you do not understand.

It will not be perfect on your first lesson. It is not supposed to be. Give it the one-question feedback, and by your fourth lesson it will fit you better than any generic explainer ever could.

Frequently asked questions

What is doceo? - doceo is an open-source Claude Code skill that turns any topic, file, folder, or URL into a one-screen visual lesson: a one-sentence answer, a diagram, an analogy, a self-quiz, and go-deeper links. The name is Latin for “I teach”.

How is it different from NotebookLM? - NotebookLM summarizes and answers questions across documents you upload. doceo teaches a single idea on one screen with an analogy and a diagram, calibrated to what you already know. Different job: NotebookLM is for research, doceo is for the moment before you understand something.

Do I need to install an app or make an account? - No. It is a Claude Code skill, a folder of instructions Claude reads. Clone the repo, add it to your skills, and run /doceo.

Where does it store what it learns about me? - Locally, in a learning folder on your own machine. Each machine keeps its own memory. Nothing personal is ever pushed to the public repo.

How does it get better? - After each lesson it asks one feedback question. The answer is saved, distilled into rules, and read at the start of the next lesson. It corrects itself against your taste over time.

Is it free? - Yes. It is open source under the MIT license.

Key takeaways

• AI explanations are usually a storage format (a paragraph), not a learning format (a lesson). Changing the format does more than changing the model.

• A lesson should fit one screen: one answer, one diagram, one analogy, where it fits, an optional set of baby steps, a quiz, and go-deeper links.

• Calibration is what makes an explanation short. A tool that knows what you already understand can skip it and spend the screen on what you do not.

• Keep the learner’s memory local. The skill is what you share, not what it learned about you.

• Ship the version with a feedback loop before it is perfect. It starts improving on real use immediately, which the perfect-in-a-month version cannot.

• doceo fills a specific gap next to NotebookLM and codebase-mappers: teaching with analogy and a progressive path over mixed knowledge.

Further reading

• doceo on GitHub - the skill, open source, MIT.

• I built this for myself. Then 1,374 strangers cloned it. - the obsidian-second-brain launch and the small-sharp-skill pattern doceo follows.

• I rebuilt Karpathy’s LLM Wiki. Here’s what’s missing. - what a working knowledge tool has to do that a static one does not.

• The CLAUDE.md behind a tool 3,000 developers use - the ship-rough-and-improve approach in practice.

• blader/humanizer - the anti-AI-slop reference doceo’s writing pass is distilled from (github.com/blader/humanizer).

About the author

Eugeniu Ghelbur is an AI automation engineer who builds production AI systems and ships open-source Claude Code skills. He writes about AI knowledge management and agent patterns at theaioperator.io. The doceo skill described here is live on GitHub at github.com/eugeniughelbur/doceo, and his obsidian-second-brain skill has been starred by over 3,000 developers.

• A CLAUDE.md is the operating manual an AI coding agent reads before every task. Get it wrong and the agent is unreliable. Get it right and you can hand it real work.

• I run one across an open-source tool that 3,000 developers have adopted. Every real win came from deleting, not adding.

• Keep it short and enforceable, push detail into skills and commands, and never write a rule the agent can’t actually follow.

Subscribe now

If you have ever asked an AI to do real work, you have felt the problem underneath this post. You explain what you want once. The next time, it has forgotten all of it. You re-explain the same context, the same rules, the same “no, not like that.” Every session starts from zero, so you never quite trust it with anything that matters.

That distrust is the real ceiling on AI at work right now. Not the model’s intelligence. The fact that it forgets, so a person has to sit next to it and check.

For AI coding agents there is a fix, and it turns out to be most of the game. It is a plain text file called CLAUDE.md. The agent reads it before it touches anything, so your standing rules load automatically and the same mistakes stop repeating. That file is the line between an assistant you check constantly and one you can point at a task and walk away from.

I ran one across obsidian-second-brain, an open-source tool I built for myself and then watched thousands of strangers adopt. Roughly 3,000 developers now run it. It is the same pattern I used when I rebuilt Karpathy’s LLM wiki gist into a working system.

Here is what actually holds up, after the file got worse before it got better.

What a CLAUDE.md actually is

Start with the mental model, because most people get it wrong, and the wrong model is why their file bloats.

A CLAUDE.md is not documentation. It is not a README. It is the set of standing instructions the agent loads into its working memory on every run, before it reads a single line of your code. Anthropic’s own docs describe it as memory that persists across sessions. That is the right way to hold it in your head: it is the agent’s memory, and memory has a budget.

So there is only one question that matters for any line in the file. Does the agent need this loaded every single time, or not? If the answer is no, that line is not helping. It is crowding out the lines that are.

Why more rules made it worse

Search “CLAUDE.md best practices” and you get the same advice everywhere. Add a rules section. Add your tech stack. Add coding standards. Add a testing policy. Add, add, add.

I did all of it. My file grew past 300 lines. And the agent got less reliable, not more.

The reason is simple once you see it. A bloated CLAUDE.md is a wall of text the model skims. Bury the three rules that actually matter inside forty rules that don’t, and the model weights them all the same. You did not give it a manual. You gave it noise, and noise is what it acts on.

The strongest outside voice on this agrees. HumanLayer runs a roughly 60-line CLAUDE.md on purpose and argues most of what people cram in there is a linter’s job. They are right, and the shift from long to short is the single biggest quality change I made.

What I deleted

The turnaround came from cutting. Here is what left the file.

The linter rules. “Use single quotes, max line length 100, sort imports.” That is not the agent’s job, it is the formatter’s job. I deleted every style rule a tool already enforces and let the tool fail the agent instead. The tool never forgets and never skims.

The obvious rules. “Write clean code. Add tests where appropriate.” The agent already tries to do this. A rule that restates the default does nothing but take up space and dilute the rules that don’t.

The aspirational rules. This is the sneaky one. “Always achieve 100% test coverage.” I was never going to enforce that, and the agent could not verify it, so the line was pure decoration. If you would not fail the work over a rule, it does not belong in the file.

What stayed is the handful of things specific to my project and non-obvious. Use uv, not pip. Vault writes follow the AI-first rule. Never touch these three protected files. Sentence-case headers, no em-dashes. Rules the agent would get wrong without being told, and that I actually check.

The three places instructions live

This is the part almost nobody writing about CLAUDE.md gets to, and it is the one that changed everything for me.

You have three places to put instructions, not one.

CLAUDE.md is always on. It loads every session, so it pays a permanent tax on the agent’s memory budget. Reserve it for the rules that apply to almost every task.

Skills load on demand. When the work matches a skill, the agent pulls in that detailed instruction set, and only then. So the deep procedure for one kind of task lives in a skill, and it costs nothing until the moment it is needed.

Commands are explicit workflows you trigger by name. The multi-step recipe you run the same way every time lives in a command, where you invoke it deliberately.

Once I understood this, the CLAUDE.md shrank on its own. Most of what I had crammed into it was not always-on knowledge. It was task-specific detail that belonged in a skill, or a workflow that belonged in a command. The same instinct that makes a good second brain rewrite itself instead of piling up notes applies here. Structure beats volume. A small file that points to the right place beats a big file that holds everything.

The one test that decides every line

Here is the test I run on every line now. Can the agent verify it did this, and would I fail the work if it didn’t?

A rule that passes both is enforceable. “Run the voice linter before saving, the file must pass.” The agent runs it, sees pass or fail, and I can check the file afterward. That rule works because there is a real check behind it.

A rule that fails the test is decoration. “Write thoughtful, high-quality code.” There is nothing to verify and nothing to fail. It reads well and does nothing.

The enforceable rules are almost always the specific ones. A named command to run. A file that must not change. A format the output has to match. The vague ones feel productive to write, and they are the first thing the model drops under load. If you want the agent to hold a line, give it a line it can check.

What this means if you don’t write code

If you run a team instead of a codebase, this is the part that matters.

The reason most companies cannot trust AI with real work is not the model. Every team has access to the same models. The difference is whether anyone wrote down the standing rules the AI needs, in a form it reads every time and a human can actually check. That is what a good CLAUDE.md is. It is institutional memory for the agent.

So the skill that separates people getting real leverage from AI is not prompting. It is knowing which rules to write down, keeping the list short enough that all of it gets read, and making every rule checkable. That is a discipline, and it is the same discipline whether you are running one agent or a whole team of them.

Strip it all back and a CLAUDE.md is one thing. It is a compression of the decisions you are tired of re-explaining. Not everything you know. The specific, non-obvious calls the agent would get wrong and that you would otherwise correct by hand every single time. Written down once, loaded automatically, kept small enough that every line still gets read.

Mine is under 150 lines now and does more than the 300-line version did. The detail did not disappear. It moved to skills and commands, where it loads when it is needed instead of taxing every task.

Add less. Delete more. Point to the real system instead of trying to be it.

Subscribe now

Frequently asked questions

What is a CLAUDE.md file? It is a markdown file an AI coding agent like Claude Code reads automatically before every task. It holds your project’s standing rules and conventions so the agent does not start each session from scratch.

Where do I put CLAUDE.md? In your repo root for project-wide rules. Claude Code also reads a personal one at ~/.claude/CLAUDE.md that applies across all your projects, and you can nest one in a subfolder for rules that only apply there.

How long should a CLAUDE.md be? Short. Aim well under 150 lines. Every line loads on every task and competes for the model’s attention, so length has a real cost. If a rule is not needed on almost every task, move it to a skill or command.

What should I not put in CLAUDE.md? Anything a linter or formatter already enforces, anything that just restates the model’s default behavior, and any aspirational rule you would not actually fail the work over.

What is the difference between CLAUDE.md, skills, and commands? CLAUDE.md is always loaded. Skills load on demand when the task matches. Commands are explicit workflows you trigger by name. Detail belongs in skills and commands, not in the always-on file.

Does CLAUDE.md work with AGENTS.md? They serve the same purpose for different tools. AGENTS.md is the cross-tool standard several agents read. The discipline is identical for both: keep it short, keep it enforceable.

Key takeaways

• A CLAUDE.md is the operating manual your agent reads before every task, and it is the real difference between an AI you babysit and one you can trust with work.

• Bloat is the main failure mode. A long file buries the rules that matter inside rules that don’t, and the model weights them all the same.

• The biggest wins come from deleting: linter rules, obvious rules, and aspirational rules you will never enforce.

• Instructions live in three places. CLAUDE.md is always-on, skills load on demand, commands are triggered by name. Most CLAUDE.md content actually belongs in the other two.

• The test for any line: can the agent verify it, and would you fail the work if it didn’t? If not, it is decoration.

• The skill is not prompting. It is knowing which rules to write down and keeping the list short enough that every line still gets read.

Further reading

• Claude Code memory and CLAUDE.md - Anthropic’s official reference on how the file loads.

• Writing a good CLAUDE.md - HumanLayer’s short-file thesis, the strongest outside take.

• AGENTS.md - the cross-tool standard, same rules for other agents.

• I rebuilt Karpathy’s LLM wiki gist - the working system this CLAUDE.md runs.

• Karpathy’s LLM Wiki v2: what to keep, what to skip - why structure beats volume in an AI-maintained system.

• obsidian-second-brain on GitHub - the open-source repo, CLAUDE.md and all.

About the author

Eugeniu Ghelbur is an AI Tooling Engineer who builds production AI systems. He ships open-source Claude Code skills and writes about AI knowledge management at theaioperator.io. The obsidian-second-brain skill described here is live on GitHub at github.com/eugeniughelbur/obsidian-second-brain, where it has been adopted by over 3,000 developers.

Here is a question nobody building an AI second brain asks until it is too late: what happens when the tool you built it inside changes?

Most people pour months into a setup that lives inside one CLI. Every command, every workflow, every habit is wired to Claude Code, or to whatever they started with. It feels great. Until that tool raises its price, changes a policy, ships a breaking update, or you simply want to try another one. Then you find out your second brain was never really yours. It was renting space inside someone else’s product.

I did not want that. So my second brain runs on four CLIs, from one codebase. Here is the idea and the build.

The brain is the files. The CLI is just the hands.

The whole thing rests on one separation most people never make.

Your knowledge is a folder of plain markdown. That is the brain. It does not care what reads it. I made the full case for keeping an AI’s memory in plain folders in its own post. The CLI, Claude Code or anything else, is just the pair of hands that reads, writes, and reasons over those files. Hands are replaceable. The brain should not be.

Once you see it that way, locking your brain to one set of hands looks like a mistake. So I stopped doing it.

One codebase, four builds

The commands are written once. A build step turns that one codebase into a package for each CLI.

I run a build script and it produces a version for Claude Code, Codex, Gemini, and OpenCode. Each build gets its own dispatcher file (the CLIs expect different names) and an auto-generated routing table that maps plain-English triggers to the right command. The vault behaves identically across all four. The only differences are the install path and the wiring underneath.

It is 45 commands in total. Four of them are Claude-Code-only (they touch Google Calendar), so the other three CLIs ship 40. Beyond that, same brain, same behavior, four front doors.

Subscribe now

You are not locked to a model either

This is the part that goes deeper than CLIs.

Because the builds are plain instruction files, not code tied to one provider, they run on whatever model the host CLI points at. The OpenCode build will happily run on an open model like Nous Hermes through OpenRouter. Point it at a small model running locally through Ollama, and nothing leaves your machine. Same commands, same vault, your choice of brain behind the hands.

So the lock-in disappears on both axes. Not chained to one company’s CLI, and not chained to one company’s model.

Why this matters more than the model race

Everyone is arguing about which model is smartest this month. That argument resets every few weeks. The thing that actually protects you is whether your setup survives the churn.

CLIs and models in 2026 change fast. Prices move, terms change, favorites get deprecated, new ones appear. If your knowledge system is welded to one of them, every one of those changes is your problem. If your knowledge system is plain files plus commands that build for anything, the churn is just Tuesday. You switch the hands and keep the brain.

That portability is the real moat. Not the model. The model is rented. The files are yours.

Where it breaks

I am not going to pretend this is free.

Maintaining four builds is real overhead. Every time I add a command I make sure it builds cleanly for all four, and a few features genuinely cannot be portable (the calendar commands lean on Claude Code specifics). If you only ever use one CLI and never plan to switch, you do not need this. Single-CLI is simpler, and simpler is correct until portability actually buys you something.

The honest rule: build for one CLI until the day a price change or a policy or a shiny new tool makes you wish you could move. The people who set it up to be portable before that day are the ones who move in an afternoon instead of a month.

If you want to do this

Start with the separation, even if you never build for four CLIs. Keep your knowledge as plain markdown in git, and keep your commands as plain instruction files, not code bolted to one provider. That alone makes you portable.

The full setup is open source. The obsidian-second-brain skill ships the build script and all four targets: one codebase, four CLIs, 45 commands, MIT licensed. Clone it, run the build for your CLI, or read it to copy the pattern.

I am not theorizing. This is the system I built for myself and then watched 2,700 developers clone. It runs on four CLIs today because I refuse to let one company own my second brain.

Frequently asked questions

Can one AI second brain run on Claude Code, Codex, and Gemini at once?
Yes. You write the commands once and a build step produces a package for each CLI, with its own dispatcher file and a routing table. The vault behaves the same on all of them. Mine runs on Claude Code, Codex CLI, Gemini CLI, and OpenCode.

Why not just pick one CLI and stick with it?
You can, and if you never plan to switch, that is simpler. The reason to go portable is that CLIs and models change fast in 2026. If your setup is welded to one, every price or policy change is your problem. Portable means you switch tools in an afternoon, not a month.

Is it locked to one AI provider’s model?
No. Because the builds are plain instruction files, they run on whatever model the host CLI uses, including open models like Nous Hermes via OpenRouter or a local model through Ollama, so nothing has to leave your machine.

Do all the commands work on every CLI?
Almost. It is 45 commands total; four that touch Google Calendar are Claude-Code-only, so the other CLIs ship 40. Everything else is identical across the four.

What is the actual brain made of?
Plain markdown files in git. No database, no app. That is the whole point: the files are the brain and they do not care which CLI reads them, so they survive any tool change.

Key takeaways

• Your AI knowledge lives in plain files. The CLI is just the hands that read and write them, and hands should be swappable.

• One codebase builds for four CLIs (Claude Code, Codex, Gemini, OpenCode) with the same 45 commands and identical vault behavior.

• Because the builds are plain instruction files, you are not locked to one model either, including open and local models for privacy.

• The real protection in a fast-churning 2026 is portability, not picking the smartest model this month.

• Single-CLI is simpler and correct until a price or policy change makes you wish you could move. Set up portability before that day.

• The files are yours. The model and the CLI are rented.

Further reading

• I built this for myself. Then 1,374 strangers cloned it. (the open-source second brain this builds on).

• How to build a folder-native AI agent. (why the brain is plain folders of markdown).

• Karpathy’s LLM Wiki v2: what to keep, what to skip. (the pattern the vault runs).

• OpenCode and the open-model route (Nous Hermes via OpenRouter, local models via Ollama). Search “OpenCode opencode.ai” and “Ollama”.

• The obsidian-second-brain skill on GitHub: github.com/eugeniughelbur/obsidian-second-brain

About the author

Eugeniu Ghelbur is an AI Automation Engineer at Single Grain, where he builds production AI systems for marketing and sales workflows. He ships open-source Claude Code skills and writes about AI knowledge management at theaioperator.io. The obsidian-second-brain skill described here is live on GitHub at github.com/eugeniughelbur/obsidian-second-brain, where it has been starred by over 2,700 developers.

Last week a thread tore through builder Twitter. One screenshot: a free, open model running 300 agents in parallel across 4,000 steps from a single prompt, scoring higher on real research than models you pay five times more for. The replies were a mix of “this changes everything” and “this is nonsense.”

I wanted to know which.

So I did the obvious thing. I pointed an agent swarm at the claim about agent swarms. A 112-agent research run, fanning out across primary sources, then a second pass where independent agents tried to refute every claim before it survived. 24 of 25 claims passed. One got killed.

Here is what came back. The pattern is real and it is worth your time. Most of the specific numbers people are quoting are not. And the gap between those two things is where most builders are about to waste a month.

What a loop actually is

For three years the question was which model is smartest. You picked one, typed into a box, got an answer, closed the tab.

A loop kills that question. The unit stopped being the model. It became the system around it.

A prompt is a wish. You re-type it every time, and it forgets everything the moment the tab closes. Run number fifty is identical to run number one.

A loop is different. A goal goes in, work comes out, and the system keeps what it learned. The next run starts ahead of the last one, because the run before it left something behind. A reusable skill. A tighter spec. A rule that stops a past mistake from coming back. The single best line from that viral thread holds the whole idea: the system that ran your task yesterday should be smarter than the one running it today.

The model stays frozen. The system compounds. That is the whole game.

The pattern is older than the hype

None of this is new, which is exactly why it works.

The base loop was published in 2022 in a paper called ReAct: reason, act on a tool, observe the result, repeat. It cut hallucination from 56 percent to near zero on a standard benchmark, simply by grounding each step in a real lookup instead of the model’s guess. Every agent today is its descendant.

A 2023 project called Voyager added the part everyone is now selling. An agent that wrote its skills as reusable code, stored them in a library, and composed them into harder skills over time. Lifelong learning without retraining the model. Sound familiar? “Save the workflow as a skill” is Voyager in a suit.

Then in 2025 a team at Every gave it a name: compound engineering. Building systems where each run makes the next one faster, safer, and better. This is the same insight I built my own setup on, and the same one behind rebuilding Karpathy’s LLM Wiki: a model does not get bored maintaining its own knowledge, so the knowledge compounds instead of rotting.

If a term in here is new to you, I wrote a plain-language guide to the core AI concepts that pairs well with this post.

Why split it into a swarm

Why fan a task out to many agents instead of asking one model to do it all? Because one agent on a long task fills its context window until it starts to drift. Researchers call it context rot. Past a point, every step gets a little worse, because the model is reasoning over a window stuffed with its own earlier output.

A swarm fixes this. A coordinator splits the job, each agent works on one piece in its own clean context, and only a short summary flows back to be assembled. Nobody drowns in a giant context, so the system holds up on work that would break a single agent. That is the real reason the parallel setup wins, and it has nothing to do with the agent count on the marketing page.

Subscribe now

The one move that separates a loop from a toy

Here is the part most threads skip, and it is the most important one.

A swarm of cheap agents will produce confident, under-cited work. Run enough of them and some will quietly contradict each other. “Looks done” and “is correct” are different planets. The first wave of autonomous agents in 2023, the AutoGPT era, failed for exactly this reason: nothing was checking the work.

The fix is a verify gate. You point a second, trusted model at the output and tell it one thing: refute, do not praise. List what is wrong.

Why this works comes down to a single asymmetry. Checking an answer is easier than producing it. So you generate cheap at high volume, and you spend your expensive, careful tokens only on the gate that catches the silent flaw. A loop without that gate is just AutoGPT again, now at scale and on your invoice.

This is the real shape of the hybrid stack everyone is excited about. A cheap open model does the work. A premium model sits at one gate and keeps it honest.

What’s real, and what’s vendor marketing

This is where the swarm I ran earned its keep. Three findings matter.

The viral “300 agents, 4,000 steps” is a capability ceiling, not a benchmark. It is a line in the open model’s own product page. The vendor’s actual public demos topped out around 100 agents on one task and about 30 on another. The “4,000” came from a separate, unrelated run. It describes what the system can be told to attempt, not the quality of what comes out at that size.

The famous “this model is four times less likely to pass its own code flaws” line is real, but softer than it sounds. It does not appear in the technical safety report at all. I checked the full document. It lives in a launch announcement, it is self-reported with no published method, and it measures honesty, that the model flags its own uncertainty, not that the code it writes is four times better.

The head-to-head benchmark numbers people are reposting, where the open model beats the big paid ones on specific tests, did not hold up. That is the one claim my refute pass killed. They could not be substantiated across sources. The open-versus-closed gap is genuinely unsettled, not won.

None of this means the tools are bad. The open model is genuinely open-weight and genuinely cheap, which is the part that actually matters. Cheap tokens are what make “run it twice and throw the first attempt away” a sane thing to do. That is the same shift that hit the field when DeepSeek landed. The economics are the story, not the leaderboard screenshots.

Why it compounds, and why that is the real moat

The reason to build a loop instead of a better prompt is defensibility.

Anyone can rent the same model you use. Nobody can copy three things: your skill library, the documents you fed in to make the output sound like you, and your constraints file, the running list of every mistake the verify gate caught and turned into a permanent rule. Those were built from months of your real runs.

That is why the first run takes twenty minutes and the fiftieth takes thirty seconds, sharper each time. The model did not get smarter. Your system did. I have watched three model generations come and go while the same files kept running, and each one got better at the job, not because of the model, but because the scaffolding around it kept absorbing what I learned.

“Self-improving” does not mean the weights retrain on your runs. They do not. The system around the model improves. Anyone telling you otherwise is selling something.

When not to build one

I am not going to pretend swarms are for everything, because they are not, and the honest version of this is what separates builders from resharers.

The strongest counter-argument is simple: the same loop that compounds wins also compounds errors. With no human-anchored ground truth, a flawed spec drifts and the system gets confidently wrong faster. The mitigations are the verify gate, the constraints file as a ratchet, and a human who stays on the question and the final decision.

Cost is the other catch. The lab that builds these said it plainly: running parallel agents this way burns roughly fifteen times the tokens of a normal chat, so it only pays off on high-value work. And it is a poor fit for tasks that need one coherent thread of reasoning, like writing a single long argument, or anything where the parts depend tightly on each other. Swarms shine on work you can split, run in parallel, and check: research, monitoring, broad data gathering. Not everything.

Build one this week

You do not need the 300-agent setup to get the benefit. Here is the smallest version that is a real loop and not a toy.

Start with a spec, not a prompt. Pick one task you actually repeat, like a weekly competitive brief. Write down what to collect, which sources count, the exact output format, and what to do when sources conflict. Treat the system like a contractor, not a genie.

Fan the independent parts out to separate agents, each working in its own clean context and handing back a short summary. Then add the gate: a second pass that tries to tear the output apart before you trust it. Capture the whole thing as a reusable skill so next week starts from it. Every flaw the gate catches becomes one line in a constraints file the system reads first, every time. Once it is stable, put it on a schedule and let it surface only the result and anything that looks off.

That is the loop. The only human left in it is the question you set and the decision you make on the answer.

I am not theorizing here. I maintain an open-source second brain that has been cloned and starred by over 2,500 developers. It is a loop: it reads its own notes, does the work in steps I can check, and writes back what it learned so the next run starts smarter. Plain files, in git, no framework. The model underneath has changed three times. The loop kept running.

Build it once. Verify it. Distill it. Then watch it get cheaper and sharper every single time you run it.

Subscribe now

Frequently asked questions

What is an AI agent loop?
It is a system where a model does a task, checks the result, and saves what it learned so the next run starts from a better place. Unlike a one-off prompt, a loop accumulates skills and rules over time, so it improves with use even though the model itself never changes.

What is an AI agent swarm?
It is many agents running in parallel on pieces of one task. A coordinator splits the job, each agent works in its own context and returns a short summary, and the coordinator assembles the result. It beats a single agent on tasks you can break apart, because each piece gets a clean, focused context.

Can an open model really run 300 agents at once?
That number is the vendor’s stated maximum, not a measured benchmark. Real public demos ran closer to 30 to 100 agents. The capability to orchestrate many agents is real. The “300 and 4,000 steps” figure is a marketing ceiling, so treat it as such.

Is “self-improving AI” actually the model learning?
No. The model’s weights stay frozen. What improves is the system around it: a growing library of saved skills, fed documents, and a constraints file of past mistakes. The loop gets smarter. The model does not. Anyone implying live retraining from your runs is overselling.

Why do I need a verify gate?
Because a swarm produces confident, under-checked output, and some of it is quietly wrong. A second model told to refute the work catches flaws before they get saved as a permanent skill. Checking is cheaper than generating, which is why this step pays for itself.

When should I not use an agent swarm?
Skip it for tasks that need one coherent line of reasoning, for tightly interdependent work, and for low-value jobs where the extra cost is not worth it. Parallel swarms can use around fifteen times the tokens of a normal chat, so they fit high-value, splittable, checkable work.

Key takeaways

• An AI loop beats a prompt because it compounds: every run leaves behind a skill, a document, or a rule that makes the next run faster and sharper, while the model stays frozen.

• The pattern is not new. ReAct (2022) gave us the base loop, Voyager (2023) gave us reusable skills, and “compound engineering” (2025) gave it a name.

• A swarm beats one long agent because each piece runs in its own clean context, avoiding the context rot that degrades a single agent on a long task.

• The verify gate is the one non-optional move. A cheap model generates at volume, a trusted model refutes the output, because checking is easier than generating.

• The viral numbers are vendor marketing. “300 agents, 4,000 steps” is a capability ceiling, not a benchmark, and the head-to-head leaderboard claims did not survive fact-checking.

• The real advantage of open models is cost, not benchmarks. Cheap tokens make “run it twice, throw the first away” rational, the same shift DeepSeek triggered.

• Swarms are for splittable, checkable, high-value work. They burn roughly fifteen times the tokens of a chat and are a poor fit for single coherent arguments or tightly coupled tasks.

Further reading

• Anthropic, Building Effective Agents (the canonical taxonomy of workflows versus agents, and the orchestrator-worker and evaluator-optimizer patterns). Search “Anthropic Building Effective Agents”.

• Yao et al., ReAct: Synergizing Reasoning and Acting in Language Models (ICLR 2023, the origin of the agent loop). On arXiv.

• Every, the compound engineering essays by Kieran Klaassen (where the self-improving-system thesis got its name).

• Cognition AI, Don’t Build Multi-Agents (the strongest skeptic case, on when parallel agents hurt you).

• I built this for myself. Then 1,374 strangers cloned it.

• The obsidian-second-brain skill on GitHub: github.com/eugeniughelbur/obsidian-second-brain

About the author

Eugeniu Ghelbur is an AI Automation Engineer at Single Grain, where he builds production AI systems for marketing and sales workflows. He ships open-source Claude Code skills and writes about AI knowledge management at theaioperator.io. The obsidian-second-brain skill described here is live on GitHub at github.com/eugeniughelbur/obsidian-second-brain, where it has been starred by over 3,000 developers.

TL;DR
A folder-native AI agent keeps its memory and its work in the same place: folders of plain markdown, in git, with no database and no framework. Google’s Open Knowledge Format (OKF) standardizes the memory half. The University of Edinburgh’s Interpretable Context Methodology (ICM) standardizes the workflow half. Wire them together and you get one agent that reads its own memory, does the work in steps you can check, and writes what it learned back, so it starts smarter every run. This post gives you the exact folder layout, what goes in each file, the loop that makes it compound, and where it breaks.

Two research groups shipped the same idea three months apart, and nobody put the two halves together.

In March 2026, two researchers at the University of Edinburgh published a paper arguing you do not need a multi-agent framework to run an AI workflow. You need numbered folders, each holding a markdown file that tells the agent what to do at that step. The folder structure is the program. Jake Van Clief, who co-authored the ICM paper, has been one of the most consistent public voices explaining how it works.

In June 2026, Google shipped the Open Knowledge Format. Its claim: you do not need a vector database to give an agent its knowledge. You need a folder of markdown files with a little metadata on top, readable by any agent or any human.

One group described how an agent does work. The other described how an agent remembers. Both landed on the same answer: plain markdown, in folders, in git. I wired the two halves into one agent. Here is exactly how it works, and how to build your own.

Subscribe now

What “folder-native” actually means

A folder-native AI agent is an agent whose memory and workflow are both ordinary files on disk, not records in a database or steps inside a framework.

That is the whole definition. No special runtime. If you can open a file, you can read its memory. If you can clone a repo, you can ship the whole agent. Three pieces make it work, and you already understand all three:

• Markdown is the format. Human-readable text with light structure.

• Folders are the organization. Nesting and naming carry meaning the agent can follow.

• Git is the spine. Version history, diffs, and rollback come for free.

Everything below is built from those three pieces and nothing else.

The filesystem keeps winning

This is not new, which is exactly why I trust it.

In 1978, Doug McIlroy wrote the rule that made Unix powerful: make each program do one thing well, and let plain text pass between them as the universal interface. Fifty years later, every clever layer we bolted on top has aged worse than the plain-text idea underneath. (the Unix philosophy, McIlroy, Bell Labs)

AI is repeating the pattern. We spent two years building scaffolding around language models: vector stores, orchestration frameworks, memory layers with their own SDKs. The quiet result of the last few months is that a folder of markdown beats most of it for the work people actually do.

I wrote about Karpathy’s LLM Wiki when it first went around. The insight: humans abandon wikis because keeping them current is tedious, but a model does not get bored. It will update a cross-reference for the thousandth time without complaint. OKF and ICM are what that insight looks like once it grows into a standard.

Two halves nobody put together

Here is the part worth your attention.

OKF is memory. It is where knowledge lives: facts, context, decisions, people, written as markdown and updated over time. The brain the agent reads from.

ICM is work. It is how a job gets done in stages: research, then draft, then produce, with a human checking the output between steps. The hands.

Every write-up I have seen treats these as separate. They are not. They share the same material, folders of markdown, which means the workflow can read straight from memory and write straight back into it. No glue code. No translation layer. The brain and the hands speak the same language because they are made of the same thing.

What the agent actually looks like

Here is the literal anatomy. One repo, two top-level folders, all markdown.

my-agent/
  memory/                  <- OKF: what the agent knows
    people/
      john-smith.md
    projects/
      weekly-report.md
    decisions/
      pricing-2026.md
    MEMORY.md              <- index: one line per note
  workflow/                <- ICM: how the agent does a job
    01-research/
      CONTEXT.md           <- instructions for this step
      output.md            <- what the step produced
    02-draft/
      CONTEXT.md
      output.md
    03-produce/
      CONTEXT.md
      output.md
  README.md                <- how to run it

Read that tree once, and you understand the entire system. memory/ is the brain. workflow/ is the job, broken into numbered steps a human can read in order. There is no hidden state anywhere. The folder structure is the program.

Inside a single stage

Each numbered folder holds two files. A CONTEXT.md that tells the agent what to do (this is the contract file the ICM paper is built around), and an output.md where it writes the result. Here is what a CONTEXT.md looks like:

# Stage 02 - Draft

## Read first
- memory/projects/weekly-report.md
- ../01-research/output.md

## Do
Write a 1-page client report. Use last week's numbersfrom the research step. 
Match the client's tone from their note in memory.

## Write to
output.md

## Stop
Wait for the human to approve before stage 03 runs.

That is the entire instruction set for one step. Plain English, two file paths to read, one file to write, and an explicit stop. The agent opens CONTEXT.md, pulls exactly the memory it names, does the work, and writes output.md. Then it stops and waits for you.

This is the part frameworks make hard and folders make trivial: every step is a file you can open, read, and correct before the next one runs.

The loop that makes it compound

A pipeline of stages is useful. The loop is what makes it an agent that gets better.

After the work ships, the agent does one more thing: it takes the new facts it learned this run and writes them back into memory/. Next run, it starts from a smarter place, because the work it did became part of what it knows.

The full cycle, all in files:

1. Read the relevant notes from memory/.

2. Do the stage, writing output.md.

3. You check the output and fix it in the file if the angle is off.

4. Write back the new facts into memory/.

5. Next run starts from the updated memory.

That is a complete agent. Memory it reads, work it runs, and a loop where the work makes the memory better. All of it plain files you can read on a Tuesday afternoon with nothing open but a text editor.

Subscribe now

A worked example: the weekly client report

Concrete beats abstract. Say you want an agent to write your weekly client report.

Stage 01 reads the client’s note from memory/people/, pulls this week’s numbers, and writes a research summary to output.md. You glance at it. If a number is wrong, you fix it in the file.

Stage 02 reads the client’s project note and the research output, then drafts the report into its own output.md. You read the draft. If the angle is off, you correct it right there before anything else runs.

Stage 03 polishes the draft into the final report.

Then the loop closes: the agent writes the new facts it learned this week (a changed priority, a new contact, a decision the client made) back into memory/people/ and memory/decisions/. Next Monday, the agent starts from a smarter place. You did not retrain anything. You did not migrate a database. You edited text files.

Why this beats the stack you were about to build

Three reasons, and none are about benchmarks.

You can see everything. No hidden state, no opaque vector index, no “trust me” black box. Every intermediate step is a file. When the output is wrong, you open the folder and find where it went wrong. The system is inspectable by default, not because someone bolted on a logging dashboard.

You can change anything. A non-technical person can edit a markdown file. The person who owns the work can correct the agent without calling a developer. The control surface is a text editor.

It outlives the model. Your knowledge and workflows are not trapped inside a product. They are files in a folder in git. When the next model drops, you point it at the same folder. Nothing to migrate, nothing to rebuild. I have watched three model generations come and go while my own setup kept running on the same files.

How to build your own this week

You do not need either standard to start. You need a folder. Here is the smallest version that works:

1. Make two folders: memory/ and workflow/. Put them in a git repo.

2. Seed memory. Drop in a handful of markdown notes about the things your agent needs to know. One fact per file. Add a MEMORY.md Index with one line per note.

3. Write one stage. Create workflow/01-do-the-thing/CONTEXT.md with three sections: what to read, what to do, what to write. Point an agent (Claude Code, or any tool that can read and write files) at it.

4. Run it and read the output. Fix the output file by hand if it is off. This is the human-in-the-loop, and it is the point, not a workaround.

5. Close the loop. Add a final instruction: write any new facts back into memory/. Run it again next week and watch it start smarter.

6. Add stages only when a single one gets crowded. Split 01 into 01-research and 02-draft When the instructions stop fitting on one screen.

Add the heavy machinery (a database, a framework) only when a folder genuinely cannot do the job. That moment is later and rarer than you think.

Where this breaks

I am not going to tell you that folders solve everything, because they do not.

The Edinburgh paper is honest about this, and so am I. This pattern fits sequential work that a human reviews. It is not built for real-time, many-agents-talking-at-once systems, or high-concurrency services where you need queues and proper infrastructure. For that, the frameworks earn their complexity.

Both standards are also early. OKF is a version 0.1 from a single company. ICM is a young methodology with a small community. This is the start of something, not a settled stack. I am betting on the direction, not claiming the destination.

But for the large, boring middle, the reports and the research and the content and the knowledge work most of us spend our days on, the folder wins. It is simpler than the problem we built frameworks to solve.

I am not theorizing

I maintain an open-source second brain that has been cloned and starred by over 3,000 developers. It is folders of markdown, maintained by AI, on the exact pattern OKF describes. The code is public: github.com/eugeniughelbur/obsidian-second-brain.

This week I made it speak the standard directly. It now exports a valid OKF bundle, so the vault any of those developers run is portable to anything that reads the format. I also run a capture pipeline that takes a voice note or a photo from my phone and files it into the right note, plus a step that means the agent never leaves a dead link: when it references a person or project that has no note yet, it creates that note and fills it.

None of that is a demo. It is what I use every day. The point is not the specific tool. The point is that the architecture works, you can see it working, and you can build it yourself, because it is just files.

Start with a folder

If you take one thing from this: stop reaching for a database or a framework as the first move. Start with a folder of markdown. Let the agent read it, work in it, and keep it current.

The filesystem won the first time, in 1978. It is winning again, for the same reason: plain text outlasts the scaffolding built on top of it. The only question is whether you start now or after everyone else has.

Subscribe now

Frequently asked questions

What is a folder-native AI agent?
A folder-native AI agent is an AI agent whose memory and workflow are both stored as plain markdown files in folders, versioned in git, with no database and no orchestration framework. The agent reads its memory from files, does work in numbered stage folders, and writes new facts back to memory.

What is the Open Knowledge Format (OKF)?
OKF is a standard from Google Cloud, released in June 2026, for packaging knowledge as a folder of markdown files with simple metadata, so AI agents can read and maintain it without a database or scraping. It defines the memory layer of a folder-native agent.

What is Interpretable Context Methodology (ICM)?
ICM is a method from a 2026 University of Edinburgh paper for running multi-step AI workflows using numbered folders and markdown instead of a coding framework. One agent reads the right file at each stage, and a human reviews the output between stages. It defines the workflow layer.

How are OKF and ICM related?
They are the same idea applied to two halves of one agent. OKF is the memory (what the agent knows). ICM is the workflow (how the agent does work). Because both are folders of markdown, you can wire them together so a workflow reads from memory and writes back to it.

Do I need a vector database for AI memory?
For a lot of everyday knowledge work, no. A folder of markdown the model reads directly avoids the “lost in the middle” problem of stuffing everything into one prompt (Liu et al., 2023), and it is far simpler to inspect and edit. Databases earn their place at scale, not by default.

Is folder-native AI ready for production?
For sequential, human-reviewed workflows, yes, people run it today. For real-time, high-concurrency, or many-agent systems, no, you still want proper infrastructure. Both OKF and ICM are early, so treat this as a direction to build toward, not a finished standard.

Can I use this with my existing Obsidian vault?
Yes. An Obsidian vault is already folders of markdown, which is most of the way to OKF. That is why the pattern is spreading fast among people who already keep notes this way.

Key takeaways

• A folder-native AI agent keeps memory and work as plain markdown in folders, in git, with no database and no framework.

• Two 2026 standards landed on the same answer independently: Google’s OKF for the memory layer, the Edinburgh ICM paper for the workflow layer.

• Wire them together and a workflow reads from memory and writes back to it, so each run makes the agent’s memory smarter.

• The build is simple: two folders (memory/ and workflow/), one markdown note per fact, one CONTEXT.md per step, a human check between steps, and a loop that writes new facts back.

• The real advantages are inspectability, editability by non-developers, and surviving the next model with zero migration. Not speed.

• Folders are not for everything. Real-time and high-concurrency systems still need real infrastructure. This fits the large, sequential, human-reviewed middle.

Further reading

• Google Cloud, How the Open Knowledge Format can improve data sharing (the OKF v0.1 announcement, June 2026).

• Van Clief & McDermott, Interpretable Context Methodology: Folder Structure as Agentic Architecture (University of Edinburgh, arXiv:2603.16021, March 2026).

• The ICM reference implementation on GitHub: github.com/RinDig/Interpreted-Context-Methdology.

• Jake Van Clief on ICM (co-authored the paper and posts regularly about the methodology publicly).

• Andrej Karpathy’s LLM Wiki gist (the origin of the “agents do not get bored maintaining a wiki” insight).

• Liu et al., Lost in the Middle: How Language Models Use Long Contexts (why folders the model reads directly beat one giant prompt).

• I rebuilt Karpathy’s LLM Wiki. Here’s what’s missing from the original.

• I built this for myself. Then 1,374 strangers cloned it.

• The obsidian-second-brain skill on GitHub: github.com/eugeniughelbur/obsidian-second-brain

About the author

Eugeniu Ghelbur is an AI Automation Engineer at Single Grain, where he builds production AI systems for marketing and sales workflows. He ships open-source Claude Code skills and writes about AI knowledge management at theaioperator.io. The obsidian-second-brain skill described here is live on GitHub at github.com/eugeniughelbur/obsidian-second-brain, where over 3,000 developers have starred it.

The internet has spent two months designing a “v2” of Andrej Karpathy’s LLM Wiki: confidence scores, supersession chains, forgetting curves, vector search, lifecycle hooks.
I rebuilt the original and have run it every day for months across a repo that 2,317 people have now starred.
Here is the honest report on which v2 ideas earn their place, and which are overkill you will rip out in a week.

Andrej Karpathy posted a gist last year describing how he keeps an LLM-maintained wiki: raw sources go in untouched, the AI owns a folder of markdown notes, and a rules file tells it how to ingest, update, and query. I rebuilt that pattern as a working system and wrote about what the original left out.

Since then a small genre has appeared. People are publishing “LLM Wiki v2” gists. The most-shared one (by a developer who goes by rohitg00) adds confidence scoring, supersession chains, forgetting curves, hybrid vector search, and event hooks. Other versions pile on audit trails, tiered memory, and quality scores.

It reads like a real upgrade. Most of it is not.

I am not theorizing. I have run my rebuilt wiki every day for months, and I open-sourced the whole thing as obsidian-second-brain. So here is the difference between the v2 ideas that survive contact with daily use and the ones that look smart in a gist and die in practice.

First, the part everyone gets right

If you landed here cold, the pattern is three layers, and it genuinely works.

One: raw sources, immutable. Whatever you feed it (an article, a transcript, a meeting) lands in a folder and never gets edited. That is your ground truth.

Two: the wiki. A folder of markdown notes the AI owns and rewrites. New information does not get appended to the bottom. It gets folded into the existing note, and contradictions get reconciled.

Three: the rules file. One markdown file that tells the AI how to ingest a source, how to update a page, how to record what it did. An index.md for navigation and an append-only log.md for history.

The reason it beats dumping everything into a giant context window: a curated wiki of 50,000 to 100,000 tokens answers most questions without loading your entire corpus. You spend tokens on the answer, not on the haystack. That part is real and v2 does not change it.

What “v2” actually means right now

There is no official v2. Karpathy’s gist is still the only canonical spec. “v2” is a community label for a pile of proposed additions, and they cluster into two buckets.

Governance features: confidence scores on claims, supersession chains so an old fact points to the new one that replaced it, and “forgetting curves” so stale notes decay instead of rotting in place.

Retrieval and infrastructure: hybrid search (keyword plus vector embeddings), lifecycle and event hooks, quality scoring, tiered memory.

The first bucket is about whether the wiki tells you the truth. The second is about machinery. After months of running this, the split between them is exactly the split between what works and what is overkill.

Subscribe now

The v2 ideas I shipped and kept

The governance bucket earns its place. Every one of these is in the system I run.

Confidence markers. Every claim my wiki writes carries a tag: stated, high, or low. It costs almost nothing (one word per fact) and it changes how you read. When the AI synthesizes across notes, a stated claim gets treated as a quote, not a truth. This is the single highest-value v2 idea and it requires zero infrastructure.

Supersession, done as reconciliation. When a new source contradicts an existing note, the wiki does not keep both and shrug. A command reconciles them: the note gets rewritten to the current truth, and the change is logged. You do not need a formal “supersession chain” data structure. You need the AI to actually resolve the conflict instead of hoarding it.

A forgetting curve, but boring. The fancy version tracks decay scores and timestamps. Mine is simpler: lessons get reviewed, and the ones that stopped being true get pruned. Notes that just accumulate become a graveyard. The point of a forgetting curve is not the math. It is that something deletes.

Lifecycle hooks, as scheduled agents. This one is real and I run it. Background agents wake up on a schedule and maintain the wiki while I am not looking: reconcile contradictions, synthesize patterns, flag stale claims. You do not need an event-bus abstraction. You need cron and a rules file.

The v2 idea I skipped, and why

Hybrid vector search is the headline feature of almost every v2 gist. I tried it. I took it out.

Here is the thing nobody writing these gists seems to have measured: at wiki scale, you do not have a retrieval problem. A curated wiki is 50,000 to 100,000 tokens. That is small. Grep plus read finds the right note faster and more predictably than an embedding lookup, with no vector database to host, no index to keep fresh, and no “why did it return that chunk” debugging.

Vector search earns its keep at hundreds of thousands of documents. A personal or team wiki is not that. Bolting embeddings onto a 200-note vault is solving a problem you do not have, and paying for a database to do it.

The same goes for tiered memory and elaborate quality-scoring engines. They are answers to scale problems. At the scale where an LLM wiki is actually useful, they are weight.

What is genuinely still missing

Honesty cuts both ways, so here is the gap the v2 gists also miss.

None of them have a real guard against the AI lying about what is in the wiki. I learned this the hard way: when I read through the forks of my repo, a stranger had added the exact thing I lacked. The most common failure is not the AI making up a fact. It is the AI saying “there is no note about that” when there is, because it answered from memory instead of actually searching.

That is the real frontier of v2. Not fancier retrieval. A rule that forces the model to verify presence and absence by listing and grepping, never from memory, before it tells you something does not exist. I am merging that guard in now. No v2 gist I have seen includes it.

The actual lesson

The v2 discourse has the direction backwards. It treats the upgrade as machinery you add: a vector store, a scoring engine, a memory hierarchy.

The version that works is the opposite. It is the smallest set of rules that makes the AI maintain its own truth. Confidence on every claim. Contradictions resolved, not hoarded. Stale notes deleted. An agent that does the maintenance on a schedule. All of that lives in the rules file, and none of it needs a database.

Karpathy’s original insight was that the wiki should be plain markdown the AI owns. The real v2 honors that. It does not drown it in infrastructure.

The full system is open source at obsidian-second-brain. I built it for myself first, and the rules file is the part worth reading. That is where the v2 actually lives.

Frequently asked questions

What is Karpathy’s LLM Wiki?
A pattern Andrej Karpathy shared for letting an AI maintain a small markdown knowledge base. Three layers: raw sources kept immutable, a wiki of notes the AI owns and rewrites, and a rules file that tells it how to ingest, update, and query.

What is “LLM Wiki v2”?
A community label, not an official release. Karpathy’s gist is still the only canonical spec. “v2” refers to additions people propose in their own gists: confidence scores, supersession chains, forgetting curves, hybrid vector search, and lifecycle hooks.

Do you need vector search for an LLM wiki?
No, not at wiki scale. A curated wiki is 50,000 to 100,000 tokens, and grep plus read finds the right note faster and more predictably than embeddings, with no database to host. Vector search earns its place at hundreds of thousands of documents.

Which v2 ideas are actually worth adding?
The governance ones: confidence tags on claims, reconciling contradictions instead of hoarding them, pruning stale notes, and a scheduled agent that maintains the wiki. Each is a few lines in the rules file, not new infrastructure.

How large can an LLM wiki get before it breaks?
It is built for small, curated corpora, roughly 50,000 to 100,000 tokens. Past that, the scale features the v2 gists propose start to matter. At the size where an LLM wiki is most useful, they are weight.

Where can I get a working implementation?
The full system is open source as obsidian-second-brain, a Claude Code skill on GitHub.

Key takeaways

• Karpathy’s three-layer pattern (immutable sources, an AI-owned wiki, a rules file) is solid, and v2 does not change it.

• “LLM Wiki v2” is a community label, not an official release. Karpathy’s gist is still the only canonical spec.

• The v2 ideas worth keeping are all governance: confidence tags, reconciliation, pruning, and scheduled agents. Each costs a few lines in the rules file.

• Hybrid vector search is overkill at wiki scale. Grep plus read wins below hundreds of thousands of documents.

• The real gap no v2 gist covers is an anti-hallucination guard against false absence: the AI claiming a note does not exist when it does.

• The upgrade is rules the AI enforces on itself, not bolted-on machinery.

Further reading

• Andrej Karpathy’s original LLM Wiki gist (2026-02)

• rohitg00’s LLM Wiki v2 gist (2026-03)

• I rebuilt Karpathy’s LLM Wiki. Here’s what’s missing from the original.

• Your notes are a graveyard. Here’s how to bring them back to life.

• obsidian-second-brain on GitHub

About the author

Eugeniu Ghelbur is an AI Automation Engineer at Single Grain, where he builds production AI systems for marketing and sales workflows. He ships open-source Claude Code skills and writes about AI knowledge management at theaioperator.io. The obsidian-second-brain skill described here is live on GitHub at github.com/eugeniughelbur/obsidian-second-brain, where it has been starred by over 2,300 developers.

Most note apps are where ideas go to die. You write something sharp, tag it, feel organized for an afternoon. Six months later you can’t find it, can’t remember the decision behind it, and you repeat a mistake you already made once and wrote down. (I wrote a whole piece on why your notes are a graveyard if you want the long version.)

I built obsidian-second-brain to end that. It’s an open-source system that turns a plain Obsidian vault into something that reads, writes, researches, and argues back, all driven by talking to an AI agent instead of clicking around. This week it got its biggest update yet. I call it The Architect, and it closes the one gap that bothered me most: the thing you spend most of your day inside, your codebase, never lived in your second brain. Now it does.

Let me show you what it could already do, then walk you through what just changed and how.

Subscribe now

What this thing actually is

If you’re new here: this started as my own attempt to rebuild Andrej Karpathy’s old “LLM Wiki” idea, a vault that rewrites itself as you feed it. I wrote up what I rebuilt and what was missing from the original. I built it for myself. Then 1,374 strangers cloned it, and it turned into a real project: 1,500+ stars, MIT licensed, and it runs on four different AI coding tools (Claude Code, Codex, Gemini, OpenCode) from one codebase.

It is not a notes app with AI bolted on the side. There’s no chat box in a corner. You operate the whole vault through commands you run by talking to the agent, and the agent does the filing, linking, and rewriting that you’d normally do by hand and never actually do.

Before: a second brain that already thinks

Here are a few of the commands that were already in place, and what they actually do day to day:

• /obsidian-save is the one that hooks people. You finish a long conversation with the AI and just say “save this.” It spins up parallel agents that pull out every person, project, decision, task, and idea from the chat, writes each one as a properly linked note, and updates your daily log. One command. You stop being a librarian for your own life.

• /obsidian-ingest takes a URL, a PDF, or a YouTube link. The vault doesn’t just file it in a folder. It rewrites itself around it: one source can touch 5 to 15 existing notes, updating what changed and linking what’s related.

• /obsidian-challenge is the one nobody expects. You pitch an idea and your own vault argues back, using your past notes and decisions as ammunition. It’s caught me about to repeat a mistake I’d already made and documented. I wrote about building a tool that lets my vault argue with me when I first shipped it.

• /research-deep reads what your vault already knows on a topic, finds the gaps, researches only those, and hands you the delta. No re-reading what you’ve already got.

• /obsidian-daily, /obsidian-visualize, /obsidian-reconcile give you your whole day pulled together each morning, a visual map of your entire knowledge graph, and a pass that hunts down contradictions across your notes and resolves them.

That was already 30-some commands of “your notes, alive.” Useful. But there was a hole in it, and once I saw it I couldn’t unsee it.

The gap: your code lived outside your brain

The vault captured my ideas, my people, my decisions, my research. But the thing I spend the most hours inside, the actual codebase, lived nowhere near it. It lived in a stale README that was wrong the week after I wrote it, and in my own head, which is worse, because heads leak.

So I’d save a sharp architectural decision into the vault (”we’re queueing webhooks instead of processing them inline, because X”), and three months later the decision note and the code that the decision shaped had no idea the other one existed. The knowledge was split in two and both halves rotted at their own speed.

That’s the gap The Architect closes.

After: The Architect

/obsidian-architect points the system at a software project and turns it into part of your second brain.

/obsidian-architect ~/Projects/my-app

Here’s what it does, in three parts, because the third part is the one that matters most.

What it does. It scans the whole project: languages, modules, dependencies, entry points. Then it writes a set of notes straight into your vault. An overview note with a diagram of how the pieces fit. One note per module, describing what that module does and what it depends on. And a “key decisions” note pulled from your own commit history, so the why behind the code gets captured, not just the what.

Why it’s powerful. Those notes aren’t dead documentation sitting in a docs/ folder nobody opens. They’re linked into everything else in your vault. A decision you saved months ago can now point straight at the module it shaped. “How does billing work again?” stops being a 40-minute code-reading session and becomes a question your vault answers in one note, with links out to the exact modules and the decisions behind them.

The part that makes it stick. Documentation always rots because writing it is a one-time act and the code keeps moving. So I built the refresh to be safe to re-run. Run /obsidian-architect again any time and it refreshes only the parts it generated. Anything you wrote by hand inside those notes is fenced off and never touched.

That fencing is the whole trick. Under the hood, the generated sections live between markers, and your hand-written notes live outside them. On a re-run, the agent regenerates what’s inside the fence and leaves everything outside it exactly as you left it. So the docs stay true as the code moves, instead of being accurate for exactly one day.

Before: my code knowledge lived in my head and decayed. After: it’s documented, linked, and self-updating, in the same brain as everything else I think about.

Everything else that got more powerful

The headline is The Architect, but this was a big release and the whole tool levelled up. The short version of what else landed:

• Research went free. Before this, /research needed a paid Perplexity key or it just errored out, which was the single biggest reason people bounced on first install. Now, with no key at all, it pulls from free public sources (Wikipedia, Hacker News, arXiv, Reddit, and more) and the AI writes the dossier from those. It works, for free, the second you install it. If you do have a key, it still uses it for deeper pulls.

• It learned your calendar. New commands pull your week into a note, book an event straight from a task, and turn a meeting into a note. There’s also a reconcile pass that checks your vault against your calendar and flags commitments you wrote down but never actually scheduled.

• It stopped lying by omission. The sneakiest AI failure mode isn’t making things up. It’s confidently telling you “you have no note on that” when you do, because it didn’t look hard enough. There’s now a hard rule baked in: search the whole vault before ever claiming something is missing.

• New thinking tools. You can convene a panel of different perspectives on a decision (/obsidian-panel), cross-reference everything your vault knows on one topic (/vault-deep-synthesis), or surface what’s actually worth working on next (/idea-discovery).

• It got trustworthy. This release added the first automated tests and CI. That’s the line between a weekend hack and something you’d hand years of your own notes to. And as of this update it runs on Codex CLI too, not just Claude Code.

Put it together and the count is now 43 commands across four AI tools. One vault that reads, writes, argues, researches, and now maps your code.

If you want the wider tour of the commands I actually use in a normal week, I broke those down in 30+ AI shortcuts I built for my own work.

Subscribe now

Already using it?

Pull the latest and that’s the whole upgrade. Everything is additive. Nothing breaks. One change worth knowing about: the optional background helper that quietly writes to your vault now ships off until you switch it on. Safer default, not a lost feature. If you relied on it, flip it back on and you’re exactly where you were.

New here?

It’s one line to install (the command is in the repo). Then run /obsidian-init to set up your vault structure, and /obsidian-daily to create your first note. After that, you mostly just talk to it.

Repo: github.com/eugeniughelbur/obsidian-second-brain

A second brain shouldn’t stop at your ideas. The code you write is knowledge too, and the decisions behind it are the part you forget fastest. Now they live in the same place as everything else you think about, and they stay true on their own.

If you build with this, I want to hear what you point The Architect at first. Reply and tell me.

I built 30+ AI shortcuts for my own work over six months.

Three of them quietly took three hours off every workday.

This post is about those three, and what makes them load-bearing.

I have a folder of small text files. Each file teaches my AI assistant to do one specific thing for me. I type a short name, hit enter, and Claude runs the recipe in that file. Some of these recipes take ten seconds to run. Some take six minutes. All of them replace work I used to do by hand.

There are thirty-something of these recipes now. Some are tiny. Some are mega-commands that pull data from five places, talk to three APIs, generate an image, and write five drafts in a row.

I do not use all of them every day. Most of them I built for one specific moment and then they sit there until that moment comes back. The interesting set is the small group I run every day, sometimes three or four times a day. Those three are the ones I want to write about. The other twenty-seven are good. These three are why my Tuesdays used to take a full day and now take a couple of hours.

What I mean by “shortcut”

If you have used ChatGPT, you have typed a prompt. A shortcut is a prompt I already wrote down for myself. Instead of typing the whole prompt every time, I type a short name and the AI loads the prompt and runs it on whatever context the conversation already has.

I work in a tool called Claude Code. It is the place I write code and the place I write everything else, including this post. Inside that tool, my shortcuts are stored as small Markdown files. There is no app to install, no SaaS to pay for, no UI. The shortcut is the prompt, and the prompt is the file. (The same setup is what I described when I rebuilt Karpathy’s LLM Wiki, if you have not read that one yet.)

This matters because the shortcuts compound. Each one I build can call any of the others. A morning routine shortcut runs a research shortcut, which calls a vault-search shortcut, which calls a write-to-disk shortcut. The composition is the whole point.

1. The one that writes my newsletter

The newsletter you are reading right now was drafted by a shortcut I built last week.

When I type the name of it, the shortcut does this: it scans the last seven days of my private notes, the last seven days of Google search data on my website, the last seven days of analytics on which posts people read, the last fourteen days of any deep-research I ran in another tool, recent issues and merges on my public GitHub repository, and a few other places. It scores every possible topic against five rubrics, then surfaces the top five candidates to me. I pick one. It then runs a research pass on that topic, drafts the newsletter, drafts the X version, drafts the LinkedIn version, drafts the Medium version, generates a hero image, runs a voice check, and saves everything.

The first time I ran it, the full pipeline took six minutes and produced a draft I could ship after fifteen minutes of editing.

Before this shortcut existed, the same workflow took me four hours on a good day. On a bad day, it took two days, because deciding what to write about was its own meeting with myself. I would scroll, second-guess, draft three openings I deleted, lose the thread, and end up posting nothing.

The shortcut does not write better than I do. What it does is remove the part where I have to start, which is the only part of writing I actually struggle with.

Saved per use: about four hours. I run it once or twice a week. That alone is about an hour back per day if I average it out.

Subscribe now

2. The one that turns my Claude chats into actual notes

I have a lot of conversations with Claude that produce real information. A decision, a project update, a meeting summary, a person I should remember, a debugging session that ended in a fix. Before I built this shortcut, all of that knowledge stayed inside the chat window. I would lose it the moment I closed the tab.

The shortcut reads the current conversation, figures out what is worth keeping, and writes the right kind of note to the right place in my second brain. A decision becomes a decision record with a date and a wikilink to the people involved. A project update becomes an append to the project’s note. A person I just talked to becomes a contact card, or updates the existing one. The whole thing takes about ten seconds and writes between one and six files.

I run this one between three and ten times a day. Every Claude session that produces something real ends with this shortcut.

The hidden value is not the ten seconds I save versus typing the notes by hand. It is that the notes actually get written. Before this existed, the answer to “did I write that down?” was almost always no. Now the answer is yes, and the writing is structured the same way every time, so future-me can find it.

Saved per day: about an hour, if you count the value of notes that would otherwise not exist at all. Hard to put a number on knowledge you would have lost, but a useful one to try.

Here I talk about the skill I built; Obsidian Second Brain (Starred by 1400 stars and used by more than 10k starngers now)

Subscribe now

3. The one that does my research

Whenever I need to understand something I do not already understand, I run a shortcut that does deep research for me. It uses Perplexity in the background, runs multiple passes, gathers citations, and writes a structured report to disk. Topics range from “is this stack the right choice for my new SaaS” to “what is the current state of this regulatory thing in Spain” to “what did this person just say on a podcast and is it on-topic for what I am building.”

A real research task that used to take me two to three hours of tabs, scrolling, and forgetting to bookmark now takes the shortcut about three minutes and produces a citation-grounded document I can either trust or push back on.

I do not use this every day. I use it three to five times a week. But each use saves enough time that on a research-heavy day, the shortcut is the difference between shipping something and not.

Saved per use: ninety minutes to two hours. Distributed across the week, this is conservatively an hour a day.

The pattern under the three

These three look unrelated. One writes a newsletter. One files notes. One does research.

They share one shape. Each one takes a thing that used to live inside my head and gives it to the machine, in a form the machine can repeat. The hard part was not the prompt. The hard part was deciding what to extract, which fields to require, which file format to write to, and what to do when the input is messy.

The actual lesson is not “build more shortcuts.” The lesson is that the bottleneck of working with AI is not the AI. The bottleneck is the lack of a clear, repeatable way to ask the AI for the thing you want, every single time, without thinking about it. Once you have that, the AI is fast, and you become fast.

Three hours a day, on a knowledge worker’s calendar, is the difference between treading water and shipping a side project.

What I am not saying

I am not saying everybody should learn to write these. Most people will not, and most people do not need to. What I am saying is that the shape of the win is reproducible. The same logic works in any tool that has prompts, including the AI tools your company is probably paying for and not using well.

If you want to see the actual shortcuts, they are at github.com/eugeniughelbur/obsidian-second-brain, MIT licensed, currently at 1,358 stars. (Earlier this month I wrote about what surprised me when 1,374 strangers cloned the repo. That post is the back-story to this one.) The shortcuts I described above are in that repo, or in a sibling project I am still building in the open.

The full set is thirty-something. Three save me three hours a day. The other twenty-seven save me thirty-second moments. The thirty-second moments add up too.

TL;DR

• Glean is a $7.2B bet that you can search your way out of a messy corpus.

• I think the wedge is the opposite: refuse bad notes at write-time.

• I have shipped the primitive at one-person scale in OSB v0.7. The company version is still a thesis.

New here? I write one post per Tuesday on AI workflows, agent patterns, and what actually works in production. Subscribe to The AI Operator →

Subscribe now

The wedge is write-time, not read-time

The way to beat Glean is to clean before you save, not search after. Glean is a $7.2B work-AI platform (Series F, June 2025, $200M ARR per Futurum 2025-09). It crawls Slack, Notion, Google Drive, Jira, builds a permissions-aware knowledge graph, and runs read-time search plus agentic actions across the pile. The pile stays a pile.

I think the better wedge is intercepting content at write-time. Before a note saves, an agent checks whether it has the metadata, the preamble, and the structure that make it findable later. If it does not, the note gets flagged at the door.

The logic is simple. If you clean on write, you do not need a seven-figure search layer to find things on read.

I want to be honest about scope up front. The validator hook runs against my personal vault, not a company corpus. But this is not pure theory either. Since shipping the primitive, a venture-backed founder who found me through the open-source repo became a paying consulting client, and over a recent in-person session signaled willingness to back the team version if I build it. The rest of this post is what that team version would look like. Public version of the pitch.

What “second brain for companies” would actually mean

A company second brain is a single graph where every document has one canonical home, typed links, and machine-readable metadata. Three properties define it:

• One canonical doc per concept. Duplicates get merged or redirected.

• Typed backlinks. Not just “this links to that,” but “this DECIDES that” or “this BLOCKS that.”

• Write-time validation. An agent reviews the note before it persists.

Glean does none of this. Glean is a flashlight in a warehouse. The thesis is to build the warehouse.

The primitive I have actually shipped

The primitive exists today as a Claude Code PostToolUse hook that enforces a write-time schema on every save. In OSB v0.7, I shipped it at hooks/validate-ai-first.sh. It runs every time Claude Code writes a file inside my vault path. The hook warns when a note violates the AI-first rule: missing frontmatter, missing preamble, missing ai-first: true, or otherwise failing the schema I have set for my own corpus.

This is a one-person primitive. It runs against my vault. It is not multiplayer, it has no duplicate detection across a team, and it has no notion of canonical ownership across humans. What it does prove is that the agent surface (Claude Code) plus the substrate (Obsidian, plain markdown, local files) can enforce a write-time schema without a separate server, a separate UI, or a separate buyer.

The repo is public at github.com/eugeniughelbur/obsidian-second-brain, MIT licensed, around 1.3K stars, 33 commands as of v0.8.0. (on May 19th, 2026).

What the company version would need

The personal hook is the architecture in miniature. To make it work for a team, four things have to be added:

1. Duplicate detection across a shared vault, not just schema checks on a single file.

2. Canonical-location suggestion when two docs claim the same concept.

3. Typed links (decides, blocks, supersedes, references) instead of bare wikilinks.

4. A multiplayer lock model so two people are not silently editing the same canonical doc.

The schema I would push for, carried in every doc’s frontmatter:

• type: decision, spec, retro, meeting, reference, draft

• owner: single human, not a team

• status: draft, active, archived, superseded-by

• links_in / links_out: typed (decides, blocks, supersedes, references)

• canonical_for: the concept this doc owns

• last_validated: ISO date

The agent rejects anything missing these. That sounds harsh. In practice the agent can fill most fields itself and ask one question. The cost of being strict at write-time is a short prompt. The cost of being loose is a six-month archaeological dig later.

Why Glean cannot pivot here

Glean cannot pivot here because write-time validation is a developer-tools sale, not an IT sale. Glean’s distribution is enterprise IT. Their buyer wants a layer over the existing mess because changing the mess is a political fight. Write-time validation requires changing how people write, which means changing the tool they write in.

That is a developer-tools sale, not an IT sale. Different buyer, different motion, different product surface. Glean does ship agentic write actions (Agentic Engine 2, Canvas co-authoring, Glean Protect Plus governance), but those are AI-agents-execute-tasks-in-source-systems, not validate-the-document-against-a-schema-before-it-saves. The wedge I want is at the editor, in the human’s write path, before the doc exists. The wedge has to start bottom-up, inside the writing tool, not top-down from a CIO budget line. That is why I built the open-source repo at github.com/eugeniughelbur/obsidian-second-brain instead of pitching a platform.

Subscribe now

How does this connect to the personal second brain

I have written about the personal version of this pattern in three places worth reading:

• I rebuilt Karpathy’s LLM wiki in Obsidian. The same canonical-doc-per-concept rule, scaled down to one person.

• I built a tool that lets my Obsidian vault talk back. The agent loop that the validator hook grew out of.

• I built this for myself, then 1,374 people cloned it. The signal that solo patterns find an audience.

The company version is not a new architecture. It is the personal vault pattern with multiplayer locks and a stricter schema.

Why this is the right wedge in 2026

Write-time cleanup became the right wedge in 2026 because three forces converged, and one third-party analyst already raised doubts about whether Glean’s knowledge-graph moat survives. Futurum Group wrote in September 2025 that Glean’s “future success depends on whether its knowledge graph depth can hold off an improving and natively integrated Microsoft 365 Copilot.” That is the moat question every founder should be asking about every search-layer business: what happens when the suite vendors index the same corpus natively. Three forces converged this year:

• Long context windows at production cost. Write-time validation against a meaningful slice of the corpus is finally cheap enough to run on every save.

• Glean’s $7.2B valuation made every PM realize search is the consolation prize for a clean corpus. The category is funded, which means the category is also legible to founders looking for the inverse bet.

• Agent surfaces inside editors are now real. Claude Code, Cursor, and the Obsidian plugin ecosystem mean an agent can sit in the write path without a custom client.

The opening is write-time cleanup as a layer that lives inside the editor, not a search box bolted on top.

Frequently asked questions

Is this a Glean competitor today?
No. Glean is a shipped product, $200M ARR by mid-2025, customers in 27 countries, $1M+ contracts growing 3x year over year (Futurum, 2025-09). I have a personal primitive and a thesis. The argument is about where the category is going, not where it is.

Does write-time AI cleanup slow people down?
It adds friction at save. The bet is that the friction is small relative to the time later spent hunting for the right version of a doc that should not have existed in the first place. I have not measured this at team scale.

Why Obsidian as the substrate?
Plain markdown, local files, plugin API, git-native. No other tool I have tried gives me a writable graph with a real agent surface I can hook into. The repo is at github.com/eugeniughelbur/obsidian-second-brain.

What is the proof you have right now?
A working PostToolUse hook in OSB v0.7 that enforces the AI-first schema against my personal vault. It runs on every Claude Code write inside the vault path. That is one-person proof of architecture. The business proof so far is one inbound founder, paid consulting client, in-person investor signal. Early. Not a term sheet. Enough to know the wedge is real to someone who runs a real company.

What would change your mind about the wedge?
If a team adopted write-time validation and the corpus did not get measurably cleaner, the thesis is wrong. The honest next step is to run that test, not to claim I already have.

So what

If you are choosing a knowledge tool in 2026, the question is not “which search is best.” The question is “what stops bad docs from being written in the first place.” Search is the tax you pay for skipping that question. The second brain for companies is the answer that skips the tax. I have the personal primitive. The company version is still a thesis, and I would rather say so than fake the receipts.

If you got value from this post:

• Free: I publish one of these every Tuesday on AI workflows, agent patterns, and what actually ships. Subscribe to The AI Operator →

• Paid ($8/mo or $80/yr): Monthly deep-dives with the actual code, configs, and setup walkthroughs behind the thesis posts. Coming up in a few weeks: the hooks/validate-ai-first.sh walkthrough, exact frontmatter schema, Claude Code PostToolUse config, and the prompt templates that catch what a regex cannot. Upgrade to paid →

• Repo: github.com/eugeniughelbur/obsidian-second-brain. The open-source primitive this post is built on. MIT licensed, 33 commands as of v0.8.0.

Find me on X: @eugeniu_ghelbur. Replies open.

Update, 2026: The AI Operator has narrowed its focus to AI and building with AI in production. This post is from before that shift. If that’s what you’re here for, start with I rebuilt Karpathy’s LLM Wiki, I built this for myself. Then 1,374 strangers cloned it., or what The AI Operator is now.

Every November, The Economist publishes a cover so dense with symbolism it launches a thousand conspiracy theories. The 2026 edition (40 years into their predictions practice) is the most analyzed magazine cover of the decade.

The question splitting readers: is it forecast, signal, or something more deliberate?

I’m an AI automation engineer. I read this cover the way I read product diagrams. Every element is there for a reason, and the reasons usually live in the second pass.

After two weeks decoding it, here’s what I found. 2026 isn’t the year the world breaks. It’s the year we discover how it already broke, and the role AI plays in keeping it that way.

Subscribe now

The Cover That Broke the Internet

Released November 10, 2025. The Economist’s “World Ahead 2026” cover renders a chaotic planet as a soccer ball, orbiting weapons, pills, surveillance drones, and a birthday cake marked “250.”

Within 48 hours it went viral. Not just in policy circles. Across TikTok, X, and conspiracy forums.

Why the obsession? The Economist isn’t just any magazine. 21% owned by the Rothschild family. Read by every G7 finance minister. When they publish predictions, markets move.

Their Editor-in-Chief attended the 2025 Bilderberg meeting in Stockholm. Their track record is “weirdly accurate.” They correctly predicted 6 of 9 major 2025 events, though they badly underestimated Trump’s 2024 victory (giving him only 33% odds).

But 2026 is different. Editor Tom Standage calls it “a year of uncertainty” where “the old world order is finished.” Not incremental change. Systemic recombination.

And almost every signal on the cover points at one accelerant: AI.

The Visual Grammar: Red vs. Blue, Chaos vs. Control

Start with the color. The cover splits the world into red and blue. That one choice is the geopolitical map.

Blue is the Western order. NATO, tech dominance, the dollar system, democratic institutions. Defensive posture, trying to hold the global chokepoints: SWIFT payments, semiconductor supply chains, shipping insurance.

Red is alarm. Disruption. Conflict. The revisionist powers (China, Russia), inflation zones, hot conflicts.

The interplay isn’t Cold War binary. It’s messier. A nervous system where a shock in one domain transmits instantly across the whole structure.

This isn’t East vs. West. It’s a Standards War. Two competing systems for AI regulation, trade rules, digital currencies, tech ecosystems.

Countries aren’t choosing sides. They’re navigating between two incompatible operating systems.

The 250 Birthday Cake: America’s Divided Jubilee

At the center sits a massive cake marked “250.” America’s 250th anniversary on July 4, 2026. Look closer.

Rising from the cake: a blue fist locked in handcuffs. Popular uprising met with authoritarian response. Below it, a cracked judicial gavel signals a fractured justice system. The balloons are red, echoing the 1983 Cold War track “99 Red Balloons” about innocent objects triggering military panic.

The Economist predicts Americans will hear “wildly diverging accounts” of their country. Two competing narratives:

• The 1776 narrative (Republican / Trump): founding ideals, nationalism, rejection of “woke” revisionism.

• The 1619 narrative (Democrat / progressive): unfinished work of democracy, reckoning with slavery and inequality.

This isn’t just a culture war. It’s a narrative civil war, and AI is the megaphone. Russia and China will amplify the divisions through AI-generated disinformation, deepfake politicians, synthetic protest footage. The 250th anniversary won’t unite America. It will reveal how fractured it already is.

Same week, Philadelphia hosts a FIFA World Cup Round of 16 match. Patriotic spectacle colliding with global sport, with strained relations between the US and co-hosts Mexico and Canada.

Subscribe now

The Soccer Ball Earth: When Sport Becomes Warfare

The planet is rendered as a black-and-white soccer ball. Direct reference to the 2026 FIFA World Cup (June 11 to July 19). First 48-team tournament. First three-nation hosting.

The symbolism runs deeper. The world as a ball being kicked around by powerful actors. Geopolitics as competitive spectacle where the referee (international law) has limited authority.

Tourism Economics projects 1.24 million international visitors, 6.5 million total attendees. The Economist warns “fans may stay away” because of political tensions. Trump threatened to remove matches from Democrat-led cities. Even the world’s most unifying event cannot escape geopolitics.

A 48-team tournament at this scale runs on AI infrastructure. Facial recognition, threat detection, drone surveillance, crowd-flow models. The stadium is the surveillance state’s product demo.

This connects to The Economist’s “Sporting Values” theme. Sport no longer offers respite from politics. It IS politics. The shift is from “sportswashing” to sports-warfare, where hosting rights and fan treatment become diplomatic weapons.

Meanwhile, the Enhanced Games debut in Las Vegas (May 2026). Performance-enhancing drugs explicitly permitted. $500,000 purses per event. $1 million for world records. WADA calls it “ridiculous and dangerous.” But it is happening.

Most of those drugs were AI-designed. Modern drug discovery is AI-first. The Enhanced Games is what happens when you stop pretending the AI-pharma pipeline exists.

The question: is enhancement cheating, or just a different game?

This extends beyond athletics. Millions take next-gen GLP-1 weight-loss pills (also AI-discovered). As The Economist notes: “Few people compete in the Olympics, but anyone can take part in the Ozempic games.”

Grey Zone Warfare: The New Normal

The cover bristles with military hardware. White missiles with red tips. Tanks scattered globally. An armed robot dog (direct reference to China’s weaponized dog-like robots deployed in 2023 military drills).

But notice. These aren’t arranged for total war. They’re positioned for perpetual tension.

The Economist predicts 2026 will see “grey zone” provocations. Hostile actions below the threshold of declared war. And the grey zone is where AI changes everything: cheaper, deniable, scalable.

Northern European front

Russia will test NATO commitment through:

• GPS jamming affecting civil aviation

• “Accidental” severing of undersea fiber-optic cables (seabed warfare)

• AI-driven cyberattacks on infrastructure (banks, power grids)

Strategic goal: fracture NATO unity. If a cable is cut and Russia denies it, does NATO invoke Article 5? The ambiguity is the weapon. AI makes the ambiguity cheaper to produce.

South China Sea front

China will test US resolve through:

• Maritime militia vessels (fishing boats acting as naval auxiliaries)

• Water-cannoning Philippine resupply ships

• “Quarantine” blockades of Taiwan

Japan’s Type-12 surface-to-ship missiles extend to 1,000km range by 2026, creating a new deterrent landscape China may test before it is fully operational.

After Gaza, The Iran War, and What The Economist Missed

The cover labeled Middle East “After Gaza.” The thesis: transition from kinetic intensity to fragile diplomacy.

They underestimated how fast the transition would invert.

On February 28, 2026, US and Israeli forces launched Operation Epic Fury. The strike assassinated Iran’s Supreme Leader Ali Khamenei and hit nuclear sites. Iran retaliated with missile and drone strikes on Israel, US bases, and Gulf states. Iran closed the Strait of Hormuz. Global trade choked.

Operation Epic Fury formally ended May 5, 2026. Thousands dead. Millions displaced across Iran, Lebanon, Israel, and the Gulf.

The ceasefire is “indefinite” but fragile. On May 10, Trump rejected Iran’s nuclear proposal. Iran’s military warned of “new arenas of war.” Drones tested the ceasefire the same day off Qatar, with airspace incursions into UAE and Kuwait.

The new power center inside Iran is IRGC Commander Maj. Gen. Ahmad Vahidi, the de facto successor to Khamenei. He is the hardliner blocking concessions on the Strait of Hormuz and Iran’s HEU stockpile. The US is pushing a one-page MoU. Iran is stalling.

Russia is rebuilding Iran’s capacity during the ceasefire. Drone components arrive via the Caspian Sea. During the war, Russia and China shared satellite imagery of US bases with Iran. The “Standards War” of the cover is now a kinetic alliance.

Iranian-backed Iraqi militias (Kataib Hezbollah, Hezbollah al Nujaba, Kataib Sayyid al Shuhada) refuse to disarm. The 2026 Iran war ended on the calendar, not on the ground.

What the cover got right: the militarization. The robot dog. The missiles with red tips. The Standards War. The Russia-China alignment.

What it missed: the speed. The assassination of a head of state. The Strait closure. The scale of displacement. The Economist projected a “Trumpian deal” for Saudi-Israel normalization. There has been no deal. There has been a war.

The accelerant the cover did not name: AI-targeted drones, AI-analyzed satellite intel from Beijing, AI-enhanced naval logistics in the US blockade. The cover showed surveillance. It did not show that the surveillance had already gone autonomous.

Subscribe now

The Brain and the Controller: Cognitive Warfare

The cover’s most dystopian image is the simplest. A human brain wired to a video game controller.

It reads two ways at once.

Technological. Neuralink brain-computer interfaces enter clinical trials. 2026 is the year biology and silicon start sharing wire.

Sociological. This is cognitive warfare. The US 250th anniversary and November midterms make 2026 a year when the “public mind” becomes the contested terrain. Political narratives play out like video games. Recommendation algorithms are the controllers. Human sentiment is the score.

The battlefield of 2026 isn’t just land or sea. It’s the neuro-circuitry of populations.

Gartner predicts 40% of enterprise applications will run task-specific AI agents by 2026, up from under 5% in 2025. But Nobel laureate Daron Acemoglu warns: “These models are being hyped up, and we’re investing more than we should.”

The Economist asks bluntly: “Will the AI bubble burst?”

By 2026, trillions will have been spent on AI infrastructure: chips, data centers, energy. Investors will demand tangible ROI. If AI hasn’t delivered productivity gains, funding could evaporate, triggering a tech crash on the scale of the 2000 dot-com burst.

The energy constraint is real. Data centers consume more electricity each quarter, forcing a pivot back to nuclear or fossil fuels, colliding directly with climate goals.

Economic Gravity Returns: The Bond Market Reckoning

A plunging red line graph with scattered US pennies appears prominently. The Economist’s warning: “rich countries are living beyond their means.”

The bond vigilante scenario

G7 governments ran massive deficits for pandemic relief, wars, and industrial policy. AI capex added trillions on top. In 2026, the bill comes due.

“Bond vigilantes” (investors who sell government debt to protest fiscal irresponsibility) may return, driving up yields. This crushes government budgets as debt service costs soar. It also crushes mortgage holders.

The choice becomes brutal:

• Austerity: cut spending (risks recession and unrest)

• Financial repression: let inflation run hot to erode debt

J.P. Morgan assigns 40% probability to a US or global recession. Fed Chair Jerome Powell’s term ends May 2026. Politicizing the Fed seat could trigger a market showdown.

Trump’s tariffs will “dampen global growth,” eventually biting consumers with stagflationary pressure.

China’s deflationary trap

China faces its own crisis: deflation, industrial glut, demographic decline. Goldman Sachs projects 4.3 to 5.0% GDP growth. But the strategy of “exporting its way out” by flooding the world with cheap goods will trigger retaliatory tariffs from the US and Europe.

The crisis creates opportunity. As the US turns inward (”America First”), China consolidates the Global South. Latin America, Africa, Southeast Asia. China presents itself as the “adult in the room,” offering trade agreements and green tech dominance: EVs, solar, batteries. All AI-optimized supply chains. Bangladesh is explicitly targeted for engagement with lower-interest loans.

The Pharmaceutical Revolution: Syringes, Pills, and the Supply Chain of Thinness

Giant hypodermic needles and scattered pills dominate the cover. The Economist’s tenth theme: “Ozempic, but better.”

Next-gen GLP-1 weight-loss drugs arrive in pill form in 2026. Eli Lilly’s orforglipron targets spring FDA approval at $149-150 per month (vs $1,000+ for current injectables). Novo Nordisk slashed prices 70%. Generic versions launch in Brazil, China, India. The global market surpassed $26 billion in 2025 and explodes from there.

The economic earthquake

This isn’t just healthcare. It’s macro-economic disruption.

• “Big Junk” food industry faces existential threat. As caloric intake drops globally, Nestlé, PepsiCo, McDonald’s see shrinking markets. Investors may short these stocks while going long on pharma giants.

• Healthcare systems face upfront cost explosions despite long-term savings from reduced diabetes and heart disease.

• The ethics debate: “Is taking them cheating?” The question extends from athletes to everyday people. Are we hacking our metabolism or addressing a health crisis?

The other syringe: pandemic stockpile

The syringes next to missiles aren’t coincidence. Pharmaceutical supply chains are now national security, and 2026 is testing them on two fronts at once.

H5N1 avian flu has 71 US cases since 2024, 43 mammal species infected, one US death in Louisiana, one child fatality in Bangladesh (January 2026), and one British Columbia case with no identified exposure source (March 2026). WHO tracked 13 zoonotic flu variant cases in Q1 2026. No sustained human-to-human transmission yet. The “yet” is doing a lot of work.

AI-discovered antivirals, AI-screened pathogens, and AI-monitored wildlife genomic surveillance are now the default pipeline for pandemic preparedness. The same AI-pharma stack that produced cheap GLP-1 pills is the stack racing the next outbreak.

The cover shows the syringe as a symbol of societal transformation and geopolitical positioning. The same syringe is the front line of biosecurity.

Subscribe now

Surveillance Omnipresence: The Transparent Battlefield

The cover swarms with drones and satellites. They visualize the “panopticon” state where privacy is extinct.

The end of privacy. Surveillance spans urban centers to the remote Arctic. Every cable, every ship, every movement is monitored. The panopticon only works at this scale because AI does the watching now. Humans do not review feeds. Models do.

Orbital warfare. These symbols warn of grey-zone provocations in space. Expect satellite dazzling, cyber-hijacking of constellations, militarization of commercial assets like Starlink. The eyes are watching. They are also targets.

The broader theme: 2026 is the year of the “Transparent Battlefield.” Advantage goes to those who see first, decide fastest, and act before the other side has processed the same data. That is an AI workload, not a human one.

The European Trilemma: An Impossible Balancing Act

The Economist identifies “Problems for Europe” as a top theme. The continent faces a mathematical impossibility:

• Increase defense spending (to deter Russia)

• Maintain social welfare (to appease voters)

• Reduce deficits (to please bond markets)

It cannot do all three.

Austerity drives voters toward anti-establishment parties threatening Euro / NATO exit. That creates an existential crisis for the EU project. The hard-right populism surge becomes the engine of political instability.

Yet opportunity exists. Defense industry renaissance. Leadership in AI regulation through the AI Act, which has become the global benchmark for governance frameworks while Washington stalls and Beijing builds its own.

Regional Outlook: The Strategic Map of 2026

Climate’s Mixed Picture: Green Hushing

The cover shows melting ice cubes. A nod to climate crisis. The Economist’s verdict: 1.5°C warming target is “off the table.”

But here’s the twist: “Green Hushing” emerges as corporate strategy. Companies keep decarbonizing, not for ideology but because solar and wind are now cheaper. They stop talking about it to avoid anti-ESG backlash in Trump’s America.

Meanwhile the Global South accelerates adoption, aided by Chinese tech. The “Green” mantle passes from West to developing world. The moral center of gravity in geopolitics shifts with it.

Geothermal energy emerges as the sector to watch. AI data centers need 24/7 baseload power that solar and wind cannot match. Geothermal can. The energy transition is now downstream of the AI capex cycle.

The Conspiracy Layer: Predictive Programming or Pattern Recognition?

No analysis is complete without addressing the elephant in the room: conspiracy theories.

Within days of release, alternative media exploded with “decoding” content. Key narratives:

The Rothschild-Bilderberg theory. With 21% Rothschild ownership and the Editor-in-Chief attending Bilderberg, conspiracists frame the predictions as elite communication, not analysis.

The Illuminati / 1776 connection. 1776 marked both US independence and the Bavarian Illuminati founding. The cake is read as “alluding to elite secret agendas.”

The “Plandemic” interpretation. Prominent syringes signal another health crisis. Marburg virus fears dominate this thread.

The mind-control theory. The brain-controller represents mass psychological manipulation via AI. This one is less conspiracy and more current operating reality of every social platform you use.

The Economist has leaned into the speculation, admitting they include “mysterious symbols or red herrings to keep conspiracists guessing.”

But here is the reality. Elite forecasters report 53% confidence but achieve only 23% accuracy (Berkeley Haas study). Fed research shows professional forecasts perform no better than benchmarks at one-year horizons.

The pattern. The Economist excels at identifying which issues will dominate discourse. Call it a trend compass. They struggle with specific outcomes, timing, and black swans.

Use these predictions as a framework for understanding what sophisticated analysts consider important, not as prophecy.

Subscribe now

What Actually Happens in 2026: The Scheduled Events

Beyond predictions, here is what is confirmed:

• February 6-22: Milano Cortina Winter Olympics (debuts ski mountaineering)

• February 8: Super Bowl LX at Levi’s Stadium

• February 2026: Artemis II, first crewed lunar mission since 1972 (NASA budget concerns may delay)

• June 11 - July 19: FIFA World Cup (48 teams, 16 US cities)

• July 4: US 250th anniversary. Time capsule burial in Philadelphia. 7th International Fleet Review (60 ships, 30 countries). MLB All-Star Game

• November 3: US Midterm Elections (Democrats need net +3 for House majority; historical trends favor opposition. AI-generated deepfake interference is the wildcard)

The Meta-Narrative: From Globalization to Game Theory

The synthesis of all this research reveals a profound shift.

We are moving from the era of “Globalization” to the era of “Game Theory.”

Relationships are transactional, strategic, zero-sum. The distinction between a trade deal and a peace treaty has vanished. Sport, health, technology, finance: all are now weapons in a single arena of competition.

The “nervous system” metaphor is perfect. A shock anywhere transmits everywhere. A tariff tweet in Washington affects chip supply in Taiwan, energy prices in Europe, bond yields in Japan.

The old world order is not dying. It is already dead. 2026 reveals what replaces it: fluid “coalitions of the willing,” competing tech standards, weaponized commerce, grey-zone conflicts where ambiguity is the strategy.

And one operating system running underneath all of it: AI.

Conclusion: Watch the Grey Zones

The Economist’s 2026 cover functions as visual information density. Too many crises to isolate, too interconnected to separate. Earth as a soccer ball orbited by weapons, pills, and surveillance while a divided America celebrates: festivity amid fragility.

The lasting value is not predictive accuracy (which will be mixed). The value is the identification of forces competing for attention. A birthday party held on a soccer ball surrounded by missiles and pills, with a handcuffed fist emerging from the cake. That is the visual thesis.

Same exercise I ran last year on the 2025 cover. The framework holds. The threat surface widened.

Here is your action framework for 2026:

1. Watch the grey zones

The next crisis will not start with a declaration of war. It will start with a severed cable in the North Sea, a “quarantine” of Taiwan, or a quiet bond market default.

2. Follow the money and the medications

The GLP-1 revolution will reshape economies faster than AI. Short junk food, long pharma, and watch for healthcare cost explosions.

3. Understand cognitive warfare

Elections, narratives, and public opinion are the battlefield. Algorithms are the weapons. Your attention is the territory.

4. Embrace transactionalism

Permanent alliances are over. Success goes to those who can play multiple sides without commitment.

5. Prepare for volatility

2026 is not the year the world breaks. It is the year we discover how it already broke and learn to navigate the fragments.

Navigating fragments is now a tooling problem. You need a personal system that captures, connects, and surfaces what matters before the next signal arrives. That is exactly what obsidian-second-brain was built for, and why I built it for myself.

In 2026 the future arrives. Not as shiny utopia. As gritty reality of AI surveillance, bio-hacked bodies, and drone warfare. Everything is connected. Everything is at risk.

The question is not whether The Economist’s predictions come true. The question is whether you are ready for a world where they are even plausible.

Your Turn: What Do You See?

I’ve decoded what five AI systems and dozens of analysts found in this cover. But symbols are Rorschach tests. They reveal as much about the observer as the observed.

What patterns do you see emerging? What am I missing?

Drop your analysis in the comments. Let’s build a collective intelligence network that rivals any think tank.

If you found this useful, subscribe to The AI Operator. One post per week. AI agent patterns, Obsidian + AI workflows, and the geopolitical context of the technology shaping 2026.

Clarity is the only competitive advantage left.

Subscribe now

Sources

• The Economist, “The World Ahead 2026” (November 2025)

• Berkeley Haas Business School, “Elite Forecaster Accuracy Study”

• J.P. Morgan Global Economic Research

• Goldman Sachs China Economic Outlook

• Gartner AI Adoption Forecasts

• Tourism Economics FIFA World Cup Impact Analysis

• Institute for the Study of War, Iran Update Special Reports (May 2026)

• CDC A(H5) Bird Flu Situation Summary

• WHO Q1 2026 Zoonotic Influenza Report via CIDRAP

What is obsidian-second-brain? A free, open-source Claude Code skill that gives Claude persistent memory through your Obsidian vault. 1,024 stars in seven weeks. MIT licensed. Built by Eugeniu Ghelbur. Repo: github.com/eugeniughelbur/obsidian-second-brain.

You use Claude every day. Every session starts from scratch. You re-explain everything. The conversation ends. Everything disappears.

You take notes in Obsidian. Hundreds of files. They just sit there. You make the same decision twice because you forgot you made it six months ago.

Two powerful tools. Completely disconnected.

That was my problem. I was tired of it. So I built the bridge.

Then I open-sourced it on GitHub. Seven weeks later, 1,374 strangers had cloned it.

This post is what I built, why people are using it, and what it might mean for you if you bring AI into your work.

What obsidian-second-brain does

obsidian-second-brain is a free Claude Code skill. Open source. MIT license. The repo is called obsidian-second-brain.

Under the hood it’s 31 commands across four layers. But you don’t need to know all 31. You only need to know what each layer DOES:

1. Claude remembers. Every meeting, every decision, every voice memo, every screenshot. It gets saved to the right place in your vault automatically. You stop losing things.

2. Claude thinks with you. Your vault argues back. Before you decide something, you can ask “have I been here before?” and it shows you your past failures and reversed decisions on the same topic.

3. Claude knows you. Your identity, your projects, your current state. Loaded in ten seconds. Every session picks up where the last one ended.

4. Claude pulls knowledge in. X posts, web research, YouTube transcripts. They go into your vault, not just into a temporary chat that disappears.

Plus four scheduled agents that run while you sleep. The vault gets smarter without you.

You don’t even have to open Obsidian to use it. Everything happens through Claude.

What it actually does

Some real moments where it changes how you work:

• After a meeting, one command saves every decision, person, task, and idea to the right note. You do nothing.

• You record a voice memo on your phone. Drop it in. It gets transcribed, the action items get extracted, the right people and projects get linked.

• You take a photo of a whiteboard. Same thing. The image becomes searchable knowledge.

• You find a great YouTube video. It doesn’t get summarized into one new note. It REWRITES your existing pages. People get updated. Contradictions get resolved. Patterns trigger new synthesis pages.

• Before a big decision, the vault searches your past notes for the same topic and pushes back with your own words. Your vault holds you accountable.

• You go to sleep, and a nightly agent runs five phases: closes the day, reconciles contradictions, finds patterns across sources, heals orphan notes, rebuilds the index. You wake up to a smarter vault.

That’s the difference between a notes app and a second brain. The notes app waits for you. The second brain works for you.

The proof

Here are the numbers, fresh from the GitHub Insights page today:

• Created seven weeks ago. 2026-03-24.

• 1,024 stars.

• 99 forks.

• 1,374 unique people cloned the repo in the last two weeks alone. That’s not vanity. Cloning means they actually pulled the code down to try it.

• 5,910 unique visitors to the repo in 14 days.

• The top referrer is Twitter, by a wide margin. The second is Google. People are searching for this and finding it.

The first public user feedback came in a LinkedIn DM from a Cybersecurity Leader. He said he was “personally impressed by the correlation engine within one hour” of migrating his own data into the vault.

The first external code contribution came from someone I had never met. He shipped 695 lines of code to add a new /podcast command. He found a real bug in my code while doing it. The project isn’t just mine anymore.

The Substack readers who actually click through to the repo convert at 24 percent. Meaning the people who read about it stay.

Subscribe now

Why this matters if you’re a founder

Your team uses AI. Your team takes notes. The two don’t talk.

You hire someone in March. They have great calls with three customers in their first week. The notes go into a tool. The Claude conversations go nowhere. By June, that person has switched roles or left. The customer insight is gone.

Multiply that by fifty people on your team and you have institutional amnesia at scale. Your company knows things, but your company can’t remember them.

This open-source skill is how I solved that problem for one person. Me. The principles are the same at any size. The code is free to fork.

If you bring AI into your team in the next six months, your team is going to hit this exact wall. The fix isn’t a new SaaS subscription. It’s a pattern. The pattern is in the repo.

Try it

GitHub repo: github.com/eugeniughelbur/obsidian-second-brain

It’s free. MIT license. One command to install.

If you don’t use Obsidian or Claude Code yet, the README explains both. If you do, you can be running it in five minutes.

Frequently asked questions

What is obsidian-second-brain?
A free, open-source Claude Code skill that connects Claude to an Obsidian vault. Every conversation, decision, meeting note, voice memo, and research finding gets saved to the right place automatically. The vault then feeds context back into every future Claude session.

Is it free?
Yes. MIT license. Free to use, fork, or extend. There is no paid tier.

Who built it?
Eugeniu Ghelbur, AI Automation Engineer at Single Grain. The repo went public on 2026-03-24. As of 2026-05-10 it has 1,024 stars, 99 forks, and 1,374 clones in the prior 14 days.

Do I need to know how to code?
No. One command installs it. The README walks you through Claude Code and Obsidian setup from scratch.

Does it require Claude Code?
Yes. It is a Claude Code skill, not a standalone app. Claude Code is free at claude.com/claude-code.

Does it require Obsidian?
Yes. Obsidian is free for personal use. The skill assumes a markdown vault on local disk.

How is this different from Obsidian AI plugins like Smart Connections?
Most plugins call an AI API from inside Obsidian. obsidian-second-brain inverts that. Claude is the operator. The vault is its memory. You can go weeks without opening Obsidian. The vault gets smarter while you work somewhere else.

Where is the repo?
github.com/eugeniughelbur/obsidian-second-brain

Subscribe now

What’s next

This is week one of The AI Operator, my publication for people building with AI in production.

One post per Tuesday. Three things I write about:

• Obsidian + AI workflows (how to make your second brain actually intelligent, like this post)

• AI agent patterns (what works, what breaks, what I’m shipping)

• AI for humans (how to bring AI into your team or your life without scaring people)

If you’re bringing AI into your work and you want to see what’s actually working in production from someone who ships it, subscribe. There’s a button somewhere obvious on this page.

Thanks for being here. I write for the people who build.

Eugeniu

Quick orientation. If you came here searching for Karpathy's original LLM Wiki gist, here it is: Karpathy’s original LLM Wiki gist. Bookmark it, it's still the cleanest starting point. What follows is the version I built on top of it, a second brain that rewrites itself, open-sourced so you can clone it: https://github.com/eugeniughelbur/obsidian-second-brain

TL;DR

• Karpathy’s LLM Wiki gist describes the right pattern but at the intent level: integrate new sources, lint periodically, treat the wiki as primary. It is a conceptual blueprint, not a runnable spec.

• The gap between the gist and a working system is in the mechanics: how integration handles contradictions, how lint runs without you asking, and who the wiki is actually written for.

• This rebuild fills in the spec on five axes: specified integration mechanics, automatic contradiction reconciliation, unsolicited synthesis, scheduled maintenance agents, and notes written for AI retrieval rather than human reading.

• The most contrarian of the five is the AI-First Vault Principle: notes designed so future-Claude can read them in 10 seconds, not so future-you can re-read them in 30 minutes. Karpathy’s gist treats the wiki as serving both humans and LLMs; this rebuild inverts that.

• The open-source implementation ships as a Claude Code skill with 31 slash commands and 4 scheduled agents.

What is Karpathy’s LLM Wiki pattern?

Karpathy’s LLM Wiki is a knowledge-base pattern published as a public gist in early 2026. You drop sources into a folder. An LLM reads them, extracts entities and concepts into wiki pages, and cross-references everything. Future questions are answered from the wiki, not from a fresh web search.

The full pattern lives in Karpathy’s gist. The core insight is correct and important: the wiki is the product, the chat is just the interface. Cross-references already exist. Synthesis already reflects everything that has been read. Knowledge compounds like interest, instead of being regenerated from scratch every time you open a chat.

This was the right starting point. It is also where most implementations stop. As of 2026-04, every public Karpathy-Wiki implementation I have reviewed (six on GitHub, two on Substack, one on dev.to) treats the original gist as a complete spec. None of them solve the problems that show up the moment your wiki crosses a few hundred sources.

Why a conceptual blueprint is not a working second brain

Karpathy's pattern is append-only by design. Every ingest creates new pages and adds cross-references; existing pages stay frozen. This works for the first 50 to 100 sources. Past that, three failure modes compound: claims go stale, contradictions accumulate faster than you resolve them, and the cross-reference graph becomes too dense to navigate manually.

A wiki built this way is essentially a logbook with internal links. It captures what you read, but it does not update what you previously believed. If you ingest a YouTube video about a person who has changed jobs, you get a new source page with the new fact, plus a backlink on the person's existing page. The person's page itself still describes them at their old job. Future-Claude reading the page sees both, has no way to know which is current, and gives you a hedged answer.

The fix is structural. A real second brain has to rewrite, reconcile, synthesize, schedule, and rewrite-for-AI. Five extensions. Below.

Five things a working second brain has to do that the original doesn't

1. Ingest has to rewrite, not just append

Real intelligence rewrites. When I ingest a YouTube video about someone already in my vault, the person’s page itself gets updated. Their startup status changes from “considering joining” to “joined in March 2026.” A thesis that was “speculation” becomes “confirmed.” The old version is preserved as a dated entry below, not deleted, but the live state of the page reflects the latest evidence.

This is the difference between a wiki that grows and a wiki that learns. Append-only knowledge bases get stale invisibly because nothing about reading them tells you that a fact is from 2024. Rewriting forces every page to carry the current best answer at the top.

2. Contradictions have to be resolved, not just flagged

Karpathy’s pattern flags contradictions during ingest. You resolve them manually. In a small wiki, that works. In a vault past a few hundred pages, contradictions accumulate faster than you have time to resolve. The wiki becomes internally inconsistent, and future-Claude pulling from it gets contradictory inputs and produces hedged outputs.

The fix is automatic reconciliation. A dedicated process scans the vault, finds claims that contradict each other across pages, and resolves them by source recency, source authority, and explicit confidence levels. The most recent, best-sourced, highest-confidence claim wins. The losing claim gets archived with an explanation of why it was superseded. The vault stays internally consistent without you babysitting it.

3. Patterns have to be surfaced without being asked

Karpathy’s wiki answers the questions you ask it. It cannot tell you about the patterns it has noticed and you have not. This is a massive missed opportunity. Half the value of a knowledge base is the LLM telling you “you have mentioned this idea seven times across five different notes and never named it. Here is what it is.”

A working second brain runs synthesis on its own. It scans the vault for unnamed recurring themes, hidden contradictions between people’s stated values and their actual decisions, and connections between projects that look unrelated. It writes synthesis pages without being prompted. The vault tells you what it has noticed about you.

4. Maintenance has to be scheduled, not on-demand

Karpathy’s pattern runs only when you prompt it. Every operation is on-demand. This means maintenance only happens when you remember it, which means it never happens. Vaults rot in silence.

The fix is scheduled agents. A nightly process closes out the day, files loose ideas, updates the daily note. A weekly process runs the full reconciliation pass and the synthesis pass. A health check finds orphaned notes, dead links, and pages that have gone stale. You wake up to a vault that has already done its homework, and you never run a maintenance command yourself.

5. Notes have to be written for AI, not for humans

This is the most contrarian point and the centerpiece of this article. Every personal-knowledge-management tradition (Zettelkasten, Building a Second Brain, evergreen notes) optimizes notes for human reading. Karpathy’s pattern follows this convention. Wiki pages look like Wikipedia articles, written in flowing prose, designed for a human to skim.

The premise is wrong. You do not read your own notes. The LLM does. So they should be optimized for LLM retrieval, not for human reading. This is the AI-First Vault Principle, and it is the single biggest unlock in this rebuild.

The AI-First Vault Principle

Notes designed for AI retrieval beat notes designed for human reading, in any vault where the LLM does most of the reading. Every note follows seven rules: a ## For future Claude preamble, machine-readable frontmatter, mandatory wikilinks, recency markers per external claim, source URLs preserved verbatim, confidence levels where applicable, and self-contained context so the note can be retrieved standalone.

---
type: person
name: "Andrej Karpathy"
date: 2026-04-29
tags: [ai-researcher, llm-wiki-pattern]
ai-first: true
confidence: high
---

## For future Claude
Andrej Karpathy is the originator of the LLM Wiki pattern, published as a public
gist in early 2026. He proposes that LLMs should maintain a living markdown wiki
as the primary knowledge artifact, not a vector store. Use this page as the
canonical reference when reasoning about the LLM Wiki pattern.

## Key claims
- The wiki is the product. Chat is the interface (as of 2026-02, karpathy gist).
- Knowledge should compound across sessions. Source: same.
- Cross-references should already exist when a question is asked. Source: same.

## Related
[[LLM Wiki Pattern]] · [[Obsidian Second Brain]] · [[Append vs Rewrite]]

This page is harder for a human to scan than a regular Wikipedia-style note. It is dramatically faster for an LLM to retrieve, parse, and reason over. The frontmatter tells the LLM what kind of note it is in three lines. The “For future Claude” preamble tells it whether to bother reading the rest in another three sentences. The recency markers tell it what to verify. The wikilinks tell it where to go next.

The inversion is uncomfortable for anyone who has invested in a beautiful Obsidian vault. It is also the only thing that makes a vault past a few hundred notes actually compound for an LLM-driven workflow. Once you stop pretending you will re-read your notes, you can write them in a way that compounds for the system that will.

Subscribe now

How this compares to Karpathy’s original and rohitg00’s v2

This rebuild is the third iteration of the public LLM Wiki pattern. Karpathy’s gist (2026-02) is v1: append-only ingest, manual lint, human-readable notes. rohitg00’s LLM Wiki v2 (2026-03) added confidence scoring, supersession of stale claims, and contradiction detection. This rebuild adds three things v2 still does not have: scheduled agents, automatic synthesis, and AI-first note structure.

None of the existing public implementations ship a working integration with Claude Code as a slash-command skill. None ship a real specification for AI-first notes. None ship scheduled agents. The repo behind this article does. It is open-source, MIT-licensed, and live on GitHub: eugeniughelbur/obsidian-second-brain.

## What I got wrong

When I first shipped `/research-deep` and ran it against my own vault, the command wrote 
three different kinds of garbage into the synthesis note. I had assigned the wrong 
Perplexity model to the synthesis call, so the API returned a hardcoded 10,000-word 
academic report instead of following the markdown structure I asked for. 
The reasoning model I switched to wrapped its internal deliberation 
in `<think>...</think>` blocks, and those tags ended up saved to the vault verbatim. 
And the frontmatter meant to log which queries had run was instead saving stringified 
Python dictionaries.

Three small bugs, but together they meant the command designed to make my vault smarter 
was making it dumber on its first run. I only caught it because I happened to test on a 
real topic in my own vault and actually read the output. If I had trusted the test less 
and the implementation more, the broken version would have shipped, and every other vault 
running the skill would have inherited the same junk.

The fix took an afternoon. The lesson took longer. **The right level of automation 
is not "everything always," it is "everything reversibly."** A second brain that 
rewrites itself is only valuable if you can see exactly what it changed and roll 
back when it gets it wrong. Every scheduled agent in this rebuild now logs its changes 
to a daily diff note and waits 24 hours before any change becomes permanent. 
The first version did not. That is the difference between a tool I trust on my own vault
and one I would never let near it.

The general lesson is that the right level of automation is not “everything always,” it is “everything reversibly.” A second brain that rewrites itself is only valuable if you can see what it changed and roll back when it gets it wrong. Every scheduled agent in this rebuild logs its changes to a daily diff note and waits 24 hours before any change becomes permanent.

Subscribe now

Frequently asked questions

What is the LLM Wiki pattern?

The LLM Wiki pattern is a knowledge-base architecture proposed by Andrej Karpathy in early 2026. You drop sources into a folder, an LLM reads them and writes wiki pages, cross-references entities, and answers future questions from the wiki rather than from fresh web searches. The wiki is a persistent artifact that compounds across sessions, instead of being regenerated each chat.

How is this different from RAG?

RAG retrieves chunks of source documents at query time and feeds them to an LLM as context. The LLM Wiki pattern flips this: an LLM reads sources once, distills them into structured wiki pages, and the wiki itself becomes the retrieval target. The result is faster, cheaper queries, plus cross-references that already exist instead of being inferred at query time. This rebuild adds write-back so the wiki stays current with new sources.

Do I need to know how to code to use this?

No. The implementation is a Claude Code skill that ships as 31 slash commands. You install it once with a shell script, then operate it with commands like /obsidian-save and /obsidian-ingest from any Claude Code session. The vault is plain markdown, so Obsidian works on top of it natively.

Will this break my existing Obsidian vault?

No. The skill never deletes or modifies notes destructively without explicit confirmation. Existing notes are left untouched. New notes follow the AI-First Vault Principle. A health-check command flags pre-AI-first notes so you can update them on your own schedule. Every scheduled agent writes to a daily diff log so you can see what changed overnight and revert if needed.

Does it work without Claude?

The current implementation is built for Claude Code, but the AI-First Vault Principle and the slash-command interface are portable. The vault format is plain markdown with YAML frontmatter, so the underlying knowledge base is model-agnostic. As of 2026-04 the production-tested integration is Claude Code only.

What does it cost to run?

The 26 vault commands work without any API keys: only your Claude Code subscription is required. The 5 research commands require API keys for xAI Grok and Perplexity. Approximate per-call costs as of 2026-04: /x-read around $0.05, /x-pulse around $0.13, /research around $0.04, /research-deep around $0.40 to $0.80, /youtube around $0.04.

Key takeaways

• Karpathy’s LLM Wiki pattern is a brilliant foundation. The wiki is the product, chat is the interface, knowledge compounds across sessions.

• Append-only ingest fails past a few hundred sources. Stale claims, unresolved contradictions, and missed patterns accumulate invisibly.

• The five extensions that turn a Karpathy-style wiki into a working second brain are write-back, reconciliation, unsolicited synthesis, scheduled agents, and AI-first notes.

• The AI-First Vault Principle is the most important of the five. Notes designed for AI retrieval beat notes designed for human reading in any vault where the LLM does most of the reading.

• Automation has to be reversible. Every scheduled agent in this rebuild writes a diff log and waits 24 hours before any change becomes permanent.

• The open-source implementation is live on GitHub and runs as a Claude Code skill with 31 slash commands. Install in two minutes.

If Karpathy’s LLM Wiki is a knowledge base you maintain with an LLM, this rebuild is a knowledge base that maintains itself.

Further reading

• Karpathy’s original LLM Wiki gist (2026-02): the canonical pattern.

• rohitg00’s LLM Wiki v2 gist (2026-03): adds confidence and supersession.

• Penfield Labs on what’s missing from Karpathy’s wiki: typed-link extension.

• Andy Matuschak on evergreen notes: the human-first PKM tradition this rebuild departs from.

• obsidian-second-brain on GitHub: the open-source implementation.

About the author

Eugeniu Ghelbur is an AI Automation Engineer at Single Grain, where he builds production AI systems for marketing and sales workflows. He ships open-source Claude Code skills and writes about AI knowledge management at ghelburlabs.substack.com. The obsidian-second-brain skill described in this article is live on GitHub at github.com/eugeniughelbur/obsidian-second-brain and has been used in production since 2026-03.

Update, June 2026: the internet has since shipped a wave of "v2" designs on top of this pattern. I tested them daily for months and wrote up the honest verdict in Karpathy's LLM Wiki v2: what to keep, what to skip.

Every productive person I know writes lessons down. “Don’t sign one-year contracts without exit clauses.” “Always run migrations on a staging copy first.” “When a client goes silent for two weeks, escalate to email.”

Then they make the same mistake six months later.

The lessons aren’t lost. They’re just buried in daily notes, dev logs, and meeting recaps that nobody opens again. The wisdom rots in place.

The problem with second brains

Most note-taking advice ends at “write it down.” But writing is the easy part. The hard part is keeping the lessons alive — surfaced, reviewed, applied.

Without that step, your second brain becomes a graveyard. The more you write, the worse it gets. Important rules get drowned by daily noise. The lesson you needed yesterday was logged eight months ago, three folders deep, with no link pulling it forward.

The fix: a command that reviews your wisdom

I just shipped /obsidian-learn in my open-source Claude Code skill. It does one thing: scans your entire vault for lessons and decides which ones still matter.

Five places it looks:

• “Lesson learned” sections in daily notes

• Architectural Decision Records (ADRs)

• Pattern reports from previous reviews

• Failure-learning phrases — “next time”, “don’t do this”, “wasted time on”

• Recurring success patterns — things that worked twice or more

Then it classifies each lesson:

Active — still applies, reinforced by something recent. Keep it.

Stale — six months old, no recent reinforcement. Archive or convert to history.

Superseded — explicitly replaced by a newer decision. Acknowledge the evolution.

Promotable — appeared three or more times across your vault. This is now a permanent rule. The command suggests exact wording to add to your operating manual.

What this does in practice

Run /obsidian-learn weekly. Get a report:

Top 5 Lessons of the Period

1. “Always verify live state before patching from memory” — 4 reinforcements. Promote to permanent rule.

2. “Never re-run destructive wizards” — reinforced after a recent incident.

3. “Talk to one named user before designing the system” — corrected twice.

4. “Pre-written decline scripts beat willpower” — recurring pattern across multiple weeks.

5. “If the side project competes with the day job for content, the side project dies” — emerged from cross-domain synthesis.

Promote the top ones into your operating manual. Now every AI session you start, on any device, opens with these rules already loaded. The wisdom you earned compounds.

Why this matters

The next decade’s competitive edge isn’t access to AI models. Everyone will have that. The edge is the corpus the model works from — your years of decisions, lessons, and patterns, organized so they actually surface when relevant.

A vault that doesn’t review itself is just a filing cabinet with extra steps. A vault that promotes its own lessons into rules becomes a personal operating system that gets sharper every quarter.

This is the latest release of obsidian-second-brain — a Claude Code skill that turns your Obsidian vault into a living knowledge base. 26 commands now. Self-rewriting ingest, thinking tools that argue with you using your own history, scheduled agents that maintain the vault while you sleep, and now a command that compounds your wisdom instead of letting it rot.

Inspired by Garry Tan’s gstack /learn pattern. Open source. MIT licensed.

github.com/eugeniughelbur/obsidian-second-brain