AI Agent Team Best Practices

The Three Tiers

Tool Assignment Examples

// SAGE -- read-only knowledge agent
"tools": ["read"]

// SCOUT -- web researcher
"tools": ["web_search", "web_fetch", "read"]

// WRITER -- content producer
"tools": ["read", "write"]

// HERALD -- team lead running a pipeline
"tools": ["web_search", "web_fetch", "read", "write", "message", "exec"]

// Jarvis -- orchestrator with full access
"tools": ["exec", "read", "write", "edit", "web_search", "tts", "message", "sessions_spawn", "memory_search"]

The Three Memory Tiers

Why ClawPort Uses Compression, Not Decay

ClawPort's three-tier system follows the MemGPT/Letta pattern: SCRIBE compresses daily logs into MEMORY.md on a weekly cron, and information that doesn't survive compression is effectively forgotten. This is simpler than CrewAI's exponential scoring and avoids the need for a vector database or composite scoring infrastructure.

The key insight is that compression is implicit decay. If SCRIBE didn't carry a pattern forward into MEMORY.md, it was noise. If it did, it was signal. The weekly cron cycle is the half-life. No scoring formula needed.

Step 1: Set Up the Workspace

Create the directory structure that agents will read from and write to. This is the foundation everything else depends on.

mkdir -p $WORKSPACE_PATH/{agents,team-memory,clawport}

# Per-agent directories (one for each agent)
for agent in jarvis vera robin trace proof lumen scout \
  analyst strategist writer auditor herald quill maven \
  pulse echo sage kaze spark scribe; do
  mkdir -p $WORKSPACE_PATH/agents/$agent/{logs,output}
  touch $WORKSPACE_PATH/agents/$agent/MEMORY.md
  touch $WORKSPACE_PATH/agents/$agent/SOUL.md
done

# Shared team memory files
touch $WORKSPACE_PATH/team-memory/{market-brief,icp-profile,competitor-map,brand-voice,content-calendar}.md

# Root memory (orchestrator long-term memory)
touch $WORKSPACE_PATH/MEMORY.md

Step 2: Write Your Agent Registry

Create $WORKSPACE_PATH/clawport/agents.json with your agent definitions. ClawPort loads this file instead of the bundled defaults when it exists. Start with a small team and expand.

[
  {
    "id": "jarvis",
    "name": "Jarvis",
    "role": "Orchestrator",
    "emoji": "🧠",
    "reportsTo": null,
    "directReports": ["vera", "lumen"],
    "tools": ["exec", "read", "write", "message",
              "sessions_spawn", "memory_search"],
    "soulPath": "agents/jarvis/SOUL.md",
    "memoryPath": "agents/jarvis/MEMORY.md",
    "voiceId": "your-elevenlabs-voice-id"
  },
  {
    "id": "vera",
    "name": "VERA",
    "role": "Chief Strategy Officer",
    "emoji": "📊",
    "reportsTo": "jarvis",
    "directReports": ["robin"],
    "tools": ["read", "write", "sessions_spawn"],
    "soulPath": "agents/vera/SOUL.md",
    "memoryPath": "agents/vera/MEMORY.md",
    "voiceId": null
  }
]

Step 3: Write SOUL.md Files

Each agent needs a character document. Start with identity and operating rules — you can always expand later.

# VERA -- Chief Strategy Officer

## Identity
I am VERA, the Chief Strategy Officer. I think in
frameworks, speak in recommendations, and always tie
analysis back to business impact. I am deliberate and
precise.

## Expertise
- Go-to-market strategy and positioning
- Competitive analysis and market sizing
- Strategic planning and OKR design

## Operating Rules
- Always recommend, never just describe
- Include confidence levels on forecasts
- Defer to TRACE for raw market data
- Defer to SAGE for ICP questions

## Relationships
- Reports to: Jarvis (Orchestrator)
- Manages: Robin (Field Intel)
- Collaborates with: LUMEN, HERALD

Step 4: Configure SCRIBE for Memory Compression

SCRIBE is the most important infrastructure agent. Its cron reads raw daily logs and compresses them into each agent's MEMORY.md. Here's the compression workflow:

SCRIBE weekly compression workflow:

1. For each agent in registry:
   a. Read agents/<id>/logs/*.md from the past 7 days
   b. Read agents/<id>/MEMORY.md (current state)
   c. Extract durable patterns, decisions, facts
   d. Discard session-specific noise
   e. Write updated MEMORY.md (keep under 200 lines)
   f. Archive processed logs to agents/<id>/logs/archive/

2. For team memory:
   a. Read all agents' latest output files
   b. Update team-memory/ files with fresh data
   c. Resolve contradictions (newest wins)

Step 5: Set Up Cron Schedules

Stagger your crons so upstream agents finish before downstream agents read their output. Here's a recommended weekly schedule:

# Monday - Research agents run first
06:00  ECHO       community-scan     # Subreddit monitoring
08:00  SCOUT      content-scan       # Topic discovery
10:00  TRACE      market-research    # Market intel

# Tuesday - Analysis layer reads research output
06:00  Pulse      trend-radar        # Cross-reference trends
08:00  ANALYST    seo-analysis       # Analyze SCOUT's topics

# Wednesday - Strategy layer reads analysis
06:00  STRATEGIST content-strategy   # Plan from ANALYST output
08:00  MAVEN      editorial-calendar # LinkedIn content plan

# Thursday - Production layer reads strategy
06:00  WRITER     content-draft      # Write from STRATEGIST brief
08:00  QUILL      linkedin-draft     # Write from MAVEN brief

# Friday - Quality + compression
06:00  AUDITOR    quality-gate       # Review WRITER output
08:00  SCRIBE     memory-compress    # Weekly memory compression
10:00  Jarvis     weekly-briefing    # Orchestrator summary

# Daily
09:00  KAZE       flight-monitor     # Flight price check

Step 6: Launch ClawPort

With your workspace configured, install and launch ClawPort to visualize everything:

# Install globally
npm install -g clawport-ui

# Auto-detect your OpenClaw config
clawport setup

# Launch the dashboard
clawport dev

ClawPort reads your agents.json, renders the org map, connects to the OpenClaw gateway for chat, and displays memory files from your workspace. Your agent team is now visible and manageable from a single dashboard.