Q. There are already plenty of note apps, so why build a separate PKM system that AI manages?
In a normal note app, a person decides the folder, adds tags, and comes back later to dig through it. If you don't have time to organize, it just turns into a pile. This system swaps who does the reading and organizing, from person to AI. All I do is toss out a line in plain language whenever something comes to mind, and the AI reads a single rules file and handles classification, summarizing, linking, and keeping things current. No app, no server, no database, just a pile of text files and a handful of scripts.
Three lines you can use today
- Put every rule into one file,
CLAUDE.md. The AI reads it first before every task. - Location is meaning. Bake structure into folder and file names so you know the category without opening the body.
- Keep "always" loads to a minimum, and cap everything else at three files, loaded only when needed. Control cost through rules.
This post is the manual for that system: how it works (Part 1), and how to build it yourself, step by step (Part 2). The story of the struggle behind why I built it this way lives in three separate posts, linked throughout if you're curious. Here, I take the finished structure apart calmly, piece by piece.
Part 1. Concept and Usage
First, what this is, and how it actually gets used. Written so it reads fine even if you don't know a line of code.
01 In One Sentence
"A personal knowledge warehouse: say it out loud when it comes to mind, leave the organizing to AI." That one sentence is the whole thing.
There's exactly one core difference. In a normal note app, a person decides the folder, tags it, and comes back to find it later. In this system, the AI does that work instead, so the person doesn't have to follow any format.
The reason I flipped the idea is simple. No matter how many notes you stack up, if you never have time to organize them, they just become a pile. So I swapped the reader and organizer from person to AI. My only job is to toss out a line when something occurs to me, the system takes care of classifying, summarizing, linking, and keeping things current.
Video: my actual knowledge vault in Obsidian graph view. Each dot is a note, each line a link. All I did was talk to it, and it grew this far.
This is actually the next chapter of an earlier story. The process of getting the AI to move fast across hundreds of notes is written up in the record of trying an ontology and finding something lighter instead, and the day I got accumulated knowledge circulating all the way into execution is in Self-Evolving Knowledge System. This post explains the finished result head-on.
02 The Whole System, in Three Boxes
Three boxes draw the whole structure: person, AI, warehouse. In the middle, the AI acts as the assistant.
The person just tosses things out, the AI organizes, and the warehouse handles storage and retrieval. The secret sits in a single rules file at the very top of the warehouse: a manual named CLAUDE.md.
The AI reads this file before starting any task. It spells out, "when this kind of input comes in, handle it this way," for everything, so it works the same way every time without being retaught. This one file is both the system's brain and its contract.
Figure 1. The person just tosses, the AI organizes, the warehouse stores and retrieves. The secret is CLAUDE.md, the rules file the AI reads first every time.
03 Two Faces: Obsidian for the Person, Claude for the AI
Both sides handle the same text files, but the person needs a screen to look at, and the AI needs hands to organize with.
Image: Claude is the backend, Obsidian is the frontend. One pile of files, shared by two faces.
There are two screens. The person looks at dashboards, calendars, and graphs through Obsidian (a note-taking app), and the AI creates files by the rules through Claude Code. Both work on the exact same .md text files.
So the person sees what the AI made right away in Obsidian, and the AI reads whatever the person moved around on the calendar. Claude handles the heavy lifting, organizing, generating, searching, while the Obsidian dashboard handles the daily work of looking things over, checking boxes, and dragging cards.
The files still open fine without Obsidian, but the visual payoff, calendars, graphs, that's what Obsidian adds. As you'll see later, this frontend is a nice-to-have option, not a requirement of the system.
Figure 2. The backend (Claude) and the frontend (Obsidian) share one pile of files. Data the AI organizes shows up on the person's dashboard instantly.
04 What the Warehouse Looks Like: Folder Structure
A house is the fastest way to picture it: every room has an assigned role, and which room something's in tells you what it is.
Image: Location is meaning. Which room something's in stands in for its category.
There are six folders and one rules file. 00-inbox is the catch-all you toss things into first, 01-core is the rules always read, 02-skills is how-to documents pulled out when needed, 03-reference is refined knowledge, 04-context is projects in progress, and 05-outputs is finished deliverables. 99-archive is the untouched back room of the warehouse.
The point of this layout is that location is meaning. Just looking at which folder a file sits in tells you its category, no need to open the body. Neither the AI nor the person ever gets lost.
Figure 3. Six folders and one rules file. Location is meaning, so you know the category without opening the body.
05 How One Piece of Information Gets Organized
Let's follow one idea from arrival to finding its place. You toss it into one spot; it gets sorted into three.
Whenever something comes to mind, it goes in as one line of plain language, piling up in 00-inbox first. That's where the person's job ends. Later, a single "process the inbox" and the AI opens each capture and splits it three ways.
Reusable knowledge goes to 03-reference, actionable work goes to 04-context, anything to discard goes to 99-archive. The person never has to think about this sorting. All you need to know is the one spot to toss things into; the judgment call gets handed off to the AI.
Figure 4. Toss into one place (inbox), the AI sorts it three ways. The person never has to think about classification.
06 A Project Grows Through Four Stages
One piece of work grows from idea to execution, to operation, to reflection. Instead of cramming that whole flow into one file, each stage gets its own file.
Image: Stages aren't overwritten, they sit side by side. That's why they read back as a single flow later.
Plan, build, run, retro, each of the four stages has its own file. So when I say "show me this project from start to finish," the AI neatly pulls together 1 through 4 in order. The context never breaks.
There's a hidden bonus. Anything in a retro that seems "worth writing about" gets flagged as a blog candidate, and anything that "proves a skill" gets flagged as a portfolio item. Later, a single "pull together the blog candidates" gathers up the material.
A structure where the record becomes a content asset by itself. The story of wiring this feedback into the whole system is in Self-Evolving Knowledge System. The point: if it only accumulates, it's a dead warehouse; once circulation kicks in, it's a living system.
Figure 5. From plan to build, run, retro. Each stage is recorded separately, and reads back as one flow later.
07 Schedule and Tasks: A Separate Track
"Do this by such-and-such date" is a different kind of thing from a general note. So tasks and schedules are managed separately, in a dedicated input file (00-inbox/일정-태스크.md).
I say it in plain language, the AI formats it into Obsidian's Tasks syntax and puts it in, and the calendar, the Tasks plugin, and the schedule/task panel dashboard visualize it. I never have to type #task or a date symbol myself.
| Say it like this (plain language) | The AI formats and saves it like this |
|---|---|
| "Need to check SEO by Friday" | Judged as a task → - [ ] … #task ➕added 📅due |
| "Doctor's appointment tomorrow at 10am" | Judged as a schedule → - [ ] 10:00 … #schedule ⏳ 📅 |
| "Remind me to look at this again next week" | Saved as a reminder + due date calculated automatically |
| "Check my tasks" / "this week's schedule" | Organized by the panel and each project's next_review field |
To move a card, just flip the checkbox in the input file from waiting to in-progress to done, and the panel updates itself. Priority is also marked with a symbol in the input file. On the surface it looks like a slick kanban board, but underneath, it's still just one text file.
08 What It Actually Looks Like Day to Day
There are no commands to memorize. Just say things in your normal way of talking. On the left below is what I say, on the right is what happens.
| Say this | This happens |
|---|---|
| "Put this in the inbox" + content | Stored as a note in the capture bin (sorted later) |
| "What do I need to do this week?" | Tasks and projects with looming deadlines, organized into a table |
| "Tell me what's in progress" | In-progress projects and next actions, at a glance |
| "Start planning the Galaxy Watch thing" | Auto-generates a new project's plan document, fully formatted |
| "Move it to the build stage" | Marks planning complete, creates a fresh document for the next stage |
| "Show me this project from the start" | Pulls stages 1 through 4 together in order and summarizes |
| "Process the inbox" / "bring the vault up to date" | Sorts and promotes accumulated captures into the right folders |
Here's the key point: no one has to memorize #task or folder rules. The AI fills all of that in. The person just says what they want, in their normal way of talking.
09 So What Actually Gets Better
More important than a feature list is how daily life actually changes. It comes down to four things.
Image: Toss into one place. The system sorts it three ways. The person never has to think about where something goes.
Organizing burden drops to zero. No agonizing over classification, tags, or folders. You toss it and you're done, so how would a pile ever build up? It's easy to find again. Everything stacks up in the same format and tag, so "show me that" pulls it right out.
Context never breaks. Projects connect stage to stage, so the flow reconstructs itself perfectly even months later. The record becomes an asset. Anything that went well automatically piles up as blog and portfolio material.
The AI handles the format, I handle the thinking. Time that used to go into organizing now goes into thinking and tossing things out.
Part 2. How It Works and How to Build It Yourself
From here on, this is for anyone building or porting this system themselves. We'll look at the internal mechanics and the step-by-step setup.
Image: No special app, no server. The surface is a pile of text files; underneath, rules and scripts run the show.
Summed up on one page, it's this: a rules file the AI reads (CLAUDE.md) + a fixed folder structure + a handful of Python scripts that build indexes. That's everything. No special app, no server, no database. It's an ordinary pile of text files, Claude Code (or GPT, Codex) reads the rules and works on top of it, and copying the whole folder ports the system as-is.
10 Core Mechanism One: The Loading Procedure That Runs Every Session
How the AI picks "what to read" when it starts a task is the first mechanism, and it's what governs cost.
Reading all the knowledge every single time is expensive and slow. Expensive here means tokens, the fee that scales with how much text the AI reads and writes. So I split things into what always gets read (rules) and what only gets read when needed (knowledge).
What decides this branch is the load_priority value in the tag (frontmatter) at the top of the file. always means it's read every time, on-demand means it's opened only when needed, and locked means it's never looked at.
Figure 6. From always-read rules (step 2) to knowledge picked only when needed (steps 3 to 4). The "max 3" funnel at step 4 controls cost.
Why specifically "max 3" matters here. Even with hundreds of knowledge files, any single task usually only needs two or three of them. The AI matches by looking at each file's use_when field in the frontmatter ("the situation this file is for").
Reading less is faster, cheaper, and more accurate. This runs against intuition, reading everything feels like it should make the AI smarter, but the more irrelevant documents get dragged in, the blurrier the answer gets, and only the bill goes up. Deciding what not to read matters just as much as deciding what to read.
The story of actually measuring, over five weeks of logs, how often this loading runs and which files really get read again is in I Thought My AI Was Learning Me. Measuring the resurfacing rate for real turned out lower than I expected, and that made this "load less" principle even more solid.
11 Core Mechanism Two: The Digest Index
Even with 100 projects in progress, you don't open all 100 files, you read a single index instead. This is the second mechanism.
Project documents keep piling up by stage. Opening dozens of files one by one just to answer "show me what's in progress" is wasteful. So I keep an index (_digest.jsonl) that pulls just the frontmatter from each file into one line of JSON.
The AI reads just this one index first to get the overall state, then opens only the files it needs. The key point is that the cost of grasping the state stays constant, regardless of how many files there are. Think of the index at the back of a book: you know where everything is without reading the whole text.
Figure 7. From frontmatter to index, the AI starts with the index. Keeps the cost of grasping state constant, regardless of file count.
The same idea applies to the knowledge folders too. build_index.py gathers the frontmatter descriptions from every file in 02-skills and 03-reference and auto-regenerates a domain-by-domain table of contents (index.md). So the "read the domain index" step from procedure 10 always points to an up-to-date list.
There's a failure behind switching to this lightweight index. I originally tried a heavy structure, a formal ontology, and dropped it once it became clear it just ate tokens without any real payoff. That trial and error is written up honestly in the record of trying an ontology and finding something lighter instead.
12 The Whole Architecture, in Four Layers
Top to bottom, there are four layers: entry, always-read rules, read-when-needed knowledge, and work plus automation.
The top two layers (entry, rules) correspond to the operating system; the bottom two (work, automation) correspond to data and tools. 99-archive is never read by any layer. This separation is what lets "rules stay stable, knowledge keeps growing" run without conflict.
Figure 8. The top two layers are the operating system, the bottom two are data and tools. 99-archive is never read by any layer.
13 The Data Model: Frontmatter Is the Database
The body of a file is for people to read, the frontmatter is for machines to read. That frontmatter is the source for indexing, search, and reminders, playing the role of a database without actually being one.
Project documents have their structure baked into the filename and the frontmatter: filenames follow the shape {stage number}_{stage}_{slug}.md, and the frontmatter has 14 fields. Even if it looks like code, there's nothing to be intimidated by. It's just a tag stuck on top of the file, and the body people actually read sits separately underneath.
# Frontmatter of 04-context/2_build_galaxy-watch.md
---
title: "Galaxy Watch Page"
lifecycle: build # plan | build | run | retro
domain: engineering # one of 5 domains
role: [planner, vibe-coder] # multiple, from 4 roles (see below)
project: "galaxy-watch" # grouping key, same value = same project
status: in-progress # planning|in-progress|paused|completed
next_review: 2026-06-23 # reminder trigger (used to compute this week's tasks)
next_action: "Finalize comparison table copy"
outcomes: [{metric: CTR, value: "+18%", period: Q2}] # quantified results
blog_candidate: false
portfolio_candidate: true # only true after user confirmation
---
# Leave blanks blank instead of filling them with plausible prose → <!-- empty: source not recorded --> (prevents hallucination)There's a trap hiding here. Fill a blank with a plausible-sounding sentence, and the AI ends up hallucinating facts that don't exist. So the rule is: when a value is missing, leave a "not recorded" marker instead of prose. Honestly leaving a blank empty beats making it look filled in.
Four Roles, One Document Wears Multiple Hats
The owner of this warehouse is one person wearing four roles at once: marketer, analyst, vibe-coder, planner. Because the role field can hold multiple values, a single document satisfies project management, blogging, and portfolio all at the same time. Say "pull together my portfolio" and it comes back grouped by role.
This design has a reason, and that reason is exactly what it achieves.
| Design rule | Reason and effect |
|---|---|
| A stage transition creates a new file (never renamed) | The previous stage's record is preserved, so the 1-to-4 flow stays intact |
Grouped by the project field | "Show me from the start" = search for the same value, then order it |
role as multiple values + candidate flags | Loads simultaneously into per-role portfolio and blog material |
outcomes as an array of objects | Forces results to be quantified → aggregates instantly in retros and portfolio |
14 Operating Rules: Images and Spreadsheets
There are two things I run into daily: organizing attached images and connecting to Google Sheets. Both are places where the same mistake keeps happening, so I nailed down rules to prevent it.
Image and Asset Rules
- Every image goes under the
assets/subfolder of whichever folder its file belongs to. Never at the folder root. - References in the body follow the shape
(spaces encoded as%20). - Notion exports dump images at the root, so when cleaning up, move them into
assets/and fix the links. - Batch cleanup runs through
organize_images.py(dry-run by default, apply with a separate flag, originals backed up).
Spreadsheet Connection Rules
- Reading and writing to Google Sheets always goes through one connector script,
pkm_sheets.py. Never rewrite auth from scratch each time. - The auth key is referenced only by its path in
.env, and the key itself never gets committed to the repo. - The target sheet has to be shared with the connector account's email as an editor before it opens.
- Frequently used sheets are registered under an alias and called by that alias.
There's one reason these got nailed down as rules. Broken image paths and repeated sheet-auth mistakes happen again in the next session no matter how careful you are. Pin it down as a rule in CLAUDE.md, and whichever AI session shows up handles it the same way.
15 Building It Yourself: A 30-Minute Setup
This isn't installing an app, it's creating folders and a rules file. Thirty minutes gets the skeleton standing.
Figure 9. Steps 1 to 5 are the core. Step 6 (Obsidian, mobile, sheets, kanban) is an optional extension you bolt on by taste.
STEP 1-2. Prerequisites and folder skeleton. Only two things are required: the Claude Code CLI (or GPT / Codex reading CLAUDE.md) and Python 3 with PyYAML. Optional: cloud sync, iOS Shortcuts, a service account key for Sheets.
# Create it all at once from an empty folder (mac / linux / WSL)
mkdir -p my-pkm/{00-inbox,01-core,02-skills,03-reference,04-context,05-outputs,99-archive,templates,scripts}
cd my-pkm
mkdir -p 03-reference/{engineering,workflow,thinking,writing,marketing}STEP 3. CLAUDE.md, the system's brain. This is the single most important file. Domain classification, folder structure, and the task-start procedure (the loading algorithm) all get written here. The skeleton of the procedure looks like this.
# CLAUDE.md task-start procedure (loading algorithm)
1. Read this file
2. Read all of 01-core/ (always)
3. Analyze the request and determine the domain
4. Read that domain's index.md
5. Pick up to 3 files whose use_when matches
6. After loading, print [Loaded: path]01-core/ holds three files (all always-loaded): persona.md for tone and role, core-rules.md for loading and prohibited-action rules, and project-management.md for filename and frontmatter rules.
STEP 4-6. Scripts, first run, extensions. Two scripts are enough to get started: build_digest.py, which builds the project index, and build_index.py, which builds the knowledge table of contents. Both need nothing more than the standard library plus PyYAML.
Confirm the first run like this: say "start planning a test project" and a 1_plan_*.md file should appear fully equipped with all 14 fields; say "show me what's in progress" and it should read the index and filter. If [Loaded: …] shows up at the top, it's working.
Extensions are entirely optional. With just the core from steps 1 to 5 (markdown + CLAUDE.md + 2 scripts + Claude Code), capture, classification, project management, and loading into blog and portfolio all run fine. Obsidian is just a frontend that adds visual payoff, it doesn't replace the core.
16 Finally, Six Things to Keep in Mind If You Build This
Now that the structure's all laid out, let's boil it down to the principles worth carrying into your own build. Each one already had its reasoning covered earlier.
- Single source of truth: Are your rules scattered around? Keep them all in one place,
CLAUDE.md. Scatter them and every AI session behaves differently. - Location is meaning: Are you hunting for classification inside the body text? Bake structure into folders and filenames so you know without opening anything.
- Frontmatter is the database: Are you searching through every full body text? Make the machine-readable frontmatter fields the source for indexing, search, and reminders.
- Load less: Is everything read every time? Keep "always" to a minimum and cap everything else at 3. Control cost through structure.
- Text only: Are you locked into a database? Use only JSONL and markdown. Safe across multiple PCs and the cloud.
- People speak plain language: Are you demanding syntax from the user? Let the AI fill in the symbols and formatting.
On the flip side, what this system doesn't do is just as clear. It never asks the user to type symbols directly, never renames a file on a stage transition, never fills a blank field with a plausible-sounding sentence. Deciding what not to do protects the system just as much as deciding what to do.
If you only take one thing away, let it be this.
The person drops the format and keeps only the thinking; the format gets handed entirely to the AI.
Sources
- The process of getting AI to move fast across hundreds of notes (ontology trial and error): Making Hundreds of Notes Fast for AI to Use
- The day I got accumulated knowledge circulating (the feedback loop): A Second Brain That Only Accumulates Is Already Dead
- Five weeks of measuring loading and resurfacing rates (the evidence for load-less): I Thought My AI Was Learning Me
- Claude Code (the AI runtime): Claude Code official docs
- Obsidian (the frontend): Obsidian
This post is a guide explaining the author's personal knowledge management system. Figures like folder and field counts are as of July 2026, and your own setup may vary.
Found this useful? Share it
Related posts
Related projects
Get new posts by email
Insights on marketing, analytics, and dev, delivered to your inbox.