Muratcan Koylan’s long Twitter thread on “Personal Brain OS” lands on a familiar frustration in AI-assisted work: repeated re-explaining, re-pasting style guides, and watching an assistant drift into generic prose halfway through a task. His answer is not a new prompt, but a file-based personal operating system for AI agents—kept in a Git repo—designed to make context available on demand without turning every session into a context-window dumpster fire.
Context engineering, not prompt polishing
Koylan frames the core bottleneck as context, not prompts. Models have limited attention, and token placement matters; overstuffing a single system prompt isn’t just inefficient, it can degrade output as instructions blur together. His architecture splits the “brain” into 11 isolated modules so writing tasks and meeting-prep tasks don’t haul irrelevant data into the same context.
A key mechanism is progressive disclosure with three levels:
- Level 1: a lightweight routing file (Koylan uses
SKILL.md) that steers the assistant to the right domain. - Level 2: module instruction files such as
CONTENT.md,OPERATIONS.md, andNETWORK.md, each with scoped behavioral rules and file inventories. - Level 3: the underlying data (JSONL logs, YAML configs, research docs) loaded only when required.
The file system as memory (and safety rail)
Instead of a database, vector store, or external retrieval service, Personal Brain OS leans on plain files versioned in Git and whatever indexing/search an editor like Cursor or Claude Code already provides. The format choices are deliberate:
- JSONL for logs, emphasizing append-only writes and line-by-line reading.
- YAML for configuration and hierarchies with comments.
- Markdown for narrative documents like voice guides and templates.
Koylan lists a sizable spread: 11 JSONL files, 6 YAML files, and 50+ Markdown files, with JSONL schema lines up front (including versions and descriptions) so agents know what they’re reading.
One of the more interesting design points is “episodic memory”: append-only logs for experiences, decisions, and failures, meant to store not just facts but judgment and reasoning—the kind of material that can keep an assistant from generating generic advice when similar tradeoffs show up again.
Flat-file “relations” and task-focused loading
While modules are isolated for loading, they’re connected by references: contact_id ties interactions to contacts; idea pillars map to brand definitions; post metrics feed reviews. Koylan describes this as a flat-file relational model that supports workflows like meeting prep by selectively traversing linked files instead of dumping the entire repo into context.
Skills: process encoded as instructions
Personal Brain OS also formalizes work as Agent Skills following the Anthropic Agent Skills standard. Koylan splits skills into two categories:
- Auto-loaded reference skills (e.g., voice guide, writing anti-patterns) that activate when relevant.
- Manually invoked task skills via slash commands (e.g.,
/write-blog,/topic-research) that act as the instruction set for a specific workflow.
Voice is treated as structured constraints: attributes rated on 1–10 scales, plus banned words, banned openings, structural traps, and even a rule limiting em-dash frequency. Templates add quality gates like multi-pass editing (structure, voice, evidence, read-aloud) rather than leaving polish as an afterthought.
Operationalizing it: content, CRM, and scripts
Koylan describes a daily operating model around the repo:
- A content pipeline (Idea → Research → Outline → Draft → Edit → Publish → Promote) with idea scoring and logs for published URLs and metrics.
- A personal CRM with contact “circles,” maintenance cadences, and interaction sentiment.
- Several scripts chained for reviews and upkeep, including a Sunday weekly review that updates metrics, flags stale contacts, and generates summaries.
What didn’t work (and why it matters)
The thread closes with lessons that read like hard-earned guardrails for anyone building agent-friendly systems:
- Overbuilt schemas created sparse data that agents struggled to handle.
- Voice guides that were too long triggered mid-document drift; front-loading distinctive rules helped.
- Module boundaries directly affected token usage and relevance.
- Append-only JSONL emerged as a key durability feature after losing data when an agent rewrote a file.
There’s also pushback in replies about file system I/O and scale, which Koylan brushes off as out of scope for a personal side project—an implicit reminder that “good architecture” depends on the job.
Original source: https://x.com/koylanai/status/2025286163641118915?s=12&
