Filesystem-First AI Agent OS for Cursor and Claude Code

Most developers use coding agents one repo at a time, starting every chat from zero. By the third session of the week, you're repeating the same instructions: don't start Docker without asking, use rg instead of grep, keep answers concise, and check the build before claiming a fix works.

To stop repeating myself, I built agent-os (case study)—an open-source, filesystem-first personal operating system for Cursor and Claude Code that sits above my code repositories.

Why prompt libraries fail (and filesystems win)

Saving prompts in Notion or a browser extension doesn't help an agent that lives inside your terminal and editor. Coding agents are native to the filesystem: they already know how to read Markdown, grep directories, and edit files in place.

When your operating system is just a folder of plain-text Markdown files with strict boundaries, the agent can read your context and update its own rules whenever you correct it.

agent-os/
├── AGENTS.md                        # Root entrypoint & operating rules
├── memory.md                        # Self-updating learned rules (updated on every correction)
├── todo.md                          # Living inbox (Now <= 5 items + project sections)
├── context/                         # Stable identity (who we are — not research dumps)
│   ├── about-me.md
│   └── tools-stack.md
├── research/                        # Three-layer knowledge base (index -> log -> canonical)
│   ├── README.md
│   ├── index.md
│   └── logs/_template.md
└── .cursor/
    ├── rules/personal-os.mdc        # Always-applied workspace rule
    └── skills/                      # Repeatable SOPs invoked via /skill-name

1. The memory.md correction loop

The highest-leverage file in the entire workspace is memory.md. In AGENTS.md and .cursor/rules/personal-os.mdc, the agent has one standing instruction:

Before every task: Read memory.md for learned preferences and corrections.
When I correct you: Add a clear, one-line rule to memory.md under Learned rules immediately.

Here is what memory.md looks like in practice:

# Memory — learned rules and preferences

## Learned rules

- Keep replies concise by default — answer first, a few lines max.
- Prefer `npm run lint` and `npm run build` for validation before claiming completion.
- Do not start local Docker database stacks unless explicitly asked.
- On git repos: leave changes uncommitted unless explicitly asked to commit and push.

Instead of tweaking a system prompt manually, the workspace learns organically from real mistakes during daily work.

2. Separating stable identity (context/) from learning (research/)

The fastest way to ruin an agent workspace is to dump every meeting note, benchmark, and article summary into one folder. Within a month, the agent is reading 40,000 tokens of stale notes on every turn.

agent-os enforces a hard split:

Directory	Purpose	Lifespan
context/	Stable identity: stack, architecture preferences, active repos	Rarely changes
research/index.md	One-row-per-study catalog of dated investigations	Read first to locate logs
research/logs/YYYY-MM-DD-slug.md	Point-in-time deep dives, benchmarks, and tool evaluations	Read on demand
.cursor/skills/<name>/SKILL.md	Proven workflows promoted out of research logs	Invoked via /skill-name

Because context/ stays lean, the agent loads only the identity files relevant to the current task and looks up research/index.md only when it needs historical data.

3. Pairing agent-os with terminal & Git automation

An agent workspace works best when the underlying shell and Git setup don't get in the way. Alongside agent-os, I open-sourced two companion repos:

• dotfiles: My single-file Neovim config (init.lua), sub-30ms Zsh prompt, and a .gitconfig that uses Git's includeIf "hasconfig:remote.*.url:..." to automatically switch my commit author and SSH/HTTPS credentials based on the repository's GitHub remote URL.
• porthog: A zero-dependency macOS CLI wrapper around lsof, ps, and launchctl that prints which repository working directory (cwd) and launchd service owns a listening TCP port before freeing it.

Takeaway

You don't need a heavy orchestration framework to give coding agents long-term memory. Clone zaynelovecraft/agent-os, wire up AGENTS.md and memory.md, and let your workspace compound every time you correct your agent. For more on the tools I pair with this setup, read Top 10 AI Tools to Build With Today.