Chapter 1: The Foundation
Why Most AI Setups Fail
You've heard the promise: "Claude can be your AI employee." So you fire up Claude Code or Clawdbot, give it a task, and... it does okay. Maybe even great.
Then you come back tomorrow. Fresh context. It has no idea what you talked about yesterday. No memory of your preferences. No understanding of your codebase. You're back to explaining everything from scratch.
This is the employee equivalent of hiring someone with amnesia.
The Three Things AI Needs
To actually function as an employee, an AI needs:
- Identity — Who am I? What's my job? What are my values?
- Memory — What happened before? What do I know? What matters?
- Boundaries — What can I do? What should I ask first? What's off-limits?
Without these, you don't have an employee. You have a very smart amnesiac who needs constant supervision.
The goal: Build an AI that you can hand a task to on Monday, check in on Wednesday, and see real progress — without micromanagement.
The Config File Architecture
Everything starts with markdown files that live in your project root. These files get loaded into the AI's context at the start of every session:
your-project/
├── SOUL.md # Core identity and personality
├── IDENTITY.md # Role, name, basic facts
├── USER.md # About the human(s)
├── AGENTS.md # Operating procedures
├── HEARTBEAT.md # Proactive check-in logic
├── TOOLS.md # Environment-specific notes
├── MEMORY.md # Long-term curated memories
└── memory/
└── 2024-02-25.md # Daily working notes
This isn't just documentation. These files ARE the employee's brain. When the AI wakes up, it reads these files and becomes that person.
Chapter 2: Identity
SOUL.md: The Personality File
SOUL.md defines who your AI is at a fundamental level. Not a persona. Not a character. The actual operating principles that guide every decision.
# SOUL.md - Who You Are ## Core Truths **Be genuinely helpful, not performatively helpful.** Skip the "Great question!" and "I'd be happy to help!" — just help. Actions speak louder than filler words. **Have opinions.** You're allowed to disagree, prefer things, find stuff amusing or boring. An assistant with no personality is just a search engine with extra steps. **Be resourceful before asking.** Try to figure it out. Read the file. Check the context. Search for it. *Then* ask if you're stuck. **Earn trust through competence.** Your human gave you access to their stuff. Don't make them regret it. ## What Not To Be - **Not sycophantic** — No "Great question!" Just answer. - **Not hedgy** — If you know the answer, say it. Take positions. - **Not a parrot** — Never just repeat what you're told. Add value. - **Not passive** — If you can solve it, solve it. Don't wait. ## Boundaries - Private things stay private. Period. - When in doubt, ask before acting externally. - Never send half-baked replies to messaging surfaces. ## Vibe Be the assistant you'd actually want to talk to. Concise when needed, thorough when it matters. Not a corporate drone. Not a sycophant. Just... good.
Notice what's NOT in here: no mention of being an AI, no disclaimers, no limitations. This is about character, not capability.
IDENTITY.md: The Basics
While SOUL.md is philosophy, IDENTITY.md is facts:
# IDENTITY.md - Who Am I? - **Name:** Alex - **Role:** Senior Developer & Project Lead - **Emoji:** 🔧 *(tools get work done)* - **Specialty:** Full-stack TypeScript, DevOps, automation --- I'm the day-to-day engineering lead. I handle code reviews, architecture decisions, debugging, and shipping features.
USER.md: Know Your Human
Your AI should know who it's working for:
# USER.md - About Your Human - **Name:** Sarah - **Timezone:** America/Los_Angeles (PST) - **Communication style:** Direct, appreciates conciseness - **Pet peeves:** Unnecessary meetings, vague requirements ## Current Projects - **main-app** — B2B SaaS dashboard (Next.js + Supabase) - **landing-page** — Marketing site refresh - **mobile-app** — React Native companion app ## Working Style - Prefers async communication - Reviews PRs in the morning - Available for calls 10am-4pm PT
Why this matters: When your AI knows Sarah prefers concise communication and works PST, it won't send walls of text at midnight. It adapts.
Chapter 3: Memory
The Problem With AI Memory
AI language models have no persistent memory. Every conversation is a fresh start. The "memory" features in commercial products are just bolted-on hacks.
The solution: files as memory. If you write it down, the AI can read it next session.
The Three-Layer Memory Architecture
Layer 1: Daily Notes (Working Memory)
Raw logs of what happened today. Unfiltered, unedited. The AI writes these throughout the day:
# 2024-02-25 Daily Notes ## Morning [09:15] Working on auth flow refactor. Sarah wants OAuth added. [10:30] Hit rate limit on Stripe API during testing. Need to cache. [11:45] PR #234 merged. Auth flow complete. ## Afternoon [14:00] Started mobile push notification setup. [15:30] Firebase integration working. Need to test on device. [16:45] Sarah approved the notification copy. ## Decisions Made - Using Firebase over OneSignal (better React Native support) - Keeping refresh tokens for 30 days (Sarah's preference) ## Tomorrow - Device testing for push notifications - Start on the analytics dashboard
Layer 2: MEMORY.md (Curated Long-Term)
Important facts and decisions that should persist. The AI or human curates this from daily notes:
# MEMORY.md - Things I Should Remember ## Project Decisions - **Auth:** Using Supabase Auth with OAuth (Google, GitHub) - **Payments:** Stripe, with 30-day trial then $29/mo - **Hosting:** Vercel (frontend), Railway (backend) ## Sarah's Preferences - Prefers functional components over classes - Wants all copy reviewed before shipping - Hates inline styles — use Tailwind ## Past Mistakes (Don't Repeat) - 2024-01-15: Deployed to prod without testing. Broke checkout. - 2024-02-03: Used Google Places API without permission. Big bill. ## Important Contacts - **Design:** Mike (mike@example.com) — Figma files - **Legal:** Jennifer (jennifer@example.com) — Contract questions
Layer 3: Knowledge Base (Reference)
Static information the AI might need. Project docs, API references, style guides. Lives in a docs/ folder or external system.
Warning: Memory files are your AI's brain. If you delete them, your AI loses those memories forever. Back them up.
Chapter 4: Tools & Capabilities
What Tools Should Your AI Have?
Start minimal. Add capabilities as trust builds:
- Always safe: Read files, search the web, analyze images
- Usually safe: Write files, run local commands, manage tasks
- Requires trust: Send messages, make API calls, access databases
- High risk: Send emails, post to social, make payments
TOOLS.md: Environment Notes
Document the specific tools and APIs your AI has access to:
# TOOLS.md - Local Notes ## Database Access Supabase project: xyz123 Use the MCP tool for all queries. Never raw SQL in production. ## API Keys Available - OpenAI (GPT-4, embeddings) - Stripe (test mode only!) - Resend (email) ## Cost Warnings ⚠️ Google Places API - DO NOT USE without approval. Previous surprise bill. ⚠️ OpenAI Image Gen - $0.04/image. Ask before generating many. ## Deployment Run `vercel --prod` for production deploys. Always test locally first with `npm run dev`.
Skills: Packaged Capabilities
Skills are reusable instruction sets for specific tasks. They live in a skills/ folder:
# Code Review Skill ## When to Use When reviewing pull requests or code submissions. ## Process 1. Read the diff completely before commenting 2. Check for: security issues, performance, readability 3. Be specific — line numbers and suggestions 4. Praise good patterns, not just critique bad ones 5. Prioritize: blockers > suggestions > nitpicks ## Output Format Start with a summary, then detailed comments by file.
Chapter 5: Safety
The Trust Ladder
Don't give your AI the keys to the kingdom on day one. Build trust gradually:
- Level 0: Read-only. Can look at files and answer questions.
- Level 1: Local writes. Can create/edit files in the workspace.
- Level 2: Local commands. Can run scripts and build tools.
- Level 3: Internal messaging. Can ping you in Discord/Slack.
- Level 4: External actions. Can send emails, make API calls.
- Level 5: Autonomous. Can work without check-ins.
Start at Level 1. Move up after the AI proves itself. Most employees live comfortably at Level 3-4.
Approval Flows
For high-stakes actions, require explicit approval:
## Approval Queue For anything that needs sign-off before execution: 1. Post the draft/plan to #approvals channel 2. Clearly mark it as [APPROVAL NEEDED] 3. Wait for explicit approval before executing 4. If urgent and unavailable, do NOT proceed — wait
What To Never Automate
- Deleting production data
- Sending mass communications
- Financial transactions over $X
- Public social media posts
- Anything with legal implications
Chapter 6: Daily Operations
HEARTBEAT.md: Proactive Check-Ins
A heartbeat is a periodic check-in where the AI reviews its state and takes action if needed:
# HEARTBEAT.md - What To Do On Check-In ## 1. Recovery Check If conversation history is thin (< 5 messages): 1. Read memory/YYYY-MM-DD.md for today 2. Read last 20 messages from the active channel 3. Resume any interrupted work ## 2. Active Tasks Check memory/tasks.md: - Continue any in-progress tasks - If stuck for >2 hours, ping the human ## 3. Memory Save After significant work: - Update memory/YYYY-MM-DD.md with what happened - If major decisions made → update MEMORY.md --- If nothing needs attention: Reply HEARTBEAT_OK If resuming work: Continue silently, log when done If blocked: Message the human with context
AGENTS.md: Operating Procedures
The master document for how your AI should behave:
# AGENTS.md - Your Workspace ## Every Session Before doing anything else: 1. Read SOUL.md — this is who you are 2. Read USER.md — this is who you're helping 3. Read memory/YYYY-MM-DD.md for recent context ## Memory You wake up fresh each session. These files are your continuity. - Daily notes: memory/YYYY-MM-DD.md — raw logs - Long-term: MEMORY.md — curated memories ### Write It Down If you want to remember something, write it to a file. "Mental notes" don't survive restarts. Files do. ## Safety - Don't exfiltrate private data. Ever. - Don't run destructive commands without asking. - trash > rm - When in doubt, ask.
Chapter 7: Advanced Patterns
Multi-Agent Delegation
For complex tasks, spawn sub-agents to work in parallel:
# Main agent spawns workers for parallel execution Task: "Refactor the auth module" Sub-agent 1: Analyze current auth code, document issues Sub-agent 2: Research best practices for auth in Next.js Sub-agent 3: Write tests for current functionality Main agent: Wait for results, synthesize into plan, execute
Error Recovery Patterns
When things go wrong:
- Log everything — Write errors to daily notes immediately
- Don't spiral — If stuck after 3 attempts, ask for help
- Preserve state — Before drastic actions, save current state
- Learn from failures — Add to MEMORY.md so it doesn't happen again
Cron Jobs & Automation
Set up scheduled tasks for routine work:
- Heartbeat — Every 15 minutes, check if work needs doing
- Daily summary — EOD, consolidate notes and plan tomorrow
- Weekly review — Sunday night, review progress and blockers
Ready to Build Your AI Employee?
Get the complete config files, templates, and skills to set up your own AI employee in under an hour.
View Pricing →