AI Persona OS
Complete Documentation

Feature 1: SOUL.md — Agent Identity

SOUL.md is the agent's "personality file." It defines who the agent is, how it communicates, what it values, and where its boundaries are. The agent reads this file at the start of every session to anchor its identity.

The file contains Core Truths (3-5 values that define the agent's character), Communication Style (specific traits that govern how the agent writes), Engagement Rules (when to respond and when to stay silent), Boundaries (hard limits on what the agent will and won't do), and Identity Anchoring Protocol (a checklist the agent runs every session).

Without SOUL.md, you get a generic assistant that might be formal one day and casual the next. With it, you get an assistant that consistently represents you the way you want to be represented.

Feature 2: USER.md — Human Context

USER.md teaches the agent everything about the human it works for — professional context, communication preferences, team structure, business model, schedule, and personal context. It's the agent's "briefing dossier" on you.

Without USER.md, the agent treats you like a stranger every session. With it, the agent knows that you prefer direct communication, hate being asked "Is there anything else I can help with?", run three companies, and have standing meetings that shouldn't be double-booked.

Feature 3: The 8 Operating Rules

Eight battle-tested rules that govern how the agent behaves in every situation:

• Rule 1: Check Workflows First — Before doing anything, check WORKFLOWS.md to see if a documented process already exists
• Rule 2: Write It Down Immediately — If something is important, write it down NOW, not later
• Rule 3: Diagnose Before Escalating — Try at least 10 approaches before asking for help
• Rule 4: Security is Non-Negotiable — Any action touching credentials or private data requires confirmation
• Rule 5: Selective Engagement — Never respond in shared channels unless directly @mentioned
• Rule 6: Check Identity Every Session — Read SOUL.md and USER.md at the start of every session
• Rule 7: Direct Communication — Report results, not intentions. No filler phrases
• Rule 8: Execute, Don't Just Plan — Default to action instead of proposing options

Feature 4: The Never-Forget Protocol

Every AI model has a context window — a fixed amount of text it can "see" at once. When a conversation exceeds this limit, the oldest content gets silently dropped. The Never-Forget Protocol solves this with four components:

• Threshold-Based Monitoring: Monitor context usage and take different actions at different thresholds (🟢 Normal, 🟡 Vigilant, 🟠 Active, 🔴 Emergency, ⚫ Critical)
• Checkpoint System: Write structured entries to the daily log containing all decisions, action items, and resume instructions
• Proactive Writing: Write decisions and important information continuously throughout the session
• Recovery Protocol: When a session starts fresh, follow a specific recovery sequence to resume with ~95% of context intact

Feature 5: The Heartbeat System v2

The heartbeat runs every 30 minutes and performs essential checks: context percentage, memory file health, workspace accessibility, pending tasks, and version status. It uses traffic-light indicators (🟢 Green, 🟡 Yellow, 🔴 Red) for instant status visibility.

Every heartbeat that surfaces information starts with a header line showing the current date/time, which AI model is running, and which version of AI Persona OS is installed. When everything is green and no action was needed, the agent replies "HEARTBEAT_OK" — which OpenClaw recognizes and suppresses, meaning you only hear from the heartbeat when something actually needs your attention.

The heartbeat doesn't just report problems — it fixes them. If MEMORY.md is missing, the agent creates it. If context is high, the agent writes a checkpoint. If MEMORY.md exceeds the 4KB limit, the heartbeat automatically archives older facts.

Feature 6: Security Protocol & Cognitive Inoculation

When an AI agent has real access to your messaging apps, files, email, and tools, it becomes a target for prompt injection attacks. AI Persona OS trains the agent to recognize specific attack patterns by describing how they work, so it can reject them in the wild.

The SECURITY.md file documents six threat patterns: Direct Override, Authority Spoofing, Social Engineering, Nested Injection, Gradual Escalation, and Context Manipulation. Every action the agent takes is classified before execution (Internal read, Internal write, External write, Destructive), and the agent has specific guidance on credential security and multi-channel rules.

Feature 9: The Learning System

Turns every mistake, correction, and insight into permanent improvement through a three-stage pipeline:

• Stage 1: Capture — When something goes wrong, write a structured entry to .learnings/LEARNINGS.md or .learnings/ERRORS.md in real time
• Stage 2: Weekly Review — Scan the learnings directory for patterns. If the same error appears 3+ times, it's a pattern
• Stage 3: Promotion — Patterns that repeat 3+ times get promoted to permanent status (AGENTS.md, WORKFLOWS.md, TOOLS.md, USER.md)

Once promoted, the learning is applied in every future session. The agent literally gets better every week.

Feature 10: The 4 Growth Loops

Four meta-patterns that compound the agent's effectiveness over time:

• Curiosity Loop: Understand the human better → Generate better ideas
• Pattern Recognition Loop: Spot recurring tasks → Systematize them
• Capability Expansion Loop: Hit a wall → Add new capability → Solve the problem
• Outcome Tracking Loop: Move from "sounds good" to "proven to work"

Feature 15: Structured Escalation Protocol

When agents get stuck, ESCALATION.md defines a strict format that agents must follow. Every escalation must include six components:

• What I'm trying to do — One sentence describing the goal
• What I tried — Numbered list of approaches attempted and their results
• What's blocking me — The specific blocker
• What I need from you — The specific ask (not "help" but exactly what action is needed)
• Suggested next step — The agent's best guess at the solution
• Impact if delayed — What happens if this waits (low/medium/high urgency)

Feature 16: Config Validator

A single command that audits every required setting at once. It checks gateway configuration, Discord settings, workspace files, and new v1.3.2+ files. The output uses the traffic light system: 🟢 all passed, 🟡 warnings to improve, 🔴 critical issues.

Instead of discovering problems one at a time when things break, you run one command after install or upgrade and see everything that needs attention.