How to Build an AI Personal Operating System Using Files and Git

Problem Statement

AI assistants often fail because the model cannot retain context over weeks or months. Language models have limited context windows and a U‑shaped attention distribution, so adding unnecessary tokens reduces recall of important information.

Attention Budget

Each token competes for the model’s attention; extra tokens dilute focus on critical data.

Progressive Disclosure

A three‑layer architecture limits the information loaded for each task:

First layer : a lightweight routing file ( instructions/_index.md) that is always loaded and tells the agent which module is relevant.

Second layer : module‑specific instruction files (e.g., instructions/content.md, instructions/network.md, instructions/research.md) loaded only when the module is needed.

Third layer : actual data files (JSONL logs, YAML configs, Markdown documents) loaded only for the specific task.

This funnel‑like design ensures the model receives exactly the information it needs.

Agent Instruction Hierarchy

Three instruction levels define behavior at different scopes: CLAUDE.md – repository‑level entry point that maps the whole project. brain.md – contains seven core rules and a decision table that maps common requests to action sequences.

Each module directory has its own instruction file that constrains behavior for that domain.

Separating rules prevents instruction conflicts between content‑creation and networking tasks.

Why No Database

The system deliberately avoids databases and vector stores, relying solely on files tracked in Git.

Format‑Function Mapping

JSONL : used for logs because it is append‑friendly and streamable; the agent reads line‑by‑line without parsing the whole file.

YAML : used for configuration due to its clean hierarchical structure and comment support.

Markdown : used for narrative content because LLMs read it natively and it renders cleanly in Git diffs.

Each JSONL file begins with a schema line, e.g.

{"_schema": "contact", "_version": "1.0", "_description": "..."}

, so the agent always knows the structure before reading data.

Scenario Memory

Beyond factual records, the system stores reasoning processes in three append‑only logs: experiences.jsonl: key moments with emotional weight (1‑10). decisions.jsonl: decisions with rationale, alternatives considered, and outcomes. failures.jsonl: problems, root causes, and preventive steps.

These logs let the agent reference past reasoning instead of generating generic advice.

Cross‑Module References

Flat‑file relationships enable joins without a database. For example, interactions.jsonl contains a contact_id that points to an entry in contacts.jsonl, and ideas.jsonl links its pillar to a definition in identity/brand.md. This allows a workflow such as “prepare a meeting with Sarah” to automatically fetch her contact record, interaction history, and pending tasks.

Skill System

Auto‑Load vs Manual Invocation

Two skill types are defined:

Reference skills (e.g., voice-guide, writing-anti-patterns) have user-invocable: false and are automatically injected when a relevant task runs.

Task skills (e.g., /write-blog, /topic-research, /content-workflow) have disable-model-invocation: true and are triggered only by a slash command.

Automatic loading ensures continuity of style and knowledge; manual invocation provides precision for distinct workflows.

Style System

The author’s voice is encoded as five scored attributes (1‑10): formal‑casual 6, serious‑playful 6, professional‑simple 7, introverted‑expressive 7, humble‑confident 7. An anti‑pattern file lists over 50 forbidden constructions, organized into three levels (prefix bans, structural traps, max one em‑dash per paragraph). The agent checks each draft against this list and rewrites violations, ensuring output matches the defined style.

Templates as Structural Scaffolds

Five content templates define structures:

Long‑form blog: seven sections (hook, core concept, framework, practice, failure mode, start‑up, conclusion) with word targets, total 2,000‑3,500 words.

Tweet thread: 11‑tweet structure with hook, deep analysis, result, call‑to‑action.

Research template: four phases (landscape map, technical depth, evidence collection, gap analysis) outputting a structured markdown file containing executive summary, evidence with citations, failure modes, and opportunity list.

Each template includes a quality checklist that the agent runs before presenting a draft.

Real‑World Operation

Content Pipeline

The pipeline has seven stages: idea capture, research, outline, draft, edit, publish, promotion.

Ideas are stored in ideas.jsonl with a 1‑5 score on five dimensions (positioning, insight, audience need, timeliness, ROI). Only ideas scoring ≥15 proceed.

Research outputs populate knowledge modules.

Drafts undergo four editing passes using the style and quality checks.

Published items are logged in posts.jsonl with platform, URL, and engagement metrics.

Promotion creates X‑post and LinkedIn versions from the tweet‑thread template.

Typical weekly output: 3‑4 posts and outlines produced in 3‑4 hours.

Personal CRM

Contacts are organized into four circles (inner, active, network, dormant) with maintenance frequencies. Each contact record includes can_help_with and you_can_help_with fields for bidirectional matching, plus sentiment tags (positive, neutral, needs‑attention). A script cross‑references these fields to surface stale relationships, and circles.yaml defines group‑specific engagement strategies (e.g., founders, investors, AI builders).

Automation Chain

Three scripts run sequentially for the weekly review: metrics_snapshot.py – updates KPI numbers. stale_contacts.py – flags relationships needing outreach. weekly_review.py – generates a summary document with completed vs. planned items, trend analysis, and next‑week priorities.

These scripts output machine‑readable data to stdout, which the agent consumes to update todos.md and goals.yaml. The review is triggered manually (e.g., npm run weekly-review) rather than as a cron job.

Pitfalls Encountered

Over‑designed schema : initial JSONL entries had 15+ fields, most empty, causing the agent to chase missing data. Reducing to 8‑10 essential fields improved behavior.

Too‑long style guide : a 1,200‑line voice.md caused the agent to lose focus after the fourth paragraph. Moving core rules to the first 100 lines fixed drift.

Module boundary importance : merging identity and brand into one module increased token usage by 40 % for style‑only tasks. Splitting them restored efficiency.

Append‑only requirement : early versions overwrote posts.jsonl instead of appending, losing three months of data. Enforcing JSONL’s append‑only pattern prevented data loss.

Results

When the repository is cloned and opened in Cursor or Claude Code, the AI instantly knows the user’s voice, brand, goals, contacts, and content pipeline. The system demonstrates that “context engineering” – designing the information architecture the model consumes – is far more powerful than tweaking prompts.

The entire OS lives in a single Git repository, making it zero‑dependency, fully portable, and version‑controlled. Every change is tracked, enabling reproducible AI behavior across machines.

Reference: Agent Skills for Context Engineering – https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering