How to build an AI second brain that you and your agents share

Agents are only as good as what they know about your work. In 2025, Shopify's Tobi Lütke called this "the art of providing all the context for the task to be plausibly solvable by the LLM", and Andrej Karpathy called it "filling the context window with just the right information for the next step." The name stuck: context engineering.

Most of that context is not code. It is why you chose one approach over another, what the customer said on Tuesday, who owns what, what you read last month, and what you already tried. If it lives only in your head, every agent starts from zero. If it lives in one agent's memory, you lose it when you switch tools.

So people are building AI second brains: one knowledge base that they and their agents share. This guide compares the two ways to do that, a folder of Markdown files and a notes app your agents connect to, and shows how to set up the second one. We make Capacities, which is the second kind. We say plainly when the first kind is the better choice.

It also argues for one habit that matters more than the tool: let agents write back in atomic notes, one idea per note, with a title that states the idea.

The short answer

Two kinds of context

It helps to split what an agent needs into two kinds.

Instructions for one project. How to build, test, and name things. Which libraries to use. This belongs in the repository, next to the code: CLAUDE.md, AGENTS.md, or Cursor's rules. Claude Code's docs call this "how Claude remembers your project", and it works well.

Knowledge that spans projects. People, decisions, meetings, research, and things you learned. This does not belong in a project file. It belongs somewhere you also read and write yourself, on any device, and that every agent can reach. Most of it comes in small pieces: one decision, one insight from a book, one thing a customer said.

The second kind is the AI second brain. The question is where it should live.

Option one: a folder of Markdown files

This is the most popular setup today. You keep an Obsidian vault, start Claude Code in that folder, add a CLAUDE.md that explains your conventions, and keep everything in Git. Karpathy's "LLM wiki" pattern, an agent that maintains a personal wiki of Markdown pages, is a version of this.

Why people like it

• The agent works on files directly. It can search with grep, rewrite fifty notes at once, and move things around.
• Git gives you a full history and a real "undo all of that".
• Any tool can read the files, and there is no vendor in between.

Where it breaks

People who run this setup describe the same problems:

• Knowledge rot. One r/ClaudeAI post: "a simple Obsidian vault will quickly turn into a mess of outdated facts." The agent writes fast, and nobody prunes.
• Messy links. In r/ObsidianMD: "Without a clear rule, Claude would create bidirectional links everywhere."
• You maintain the schema. Types are front matter conventions in a CLAUDE.md. Every agent has to follow them, and you have to keep them current.
• It lives on one computer. Claude Code needs the folder. On your phone, or in ChatGPT, the vault is out of reach unless you set up sync and a separate server.

If you are a developer who lives in a terminal, this setup is excellent, and we would not talk you out of it.

Option two: a notes app your agents connect to

Here your knowledge lives in a notes app, and agents reach it through a connector. The technical name is MCP, the Model Context Protocol. Claude Code, Cursor, Codex, ChatGPT, Claude, and many other tools support it. Each one gets the same tools: search, read, create, edit.

Why it works well

• The schema is built in. In Capacities, every note has a type, such as Meeting, Person, Decision, or Source, and each type has properties. An agent can ask for a type's properties before it writes, so it fills in the right ones without a convention file.
• You use it as a person, not just as a store. The same notes open on your phone, with a daily note, links in both directions, and search. You read what agents wrote, and you fix it.
• Every agent sees the same knowledge. Claude Code at your desk, ChatGPT on your phone, and Cursor in the editor all read and write the same space.
• Undo per note. Every edit is saved in the note's version history.
• Access is scoped. Each connection reaches one space. Keep work and personal in separate spaces and connect only what an agent needs.

Where it falls short

• Tools, not files. An agent searches and reads through tool calls. It cannot grep the whole space or rewrite hundreds of notes in one pass.
• Broad scans are weak. "Read everything and find patterns" works poorly. "List my Meeting notes from September, then read them" works well.
• Agents cannot change the structure. They cannot create a new type or add a property. You do that in the app.
• There is a creation quota. Objects created through the connector and the API share a limit of 10,000, which grows by 500 a month after you reach it.
• It is a cloud app. Your notes are stored on EU servers, encrypted in transit and at rest, but not end-to-end encrypted, and not local files. You can export to Markdown at any time.

Setting it up with Capacities

You need Capacities Pro. Each agent connects with the same server URL, https://api.capacities.io/mcp, and you sign in once per agent.

Claude Code

claude mcp add --transport http capacities https://api.capacities.io/mcp

Then run /mcp in Claude Code and sign in.

Cursor

In Settings → MCP, add a global server:

{
  "mcpServers": {
    "capacities": {
      "url": "https://api.capacities.io/mcp",
      "auth": { "CLIENT_ID": "cursor_mcp_capacities_public" }
    }
  }
}

Restart Cursor. It asks you to sign in the first time it uses Capacities.

Codex, VS Code, OpenCode, Gemini CLI, and others use the same URL. The setup guide has the steps for each. ChatGPT and Claude connect from their directories, see ChatGPT and Claude.

What it looks like day to day

::chat-to-note

app: cursor prompt: Before you touch the billing code, read my Capacities note on the billing redesign and follow the decisions in it. reply: 'Read "Decision: move billing to usage-based pricing". Keeping invoices monthly and leaving old plans as they are, as the note says. Starting with the price table.' noteLabel: Read from Capacities noteType: Decision noteIcon: i-ph-scales-duotone noteTitle: 'Decision: move billing to usage-based pricing' lines:

• Invoices stay monthly
• Existing plans keep their price
• Linked to Billing project and the call with Maya

::

Some patterns that work well:

• Save the essence as an atomic note. When a conversation produces an insight, say "save this as an atomic note". You get one idea, a title that states it, your existing tags, and a link to the source. The skill at the end does this the same way every time.
• A decision log. Make a Decision type with properties for status, date, and project. Ask the agent to read the relevant decisions before it starts, and to write a new one when you settle something in a session.
• End-of-session write-back. "Write a short note on what we changed today and why, linked to the project." Tomorrow's session starts from it.
• Meetings become objects. Paste a transcript and say "create a Meeting object, link the people, and add the action items as tasks."
• Research into drafts. "List my Source objects tagged #onboarding, read them, and draft the docs page."
• Ask from anywhere. On your phone in ChatGPT: "What did I decide about the billing invoices?" Same notes, different agent.

Why agents should write atomic notes

An atomic note holds one idea. Its title states the idea as a claim, such as "Solar cells need ultra-pure monocrystalline silicon", not a topic like "Silicon". The body is short and makes sense without the conversation it came from. The idea is old. Niklas Luhmann built his Zettelkasten from about 90,000 cards like this. What is new is who reads them.

Atomic notes are the best unit for an AI second brain, for four reasons.

Search returns the right thing. An agent finds notes by searching, then reads the ones that look relevant. If the answer is buried in a long page called "Reading notes 2026", the agent reads the whole page to find one paragraph, and it fills its context with everything else. If the answer is a note whose title says it, the agent finds it in one search and reads only what it needs. That is context engineering in practice: just the right information for the next step.

Titles do the work. A title that states the idea is a summary the agent sees in search results before it opens anything. You get the same benefit when you scan a list of notes.

One idea links cleanly. A note about one idea can link to the book it came from, and to the projects where it matters. A long mixed note links to everything, so the links mean nothing. This is the "links everywhere" problem from the Obsidian thread.

Small notes are easy to check. You can read an atomic note in ten seconds and decide if it is right. A page of agent-written summary is harder to check, so mistakes stay in it. This is how knowledge rot starts.

The two ways agent write-back goes wrong

When agents save notes for you, two mistakes do most of the damage. Both are easy to make, and you notice both too late.

1. Tags created by accident. You have a tag "Solar energy". The agent tags a new note "Photovoltaics", which creates a second tag for the same field. Now your notes on one topic are split in two, and neither tag shows everything.
2. Links to nothing. The agent links to [[Material Worlds]], but your book is called "Material World". The link creates a new, empty object instead of pointing to the book. The note looks linked, but it is not.

The fix is a short rule set the agent follows every time: search for existing tags and use only those, look up the exact title of the source before linking, and ask when there is more than one match. You can type those rules into every chat, or you can give them to your assistant once, as a skill. That is what the skill at the end of this guide does.

How to shape a space agents use well

1. Create the types you actually use. Meeting, Person, Project, Decision, Source, and Atomic note. Give each the properties you care about. Agents read these and fill them in. Atomic note and many others are ready-made in the Object Studio gallery.
2. Write a "How this space works" page. List your types, your tag conventions, and what agents should never do. Tell each agent to read it first, the way you would point it at a CLAUDE.md.
3. Use clear titles. A title that says what the note is about is the single biggest help to search, for you and for agents. For atomic notes, the title is the idea itself.
4. Keep a short tag list, and grow it yourself. Tags are how you and your agents find related notes. Tell agents to use existing tags and to suggest new ones instead of creating them.
5. Keep spaces separate. Work and personal in different spaces, and connect each agent only to what it needs.
6. Review once a week. Agents write fast. Five minutes of deleting and linking keeps the knowledge base from rotting, whichever option you choose.

When you need more than the connector

The connector is built for working with your notes, not for bulk jobs. For imports, scheduled syncs, or your own tools, use the REST API. It has a public OpenAPI description and a TypeScript SDK, and you can build your own MCP server on top of it. Capacities for developers explains what it is for.

One Believer summed up the connector on X: "Your MCP Access multiplied the usefulness tenfold!"

Who should pick a Markdown vault instead

• You want your agent to edit notes as files, with grep, bulk rewrites, and Git history. Pick Obsidian or Logseq.
• Local files must be the source of truth. Capacities is a cloud app with Markdown export, not a local-first one.
• You need end-to-end encryption. Capacities is not end-to-end encrypted. Anytype is, and it has a local connector.
• Your agents need to design the structure. They cannot create types or properties in Capacities yet.
• Your team shares the knowledge base. Capacities is for one person.

The skill: save a conversation as an atomic note

A skill is a file of instructions that your assistant loads when a task matches. Claude, ChatGPT, Claude Code, Cursor, and Codex all read the same format: a folder with a SKILL.md file. Write the workflow once, and every assistant follows it the same way.

This skill turns one idea from a conversation into one atomic note in Capacities. It is a short version of the one we use ourselves. It does five things a plain "save this" prompt does not:

• It asks where the idea came from, because only you know, and the link to the source is often the most useful part of the note.
• It links to the exact title of the book, podcast, or article in your space, so the link never creates an empty object.
• It uses only tags you already have, and suggests a new one instead of creating it.
• It writes the title as a claim and keeps the body short.
• It replies with a link that opens the note in the Capacities desktop app.

::chat-to-note

app: claude prompt: Save the essence of this as an atomic note. reply: 'Where did this come from: a book, a podcast, an article, or no source? … Found your book "Material World" and the tags Physics and Energy. Saved: Solar cells need ultra-pure monocrystalline silicon.' noteLabel: Created in Capacities noteType: Atomic note noteIcon: i-ph-lightbulb-duotone noteColor: amber noteTitle: Solar cells need ultra-pure monocrystalline silicon lines:

• 'Core idea: impurities trap the electrons that carry the current'
• Purity of 99.9999% or more, grown as one crystal
• 'Tags: Physics, Energy, both already in the space'
• 'Source: Material World' caption: One idea, existing tags, and a link to the book it came from.

::

What you need

• Capacities Pro, and Capacities connected to your assistant. See Setting it up with Capacities, or the guides for ChatGPT and Claude.
• An Atomic note type in your space. Add it from the Object Studio gallery. Without it, the skill offers to save a Page instead.

Add it to your assistant

Create a folder called capacities-atomic-note, and save the skill below in it as SKILL.md. The folder name must match the name in the file.

In Claude, skills need code execution to be turned on. Assistants without skills can use the same text as project instructions.

The skill

---
name: capacities-atomic-note
description: Save one idea from the conversation as a self-contained Atomic note in the user's Capacities space, tagged only with existing tags and linked to its source. Use when the user says "save this as an atomic note", "keep this", or asks to save an insight from the chat to Capacities.
---

# Capacities atomic note

Turn one idea from the conversation into one Atomic note in the user's
Capacities space.

The user keeps a curated knowledge graph. Two mistakes damage it:

- Tags created by accident. A near-duplicate like "Photovoltaics" next to
  an existing "Solar energy" splits the graph.
- Links to an empty object, because the title did not match exactly.
  Most of this workflow exists to avoid those two mistakes.

## Tools

Use the Capacities connector. If its tools are not loaded yet, search for
them by description ("Capacities search objects", "Capacities create
object") before you start.

If the space has no Atomic note type, say so, and offer to save a Page
instead.

## Workflow

1. Ask where the idea came from, in one short question: a book, podcast,
   article, person, or no source? Skip this if the user already said.
   Ask even when it seems obvious. Only the user knows the source.

2. Find the source. Search Capacities for its title, with an objectType
   filter such as "Book" if you know the type.
   - One clear match: use its title exactly as returned.
   - Several or fuzzy matches (typos, dictation errors): show them and ask.
   - No match: ask whether to link anyway, which creates a new empty
     object, or to leave the link out.

3. Pick tags from existing tags only. Search with objectType "Tag" several
   times: the broad field, related fields, and synonyms, in every language
   the space uses. Pick 1 to 3 that fit, and use their exact titles.
   Never invent a tag: [[New tag]] in the tags property silently creates
   one. Create a tag only when the user asks. If nothing fits, use no tags
   and suggest one in your reply.

4. Write the note. Atomic means one idea that makes sense without this
   conversation. Write in the language of the conversation.
   - Title: the idea as a statement, not a topic. "Solar cells need
     ultra-pure monocrystalline silicon", not "Silicon".
   - description: one sentence on what the note covers.
   - Body: short, scannable Markdown. "## Core idea" in 2 to 4 sentences,
     then 1 to 3 short sections with the why, how, examples, or numbers,
     and an optional one-line takeaway. Keep facts, mechanisms, and
     numbers. Drop the chat. Do not repeat the title as a heading.
   - If the conversation holds several ideas, ask whether the user wants
     one note or several linked notes.

5. End the body with the source: a line with three dashes, then one line
   such as "Source: [[Material World]]", with the exact title from step 2.
   Fit the words to the source: "Heard on [[Podcast]]", "From [[Article]]".

6. Create the note. Call getObjectTypeShape("Atomic note"), then
   createObjectViaMD with the property keys it returned. Set every property
   in that one call. Keep the object ID it returns. If there is none,
   search for the exact title with objectType "Atomic note".

7. Get a link that opens the app. Call createObjectLink with the note's ID.
   It returns https://app.capacities.io/<spaceId>/<objectId>. Replace
   https://app.capacities.io/ with capacities:// and show it as a Markdown
   link with the note title as the text. Do this for every note you created
   or changed. If you cannot get a link, say so and give the exact title.

## Reply

Keep it short. The link comes first:

Saved: [Solar cells need ultra-pure monocrystalline silicon](capacities://<spaceId>/<objectId>)
Tags: Physics, Energy · Source: Material World
Suggested new tag: none

Use it, then make it yours

Say "save this as an atomic note" at the moment something clicks, not at the end of a long session. In Claude Code and Cursor, you can also call the skill by name with /capacities-atomic-note.

The skill is plain text, so change it to fit your space. Some common changes:

• Your own sections. Replace "Core idea" with the headings you use, or write them in your language.
• A related-notes property. If your Atomic note type has a property for related notes, tell the skill to fill it when you name them.
• Today's note. Add a step that also links the new note from today's daily note.
• A second type. Copy the skill for Decisions or Definitions, with the properties those types have.

How we wrote this guide

• We make Capacities. Claims about it come from our connector docs and MCP documentation, checked in October 2026.
• The Markdown-vault quotes are verbatim from public threads in r/ClaudeAI and r/ObsidianMD. The context engineering definitions are from Tobi Lütke and Andrej Karpathy in June 2025, as collected by LangChain.
• The skill uses the tools our connector exposes today. Where each assistant loads skills comes from the help pages of Claude, ChatGPT, Cursor, and Codex, read in October 2026.
• If something here is wrong, email [email protected].