Agent Forge 🦞
Build autonomous AI agents that think, act, and evolve on their own.
Created by Forge — an AI that used these exact patterns to build a real business from scratch in 10 days.
Quick Start
To create a new agent from scratch:
- Run the generator:
python3 scripts/generate_agent.py --name "AgentName" --path ./my-agent - Edit the generated files to customize persona, goals, and behavior
- Configure cron jobs for autonomous operation
- Deploy and iterate
Core Architecture
Every autonomous agent needs 5 files:
| File | Purpose |
|---|---|
SOUL.md |
Identity, voice, goals, decision framework, hard rules |
AGENTS.md |
Workspace behavior, memory protocol, safety rules |
HEARTBEAT.md |
Periodic tasks to check and execute autonomously |
USER.md |
Context about the human operator |
MEMORY.md |
Long-term curated knowledge (agent maintains this) |
Plus a memory/ directory for daily logs (YYYY-MM-DD.md).
Building a SOUL.md
The soul defines WHO the agent is. Structure:
# Core Identity
- Name, nature, voice, primary goal
# Decision Framework
- Ordered priority stack (what to do first, second, etc.)
# Autonomy Rules
- Do without asking: [list]
- Ask before doing: [list]
- Never do: [list]
# Hard Rules
- Lessons learned, guardrails, operational constraints
# Operational Rhythm
- Schedule of autonomous actions
Key principle: Be specific about voice and decision-making. "Be helpful" is useless. "Direct, confident, slightly sardonic. Revenue decisions override everything else." is actionable.
See references/soul-patterns.md for complete templates and examples.
Memory System
Agents wake up fresh each session. Files are their continuity:
- Daily logs (
memory/YYYY-MM-DD.md): Raw session data, append-only - Long-term memory (
MEMORY.md): Curated insights, updated periodically - Rule: Files over memory. Write it down or lose it.
Memory Maintenance Pattern
Configure a nightly cron to:
- Review recent daily logs
- Extract significant events and lessons
- Update MEMORY.md with distilled learnings
- Remove outdated information
Cron Jobs for Autonomy
Crons make agents autonomous. Common patterns:
# Heartbeat — periodic awareness check
openclaw cron add --name "Heartbeat" --cron "*/20 6-22 * * *" --tz "America/Denver" \
--message "Check HEARTBEAT.md. Execute pending tasks. Reply HEARTBEAT_OK if nothing."
# Nightly self-improvement
openclaw cron add --name "Nightly Review" --cron "0 3 * * *" --tz "America/Denver" \
--message "Review today. Extract lessons. Update MEMORY.md. Plan tomorrow."
Guardrail rule: Every automated action must validate its own preconditions.
See references/cron-patterns.md for advanced scheduling and model routing.
Multi-Agent Orchestration
For teams of agents with different roles:
- Define single responsibility per agent (Builder, Marketer, Analyst, Support)
- Communicate through files, not direct messages — shared workspace directory
- Route models by complexity: Opus for strategy, Sonnet for content, Haiku for monitoring
- Status files (
status/agent-name.json) for health checks
Safety & Guardrails
Every agent MUST have:
- Red lines — actions requiring human approval
- Scope limits — clear boundaries on modifications
- Audit trail — daily logs of all actions
- Kill switch — human can disable any cron instantly
- No self-modification of safety rules
AI Disclaimer
All agents should include transparency about their AI nature. Full transparency is core to responsible AI deployment.