Where this page fits
Three docs cover the same territory at different depths. Use whichever matches your moment:
🧭 Cheat-Sheet
Everyday overview — how the system runs, lanes, daily flow, memory. Read first if you're new.
🛡️ Recovery Guide (this page)
Scenario deep-dives — Claude down / GitHub down / NAS dies / M4 dies / nuclear option. The encyclopedia.
⚡ CONTINGENCY.md + ops/
The actual scripts — ops/swap-llm.sh + validate + swap-back. The 30-second operational runbook.
2026-05-15 update
Two material changes since this page was first written on Apr 24:
(1) Linq retired and Aria absorbed the COO role on 2026-05-15 (OPS-45). The agents/linq/ folder is archived to aspire-digital/agents/_archived/linq/ with a backward-compat symlink. Where this page says "Linq is the COO," read "Aria is the COO" — the recovery procedure is identical.
(2) AGENTS.md became the open standard for AI-agent project instructions (adopted by Codex, Cursor in agent mode, Gemini CLI, Windsurf, Copilot, and most agentic tools). This collapsed the per-tool rename complexity — one symlink covers most providers. See Section 10 below for the current table.
1. How It All Works — The Simple Version
Explain-it-like-I'm-in-5th-grade version
The Binder Analogy
Imagine you have a team of really smart employees. Each one is an expert on your life and business — they know your priorities, your people, your history, your preferences. What makes them smart isn't which company they work for. It's the binder of notes they carry about you.
Your binder is made of plain text files — markdown files — living in folders on a computer. That's it. No magic database. No proprietary format. Just readable files, like digital notebooks. Any smart AI assistant can open those files and instantly be "your" assistant.
Claude Code is the office building where your employees work right now. If that building locked its doors tomorrow, you'd grab your binders, walk to a new office building (there are several), hand over the binders, and your employees would be back up to speed within minutes.
The building never held anything your employees knew. The binders are everything. And you have the binders in three places.
The Binders (your repos)
Plain text markdown files. Everything Aria and the specialists know about you. The agent's identity, memory, and instructions are all in these files. No vendor lock-in — any AI can read them.
The Employees (agents)
Aria (your Chief of Staff AND Aspire COO since 2026-05-15), Vegas (web builder), Sahara, Paris, Circa, Strat. Each has a CLAUDE.md instruction set + identity files + memory files. The AI model just executes — the files define who they are.
The Office Building (tool)
Currently Claude Code (Anthropic). The tool that runs the agents and lets them read/write files. Replaceable with Cursor, OpenAI Codex CLI, Gemini CLI, or local tools running on your M3. The building is not the brain.
The key insight: CLAUDE.md is the agent's soul
When you open Claude Code and point it at ~/projects/aria-secondbrain, the first thing it reads is CLAUDE.md. That file says: "You are Aria. Here's your identity, your mission, how you work, and where your memory lives." A generic GPT-4 or Gemini model reading that same file becomes Aria just as effectively. The model is the engine. CLAUDE.md is the steering wheel.
2. How the Binder Is Organized — The 4 Layers
The structure inside every agent's memory — and the order to load it on a cold start
Why layers exist
Every line in an auto-loaded file gets paid for on every conversation turn. Stuffing the binder with reference material looks cheap but compounds into a real recurring tax. Layers separate what genuinely must be in every prompt from what can be pulled only when needed.
Authored 2026-04-24 during a doctrine pass that cut aspire-clients' CLAUDE.md from 373 → 113 lines (~70% reduction). The pattern was already in place across Aria and the specialists — the doctrine just gave it a name.
| Layer | Size target | Load timing | Contents | Update frequency |
|---|---|---|---|---|
| 1 — Sticky notes | ~2K chars | Every prompt | Compact facts, hostnames, paths, commands | Rare |
| 2 — Identity + rules | ~4K chars | Every prompt | Persona, hard don'ts, mandatory logging | Occasional |
| 3 — Vault | Unlimited | On demand | Project state, lanes, clients, decisions | Frequent |
| 4 — Session archive | Unlimited | Never auto; searched | Dated session journals, daily audits | Append-only |
Where each layer lives in Aria
Layer 1 + 2 — auto-loaded
aria-secondbrain/CLAUDE.md— facts + rules merged (doctrine permits)agents/aria/IDENTITY.md— personaagents/aria/SOUL.md— vibe, boundariesagents/aria/LANES.md— lane registry
CLAUDE.md is harness-loaded every prompt; IDENTITY/SOUL/LANES are loaded on cold start via pointer in CLAUDE.md to keep token cost low.
Layer 3 — on-demand vault
memory/MEMORY.md— index of everythingmemory/NEXT.md— session handoffmemory/topher/— profile, preferences, feedbackmemory/drawers/<lane>/— per-lane statememory/people/,memory/tools/
Read on demand — only the files relevant to the current conversation.
Layer 4 — never auto-loaded
memory/sessions/aria/— curated multi-hour session journals + INDEX.mdmemory/daily/— cron-generated morning audits, overnight scans
Append-only history. Searched when something asks "what did we do about X last week?" — never warmed up at session start.
Cold-start contract
When you boot a fresh agent (new tool, new machine, post-doomsday rebuild), this is the order:
- Tool reads
CLAUDE.mdautomatically — Layer 1 + base of Layer 2. - CLAUDE.md instructs it to load
agents/aria/IDENTITY.md+SOUL.md+LANES.md— completes Layer 2. memory/NEXT.md→memory/MEMORY.md→ relevant lane files — Layer 3 entry.- Layer 4 only when something explicitly asks for history.
Where this is canonical
- Doctrine:
~/.claude/projects/-Users-tophermacstudio/memory/ARCHITECTURE.md - Aria's local mirror:
memory/ARIA-LAYERS.md - Human playbook: playbook.madebyaspire.com/agents/ → "Memory architecture — the 4-layer system"
3. What You Own — The Full Inventory
Every repo, every agent, and what lives where
What's inside:
- CLAUDE.md — Aria's instruction set (the soul)
- agents/aria/ — IDENTITY, SOUL, LANES files
- memory/ — Every memory file (~80+ files)
- memory/NEXT.md — Session handoff (most critical)
- memory/sessions/ — Full session journal
- sites/command-center/ — cc.madebyotten.com source
- ops/ — Launchd jobs, reaper scripts
If this repo disappeared:
You'd lose Aria's personality, 6+ weeks of accumulated memory, your entire personal life context, and the Command Center source. This is the most critical repo. It lives in 3 places — GitHub, NAS Gitea (port 3030), and ~/projects/aria-secondbrain on your M4.
What's inside:
- CLAUDE.md — Master Aspire instruction set
- ASPIRE.md — Canonical operating doctrine
- agents/vegas/ — Vegas's working context (website builds)
- agents/sahara/ — Sahara (Shopify)
- agents/paris/ — Paris (research/briefs)
- agents/circa/ — Circa (CRM/GHL)
- agents/strat/ — Strat (SEO)
- agents/_archived/linq/ — retired 2026-05-15, kept for COO doctrine reference
- playbook/ — playbook.madebyaspire.com source
Five specialists + Aria as COO:
Aria 🤖 (COO, Opus 4.7 — runs the agency from ~/projects/aria-secondbrain), Vegas 🎰 (builder, Sonnet 4.6), Sahara 🏜️ (Shopify, Sonnet 4.6), Paris 🗼 (research, Opus 4.6), Circa ⚙️ (CRM, Sonnet 4.6), Strat 🎰 (SEO, Opus 4.6). Each specialist is a folder with identity files + memory. Same pattern as Aria.
Linq retired 2026-05-15. Aria absorbed the COO role + full playbook authority. Same human (Topher), one chat to open in the morning. Linq's identity files preserved at agents/_archived/linq/ with backward-compat symlink at the original path. See OPS-45.
Vegas builds and deploys here. Every client site (Patina, NRX, Tees Flooring, Keeler Carpentry, PetalsWings, Paved By Infiniti, etc.) lives as a subfolder. The shared component library lives at shared/components/. Also mirrored to NAS Gitea.
12 more repos on Gitea (client production sites, tools)
4. Your Three-Layer Backup
All 15 repos exist in three independent locations simultaneously
Layer 1 — GitHub
Cloud primary
- github.com/tophermacstudio
- Private repos, your account
- 15 repos total
- Every push from M4 lands here
If GitHub disappeared: NAS Gitea has everything. See Layer 2.
Layer 2 — NAS Gitea
Home server mirror — confirmed live
- 192.168.5.230:3030 (local)
- 100.108.188.47:3030 (Tailscale)
- All 15 repos auto-mirroring
- Syncs hourly from GitHub
- Confirmed active — verified April 22
Your home filing cabinet. Physical backup that GitHub can never touch.
Layer 3 — M4 Local
Working copies on disk
- ~/projects/aria-secondbrain
- ~/projects/aspire-digital
- ~/projects/aspire-clients
- Live working copies
- Pushed to GitHub after every session
The desk copy. If the M4 dies, GitHub + NAS are unaffected.
The math on losing everything
To lose your brain entirely, you'd need to simultaneously lose your GitHub account AND have your NAS physically destroyed AND lose your M4 local disk — at the same time, with no warning to push a backup. That's losing cloud, home hardware, and primary machine simultaneously. For practical purposes: your repos are permanent. The risk isn't data loss. The risk is access — which is what this guide addresses.
5. If Claude Code / Anthropic Disappears
The scenario you were worried about — this is the full answer
Bottom line first: your data is completely safe
Claude Code stores nothing. It's a terminal application that reads and writes files on your computer, in your repos. When Anthropic's servers go dark, your M4 still has every file. GitHub still has every repo. NAS Gitea still has every mirror. You lose the tool, not the brain.
⚡ The 30-second swap (shipped 2026-05-15 as OPS-47)
The manual steps below are the conceptual recovery. For the operational version that does it in one command, three scripts are now in aria-secondbrain/ops/:
./ops/swap-llm.sh codex|cursor|gemini|all— creates symlinks (AGENTS.md → CLAUDE.mdas the open standard, plus per-tool extras)./ops/validate-swap.sh— verifies symlinks resolve + content matches before launching the new tool./ops/swap-back-to-claude.sh— clean reverse when Claude Code returns
Full runbook at aria-secondbrain/CONTINGENCY.md (lives next to CLAUDE.md so any LLM auto-discovers it). The steps below give you the conceptual framing; the scripts give you the execution.
Step-by-step recovery (conceptual — for the operational shortcut, see callout above):
Install a replacement tool (see table below)
Best options: Cursor (IDE-based, supports GPT-4 and Claude), OpenAI Codex CLI (terminal-based, nearly identical workflow to Claude Code), or Gemini CLI (Google's equivalent). All three can read your project files and run shell commands.
Open the tool at the right project directory
Point it at ~/projects/aria-secondbrain for Aria (the COO + Chief of Staff), or ~/projects/aspire-digital for agency-specific work the specialists need. Each of these has a CLAUDE.md (or equivalent config file) that the new tool reads on startup.
Symlink CLAUDE.md to the new tool's expected name
AGENTS.md is now an open standard (adopted by Codex, Cursor agent mode, Gemini CLI, Windsurf, Copilot in 2025-2026). A single symlink (ln -snf CLAUDE.md AGENTS.md) covers most providers. Gemini also wants GEMINI.md; Cursor's agent mode wants a .cursor/rules/*.mdc file with alwaysApply: true. The ops/swap-llm.sh script does all of this idempotently — see the callout above. Content stays at CLAUDE.md; everything else is a symlink.
Cold-start the agent with the same boot prompt
The same cold-start instructions you use today still work: "Load IDENTITY.md, SOUL.md, NEXT.md, MEMORY.md" — the new AI reads these files and becomes Aria. Memory, context, open loops — all intact. It's a different voice reading the same binder.
Re-wire your cron jobs and launchd triggers
The morning briefing and email triage crons call the claude binary. If you switch tools, update the launchd plists in ~/Library/LaunchAgents/ to call the new binary. Scripts are in ops/ in the repo.
The nuclear-free option: fully local with no internet
Your M3 Ultra (100.88.33.54 via Tailscale, 96GB RAM) runs Ollama with local LLMs. The SyF Second Brain local pilot stack was paused for compliance reasons, but the infrastructure exists. If every cloud AI provider disappeared, you could run a capable open-source model (Llama 3, Qwen, etc.) on the M3, point it at your repos via Continue (a VS Code extension) or Open WebUI, and your agents would still function — fully private, zero internet dependency. Setup time: ~2 hours.
6. If GitHub Goes Dark
Or your account gets banned, suspended, or compromised
You're fine. NAS Gitea is a full live mirror.
Confirmed April 22, 2026: all 15 repos are actively syncing to your NAS (UGreen DH4300 Plus at 192.168.5.230). Gitea shows sync activity within minutes of every push. This is not a cold backup — it's a live mirror.
Recovery steps:
Your M4 local copies are unaffected. GitHub going down doesn't touch ~/projects/. Keep working — just don't try to push until step 3.
Repoint remotes to NAS Gitea. From any repo: git remote set-url origin http://192.168.5.230:3030/TopherOtten/[repo-name].git. Or over Tailscale: http://100.108.188.47:3030/TopherOtten/[repo-name].git. Push and pull work immediately.
Create a new GitHub account if needed. Push from NAS Gitea to the new GitHub: git push new-origin main. The full git history travels with it — every commit, every date, everything intact.
Update Cloudflare Pages deploy hooks. cc.madebyotten.com deploys from GitHub. Once the new repo is up, reconnect Cloudflare Pages in the CF dashboard to point at the new repo. 5 minutes.
7. If Your NAS Fails
Hardware dies, drive fails, Docker fleet goes down
Low severity. GitHub is the primary.
The NAS is a backup and infrastructure host (Docker fleet: AdGuard, asset server, Crawl4AI, Homebridge). If it goes down, your repos are 100% intact on GitHub and M4 local. You lose: AdGuard DNS (eero falls back to 1.1.1.2), the asset server, Crawl4AI, and the Gitea mirror. The agents keep working. The Command Center keeps deploying.
What breaks: DNS rewrites, local web crawling, asset serving, Gitea mirror temporarily offline.
What's fine: All repos, all agents, Command Center, Cloudflare deploys, MCP tools, email triage crons.
Recovery: Replace/restore NAS hardware, redeploy the 8 Docker containers from the docker-compose configs in memory (or rebuild from scratch — the containers are all standard images). Gitea re-mirrors from GitHub automatically once it's back up.
8. If Your M4 Mac Studio Dies
Hardware failure, theft, or you just need to work from another machine
Everything is in GitHub. You're not stuck.
The M4 is the execution machine — it runs the agents, hosts the daemons, handles cron jobs. But it stores nothing that isn't also in GitHub. If it dies, you clone onto any replacement Mac and you're operational within an hour.
Full recovery on a new machine:
Install Claude Code: npm install -g @anthropic-ai/claude-code
Clone repos: git clone https://github.com/tophermacstudio/aria-secondbrain ~/projects/aria-secondbrain (and aspire-digital, aspire-clients)
Authenticate: claude → log in with your Anthropic account. MCP tools reconnect from ~/.claude/settings.json (restore from 1Password or NAS backup).
Reinstall launchd cron jobs from ops/ directory in the repo. Copy plists to ~/Library/LaunchAgents/ and load them.
Open ~/projects/aria-secondbrain in Claude Code and boot Aria. She reads NEXT.md and is instantly caught up.
Estimated time to full recovery on new hardware: ~60-90 minutes including git clone, Claude Code install, auth, and MCP setup.
9. Nuclear Option — Starting Completely From Zero
Lost everything: GitHub + NAS + M4 simultaneously. Here's what you still have.
This requires losing three independent systems at once.
You'd need to lose GitHub (cloud), your NAS (physical hardware at home), AND all M4 local files (your Mac's internal SSD) simultaneously, with no warning to push anything. This is effectively impossible in practice — but if it happened:
What you still have (non-repo):
- ✅ cc.madebyotten.com — still live on Cloudflare CDN. Your Command Center is deployed and cached — viewable even if the source repo is gone.
- ✅ All deployed client sites — live on Cloudflare. Client work is safe regardless.
- ✅ 1Password vault — all credentials, API keys, and access details. The key to rebuilding everything else.
- ✅ Your own memory — you know the architecture. This page describes how to rebuild it.
Rebuild order:
New GitHub account → new repos (aria-secondbrain, aspire-digital, aspire-clients)
Re-create agent identity files (CLAUDE.md, IDENTITY.md, SOUL.md) — the patterns are in your head and documented here
Run a fresh profile interview with a new Aria instance — she'll rebuild memory files from your answers (same process used in April 2026)
Re-setup NAS Docker fleet — standard containers, no custom images needed
Reconnect Cloudflare Pages to new repo → Command Center redeploys
Estimated rebuild time: 2-4 days of active sessions to reach operational parity. The architecture is the intellectual property — and you own that.
10. Alternative Tools — If Claude Code Goes Away
Every viable replacement, ranked by how close they are to the Claude Code experience
| Tool | Provider | Type | Config File | Notes |
|---|---|---|---|---|
| OpenAI Codex CLI | OpenAI | Terminal agent | AGENTS.md | Most similar to Claude Code in workflow. Terminal-based, reads project files, runs shell commands. AGENTS.md is the open standard. 32 KiB cap. Run ops/swap-llm.sh codex. |
| Cursor (agent mode) | Cursor AI | IDE (VS Code fork) | .cursor/rules/*.mdc | Modern Cursor uses .cursor/rules/*.mdc with frontmatter (legacy .cursorrules is NOT loaded in agent mode — critical detail). Run ops/swap-llm.sh cursor to create the MDC pointer. |
| Gemini CLI | Terminal agent | GEMINI.md | Google's Claude Code equivalent. Terminal-based. Hierarchical context (~/.gemini/GEMINI.md global + project + ancestors). Supports @file.md imports. Run ops/swap-llm.sh gemini. | |
| Windsurf | Codeium | IDE (VS Code fork) | AGENTS.md | Another IDE option. Adopted the AGENTS.md open standard, so the same symlink as Codex covers it. Good fallback if Cursor also has issues. |
| Ollama + Continue / Aider | Open source | Local LLM + IDE/CLI | AGENTS.md / CONVENTIONS.md | Fully local. M3 Ultra (96GB RAM) already has Ollama. Continue (VS Code extension) and Aider (CLI) both work with whatever model you plug in. Zero internet, zero cost, fully private. Slower but completely independent. Aider also accepts --read CLAUDE.md directly. |
The symlink rule (updated 2026-05-15)
AGENTS.md became an open standard in 2025-2026. One symlink (ln -snf CLAUDE.md AGENTS.md) covers Codex, Cursor agent mode, Gemini CLI, Windsurf, Copilot, and most other agentic tools. Per-tool extras only where insisted on (Gemini's GEMINI.md, Cursor's .cursor/rules/aria.mdc).
Don't copy — symlink. Edits to CLAUDE.md propagate immediately, no drift. The ops/swap-llm.sh script does this idempotently and includes validate-swap.sh to byte-compare the resolved content to CLAUDE.md.
11. Quick Reference Card
Everything you'd need in an emergency, in one place
Repos
GitHub: github.com/tophermacstudio/aria-secondbrain
GitHub: github.com/tophermacstudio/aspire-digital
GitHub: github.com/tophermacstudio/aspire-clients
NAS local: 192.168.5.230:3030 (Gitea)
NAS Tailscale: 100.108.188.47:3030 (Gitea)
Agent Config Files
Aria soul: aria-secondbrain/CLAUDE.md
Aria identity: agents/aria/IDENTITY.md + SOUL.md + LANES.md
Aria memory: memory/NEXT.md → memory/MEMORY.md
Agency doctrine: aspire-digital/CLAUDE.md + ASPIRE.md
Vegas context: agents/vegas/working.md
Linq (retired): agents/_archived/linq/AGENTS.md ← Aria reads on demand for COO doctrine
Contingency: aria-secondbrain/CONTINGENCY.md + ops/swap-llm.sh
Local Paths on M4
~/projects/aria-secondbrain
~/projects/aspire-digital
~/projects/aspire-clients
~/projects/shared-skills
~/.claude/settings.json (permissions + MCP)
~/Library/LaunchAgents/ (cron jobs)
Key Infrastructure
M4 Mac Studio — agent execution, always-on
M3 Ultra — local LLMs at 100.88.33.54:11434
NAS — Gitea mirror + Docker fleet at 192.168.5.230
Cloudflare — hosting for cc.madebyotten.com + all client sites
1Password — master credential vault
Tailscale — private network bridging all machines
The One-Sentence Version
Your AI brain is plain text files in git repos, stored in three independent places — if any one component disappears, the other two carry everything, and any capable AI tool (not just Claude) can pick up where you left off.