How to Build a "Second Brain" with Obsidian That Your AI Agent Can Read, Without Building a Custom RAG Pipeline

Connecting Obsidian, Git, and AI Agents with nothing but plain Markdown. The Seamless Integration by Design philosophy from NEXT4I.

#Obsidian #BuildinPublic #SecondBrain #KnowledgeManagement #AITools

---

Ever run into this? You wrote a detailed technical spec three months ago, and today someone asks "how did we design this module again?" You end up spending 20 minutes hitting Cmd+F across Google Docs, Trello, and README.md files scattered across different repos, or sometimes there's no documentation at all, so you have to dig through the code and reverse-engineer it by eye.

TLDR; I built a knowledge-base system for NEXT4I using Obsidian (plain Markdown) together with Git and a VS Code AI agent, without writing a single line of custom integration. The core of the system is choosing tools that already "speak the same language" from day one (plain text, open formats), so AI can read our knowledge base practically for free, no RAG pipeline required.

---

Pain Point: Scattered Knowledge and Requirements Make Search Hard and Nothing Stays in Sync

Before this system, all of NEXT4I's knowledge was scattered across many places: notebooks, Apple Notes, Google Docs, Google Sheets, Trello, README.md files, or, even worse, sometimes there was no documentation at all, just buried in the code, spread across multiple repos each written in a different language, frontend and backend alike.

This isn't just an inconvenience. It makes search genuinely hard, sometimes it's Cmd+F and pray. Worse: my AI coding agent could read the entire codebase, but it had zero visibility into the reasoning behind that code, because that reasoning was scattered somewhere the AI couldn't reach.

---

Design Constraints: 3 Non-Negotiables

Before picking a tool, I set 3 rules:

1. It has to be affordable, or free if possible.
2. It has to be accessible online anytime, from my phone, and still work offline.
3. Plain text, zero lock-in. If the tool disappears tomorrow, the files must remain immediately readable and usable.
4. Local-first, Git-friendly. It has to be a normal folder I can git init and track right away.
5. AI-readable without building extra infrastructure. My AI agent already lives in VS Code, so the knowledge base has to sit inside that workspace without me building an extra pipeline.

Obsidian passed everything, because at its core, an Obsidian vault is just a folder of .md files.

---

Architecture: Vault Structure

vault/
├── Ideas/          # Raw concepts, brainstorming
├── Manifesto/      # Vision, mission, core policies
├── Principles/     # Design rules, engineering guidelines
├── Infrastructure/ # Deployment topology, IaC specs
├── Platform/       # Domain model, API contracts
├── Script/         # Utility scripts, automation, runbooks
├── Skill/          # Patterns, checklists, reusable knowledge
└── Appendix/       # Domain glossary, citations

Every file is a plain .md. Links use [[wiki-link]] syntax. Metadata lives in YAML frontmatter, and Graph View renders the relationships as a visible dependency graph.

Version control is just git init inside the vault folder, then committing every change with a rationale. git log -- "Infrastructure/sharding-strategy.md" shows the full decision history for that topic. Push it to a private GitHub repo and you get backup, an audit trail, and branching for major revisions, all for free.

---

Key Insight: AI Access Without Building Anything

This is the part that changed everything.

Obsidian vault = a folder of .md files. VS Code = opens any folder as a workspace. AI coding agent (running as a VS Code extension) = reads every file in that workspace.

So the "integration" here is: open the vault folder in VS Code.

That's it. No API, no embedding pipeline, no vector database, no chunking strategy. Just plain Markdown files that the AI agent reads natively.

---

Prompt Patterns I Actually Use

Contextual search + reasoning:

Search all documents that mention our sharding strategy.
Summarize every trade-off we've considered
and tell me which approach we ultimately chose and why.

Gap analysis:

Look at everything in the Infrastructure/ folder
and tell me which architectural decisions are still undocumented,
compared against the template in Skill/.

Drafting from conventions, not from a blank page:

Using the patterns in Skill/go-backend/ and the domain model in Platform/core/,
draft a design doc for a new message consumer
following our established conventions.

Impact analysis via link traversal:

If I change the authentication rule in Principles/auth.md,
trace every file in Platform/ and Skill/ that links to it via [[links]]
and tell me what needs updating.

The AI reads across multiple files, follows [[wiki-links]], understands the relationships, and synthesizes an answer, without me writing a single line of integration code.

---

Philosophy: Seamless Integration by Design

The pattern here isn't "integrate 3 tools." It's choosing components that already speak the same language.

Obsidian chose Markdown, the most universally readable format in computing, over a proprietary database. Git works with any plain text. AI agents already know how to read files in a VS Code workspace.

I didn't build the integration. I chose integration, by picking tools that respect open, simple formats. The "work" is the discipline to keep everything plain, not writing code to glue it together.

This is the same philosophy I apply to NEXT4I's backend services: when every component speaks the same language, everything flows, without anyone having to force it.

---

Bonus: Obsidian Canvas as a Visual Layer

Obsidian's Canvas is an infinite whiteboard, place document cards, text, media, then draw connections between them.

I use Canvas for:

• System architecture sketches: each service as a card, data flow arrows, real specs embedded right on the board
• Decision trees: "if we pick X, then Y and Z are affected," with linked evidence
• Plan strategy & flow: for planning work, sequencing, and various NEXT4I workflows

Canvas files are Markdown too under the hood (JSON-like structure), so they're Git-versioned and AI-readable as well. Drop a .canvas file into your VS Code workspace and ask the AI to analyze it for circular dependencies or single points of failure.

---

What I Learned

What makes this system work isn't the technology, it's what I didn't build. No middleware, no proprietary pipeline, no vendor lock-in.

The discipline of plain text + Git + open formats is a feature, not a limitation.

If you're a dev or a small team drowning in scattered documents, try this before jumping to a heavyweight knowledge-management platform. Plain Markdown with a good folder structure will take you further than you'd expect.

---

Thanks for reading all the way to the end, I'll keep working on more articles like this.

---