Building a Personal Knowledge Base

Appearance

How It Works ​

You have a folder of markdown files, an AI assistant, and a handful of tools. This page explains how those pieces fit together -- and why each one is replaceable.

The Architecture ​

Five layers, each with one job:

🔌
Layer 5: The Tools (MCPs)
Search, project tracker, chat, calendar, data warehouse. Claude calls them on your behalf. Add or remove without changing anything else.
CONNECTIONS
📁
Layer 4: The Knowledge Base (files + Obsidian)
Markdown files with metadata, wiki-links, and folder structure. Obsidian helps you browse them. Claude Code helps the machine read them.
MEMORY
🖥️
Layer 3: The IDE (VS Code)
Where you interact with Claude Code. File browser on the left, AI chat on the right, everything in one window.
WORKSPACE
⚙️
Layer 2: The Harness (Claude Code)
The orchestrator. Decides what the LLM sees, which files to load, which tools to call, how to search. The traffic controller between you and the brain.
ORCHESTRATOR
🧠
Layer 1: The LLM (Claude)
The brain. Reads text, reasons about it, writes responses. Accessed via API. Does not remember between conversations on its own.
THE BRAIN

Each layer has one job. Together they create a system where Claude remembers, searches, and acts with context.

Layer 1: The LLM ​

Claude is the brain. It reads text, reasons about it, and writes responses. It is extraordinarily capable -- but it has no memory of its own. Every conversation starts blank. Without context, it gives you generic answers. With the right context, it gives you answers that feel like they came from someone who has been sitting next to you for months.

The LLM is also the most replaceable layer. If a better model comes along, you swap it. Your files, your structure, your skills -- all of that stays.

Layer 2: The Harness ​

Claude Code is the orchestrator. It sits between you and the LLM and decides what the model sees. When you open your workspace, Claude Code reads your CLAUDE.md file, loads your configuration, and understands what tools are available. When you ask a question, it decides whether to search your knowledge base, call an external tool, or just answer from what it already knows.

Think of it as a traffic controller. You say "prep me for my 1:1 with George." The harness figures out that it needs to find your notes on George, check recent meeting history, look at open action items, and pull in relevant context -- all before the LLM writes a single word.

Layer 3: The IDE ​

VS Code is just the window. File browser on the left, Claude Code chat on the right. You can see your knowledge base files, edit them, and talk to Claude all in one place. But the IDE itself is not doing any of the heavy lifting. You could use the terminal, JetBrains, or any other editor. The IDE is a preference, not a dependency.

Layer 4: The Knowledge Base ​

This is the layer you actually own. Markdown files on your disk, organized in folders, with frontmatter metadata and wiki-links connecting them. Obsidian gives you a nice way to browse and edit these files as a human. Claude Code gives the machine a way to read and reason about them.

The knowledge base is where your meeting notes live, your people profiles, your project summaries, your decisions, your action items. It is the accumulation of everything you have fed into the system. And because it is plain markdown, it will outlive every tool in this stack.

Layer 5: The Tools ​

MCPs (Model Context Protocol servers) are plugins that give Claude the ability to reach outside your file system. A search tool lets it query your company's knowledge base. A calendar connector lets it check your schedule. A chat tool lets it read Slack threads. A data warehouse connector lets it run queries.

Each tool is an independent plug. Add one, remove one -- nothing else changes. The tools are how Claude gets fresh information that is not already in your files.

Nothing Is Locked In ​

Every layer in the stack can be swapped without losing your knowledge:

Layer
You use
You could swap for
What stays the same
LLM
Claude (Anthropic)
GPT, Gemini, Llama
Files, skills, tools, structure
Harness
Claude Code
Cursor, Windsurf, open-source
Files and structure. Skills need adaptation.
IDE
VS Code
Terminal, JetBrains, any editor
Everything. The IDE is just a window.
Viewer
Obsidian
Any text editor, Logseq, VS Code
Everything. Files are plain markdown.
Tools
Your MCPs
Any tool with MCP connector
Everything else. Individual plugs.

Your knowledge is the asset. The tools are the interface.

We are building on open standards, not quicksand. The knowledge base is markdown files on your disk. Every tool is a choice you can revisit. Invest in the knowledge, not the tooling.

How the Layers Talk to Each Other ​

Let's trace a real request through the stack.

You type: "Prep me for my 1:1 with George"

Here is what happens:

1
Harness reads your config
Claude Code loads your CLAUDE.md and settings.json. It sees what skills, tools, and instructions are available. It knows about your knowledge base folder structure.
CONFIG
2
Harness detects what you need
It recognizes "George" as a person and "1:1" as a meeting type. It knows it needs people context, recent meeting history, and open action items.
ROUTING
3
Harness searches the knowledge base
It finds People/George-Costanza.md with his profile, recent meeting notes mentioning George, and any open action items tagged to him. All loaded as context for the LLM.
KB SEARCH
4
Harness calls external tools
It checks your calendar for the upcoming 1:1 time. It searches your company's search tool for any recent documents George shared. It checks your chat tool for recent messages from George.
MCP CALLS
5
LLM generates your prep
With all that context loaded, Claude writes a prep document: George's current priorities, open items from last time, topics to raise, things to follow up on. Specific, actionable, grounded in real data.
OUTPUT

Five steps, under three seconds. The same request without context would give you a generic template. With context, it gives you a real briefing.

The key insight: the LLM did not change between the generic answer and the great one. The same model powers both. What changed was the context the harness assembled before the model saw your request. That is the entire game -- giving the brain the right information at the right time.

The Bigger Picture ​

Every interaction with your knowledge base makes it more valuable. This is not a tool you configure once and forget. It is a system that compounds.

After 3 meetings processed: You have a handful of notes. Claude knows a few people's names and what they care about. Action items from those meetings are tracked. It is already more useful than a blank conversation, but still early.

After 10 meetings processed: Patterns start emerging. Claude can tell you "Sarah has raised the timeline concern in three of the last four syncs." Your people profiles have real substance -- working styles, priorities, communication preferences gathered from actual interactions. Meeting prep starts feeling genuinely useful.

After 20 meetings processed: The knowledge base has density. Cross-references between people, projects, and decisions create a web of context. Claude can connect dots you have forgotten -- "the last time this vendor was discussed, the team decided to hold off until Q2. That was six weeks ago." Your weekly reviews surface themes you would not have noticed manually.

After 3 months: This is where it gets interesting. You have a living institutional memory. New team members can be briefed in minutes. Recurring meetings have continuity even when you miss one. Decisions have traceable history. The system is not just organizing your notes -- it is giving you a searchable, reasoned, cross-referenced record of your professional life.

The progression is not linear. Each new piece of information makes every existing piece more valuable because it adds another node to the context graph. The twentieth meeting note is more useful than the first, not because it is better written, but because it connects to nineteen others.

This is not about organizing files. It is about giving Claude the context it needs to be genuinely useful.

Deep Dives ​

Each layer has more depth than we can cover on one page. When you are ready to go deeper:

Next: Adding Tools and Customizing -- make the system yours by connecting your tools and writing custom skills.

Built with VitePress