Life OS Architecture — How I Built an AI-Operable Life Operating System

The most critical component of my AI system doesn’t use AI at all.

It runs on bash scripts. Zero LLM tokens. Zero hallucinations. Zero GPU contention. It’s faster, cheaper, and more accurate than any model I’ve tested — and it’s the only part of the system I trust to run without supervision.

This is the monitoring layer of the Life OS — a 5-layer, file-based, AI-operable personal operating system that I’ve been building over the last few weeks. It orchestrates my projects, tracks my areas of responsibility, cross-references my knowledge, and reports on its own health. My AI agents (Hermes, Cline, future ones) can read and write to it natively. And so can I — using just a file browser and a text editor.

Here’s how it works, why I built it this way, and the one pattern you should steal for your own system.

The Problem: Information Systems Are Designed for Humans or Machines, Never Both

I used to run a “Second Brain” across half a dozen note-taking apps. Logseq for deep notes, AnyType for project tracking, Google Keep for quick captures, a MediaWiki for reference — each one a silo. The knowledge was in there somewhere, but it was locked to each app’s format, each app’s API, each app’s permissions. If I wanted an AI agent to read across them, I needed to build bridges between every pair. I didn’t want a graph of apps connected by duct tape — I wanted one system that worked for everything.

I was diagnosed with having ADHD late in my life, at 40, so the novelty and habit of system hopping was real — I kept building the same structures in whatever app I was using. If that system doesn’t put the right information in front of me with zero friction, I won’t use it. I also have AI agents that need to navigate my workspace without being told what every folder is.

The tools I tried all forced me to pick one audience:

  • Notion, Obsidian, Logseq, Anytype, OneNote, Loop, etc — Great for humans. Opaque to agents. Proprietary formats, API authentication overhead, permission nightmares.
  • Databases, APIs, structured configs — Great for machines. Hostile to humans. Try opening a SQLite dump when you need a quick answer.

The insight that cracked it: file systems are the universal interface.

But here’s the honest part: I’m writing this two weeks in. The system has 26 projects, 14 areas, and 19 resource folders — most of them migrated from years of accumulated Google Drive clutter with timestamps showing 300+ days of staleness. The monitoring scripts are running, the Grafana dashboard is live, and the first reports are coming in. But I’m not claiming it’s finished. I’m claiming it’s working, and that the pattern scales whether you have 5 folders or 50.

Let me show you what I’ve built so far, why each layer exists, and what I’ve already learned from the parts that are running.

Every OS, every agent, and every human already speaks filesystem. Folders plus plain-text manifests equals zero dependencies, zero auth, zero friction. The question was: what’s the smallest amount of structure I can add to make folders speak to agents?

The answer was 800 tokens.

But before I walk through the layers, it’s worth naming the three standards this system is built on — because I didn’t invent any of them. I just combined them.

  • AGENTS.md is an emerging convention: a single markdown file per folder that tells any AI agent “here’s what this workspace is, here’s how to navigate it.” It’s the agent’s README. The agents.md site defines the standard — one file, plain markdown, checked by every agent on entry. My system follows this exactly. No customization, no fork. Just adoption.
  • PARA (Projects, Areas, Resources, Archives) is Tiago Forte’s method for organizing digital life. I use a stock PARA folder structure with one modification: every project and area folder gets an AGENTS.md. PARA gives humans the orientation they need; AGENTS.md gives agents the same.
  • ICM (Interpretable Context Methodology) is a structured approach to multi-step agentic workflows — published research from 2025 that treats context as a layered contract rather than a prompt. I use ICM to run the content pipeline that produced this very post. The blog you’re reading was ideated, researched, composed, and published by agents running ICM stages, each with a defined context contract.

Three standards, zero lock-in. AGENTS.md for agent navigation, PARA for human organization, ICM for workflow orchestration. They don’t compete — they cover different layers of the same problem: how do humans and agents share a workspace without constant hand-holding?

Layer 0: AGENTS.md — The Full System Map

Before I could put AGENTS.md in every folder, I needed a single entry point. When Hermes starts a new session in my Google Drive root, it needs to know: what’s here, what’s worth looking at, and where do I start?

The answer is AGENTS.md at the root — one file that covers the whole topology:

~/GoogleDrive/AGENTS.md                          System map
~/GoogleDrive/projects/AGENTS.md                  Container listing (26 folders)
~/GoogleDrive/projects/<name>/AGENTS.md            Per-project manifest
~/GoogleDrive/areas/AGENTS.md                     Container listing (14 folders)
~/GoogleDrive/areas/<name>/AGENTS.md               Per-area manifest
~/GoogleDrive/resources/AGENTS.md                 Container listing (19 folders)
~/GoogleDrive/archive/AGENTS.md                   Container listing (2 folders)
~/GoogleDrive/inbox/AGENTS.md                     Container listing (1 folder)

Every level uses the same AGENTS.md format. The root file covers the big picture:

# AGENTS.md — Life OS

**Type:** Root Workspace
**Last reviewed:** 2026-05-31

## PARA Structure
| Section | Count | Detail |
|---------|-------|--------|
| [projects/](projects/AGENTS.md) | 26 | [Listing](projects/AGENTS.md) |
| [areas/](areas/AGENTS.md) | 14 | [Listing](areas/AGENTS.md) |
| [resources/](resources/AGENTS.md) | 19 | [Listing](resources/AGENTS.md) |
| [archive/](archive/AGENTS.md) | 2 | [Listing](archive/AGENTS.md) |
| [inbox/](inbox/AGENTS.md) | 1 | [Listing](inbox/AGENTS.md) |

## Routing
- Code → ~/Workspace/
- Docs → GoogleDrive PARA
- New → inbox/

An arriving agent reads one file and gets the complete system map. From there it drills into specific containers (projects/AGENTS.md for the full listing), then into individual workspaces.

I call this Layer 0 because it’s the entry point — the front door that tells an agent “here’s the system, here’s how to navigate it.”

Layer 1: AGENTS.md — The Per-Workspace Manifest

Every project and area folder has its own AGENTS.md. Resources, archive, and inbox get container-level AGENTS.md (listing their subfolders) but not per-folder manifests — they’re reference, cold storage, and transient, not workspaces.

# AGENTS.md — Blog Pipeline

**Type:** Project | **Status:** Active
**Last reviewed:** 2026-05-30

**What this is:** Automated ICM blog content pipeline.

**Key files:**
  - `01-ideation/` — Drive monitoring → blog ideas
  - `scripts/` — Automation helpers

**Relationships:**
  - [[ghost-blog-operations]]

That’s it. No JSON schema. No vector database. No GraphQL endpoint. One markdown file that an agent can read in a single request and orient itself.

I call this Layer 1 because it’s the identity layer — it sits over the system map from Layer 0 and tells agents where they are within a specific workspace. When Hermes connects to a new session, it reads the root AGENTS.md first for the big picture, then the AGENTS.md of whatever folder it lands in for the local context.

The format is deliberately minimal:

  • Type — Project (time-bound) or Area (ongoing life domain)
  • Status — Active, Paused, or Completed
  • What this is — One sentence
  • Key files — What’s in this folder and why it matters
  • Relationships — [[wikilinks]] to the knowledge wiki

Why this matters: It’s the cheapest interface I’ve ever built. One API call worth of tokens replaces an entire RAG pipeline. An agent opens the folder, reads the file, and knows where it is — no vector search, no embedding, no hallucination risk.

Layer 1: PARA — The Human Side

Under the AGENTS.md layer sits a modified PARA structure. Tiago Forte’s original PARA was designed for human knowledge workers. My version is PARA with training wheels for agents:

~/GoogleDrive/
├── projects/        # Active, time-bound deliverables
├── areas/           # Ongoing life domains
├── resources/       # Reference material
└── archive/         # Inactive

Each project and area folder gets its own AGENTS.md. Resources and archive get container-level AGENTS.md (listing their subfolders), but individual resource and archive folders don’t get per-folder manifests — only active workspaces need that level of detail.

The routing convention is what makes it work for both human and agent:

ContentGoes ToWhy
Code, builds, git~/Workspace/<project>/Each folder = its own repo
Docs, planning, research~/GoogleDrive/projects/<name>/PARA home
Life domains~/GoogleDrive/areas/<name>/Health, finance, etc.
Reference~/GoogleDrive/resources/<topic>/Read-only
Dead~/GoogleDrive/archive/Don’t delete, just move
Uncategorized~/GoogleDrive/inbox/Pending triage

An agent or human can navigate this by following the same rule: check the AGENTS.md first, know where you are, then look at the files.

Layer 2: The Wiki — Cross-References Without a Database

AGENTS.md files are local. They describe this folder, this project, this area. But concepts don’t stay in one place. The same tool — Docker, say — might appear in a project AGENTS.md (“deploys via Docker Compose”), an area AGENTS.md (“home server runs on Docker”), and a resource folder (“Dockerfile templates”). Three files, one concept. No single source of truth.

That’s what the wiki solves. It’s the cross-reference layer — a flat directory of markdown pages at ~/GoogleDrive/resources/AI/_wiki/ that links together everything the AGENTS.md files mention more than once.

_wiki/
├── SCHEMA.md      — Rules and tag taxonomy
├── index.md       — Every page listed
├── entities/      — People, tools, services
└── concepts/      — Cross-cutting ideas

The key design choice: the wiki is a cross-reference engine, not a content store. It doesn’t duplicate what’s in AGENTS.md files or project folders. It links them together. If a reference only appears in one place, it doesn’t get a wiki page — the AGENTS.md handles it.

The threshold rule: create a wiki page when an entity or concept appears in 2+ sources. This keeps the wiki sparse and useful. Every link means something.

Who uses it and when

Two audiences, two patterns:

  • Agents — When an agent reads an AGENTS.md and encounters a [[wikilink]], it resolves it against the wiki to get the full picture. For example, reading Relationships: [[hermes-agent]] triggers a wiki lookup that returns “Hermes Agent: session-based AI agent, used in blog pipeline and Life OS monitoring.” The agent now knows what that thing is without having to search the entire filesystem.

  • Humans — When I’m researching or planning, the wiki serves as a lightweight index. “What projects use my local GPU?” → search wiki for “gpu” → find the page → see every AGENTS.md that links to it.

The wiki is queried on-demand, not pre-loaded. Neither agent nor human reads the whole thing — they follow links from whatever AGENTS.md they’re looking at. The index.md serves as a table of contents when you need to browse.

How it’s maintained

Maintenance is split between the monitor layer and the agents themselves:

MechanismWhat It CatchesFrequency
Agent creates pageAgent encounters the same concept in 2+ AGENTS.md files → auto-creates wiki entryOn discovery
Monthly audit (monitor)Scans all AGENTS.md files for [[wikilinks]], reports any that point to non-existent wiki pagesMonthly
Weekly review (monitor)Checks for orphaned wiki pages — pages with no incoming [[wikilinks]] from any AGENTS.mdWeekly
Human curationRenames pages, merges duplicates, prunes stale entriesAs needed

The monitor scripts don’t fix broken links — they report them. When the monthly audit flags a [[broken-link]] with no wiki page, I get a Telegram notice and one of my agents creates the page from context. The system heals itself with human oversight, not automation.

Layer 3: .monitor/ — The Part That Doesn’t Use AI

AGENTS.md files are promises. Every AGENTS.md makes a claim: “this folder is a project called X, here are its key files, here’s what links to it.” But promises rot when nobody checks them. Folders get renamed, projects stall without their AGENTS.md being updated, files move, wikilinks break. Without a feedback loop, the system drifts — and your agents start navigating with stale maps.

That’s what .monitor/ is for. It’s the system’s immune system — a set of bash scripts running on cron that check every promise against reality and alert me when they don’t match.

The .monitor/ directory lives at the root of my Google Drive and contains:

.monitor/
├── PARA-STANDARDS.md     — The rules of the road
├── scripts/
│   ├── daily-pulse.sh    — What changed in the last 24h
│   ├── weekly-review.sh  — Staleness scan
│   └── monthly-audit.sh  — Full inventory
└── health/
    ├── daily/
    ├── weekly/
    └── monthly/

Example of a Weekly Monitor run notice via Telegram

Three bash scripts, running on cron, with zero LLM involvement. Here’s how it works:

# daily-pulse.sh (simplified)
# Scans projects/ and areas/ for changes in the last 24h
# Checks each folder for AGENTS.md presence
# Silent exit if nothing changed

# Count total folders and AGENTS.md coverage
for dir in projects/*/ areas/*/; do
  [ -d "$dir" ] || continue
  TOTAL=$((TOTAL + 1))
  [ -f "$dir/AGENTS.md" ] && WITH_AGENTS=$((WITH_AGENTS + 1))
done

# Write report with YAML frontmatter
cat > ".monitor/health/daily/$(date +%Y-%m-%d).md" <<REPORT
---
type: daily
changed_folders: $CHANGED
total_folders: $TOTAL
agents_coverage: $WITH_AGENTS
---
...
REPORT

The output format follows the same rule I applied everywhere: machine-parseable frontmatter for automation, warm 4-line summary for humans.

The daily pulse runs every weekday at 7am. If nothing changed, it exits silently — no notification noise. When something does change, I get a Telegram message like this:

☀️ Daily Pulse — 2026-05-31
Changed: 2 folder(s)
Projects: • project-alpha
✅ AGENTS.md: 4/4
📁 Report: .monitor/health/daily/2026-05-31.md

That’s it. Four lines. The full report stays in the file. No filler, no “Keep up the great work!” — just what I need to know.

Remediation: When the Monitor Finds Something

The monitor doesn’t fix things — it surfaces what needs fixing. Each alert type has a defined response:

AlertWhat HappensWho Handles It
Missing AGENTS.mdFolder exists but has no manifesto → agent can’t navigate itAgent creates one from the nearest template, flagged for review
Stale contentFolder untouched 90d+ → probably should be in archiveManual triage — is this still active?
Broken wikilink[[page]] points nowhere → agent will hit a dead endAgent searches wiki, fixes link or creates missing page
Coverage dropAGENTS.md count fell below 100% → system integrity degradedAudit what changed, restore coverage

The daily pulse flags the first two. The weekly review catches staleness. The monthly audit catches everything else. Reports accumulate in .monitor/health/ so I can track trends — is coverage improving? Are we accumulating cruft faster than we archive?

This is the one layer I trust to run without supervision. Not because the scripts are clever — they’re trivial. But because they tell me when I need to pay attention, and otherwise stay silent. That’s the hardest thing for an AI to learn: when not to speak.

The Counterintuitive Discovery: Bash > LLM for Monitoring

I didn’t start here. My first attempt used gemma4:e4b-it-q8_0 (a local LLM running on my Radeon RX 7900 XT) to summarize the monitoring data. It seemed like the obvious approach — LLMs are good at summarization, right?

The local model:

  • Hallucinated numbers — reported $3 instead of 3, dropped data points
  • Made up projects — mentioned folders that don’t exist
  • Added filler — “Keep up the great work!” when I just wanted the numbers

The irony isn’t lost on me. I was building an AI-operable system, and the AI was the worst part of it.

Bash scripts are:

  • 100% accurate — the data comes from stat, find, and grep. No interpretation layer.
  • Instant — the daily pulse runs in under 200ms
  • Free — zero GPU contention, zero API costs
  • Silent when nothing’s wrong — no “nothing to report” notifications

The lesson: use AI for what AI is good at (generation, synthesis, novel insight) and use bash for what bash is good at (data collection, monitoring, reporting). The most common mistake in AI architecture is using a language model where a shell script would do.

The Pattern Worth Stealing

The architecture here is specific to my setup, but one pattern generalizes: AGENTS.md.

One markdown file per folder. 800 tokens. Read by every agent on entry. It’s the smallest possible interface between a human and an AI agent — and it replaces an entire stack of infrastructure.

You don’t need a vector database to tell an agent where it is. You don’t need a RAG pipeline to retrieve context about a project. You need one file that says “this is what this folder is” — and a convention that every agent checks it before doing anything else.

Here’s a template you can use:

# AGENTS.md — Your Project Name

**Type:** Project | **Status:** Active
**Last reviewed:** $(date +%Y-%m-%d)

**What this is:** One sentence.

**Key files:**
  - `file.md` — What it does

**Relationships:**
  - [[related-wiki-page]]

Put one in every project folder. Tell your agent to read it on entry. Watch how much context it reclaims from your attention budget.

Build Your Own: What You Need

Reading this post won’t change your system. Giving the post to an agent might.

You need an agent harness — not a chat interface. ChatGPT and Claude’s web UI can read the theory, but they can’t create files, write bash scripts, or set up cron jobs. The monitoring layer, the AGENTS.md scaffolding, the cron schedules — these require an agent that has:

  • File system access — to create folders, write AGENTS.md files, scaffold PARA structure
  • Terminal access — to run bash, install tools, execute monitoring scripts
  • Cron/scheduler capability — to set up daily, weekly, and monthly monitor runs
  • Persistent memory — to remember conventions, wiki schema, and your preferences across sessions

I use Hermes Agent — an open-source, terminal-native agent that runs on my home server with full file system and cron access. But any agent that can execute commands and persist state will work: Claude Code, Codex CLI, or a custom setup with a local MCP server.

The Prompt

Copy this and paste it into your agent of choice:

Read the article at https://github.com/craigMull/spirit-machine-life-os-architecture-sample
and https://agents.md/ for the AGENTS.md standard.

1. Clone the sample repo: https://github.com/craigMull/spirit-machine-life-os-architecture-sample
2. Replace sample folders (project-alpha, project-beta) with my actual project names
3. Create an AGENTS.md in each project folder following the template in the article
4. Set up the .monitor/ scripts on a cron schedule
5. Create a _wiki/ directory with SCHEMA.md and index.md
6. Show me what you built before running anything

Replace the sample projects with your own. Five minutes of setup, then walk away — the monitor scripts keep the system honest from day one.

Reference

  • Sample repo — Complete Life OS structure with working monitoring scripts
  • AGENTS.md — The standard for agent-readable workspace manifests
  • PARA Method — Tiago Forte’s organization system
  • ICM Paper — Interpretable Context Methodology for multi-step agent workflows

The most surprising lesson from building this system? The AI agent helped design the logo, the monitoring system runs on bash, and the blog about both is being published by another agent. That’s the spirit of the machine — not replacing humans, but making the interface between us and our systems invisible.

Now go give your agent something to read.