Weekly agent architecture insights + a free cheatsheet.
No spam. Unsubscribe anytime.
The File-Based Second-Brain Infrastructure
Tier 3 · Everything Built8 min read
A multi-agent system that can’t reliably tell you what it did last week is a liability. Not because the individual agents are dishonest, but because sessions rotate, agents run in parallel, and the only record that survives all of that is a file. This article covers the specific file architecture built to solve that problem.
This appends a timestamped entry to ~/clawd/projects/<slug>/CHANGELOG.md:
## 2026-04-16
- 09:17 — Shipped something useful
If --completes <milestone-id> is passed, it also flips the matching - [ ] M3.2 line in WORKPLAN.md to - [x] M3.2. One call does both. The rule is in CLAUDE.md: “material” means anything that changes system state — scripts written, files edited, migrations run, bugs patched, configs changed, decisions made. Pure information-gathering and one-line trivial edits don’t trigger it. Everything else does.
The trigger is the CHANGELOG entry from 2026-04-16 that explicitly called out skipping this step as the agent equivalent of invisible work: “This is how JD and the next session see what shipped without reading chat history — skipping it means the work is invisible.”
Projects vs domain todos is an important distinction the registry enforces. A project has a goal, an end-state, and produces an artifact. A domain todo is a single action or chore. The rule: “when in doubt, domain todo.” Don’t scaffold a project for a task that doesn’t produce an artifact.
Each of the 8 domains (school, family, growth, ai-foundry, siemens, consulting, health, life-ops) has its own workspace at ~/clawd/domains/<domain>/state/. Inside: per-domain tasks.yaml, report.md (written by the hourly heartbeat), and domain-specific config files. These are what the domain agents read and write — the ground truth for each life area.
The tasks.yaml files feed the Supabase tasks table (47 rows across all 8 domains at the last sync), which in turn powers the Tasks page in the Nerve Center cockpit.
Last generated 2026-06-10 04:40 MDT from 69 active projects.
daily-rollup.sh runs twice daily (04:40 and 23:55 MT per crontab) and assembles all per-project CHANGELOGs into the master, organized newest-day-first. The result is 1,182 lines covering 2026-04-10 through 2026-06-09 — a continuous record of everything the system shipped, queryable by project slug or date.
Any agent — including a fresh session that has never seen the prior context — can answer this question by reading one file:
Terminal window
head-200~/clawd/CHANGELOG.md
The morning briefing script does exactly this. The CEO orchestrator reads it at the start of each work-queue cycle. The session digest generator reads it as part of the recap command. The file is the memory; the agent is just the reader.
Before the 04:40/23:55 split cron was installed, the rollup ran once daily at a fixed time. Two problems:
Work logged at 11pm didn’t appear in the master until the next day’s run.
If the cron failed silently (which happened), the master could be days stale without anyone noticing.
The fix was a twice-daily schedule plus the stale-cron alerter (covered in Cron Catchup & Resilience). If the rollup misses two consecutive intervals, it pings Telegram. The alerter watches 7 critical crons; the rollup is one of them.
Alongside the per-project and per-domain files, there are four files that load into every decision-making session:
jd-wiki.md
Who JD is, the 8 life domains, and the top 20 people. Context for any agent making decisions on his behalf.
jd-mental-models.md
Decision priors on money, time, family, work, risk, and energy. The “how JD thinks” layer.
jd-voice.md
10 example passages that match JD’s writing voice, 10 anti-examples, and the rules. Required for any draft-as-JD work.
jd-protocols.md
Hard rules — time/money/communications/engineering. Non-negotiable constraints that override any agent’s default behavior.
These live at ~/clawd/state/jd-*.md. An agent that doesn’t read them before drafting a message as JD, or before making a decision about money, is operating without the most important context in the system.
There’s one documented failure mode worth naming: the 2026-05-31 audit found several hollow agents and outdated dashboards. The audit’s own verdict — “budget shows April as current” — meant the system’s state files had drifted from reality. The second-brain infrastructure only works if agents actually call clawd-log.sh. A system that instruments everything except the agents that got built in a hurry will have blind spots.
The process fix was a doc-coverage-check script (agents/ai_os/doc_coverage_check.py) and a weekly sweep that flags agents with missing CHANGELOGs or stale reports. The system can’t police itself perfectly — but it can make gaps visible rather than invisible.