PKM Wiki

Personal OS

5 min read

A Personal OS is a file-based, Git-versioned, user-owned information architecture designed for AI agents to read natively — an evolution of the PKM vault from "notes a human reads" to "context a human and their agents share." Muratcan Koylan's "Personal Brain OS" (2026) is the canonical worked example: ~80 files in markdown/YAML/JSONL, no database, no API, no build step, structured so any AI tool pointed at the repository has instant context on identity, voice, goals, contacts, and decisions.

The term also surfaces in adjacent framings: Karpathy's LLM Wiki, YB's agentic constitution + subroutines, TfTHacker's Obsidian-as-app-platform argument. All describe the same direction with different emphasis.

Core Claim

The filesystem is enough. You do not need a database, vector store, specialized retrieval system, or cloud service to build a personally-useful context substrate for AI agents. Markdown, YAML, and JSONL on disk, versioned with Git, read by LLMs directly, are sufficient.

This is the local-first, user-owned, vendor-independent end of the PKM spectrum. The opposite end is SaaS PKM (Notion, Evernote), where the user's context is rented from the vendor.

Why Personal OS, Not Just Vault

"Vault" names a content store. "Personal OS" names the operating system layer around the content — the routing, the instructions, the workflows, the skills, the orchestration. The difference:

Vault Personal OS
"My notes" "My notes + how I work + how my agents work"
Read by me Read by me and by my agents
Organized for my recall Organized for routing + recall + agent action
Growth = more notes Growth = more notes + more skills + better routing
Success = findability Success = agents behaving like me

The Personal OS frame makes explicit that the agent-substrate role of a modern vault is a first-class design concern, not incidental.

Design Principles (across the practitioner corpus)

1. User-owned, local-first

Files live on disk. Git versions them. No hosted service is required. The user can move everything to a new machine, a new tool, a new agent — nothing is trapped in a vendor database.

2. Plain-text substrates only

Markdown, YAML, JSONL. No binary formats. LLMs read them natively. Humans read them natively. Diffs work. Merges work. Grep works.

3. Schema-first JSONL

Koylan's pattern: every JSONL file begins with a schema line ({"_schema": "contact", "_version": "1.0", ...}). Agents know the shape before reading data. Versioning is explicit.

4. Progressive disclosure

Not everything loads at once. A small routing layer points to a larger module layer points to a larger data layer. See Progressive Disclosure Architecture.

5. Separation of knowledge and judgment

Separate stores for facts (content, contacts, metrics) and judgment (episodic memory — experiences, decisions, failures).

6. Cross-module references without coupling

Flat-file relational model: contact_id in interactions.jsonl references contacts.jsonl; pillar in ideas.jsonl references brand.md. Modules isolated for loading, connected for reasoning.

7. Agents have instructions too

CLAUDE.md / AGENTS.md at the repo level, AGENT.md at the brain level, per-module instruction files. Instructions are themselves vault content, not something external.

Components

A mature Personal OS typically contains some or all of:

  • Identity layer — voice guide, values, goals, manifesto, personal identity notes
  • Content layer — templates, posts log, ideas, drafts, publication metrics
  • Relationships layer — contacts, interactions, circles
  • Knowledge layer — research, highlights, reference material
  • Memory layer — experiences, decisions, failures (episodic)
  • Process layer — workflows, routines, skills, automation scripts
  • Agent layer — instruction hierarchy, skill registry, routing

Not every Personal OS has all components; most start with a subset and accrete.

  • vs. LLM Wiki — LLM Wiki emphasizes AI-maintained interlinked knowledge articles with source provenance; Personal OS is broader and includes workflow, skills, and episodic memory
  • vs. Agentic Constitution — the agentic constitution is one file within a Personal OS, the orientation document every agent reads first
  • vs. Second Brain — Second Brain is human-reader-oriented; Personal OS is human-and-agent-reader-oriented. Overlapping artifacts, different design emphasis.
  • vs. Exocortex / Extended Mind — Exocortex is the cognitive framing; Personal OS is the architectural instantiation

The Open Problem

After two years of building, Koylan's own (2026-04) assessment: architecture is the easy part. Keeping it fed is the hard part. See Knowledge Transfer Pipeline. The compound is: file system + routing + skills + episodic memory is solved as a structure; the ongoing labor of placing material in the right files at the right time in the right shape is not.

This is the pipeline problem: capture tools, processing pipelines, trigger APIs, agent-driven routing. "Nobody wants to be the cron job for their own life" (Koylan). The next generation of Personal OS tooling likely competes on pipeline automation, not file structure.

Key Points

  • Personal OS = file-based, user-owned agent-readable context substrate
  • Canonical worked example: Koylan's Personal Brain OS (2026)
  • Evolution of vault from "content store" to "operating-system-around-content"
  • Plain-text only; Git-versioned; no database or vendor service
  • Design principles: local-first, progressive disclosure, schema-first, separated knowledge/judgment, cross-module references, agents-have-instructions-too
  • Contrasts: broader than LLM Wiki, inclusive of Agentic Constitution, beyond Second Brain
  • Current open problem: keeping the Personal OS fed; architecture alone is insufficient

Open Questions

  • Will a standardized Personal OS schema emerge across the practitioner community, or will each practitioner maintain their own?
  • How much of a Personal OS's value requires user-specific tuning vs. general best-practice templates?
  • What is the transition cost when migrating between AI agent platforms with an already-compounded Personal OS?

References

  • Muratcan Koylan, "The File System Is the New Database" (2026-02)
  • Andrej Karpathy, LLM Wiki pattern
  • YB, Claude-Obsidian setup + agentic constitution articulation
  • TfTHacker, Obsidian as app platform