Your context folder is the new second brain, and why most people get it wrong

TL;DR: A context folder is a small set of files (operator profile, audience, voice, principles, decisions, current project, performance patterns) that an AI agent reads before answering. The shape took off in mid-2025 after Andrej Karpathy framed it as context engineering. Most people get it wrong by treating it as storage. The harder problem is recall.

For two decades the second-brain pitch was about you reading your own notes later. Tools like Evernote, then Notion, then Obsidian sold the idea that if you wrote things down well enough, future-you would thank present-you. It mostly did not happen. Most knowledge workers still cannot find the meeting note from six weeks ago without three searches and a guess.

Then AI agents arrived, and the audience for your notes changed. The reader is no longer just you. It is Claude Code on your machine at 11pm, or Codex inside a Cursor window, or a ChatGPT thread that needs to know what your audience cares about before it writes the email. Your notes file became a context file. The second brain stopped being a private library and turned into an interface.

What is a context folder, and why did it appear in 2025?

A context folder is a flat directory of short markdown files that an AI agent reads as background before it tries to help you. The pattern was formalized in Wyndo's piece on aimaker.substack.com, which describes a /foundational folder of seven files: an operator profile (how you work), an audience profile (who you serve), a creator style guide (voice and tone), a point-of-view document (values and beliefs), decision rules, a current project context, and a performance patterns file. An instruction file (CLAUDE.md or AGENTS.md) sits next to it and tells the agent which file to read for which task.

The terminology got pinned down by Andrej Karpathy on X on June 25, 2025: this is context engineering rather than prompt engineering, because the constraint is no longer your wording but what the agent already knows about your situation. The folder is the answer to that constraint.

Practitioners have written variations on the same idea for Claude Code, Codex, Cursor, and Cowork. The file count and naming vary, but the shape is consistent: a small canon of background documents the agent reads on demand, not a giant single prompt pasted into every chat.

Why do most people structure their context folder wrong?

Most first attempts at a context folder fail in one of two predictable ways.

The first failure is the dump. Every meeting transcript, every old blog draft, every Slack export, all of it goes into the folder, and the agent is told to use this. This breaks because LLMs do worse with more noise, not better. The signal in the canon gets diluted by every irrelevant page next to it.

The second failure is the cathedral. People spend a weekend building a beautiful seven-file structure, write 8,000 words of self-portrait, and then never touch it again. By month three the audience profile is stale because the business pivoted, the project context is from a launch that already happened, and the decision rules describe a person they were two quarters ago.

Wyndo's own framing in the source piece points at the deeper issue: "If the agent already knew the important parts of my world before I started typing, I would not need to paste them in every time." The agent should not need you to remember to attach files. It should surface what matters when it matters. That is a recall problem, not a folder problem.

The seven files and what they are really for

The seven-file template from the source is a useful starting shape because it pre-segments your background by retrieval intent. You do not load all seven for every task. You load the operator profile when the agent is planning your day. You load the audience profile when it is drafting copy. You load the decision rules when it is helping you choose between two options.

That is progressive disclosure. You are not handing the agent your whole brain. You are handing it the slice that matches the question. If your context folder cannot answer "which slice is this question?", it has the wrong architecture. The seven files work because each name maps to a clear task family.

Where this falls apart in practice: people store the files but never wire the routing. The instruction file is the part most setups skip, and it is what separates a folder of notes from an actual context system.

If you have been comparing AI memory features across tools, the question of when to use a context file versus persistent memory comes up fast. A separate write-up on ChatGPT memory, Claude Projects, and Gemini's recall walks through where each model's built-in memory ends and where a context folder picks up.

What happens when retrieval is the problem, not storage?

Once you have written the files, the work shifts. You stop asking "did I write this down?" and start asking "will the right file open at the right moment?" That second question is where most personal knowledge systems lose.

Obsidian and Notion both store context beautifully. They are excellent libraries. They are not recall engines. The friction of opening the right note, copying the right paragraph, and pasting it into the right chat is small per instance and very large over a year. A general look at how Obsidian and Notion compare to plain notes covers this in more detail.

The shift that matters in 2025 is treating recall as the design surface. Saving is easy. Search inside one file is easy. Knowing that the paragraph you wrote eight months ago about how you price discovery calls is the exact thing this current Cursor session needs, that is the hard part. A context folder makes that paragraph addressable. It does not, by itself, make it findable at the right time.

This is also why save-everything-to-one-big-document and let the agent figure it out usually disappoints. Context windows have grown, but useful retrieval has not scaled at the same rate. A focused 600-word file the agent loads on purpose beats a 40,000-word dump it has to skim.

From folder to recall surface

The practical move is to stop thinking of your context folder as a writing project and start thinking of it as a save-and-surface loop. Every time you make a decision, articulate a principle, or notice a pattern that worked, that thought goes somewhere your agent can reach without you typing it again. Every time the agent asks you something it should already know, that gap goes back into the folder.

The capture half of this loop is what most setups still do by hand. You highlight a paragraph, you open the folder, you find the right file, you paste, you save. Five steps, every time, forever. The folder grows when willpower is high and stagnates when willpower is low.

This is the part where a tool like dEssence becomes worth considering. It is a memory product in beta that lets you save context from a Chrome extension, Telegram bot, or the web app at dessence.ai, and surfaces those saved items when they are relevant to whatever you are working on. The tradeoffs are real and worth naming: it is beta-stage, the free tier caps archive size, there is no native iOS or Android app yet, and the paid tier is not finalized. The reason it fits this conversation is that it inverts the recall problem. You do not maintain the file structure. You save where you already are and trust the surfacing layer to bring things back. For a longer look at the underlying idea, the post on AI context memory goes deeper.

Frequently Asked Questions

Do I need a context folder if I already use ChatGPT memory or Claude Projects?

Built-in memory and a context folder solve different problems. Memory features remember snippets across chats inside one product. A context folder is portable, version-controlled, and works across Claude Code, Codex, Cursor, and any agent that can read files. Most serious users end up with both: built-in memory for short personal facts, a folder for the structured canon.

How many files should be in a context folder?

The Wyndo template uses seven. In practice, between five and ten focused files is the working range. Past ten you lose the benefit of progressive disclosure because the agent (and you) cannot reliably route to the right slice.

How often should the context folder be updated?

Treat it like a living document, not a launch artifact. The project context file changes weekly. The audience profile changes every quarter or two. Decision rules change rarely. If nothing in your folder has changed in three months and your work has, the folder is stale.

What format should the files use?

Plain markdown, one topic per file, short headers the agent can grep. Avoid long prose blocks. Bullet points and short sections retrieve cleanly and let the agent quote you back to yourself.

This article was inspired by aimaker.substack.com's piece on the context folder for AI agents.