I moved my second brain out of Notion and into a folder of markdown files in a git repository. The structured parts, the things that used to be Notion databases, became small custom apps with an ag-Grid table on top. Notion did nothing wrong. What changed was who reads my knowledge base. For years it was me, clicking through pages. Now it is mostly AI agents, and agents want something different from a second brain than people do.
Why did Notion stop fitting?
Notion is designed for a person in a browser. Pages, blocks, databases, permissions, a beautiful editor. Everything lives in Notion's cloud, and the way in for software is an API that hands you content block by block, under rate limits, through an integration you have to grant page access to. That is a reasonable design for a product used by people. It is a bad shape for an agent that needs to read forty documents, change three of them and show me exactly what it changed.
I run a fleet of agents that do routine work across the business, which I described in an executive's week on an AI agent fleet. Every one of them is at its best in a directory of files. They grep, they open, they edit, they commit. Give the same agent a Notion workspace and it slows to the speed of the API, and you lose the one thing you most need when software edits your knowledge: a diff.
What does the markdown second brain look like?
It is a private git repository organised with PARA: seventeen top-level areas, each split into Projects, Areas, Resources and Archive. Text is plain git. Binaries such as PDFs and scans go into Git LFS. Anything over 50 MB stays out of the repository entirely; it goes to cloud storage, and a small pointer file with the link, size and checksum takes its place in the tree. Those offloaded files are mirrored to a second storage provider every night with a checksum check.
Every machine I work on, four workstations and the server, carries a full working copy. That is the part that matters. When I ask an agent a question about a contract, a tax filing or a past project, it reads the file on disk. There is no connector to authorise, no export to refresh, no search index that may or may not be current. The agent has the same view of my knowledge that I have.
Git does the work a second brain app usually charges for. History on every file. A clear record of what an agent changed and when. Branches when I want a reorganisation reviewed before it lands. And the files will open in any editor in twenty years, whatever happens to the company that sold me the app.
Where do the databases go?
This is where most "just use markdown" advice falls apart. Prose is natural in markdown. Rows are not. A partner list, a household inventory, a revenue ledger: these were Notion databases for a reason, and a folder of markdown tables is a worse version of them.
So the rows moved into small custom management apps, one per domain. My revenue tracker is a typical one: a FastAPI service, a MariaDB database, a JSON API with one endpoint per change, and an ag-Grid table as the screen I actually look at, all behind Cloudflare Access. ag-Grid gives me the part of Notion databases I liked: sorting, filtering and inline editing on thousands of rows, in a browser, loaded from a CDN with no build step.
The difference from Notion is that the rules are code. In my revenue tracker, for example, the ledger is append-only: a correction is a new adjustment entry, never an edit, and the database itself refuses an update. Validation, currency conversion and rollups live in one service module that the UI, the importers and the agents all go through. An agent cannot quietly overwrite a number, because no such path exists. In a Notion database the best you get is a property type and hope.
Building one of these used to take long enough that a Notion database was the obvious shortcut. With coding agents doing the build, that is no longer true, and the agents then become its main users through the same API they built.
What did I give up?
Three things, and they are real. First, polish. Notion's editor is better than any markdown editor for writing a page someone else will read. Second, sharing with non-technical people. A collaborator can open a Notion link with zero setup; nobody I work with wants a git clone. I still use Notion for shared pages that other people edit, and copy the final version back into the vault. Third, the custom apps are mine to maintain. When one breaks, there is no vendor to email.
It is the same trade I make in training. An off-the-shelf plan is easier to start, but once you know what you are actually optimising for, a plan written for that goal wins, and you accept that you own it.
The rule I use now
Prose goes in markdown, in git, where agents and I can both read it. Rows go in a real database with an ag-Grid table on top and an API in front, so the rules are enforced in code. Notion keeps the pages that other people need to edit. Since I split it that way, my second brain is the one system the agents never have to work around.
If you are choosing tools rather than building, the wider field of traditional and AI-native second brain apps, Obsidian and Notion included, is covered in the We The Flywheel overview of second brain tools. More on this pillar: Compounding CEO.
Frequently Asked Questions
Why move a second brain from Notion to markdown files?
Because the main reader changed. A second brain that AI agents work in every day needs to be files they can search, edit and commit directly. Notion keeps content in its own cloud database, so an agent has to go through an API or connector, page by page, with rate limits and a permission model built for people. Plain markdown in git gives agents the same access a developer has to a codebase, plus a full history of every change.
What replaces Notion databases if your notes are in markdown?
Markdown is good for prose and bad for rows. Anything that is really a table, such as a partner list, an inventory or a revenue ledger, moved into a small purpose-built app: a real database, a JSON API with one endpoint per change, and an ag-Grid table as the editing interface. People edit in the grid, agents call the same API, and the rules for what counts as valid data live in one place in code.
Is Obsidian needed for a markdown second brain?
No. Obsidian is a good editor for a folder of markdown files, and the files stay usable without it. The point of the setup is that the vault is just a directory: any editor, any coding agent, grep and git all work on it. Obsidian is optional on top.
Is Notion still useful in this setup?
Yes, for pages that other people need to read and edit with no setup. Notion is very good at shared, polished documents for people who will never open a terminal. It stopped being the right home for my own knowledge base once agents became its main reader.
Ready to Transform Your AI Strategy?
Get personalized guidance from someone who's led AI initiatives at Adidas, Sweetgreen, and 50+ Fortune 500 projects.
