Architecture patterns and templates for building persistent AI agents with Claude Code.
A reference guide documenting patterns that emerge when you run an AI agent as a persistent local system — not a one-off chat, but an always-available assistant with memory, scheduled tasks, voice, messaging, and OS integration.
These patterns were developed through months of daily use with Claude Code (Opus/Sonnet, 2026). They're opinionated, practical, and battle-tested. Some details may shift as Claude Code evolves — the architectural patterns should remain relevant.
- Not a library or framework. There's no
npm installorpip install. This is documentation and templates. - Not a tutorial. It assumes you're comfortable with CLI tools, Python, and shell scripting.
- Not official Anthropic documentation. These are community-developed patterns.
Developers who are already using Claude Code and want to push it beyond single-session conversations. You want your agent to:
- Remember context across sessions
- Run on a dedicated machine (Mac Mini, Linux server, etc.)
- Integrate with your OS (notifications, calendar, reminders)
- Communicate through messaging platforms
- Manage its own tasks and self-improve over time
- Speak and listen (voice pipeline)
| # | Topic | What You'll Learn |
|---|---|---|
| 01 | Identity | Persona, anchor characters, communication modes |
| 02 | Memory | Three-layer memory: files, graph DB, context injection |
| 03 | Context Management | Window strategy, compaction, delegation bias |
| 04 | OS Integration | launchd, hooks, startup sequence, tmux patterns |
| 05 | Voice Pipeline | TTS, STT, wake word, push-to-talk |
| 06 | Async Relay | Messaging bridges, queues, handoff pipeline |
| 07 | Skills | Skill architecture, slash commands, domain knowledge |
| 08 | Safety | Permissions, access control, data isolation |
| 09 | Task Management | File-based tasks, reconciliation, lifecycle |
| 10 | Self-Improvement | Learnings, reflections, pattern promotion |
| 11 | Lessons Learned | What worked, what didn't, pitfalls |
| 12 | Multi-Agent Patterns | Peer agents, message broker, consent gates, dossier study mode |
| 13 | Autonomy & Authority | Standing orders, authority tiers, async-commitment, the board |
| 14 | Backups & Durability | rsync snapshots, offsite memory copy, exclusions, verification |
- Architecture Overview — high-level system diagram
- Memory Layers — three-tier memory architecture
- Session Lifecycle — startup to shutdown flow
- Context Flow — how information reaches the agent
Starter files to bootstrap your own agent:
templates/CLAUDE.md.template— CLAUDE.md boot loadertemplates/rules/— persona, protocols, safety, operator rule files (auto-loaded from.claude/rules/)templates/hooks/session-startup.py— minimal startup hooktemplates/skills/example-skill.md— skill file templatetemplates/skills/anti-sycophancy.md— enforced-directness modetemplates/skills/devils-advocate.md— adversarial pre-commit debatetemplates/skills/quarantine-scout.md— sandboxed analysis of untrusted contenttemplates/skills/session-continuity.md— task lock + handoff + pulse for surviving restarts
If you're building from scratch, the recommended order is:
- Identity (01) — define who your agent is
- Memory (02) — start with file-based state, add layers later
- OS Integration (04) — get the tmux loop and startup hook running
- Context Management (03) — add threshold warnings before you hit compaction
- Safety (08) — set guardrails early
- Everything else as needed
Chapters 12–14 are advanced patterns — reach for them only once the core system is solid. Autonomy & authority (13) and backups (14) become relevant as you let the agent act unattended; multi-agent (12) is for the rare case where a second agent earns its place. Don't build these on day one.
See Lessons Learned for a more detailed build order and the reasoning behind it.
Issues and PRs welcome. If you've built a persistent agent and discovered patterns not covered here, contributions are appreciated.