Shadman's AI Operating System: Architecture Map v5.3

01 · Data Sources

Meeting Memory (Granola)

Meeting transcripts, summaries, action items

hourly

→ trace flow

Reads into

Obsidian vault via granola-obsidian-sync. Fan-out to _scratch/granola/ staging by granola_ingest.sh (hourly LaunchAgent), then 2 active per-meeting sinks: sink_post_meeting.sh (updates _product-brain PPP, Sonnet, 240s watchdog), sink_people_sync.sh (writes memory/people_*.md, Sonnet, 180s watchdog).

Work context (Confluence)

Work wiki, team docs, project pages

hourly weekdays

→ trace flow

Reads into

Obsidian vault via confluence-obsidian-sync. Used as RAG source by ask/recall router intent.

Calendar & Inbox (Microsoft 365)

Outlook calendar, email, Teams messages

06:30 + pre-cache 3x

→ trace flow

Cache written to

_work/pm-workspace/.cache/calendar-YYYY-MM-DD.json. Read by morning digest + midday ping.

Code & PRs (GitHub)

PRs, CI status, work tickets, review requests

on demand

Access via

gh CLI with Keystone SSO auth. No live cron feed. Queried on demand via Telegram command or ad-hoc session.

Task Queue (Jira)

Work queue, sprint tickets, backlog items

08:25 pre-digest

→ trace flow

Cache written to

_work/pm-workspace/.cache/queue-YYYY-MM-DD.json. Read by morning digest + midday ping.

CCG Analytics (GA4)

claudecodeguide.dev traffic, page stats

Sun 07:30

→ trace flow

Snapshot written to

_tools/ccg-analytics/snapshots/. Read by Nabila moonlight pipeline Sunday review.

PrintPick Signals (GA4 + GSC)

printpick.dev traffic, affiliate conversions, and Search Console CSV + snapshot

Sun 07:35

→ trace flow

Snapshot written to

_tools/printpick-analytics/snapshots/. GA4 reads via the canonical ga4-reader service account key; both GSC jobs needed a PATH export fix. All 4 Sunday analytics jobs (CCG GA4, PrintPick GA4, PrintPick GSC) confirmed alive again 2026-07-02 after two dead weeks. Nabila moonlight pipeline reads for side project revenue tracking.

Keystone Leads Performance (Ad Server)

Ad flight performance, campaign visibility, CTR

08:00 daily

→ trace flow

Output

Ad server pulse.py queries API, writes JSON. Used for work context only.

Telegram Inbox (Daily Inbox)

_scratch/inbox/YYYY-MM-DD.md
Telegram messages from @ShadmansRootBot written here by Hermes, which now owns inbound Telegram directly

long-poll

→ trace flow

Written by

Hermes gateway (long-polling). telegram_router.py, the old standalone daemon, was retired 2026-07-02 after a stuck getUpdates conflict broke inbound commands since Jun 20; Hermes took over the inbound path. Writes free-text messages to daily inbox file. Nabila reads at scheduled times.

Knowledge Base (Work Wiki)

Confluence clone for RAG and work corpus

23:00 nightly

→ trace flow

Written to

_reference/library/work-corpus/ via wiki_ingest.sh (nightly 23:00, 600s watchdog) + work_corpus_sync.sh (Sun 21:00, 600s watchdog). Both patched 2026-05-21 to replace broken perl alarms. Used as RAG by ask intent.

01b · Control Plane (Hermes Inbound Gateway)

Hermes inbound gateway always-on · replaced telegram_router.py 2026-07-02

Long-polling getUpdates · offset tracking · fast-path dispatch. The old standalone telegram_router.py daemon was retired after a stuck getUpdates conflict broke inbound commands for two weeks; Hermes now owns the inbound Telegram path directly.

/help

/ask

/note

/nina

/week

/coach

/status

/ask → ask_root.py

Classify domain (Haiku) → read corpus files → ROOT search → Sonnet or Opus synthesis → Telegram reply. Strategic questions route to Opus.

Also triggered by

Natural language ending in ? or starting with what/why/how/should/is. Everything else is captured as a note.

/note → ROOT capture

Captures tweet, thought, or observation to _context/root/captures/ and iCloud vault. ROOT indexes within 1 hour. No model call on capture path.

Also via plain text

Any message without a slash that is not a question goes directly to capture. Type it, it lands in ROOT.

/status → last log line per script

Reads last line from active log files. Replies in under 1s. No model call.

Covers

granola-sync, wiki-ingest, nina-brief, meeting-coach, granola-ingest, router. Strips ISO timestamp prefix.

01c · Agent Runtime + Operator

Hermes Runtime tools · skills · cron · MCP · gateway

Execution substrate for tool-using agents. Hermes lets Orbit read files, run commands, inspect Root, schedule jobs, use browser/MCP tools, and deliver verified outcomes back to Telegram.

terminal

files

Root MCP

cron

skills

Harness job control plane · deterministic · zero LLM

Supervises every scheduled job. Each one enters through a single safe entrypoint and runs against a declared contract. A job counts as done only if it produced its promised result, not just a clean exit code. Silent failures get flagged.

job-registry.json

side-effect contract

harness.db

jobctl doctor

→ trace flow

Why

A green checkmark used to mean the script finished. Now it means the work happened, with proof. 28 jobs declared, every run recorded: jobs rows are now written before spawn and guaranteed on failure paths, and a startup reconcile sweep closes stale "running" rows, so harness.db can no longer under-report.

Orbit Operator

AIOS admin for Root, Hermes, LaunchAgents, cron, logs, workspace drift, and delivery failures.

→ trace flow

Use when

“What broke overnight?”, “Audit Root health”, “Which agents are fake-alive?”, “Fix this cron.”

Pulse + Reality Check

Combines Root context with live files, dashboards, and cron output to surface stale loops and next actions.

→ trace flow

Use when

“Give me my work pulse”, “Check PrintPick”, “What has gone quiet?”, “What should I kill?”

Verified Repair Path

Read actual state → diagnose root cause → patch → run → verify → concise Telegram report.

→ trace flow

Rule

Not “I would check.” Orbit inspects, fixes when safe, then reports real output.

02 · Persona Agent

Root v5 · ROOT knowledge graph

3 layers · Ingest · Query · Scheduled outputs

Ingest (hourly)

granola-obsidian-synchourly, public API

confluence-obsidian-synchourly :30

ROOT indexerhourly :15

wiki_ingest.shnightly 23:00

Corpus (8 files)

finance.md100K goal, debt

career.mdKEG, FTS, Heimdall

moonlight.mdPrintPick, CCG

work-relationships.mdNina, Viktor, Leif

Scheduled outputs

nina_brief.pyFri 13:30

weekly_actions.pySun 10:00

nabila_meeting_coachon-demand /coach

nabila_nina_post_1on1Fri 16:00

Query interface

ask_root.py/ask or ? text

Haiku classifydomain + complexity

Sonnet synthesisroutine queries

Opus synthesisstrategic queries

Reads: Granola (public API) · Confluence · VibeCoding vault · _context/root/ corpus · ROOT graph (2,579 notes, 15,124 entities) · Telegram commands

Root answers knowledge questions. Orbit may call Root, but Orbit is not the knowledge brain. Three layers, one brain. Ingest: Granola meetings and Confluence pages sync to VibeCoding hourly, ROOT indexer extracts entities, wiki ingest runs nightly. Corpus: 8 standing-facts files in _context/root/ cover finance, career, moonlight, family, relationships, content, house, and principles. Query: any question via Telegram routes through ask_root.py, Haiku classifies the domain, corpus files plus ROOT search assemble context, Sonnet or Opus synthesizes a Shadman-specific answer. Two scheduled outputs: Nina brief Friday 13:30 and Sunday week plan. Cost tracked in llm_calls.jsonl.

03 · Memory and Knowledge Store

Hot: Always Loaded

MEMORY.md router

CLAUDE.md

session context

Under 200 lines combined. Routes to topic shards on demand.

Constraint

200-line hard limit. Anything past that is truncated by the harness. Keep the index lean. MEMORY.md now runs 10 Active This Week / 7 Recent handoffs, cap enforced by the handoff skill. INDEX.md is auto-generated nightly by build_handoff_index.py; handoffs older than 90 days auto-archive to _context/handoffs/_archive/.

Warm: Loaded on Demand

_index_work.md

_index_moonlight.md

_index_infra.md

_index_feedback.md

_index_people.md

705 topic files

Load pattern

MEMORY.md router table decides which shard to load. Never load all shards. Token budget rule: max 2 files in main thread before subagent.

Semantic: ROOT Index

ROOT MCP

Obsidian vault (5min)

hourly indexer (Haiku)

vault topic index (18:15)

How it works

ROOT indexes the Obsidian vault. Vector lookup = zero LLM tokens. Used by recall intent + planned overnight block analysis.

Hermes / Orbit Memory

user profile

infra facts

skills

session search

Boundary

Memory stores stable preferences and environment facts. Repeatable procedures become skills. Temporary task state stays in session logs.

_product-brain/

Living project files per moonlight project. Router appends captures. Morning digest reads for context.

Pattern

One .md file per project. Capture handler appends timestamped sections. Nabila morning digest reads first 6KB of each.

_context/handoffs/

Session continuity. Handoffs written after multi-step work. Last 7 surfaced in MEMORY.md router.

Aging

Full list at _context/handoffs/INDEX.md, auto-generated nightly by build_handoff_index.py. Last 7 entries shown in MEMORY.md. Handoffs older than 90 days auto-archive to _context/handoffs/_archive/; older ones searchable via ROOT.

_reference/library/

Work corpus (weekly sync), research, Confluence clone (nightly). 90-day idle sweep.

Lifecycle

Read-only. scratch_retention.sh sweeps after 90 days idle. Build artifacts stripped on clone.

04 · Governance and Health

Workspace Health

Invariant check: git, structure, soak rules, paths.

09:00 daily

Checks

28 invariants including: git clean, nested repo isolation, runtime state gitignored, LaunchAgent exit codes, cron log freshness, Telegram reachability. workspace_doctor.py runs a zero-LLM maturity score (0–10) on top of these checks.

Orbit AIOS Admin

On-demand operator for launchd, cron, stale logs, Root health, Hermes config, memory drift, and delivery failures.

ask anytime

Examples

Audit my AIOS health. Check what broke overnight. Repair this cron. Archive dead agents. Make this recurring.

Cost Dashboard

Daily quota usage across all LLM crons. Posts to Telegram.

22:00 daily

Why it matters

All 25+ agents share one Claude Max subscription. One quota blowout breaks all downstream agents until reset. Circuit breaker.

Log Alerter

Scans cron logs for FAIL signatures. Fires Telegram on first match. launchd-only now, crontab duplicate removed.

every 15 min

Pattern

Reads _tools/scripts/.logs/*.log and ~/Library/Logs/granola-ingest-v2.* for FAIL signatures, plus an expanded watch list added 2026-07-02 (the 4 analytics logs, root-indexer.err, weekly-action-scanner.log) and artifact-staleness probes. One alert per failure window. Stops noise on repeat failures.

Semantic Lint

LLM pass over workspace for drift, stale rules, broken refs.

1st Sun/month

Scope

Checks MEMORY.md shards, CLAUDE.md, rule files, skill definitions for internal contradictions and rot. The contradiction pass now actually runs via claude --print, fixed 2026-07-02 after silently skipping in 100% of prior runs.

Skill Audit

Reviews Claude skill definitions for staleness.

monthly, 1st Sun

Checks

33 skills across _context/skills/ and ~/.claude/skills/ (39 archived 2026-07-02 to _archive/skills-2026-07-02/). Flags trigger conditions that no longer match real usage patterns. Cadence moved from weekly to monthly first Sunday.

Memory Drift

Weekly MEMORY.md re-bloat check.

Sun 21:00

Rule

MEMORY.md hard limit: 200 lines. Drift check catches entries that should graduate to topic shards per aging policy. Staleness now measured off git commit dates, not file mtimes, after a repo migration reset 640 of 707 mtimes to one timestamp and blinded the old detector.

AIOS Drift Check NEW

Weekly single source of truth for whether the map and the docs still match reality.

Sun 08:20

9 checks

Map truth, feeds fresh, harness ledger, scheduler hygiene, context-tax growth, declared-vs-enforced registry, memory caps, git sync, heartbeat. Silent when clean, one Telegram alarm on failure. Added 2026-07-02 after the holistic repair.

Weekly Actions

Sunday action doc: open commitments, new items, auto-closures from completion signals.

Sun 10:00 CEST

→ trace flow

Pipeline

Scans Obsidian Keystone/ (incl. Captures/ from Telegram). Detects completion signals. Auto-closes matched open items. Output: _work/agent-deliveries/actions/YYYY-MM-DD-week-actions.md

Open Loops

Monthly count of unresolved TODOs across topic shards.

1st of month

Source

Scans all _index_*.md files for TODOs and "open:" markers. Reports count per shard.

Eval Harnesses NEW

Regression seeds for live deliverables, not the retired persona crons.

change-triggered

_tools/evals/

weekly_actions (6 seeds, 6/6 pass), friday_brief (4 seeds, hermetic via --setting-sources project), wiki_ingest (repaired, 4/4 pass). Run on change, not on a schedule.

Scratch Retention

Per-folder sweep of _scratch/. Marks delivered files. Now LIVE, no longer dry-run.

Sun 23:00

TTL rules

ideas/: 30d. playground/: 14d. dogfood/: 7d after report. granola/: 90d. DRY_RUN=0 as of 2026-07-02, files actually delete now.

Auto-Sync

Nightly backup commit across all workspace repos.

22:00 daily

Safety

mkdir mutex to prevent race with SessionEnd hook. EDEADLK guard added May 5. Gitignores: .state/, .locks/.

Zombie Scripts

Quarterly scan for cron scripts untouched 90+ days.

quarterly

Action

Reports scripts to decommission. Does not delete. Requires manual confirmation before removal.

AIOS Doctor

Zero-LLM maturity score (0–10) across 8 control-plane groups. Exits 1 on any WARN or FAIL.

on-demand / verify

How it works

workspace_doctor.py wraps workspace_health.py, loads delivery and job registries, and scores identity, governance, job control, ROOT hygiene, git hygiene, launchd health, interfaces, and runtime drift. Run via _tools/scripts/verify_workspace.sh. New rule: every policy marked "mandatory" must name the cron, hook, or gate that enforces it, checked against _tools/evals/enforcement-registry.json by the AIOS Drift Check's declared-vs-enforced pass.

05 · Delivery and Security

Primary surface. Root answers knowledge questions; Orbit/Hermes returns operator briefs, verified fixes, and scheduled health/revenue pulses.

Ingest · Query · Orbit audit · Repair reports · Pulses

Constraints

Plain text only. No markdown tables. 4000-char limit per message. Long replies split with notification suppression on continuations.

Brief Archive

Every pipeline delivery archived to
_work/agent-deliveries/

Structure

Root → nina-1on1/, coaching/, actions/. One .md file per run. Searchable history via ROOT graph.

Obsidian Vault

Synced every 5 min. Human-readable view of all structured knowledge. Mobile via Obsidian app.

every 5 min

Bidirectional via ROOT

workspace → Obsidian (sync). Telegram captures also write TO Obsidian Keystone/Captures/ so ROOT indexes them. ROOT feeds the weekly action scanner. The vault is the single source of truth for all indexed knowledge.

Credential Architecture

1Password (canonical)

Telegram bot · GA4 SA · Atlassian · Anthropic API

↓

bootstrap_secrets.sh

Portable restore on new Mac. Single command.

↓

~/.config/shell/secrets.env

Cron runtime. No biometric. No network.

Remote sessions: read+draft only. Orbit can operate local systems; remote action keys stay isolated.

Security boundary

Remote Claude Code sessions (web, Codex CLI) see context-snapshot mirror. Never the secrets.env file. Deliberate isolation.

Operating Principles

Root is the single interface

Root owns all three layers: ingest, query, and scheduled outputs. One brain, one Telegram handle, no split ownership.

Why

Unified ownership eliminates overlapping briefs and duplicate LLM calls. One agent with four scopes beats four agents with one scope each.

Root brain, Orbit operator

Root owns remembered knowledge. Hermes runs tools. Orbit inspects live state, fixes drift, verifies, and compresses reality into decisions.

Why

Prevents persona confusion. Knowledge answers and operational repairs are different flows with different proof requirements.

7-day soak rule

No new automation until the previous one runs unattended for 7 days.

Why

Stability over velocity. New agents frequently have silent failure modes that only surface under real conditions over time.

Subagent-first

3+ files = subagent. Parallel over sequential. Main thread stays lean.

Enforced by

UserPromptSubmit hook (subagent-nudge.sh) that warns when the pattern is about to be violated.

Repos stay clean

No secrets in any repo. Runtime state gitignored. Portability lives in 1Password.

Enforced by

git_guard.py pre-commit hook. .gitignore covers .state/, .locks/, secrets.env patterns.

Ship and verify

"Shipped" = live URL + HTTP 200 + fingerprint grepped. Not "merged." Not "pushed."

Why

"Push to main" and "live for users" are not the same event. Shadman ships solo and needs confirmation to move on.