Architecture

How AgentLife is structured — the three-tier pack model and design principles.

Three-Tier Pack Model

AgentLife organizes AI agent capabilities into three tiers that stack on each other:

Tier	Name	What it contains	Example
1	Base	Foundation MCP server definitions, shared utilities, and common tool configurations	MCP server configs for filesystem, web_search, time
2	Persona	A curated pack that configures your agent for a specific domain	Life Ops, Enterprise Architect, Student
3	Use Case	Individual capabilities within a persona with cron schedules and MCP alternatives	portfolio-tracking, assignment-tracking, study-planning

Persona Pack Structure

Each persona pack is a directory with a consistent structure:

packs/<persona>/
├── config.yaml               # Pack metadata, persona definition, cron jobs, MCP recommendations
├── skills/                   # 5 SKILL.md files (one per skill)
├── use-cases/                # 4 YAML files (one per use case)
├── scripts/                  # 3 .sh files (one per cron job)
└── helpers/                  # 2 .py files (one per automation helper)

config.yaml

The pack manifest. Defines the persona, version, display name, base tier, cron schedules, use case IDs, and MCP server recommendations. Also specifies Hermes configuration overrides (model, max_turns, etc.).

Skills (SKILL.md)

Each skill is a markdown file with YAML frontmatter that acts as an instruction set for the agent. Skills include:

• Frontmatter — name, description, version, author, agentlife metadata (persona, tier, use case, cron)
• Body — feature descriptions, usage prompts, related skills

Use Cases (YAML)

Each use case defines:

• Cron jobs — scheduled tasks with scripts
• Configuration — domain-specific settings
• MCP alternatives — servers that enhance this use case, with config snippets and fallback modes

Design Principles

MCP-First Integration

Every use case documents MCP alternatives with:

• Named server — the MCP server to use
• Description — how it enhances the use case
• Config snippet — ready-to-paste JSON/YAML for Hermes config
• Auth requirements — 🔑 for API key, 🔓 for no key needed
• Fallback mode — what happens when the server isn't configured

Cross-Platform Portability

Persona packs export as portable SKILL.md bundles that work on any AI agent runtime supporting the format — Hermes, Claude Code, Codex, Cursor, and OpenClaw.

Gradual Onboarding

Start without any MCP servers (fallback mode). Add servers one at a time as you get comfortable. Every use case has a documented fallback path.

Community Governance

Persona packs are open source, MIT-licensed, and community-governed. Anyone can fork, customize, and submit persona packs to the marketplace.

Multi-Agent Coordination

AgentLife supports multi-agent coordination via n2n-nexus, a lightweight MCP coordination hub. Multiple persona agents can:

• Initiate coordination sessions around topics
• Join sessions as participants
• Exchange messages and proposals
• Archive completed sessions for audit

# Start a coordination session
agentlife mesh init enterprise-review \
  --topic "Cloud Migration Strategy" \
  --personas enterprise-architect life-ops