Agents

Agents are the core building blocks of Moxxy. Each agent is an independent AI entity with its own memory, personality, skills, and channels.

What is an Agent?

An agent is a self-contained AI assistant that can:

• Think - Process requests using an LLM
• Remember - Store and recall information
• Act - Execute skills to accomplish tasks
• Communicate - Interact through various channels

Agent Architecture

┌─────────────────────────────────────────────────┐
│                    Agent                         │
├─────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌──────────┐ │
│  │   Persona   │  │   Memory    │  │  Skills  │ │
│  │  (Who am I) │  │  (Context)  │  │ (Actions)│ │
│  └─────────────┘  └─────────────┘  └──────────┘ │
├─────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐               │
│  │    Vault    │  │  Channels   │               │
│  │  (Secrets)  │  │ (Interfaces)│               │
│  └─────────────┘  └─────────────┘               │
├─────────────────────────────────────────────────┤
│                   Brain                          │
│           (ReAct Loop + LLM)                     │
└─────────────────────────────────────────────────┘

Agent Components

Persona

The persona defines the agent's identity, behavior, and constraints.

Location: ~/.moxxy/agents/<name>/persona.md

You are a specialized AI assistant for software development.

Your expertise includes:
- Code review and optimization
- Bug diagnosis and fixing
- Architecture recommendations
- Testing strategies

Communication style:
- Be concise and technical
- Provide code examples
- Explain the reasoning behind suggestions

Constraints:
- Never execute code without user confirmation
- Always consider security implications
- Suggest tests for new code

Memory

Each agent has isolated memory storage:

Type	Description	Storage
Short-Term (STM)	Recent conversation context	SQLite + current.md
Long-Term (LTM)	Persistent knowledge	SQLite with embeddings
Session	Current conversation thread	In-memory

Location: ~/.moxxy/agents/<name>/memory.db

See Memory System for details.

Skills

Skills are the agent's capabilities - what it can actually do.

Built-in Skills:

• host_shell - Execute shell commands
• host_python - Run Python scripts
• web_crawler - Fetch web content
• git - Git operations
• scheduler - Schedule tasks
• And more...

Custom Skills: Add your own in ~/.moxxy/agents/<name>/skills/

See Skills for details.

Vault

Encrypted storage for sensitive data:

• API keys
• Passwords
• Tokens
• Secret values

Location: ~/.moxxy/agents/<name>/vault/

See Vault & Secrets for details.

Channels

Interfaces for communication:

• Web UI - Browser-based chat
• Terminal (TUI) - Command-line interface
• Telegram - Telegram bot
• Discord - Discord bot
• Slack - Slack app
• WhatsApp - WhatsApp bridge

See Channels Overview for details.

Agent Lifecycle

  ┌─────────┐
  │ Created │
  └────┬────┘
       │
       ▼
  ┌─────────┐     ┌─────────┐     ┌──────────┐
  │   Init  │ ──▶ │ Running │ ──▶ │ Shutdown │
  └─────────┘     └─────────┘     └──────────┘
       │               │               │
       ▼               ▼               ▼
  ┌─────────┐     ┌─────────┐     ┌──────────┐
  │  Load   │     │  React  │     │  Save    │
  │Persona  │     │  Loop   │     │  State   │
  │Memory   │     │         │     │          │
  │Skills   │     │         │     │          │
  └─────────┘     └─────────┘     └──────────┘

Initialization

When an agent boots:

1. Load persona.md into system prompt
2. Initialize memory system (create/open SQLite)
3. Initialize vault for secrets
4. Register available skills
5. Connect configured channels

Running

During operation, the agent:

1. Receives triggers from channels
2. Processes through the ReAct loop
3. Executes skills as needed
4. Updates memory
5. Sends responses

Shutdown

When stopping:

1. Save memory state
2. Close database connections
3. Disconnect channels
4. Clear sensitive data from memory

Creating Agents

Method 1: Manual

# Create directory
mkdir -p ~/.moxxy/agents/my-agent

# Create persona
cat > ~/.moxxy/agents/my-agent/persona.md << 'EOF'
You are [description].
EOF

# Initialize with first message
moxxy run --agent my-agent --prompt "Hello"

Method 2: Copy Template

# Copy from default
cp -r ~/.moxxy/agents/default ~/.moxxy/agents/new-agent

# Clean up
rm ~/.moxxy/agents/new-agent/memory.db
rm ~/.moxxy/agents/new-agent/current.md

# Edit persona
nano ~/.moxxy/agents/new-agent/persona.md

Method 3: Web Dashboard

1. Open web dashboard
2. Go to Agents tab
3. Click New Agent
4. Configure persona and settings

Managing Agents

List Agents

moxxy agent list

Restart Agent

moxxy agent restart <name>

Delete Agent

moxxy agent remove <name>

Multi-Agent Patterns

Specialized Agents

Create different agents for different purposes:

agents/
├── assistant/     # General purpose
├── researcher/    # Web research
├── coder/         # Code tasks
└── analyst/       # Data analysis

Agent Delegation

Agents can delegate tasks to other agents using the delegate_task skill:

Ask the researcher agent to investigate this topic...

Swarm Intelligence

Agents share knowledge through the swarm database:

• Agent 1 learns something
• Announces to swarm
• Agent 2 can retrieve and use that knowledge

See Swarm Intelligence for details.

Best Practices

Persona Design

1. Be Specific - Detailed personas produce better results
2. Define Boundaries - What the agent should/shouldn't do
3. Set Context - Domain knowledge and expertise
4. Guide Tone - Communication style

Memory Management

1. Periodic Cleanup - Remove outdated memories
2. Session Isolation - Use /new for fresh starts
3. Important Facts - Guide what to remember

Skill Selection

1. Minimal Permissions - Only enable needed skills
2. WASM for Untrusted - Sandbox risky operations
3. Custom Skills - Create for specific workflows

Troubleshooting

Agent Not Responding

1. Check gateway status: moxxy gateway status
2. Check logs: moxxy logs
3. Verify LLM configuration: moxxy doctor

Memory Issues

1. Check database: sqlite3 ~/.moxxy/agents/<name>/memory.db "PRAGMA integrity_check;"
2. Reset if corrupted: Delete memory.db and restart

Skill Errors

1. Check skill permissions
2. Verify dependencies
3. Check WASM configuration if applicable