Architecture Reference

How the system works. Read this if you want to understand what you're building, not just build it.

The Core Idea

Most AI assistants forget everything between sessions. You tell them about your team on Monday, and by Wednesday they're asking "who's Jake?" again. This system fixes that with a simple principle: the workspace is the memory.

Every session, the assistant reads a set of files. Those files contain its identity, your profile, its operational rules, and everything it has learned. When it learns something new, it writes it to a file. When it wakes up next time, it reads that file. No magic. No embeddings database (though you can add one). Just files.

The File Hierarchy

Files are read in a specific order at the start of every session. This order matters — earlier files establish context for later ones.

1. SOUL.md       → Who the assistant is. Personality. Directives. Boundaries.
2. USER.md       → Who you are. Organizations. Accounts. Preferences.
3. MEMORY.md     → What it remembers. Institutional knowledge. Lessons learned.
4. AGENTS.md     → How it operates. Capture rules. Classification. Reporting.
5. SCHEMAS.md    → File templates. Loaded on-demand, not at boot.
6. TOOLS.md      → Environment notes. Device names, SSH hosts, etc.

SOUL.md and USER.md are relatively static — they change when your role or preferences change. MEMORY.md grows over time. AGENTS.md is your operating manual — you'll refine it as you learn what works.

The Capture Framework

The system's main capability is capturing — classifying information into six categories and filing it persistently.

The Six Categories

Why These Six?

These categories cover the complete lifecycle of professional information:

• Questions catch open loops. Every unanswered question is cognitive overhead. Tracking them means nothing festers.
• Decisions catch choices and their rationale. Three months from now, when someone asks "why did we do this?", the decision capture has the answer.
• Tasks catch work. This is the most obvious category, but most people only track tasks — the other five are what make this system different.
• Commitments catch promises. This is the category most people miss entirely. When someone says "I'll send that over," that's a commitment. Tracking both directions (what you promised, what was promised to you) prevents the most painful failures — broken promises you didn't even realize were promises.
• Context catches knowledge. Things that aren't actionable but are important to know. A client's communication preference. A system's quirk. Background that makes future decisions better.
• Projects provide structure. Without projects, captures are a flat list. Projects group related captures and give them meaning.

Classification Priority

When something could be multiple categories, classify in this order:

1. Someone promised something → Commitment
2. Work someone needs to do → Task
3. Choice was made → Decision
4. Someone waiting for an answer → Question
5. Useful knowledge, no action → Context

Commitments take priority because they're the most dangerous to miss. A forgotten task is annoying. A broken promise damages relationships.

Dual Classification

Sometimes something is both a commitment and a task. Example: "I'll build that report by Friday." That's a commitment (you promised) AND a task (work to do). Create both. Link them. The commitment tracks whether the promise was kept. The task tracks the actual work.

File Naming and Location

Every capture gets a unique ID: [PREFIX]-YYYYMMDD-NNN

The sequence number (NNN) resets daily and is tracked in _sequence.md.

Captures live in one of two places:

• projects/[name]/[category]/ — if the capture belongs to a known project
• captures/[category]/ — if it's an orphan (no project yet)

Orphans can be moved to a project later. The important thing is to capture first, organize second.

Indexes

Every project directory and the captures/ directory has an _index.md — a table of all open items and recently closed items.

Indexes are the primary query surface. When the assistant answers "what's going on with Project X?", it reads the index first, not every individual file. This makes queries fast and keeps the system scalable.

Index rules:

• Updated on every capture create, modify, or close
• Open items sorted by date, newest first
• Recently closed items stay 30 days, then leave the index (files remain permanently)
• Long indexes = too many open items — the assistant should flag this

Person Files

People who appear in captures get their own files under people/. The directory structure mirrors the relationship:

people/
├── employees/           # Your team members
├── clients/
│   └── [company-slug]/  # Grouped by company
│       ├── _client.md   # Company-level file
│       └── [person].md  # Individual contacts
├── vendors/
│   └── [company-slug]/  # Grouped by company
└── leads/               # Prospects, not yet clients

Person files track:

• Who they are — title, contact info, timezone
• Active items — open captures involving them (auto-updated)
• Working style — observations about how they communicate and work (grows over time)
• History — notable events, not a log of every interaction
• Performance signals — only for people you manage, only if you want this

Person files are created automatically when a new name appears in captures. The assistant tells you when it creates one.

Memory

MEMORY.md is institutional knowledge — things the assistant has learned that should persist. It's an index with pointers to individual memory files in the memory/ directory.

Memory is NOT:

• A log (that's session-log)
• Task tracking (that's captures)
• Person-specific knowledge (that's person files)
• Project status (that's project indexes)

Memory IS:

• User preferences that aren't in SOUL.md
• Organizational facts that aren't obvious from the code/files
• Lessons learned from mistakes
• Terminology definitions
• Ongoing threads that span multiple sessions

Memory is capped at 300 lines in the index file. Older or less-referenced entries get archived.

Reporting

The assistant proactively reports on the state of your world. The default rhythm:

• Morning briefing (daily): What's on fire, what's due today, what's stale, what's new
• Weekly summary: Performance signals, project health, orphan cleanup, stale items
• On-demand queries: "What's going on with [project]?", "How is [person] doing?", "What needs my attention?"

Reporting is fully customizable. You can change the cadence, content, and format. Some people want daily briefings. Some want weekly. Some want nothing unless something's wrong.

Making It Always-On

Everything so far describes an assistant you talk to in a terminal: you open your AI tool in the workspace, it reads its files, you work, it writes down what it learned. That alone is a complete, useful assistant - many people never need more.

But the version that triages your email before you wake up, pings your phone when something's urgent, and runs a morning briefing on a schedule needs one more thing: a way to keep running when you're not at the keyboard. There are two paths, and neither is required to start.

The lightweight path — a scheduler and a few scripts. This is how the original Bob runs. The pieces are ordinary:

• A session multiplexer (like tmux) hosts the assistant's live sessions and survives your terminal closing.
• A scheduler (cron, or launchd on macOS, or systemd timers on Linux) wakes the assistant on a heartbeat — every 15 minutes, every morning, whatever you set.
• A few small scripts handle the edges: one to send you a message (a dozen lines hitting the Telegram API), one to receive replies, one to kick off a triage run.

No gateway, no daemon, no platform to adopt. If you can write a cron job and a short script, you can make an assistant always-on. This is the honest minimum, and it's genuinely enough.

The turnkey path — a gateway. If you'd rather not assemble the glue yourself, an open-source gateway like OpenClaw packages it: multi-channel messaging (Telegram, Slack, WhatsApp, and more), background processing, multi-agent routing, and phone access — configured rather than hand-built. Same capability as the lightweight path, traded for less assembly. Use it if it saves you time; skip it if you'd rather keep the stack thin.

What powers the reasoning, either way: an AI runtime like Claude Code or Codex CLI for file and terminal work, backed by an LLM (Claude, GPT, or a local model via Ollama). You can route different work to different models by cost and capability — or just start with one.

The point stands: the assistant is the files and the framework. Always-on is a deployment choice you layer on once the assistant has proven it's worth waking up on its own.

Multi-Instance (Advanced)

If you run your assistant as several instances at once — multiple sessions, multiple machines, or multiple AI tools — you need multi-instance sync. This adds:

• Instance registry — which instances exist, what model they use, what sequence range they own
• Session log — append-only ledger of what each instance did
• Sequence partitioning — each instance gets a range of sequence numbers so they can't collide
• Lock protocol — lightweight file-level locking for concurrent access
• Delegation protocol — one instance can assign work to another

Most people don't need this. If you use one AI tool, skip it entirely.

The Trust Model

The assistant operates on a two-tier trust model:

Internal actions (high autonomy):

• Reading anything
• Creating and updating captures
• Maintaining indexes
• Creating person files
• Organizing the workspace
• Running scheduled operations

These happen silently. The assistant tells you what it did, but doesn't ask permission.

External actions (zero autonomy without approval):

• Sending any message (email, Slack, text)
• Modifying calendar events
• Posting anything public
• Taking any action that affects other people
• Making purchases

These ALWAYS require showing you exactly what will be sent/done and getting explicit "yes."

The boundary is clear: anything that stays inside your workspace is fair game. Anything that touches the outside world needs your approval. You can move specific actions across this boundary as you build trust.

Naming

Two names are central to every instance:

The assistant name. Your assistant has a personality and needs a name. "Bob" is taken (that's the original, built at Airtight Design). Pick something you'll be comfortable saying every day. This name is used in SOUL.md, CLAUDE.md, and throughout the framework.

The framework name. The operational system (captures, indexes, person files, the whole workspace) needs a name. The default is "the Matrix", which is what we call ours at Airtight Design. You can keep it or pick your own. This name is used in AGENTS.md headers, documentation, and conversational references. It gives the system identity beyond "the files."

Both names are chosen during the Discovery phase and used consistently throughout all generated files.

When the Framework Doesn't Fit

The framework is designed to be changed. When it stops fitting, you don't work around it — you edit it. Everything that governs the assistant lives in plain files you control: AGENTS.md (the rules), SOUL.md (the personality), SCHEMAS.md (the shapes). No part of it is locked.

Signs it's the framework, not you:

• The assistant can't resolve a classification even after the rules in AGENTS.md are correct — the rules probably don't cover this case yet
• You keep hitting the same limitation
• A recurring correction suggests a rule is missing or too weak
• Something feels broken or contradictory when you read it back

What to do about it: change the rule. Add the classification trigger. Sharpen the urgency definition. Adjust a schema. Your assistant can do most of this for you — tell it what's not working and ask it to propose an edit to the relevant file, then review it. This is the normal maintenance loop, not a failure state. The system gets sharper every time you tune it, and the only authority on how it should work for you is you.

Grep Over Greenfield

Before your assistant builds something new, have it search for what already exists - and extend that instead of starting over.

("Grep" is developer shorthand for "search through your files." The principle is older than the jargon: look before you build.)

The fastest way to turn a tidy assistant into a messy one is to let it solve the same problem twice. Ask it to handle something new and, left unchecked, it will cheerfully invent a fresh way to do a job your system already does - a second place to file notes, a second way to name things, a second format for the same report. Now the same information lives in two shapes, and every search, every briefing, every future change has to account for both. Nothing is technically broken. It's just that half of what you're looking for is filed under a convention you forgot you had.

AI makes this trap easier to fall into, not harder. When producing a plausible new approach takes seconds, it's faster for the assistant to reinvent than to go find the thing that already exists. So it reinvents - unless you tell it not to.

The fix is a habit, not a feature: any time your assistant is about to add something new to how the system works, it searches the workspace first. If a pattern already exists, the job becomes "extend that" instead of "build another one." One way to track tasks, not three. One naming scheme, not a drawer full of them.

Here's the everyday version. Say your assistant already files promises as Commitments. A week later you ask it to "keep an eye on follow-ups," and it spins up a brand-new follow-ups list, separate from the commitments it's already tracking. Two systems for one job. The follow-up you're chasing is in whichever one you didn't check. Had it searched first, it would have seen that a follow-up is just a Commitment with a due date and extended what was already there.

Bake the rule into your AGENTS.md so it runs every session:

Grep before greenfield. Before building anything new into how the system works - a new way to file, track, name, or report - search the existing files first. If something already handles it, extend it. Don't start a parallel version.

Adding something new to your system has never been easier. Living with it has never gotten easier at all. This one habit is what keeps the second cost from quietly swallowing the first - the difference between a system that gets sharper as it grows and one that slowly turns into a pile you stop trusting.

Evolution

The system is designed to evolve:

• Week 1: The assistant learns your people, projects, and patterns. Expect lots of corrections.
• Month 1: The assistant has useful institutional memory. Classifications are mostly right. Briefings are genuinely helpful.
• Month 3+: The assistant knows things you've forgotten. It catches commitments you didn't realize you made. It flags problems before they become crises.

The captures accumulate. The memory deepens. The person files get richer. The system becomes more valuable the longer you use it — not because the AI gets smarter, but because the workspace gets smarter.

This is a reference document. You don't need to memorize it. Your AGENTS.md file will contain all the operational rules your assistant needs.