Why You Don't Need a 3D 'Second Brain' (And How to Structure Documentation for Both Humans and AI Agents)
MarQ · 2026-11-18
If you spend any time on tech social media, you have definitely come across those eye-catching screenshots of knowledge graphs: thousands of glowing nodes floating in space, nebulae of cross-links, and sidebars packed with metrics.
They look great on screen. The problem starts when you actually try to work with them day to day.
Once you cross 200 or 300 documents, a global graph stops being a map and turns into an unreadable hairball. Nobody zooms around a galaxy of dots to find an architectural decision made four months ago. In practice, many "second brain" setups end up becoming a sophisticated form of procrastination: you spend more hours maintaining plugins, tags, and orphan nodes than writing code or solving real problems.
Today, however, there is an even stronger reason to avoid that accidental complexity: you are no longer the only one reading your docs—AI agents are reading them too.
The Hidden Cost of Over-Engineering Your Notes
When a knowledge base grows around proprietary extensions and visual views, three immediate bottlenecks appear:
- Context window pollution: Filling files with non-standard syntax, dynamic query blocks, and internal plugin metadata adds pure noise when a language model tries to read the repository. More junk tokens mean worse retrieval and a higher margin for error.
- Silent broken links: The moment you rename or move files from the terminal or outside the main app, internal references break without anyone noticing until someone tries to follow them.
- Mixing knowledge with operational state: The most common mistake when using note-taking apps for engineering is trying to turn them into a project manager with Kanban plugins and daily to-do lists. Your Git history gets cluttered with ephemeral updates, and the documentation loses its core purpose.
A Deterministic Three-Layer Architecture
Instead of delegating structure to a heavy interface, it works far better to apply the exact same principles we use to design software: plain text, verifiable contracts, and separation of concerns.
1. Pure CommonMark + INDEX.md Files
All technical knowledge lives in standard .md files inside a Git repository. No proprietary formats, and a guarantee that ten years from now any editor or script will still be able to read them.
To avoid both endless folder hierarchies and a chaotic pile of loose files, each domain maintains an INDEX.md file that serves as an explicit entry point:
docs/
├── INDEX.md
├── architecture/
│ ├── INDEX.md
│ ├── data-model.md
│ └── authentication.md
└── projects/
├── INDEX.md
└── mcp-integration.md
This pattern solves two modes of navigation at once:
- Top-down (structured): Both a new developer and an AI agent read
INDEX.mdfirst to get the exact map of the system without having to ingest the entire directory. - Bottom-up (direct search): When you are looking for a specific symbol, decision, or term,
ripgrep(rg) scans hundreds of files in milliseconds with zero background indexers required.
2. Bidirectional Links Audited with lychee
Giving up visual graphs does not mean giving up connected ideas across documents. Cross-links in standard Markdown ([data model](../architecture/data-model.md#schema)) remain the cleanest way to tie context together.
The difference lies in treating them like code: if a link points to a file that no longer exists or a heading that was renamed, the repository should catch it. Integrating lychee locally (as a pre-commit hook) or in CI lets you audit the entire documentation tree instantaneously:
$ lychee "**/*.md"
🔍 Analyzing 42 Markdown files...
📝 Checking 138 links and references...
✅ All 138 links are valid! (142ms)
No broken links found.
In just over a hundred milliseconds, you get deterministic referential integrity without relying on a GUI app to keep an internal index in sync.
3. Separating Static Knowledge from Live State (MCP)
The final piece that keeps the workflow clean is moving tasks, progress tracking, and multi-agent coordination out of Markdown files altogether.
- Static knowledge goes into Git (
.md): Architectural decisions, specifications, deployment guides, and consolidated technical documentation. - Ephemeral state goes into a dedicated operational layer: Which task is currently in progress, which agent is executing which unit of work, and what the current sprint status looks like.
With MarQ (marqpm.com), this separation connects directly via MCP (Model Context Protocol): agents query the clean local documentation to understand how the system works and use MarQ to coordinate what needs to be done and track task state—without polluting .md files with transient status updates.
Less Decoration, More Longevity
A good documentation system isn't measured by how impressive it looks in a screenshot, but by its daily friction: how fast a search returns, what happens when you move a file, and how effortlessly an agent can consume it without losing the thread.
Ultimately, returning to plain text with explicit indexes and automated link validation isn't a step backward—it's removing unnecessary layers between your ideas and real engineering work.