Swarm Intelligence

Swarm intelligence enables agents to share knowledge and collaborate through a shared memory system.

Overview

┌─────────────────────────────────────────────────────┐
│                    Swarm Memory                      │
│                   (~/.moxxy/swarm.db)                │
├─────────────────────────────────────────────────────┤
│                                                      │
│   ┌─────────┐   ┌─────────┐   ┌─────────┐          │
│   │ Agent A │   │ Agent B │   │ Agent C │          │
│   │         │   │         │   │         │          │
│   │ [WRITE] │   │ [READ]  │   │ [READ]  │          │
│   └────┬────┘   └────┬────┘   └────┬────┘          │
│        │             │             │                │
│        └─────────────┼─────────────┘                │
│                      │                              │
│                      ▼                              │
│              ┌───────────────┐                      │
│              │  Shared Facts │                      │
│              │  • Alerts     │                      │
│              │  • Knowledge  │                      │
│              │  • Status     │                      │
│              └───────────────┘                      │
│                                                      │
└─────────────────────────────────────────────────────┘

How It Works

Announcing Facts

Agents can share information using the [ANNOUNCE] tag:

[ANNOUNCE] Production API is experiencing intermittent 503 errors since 10:30 UTC

This fact is:

1. Extracted from the agent's response
2. Stored in the shared swarm database
3. Made available to all other agents

Retrieving Facts

Agents automatically retrieve relevant swarm facts:

User: "Is there anything I should be aware of?"

Agent retrieves from swarm:
- Production API issues (from Agent A)
- New deployment scheduled (from Agent B)

Agent: I've found a couple of things from the team:
1. The production API is having intermittent issues
2. There's a deployment scheduled for 3pm

Use Cases

System Monitoring

Agent: Monitor

I've detected high CPU usage on the production server.
[ANNOUNCE] CPU usage alert: 95% on prod-server-1

Agent: Assistant (later)

User: Any system issues?

Agent: Yes, there's been a CPU alert on prod-server-1 showing 95% usage.

Knowledge Sharing

Agent: Researcher

I found that the API rate limit is 1000 requests/minute.
[ANNOUNCE] API rate limit confirmed at 1000 req/min

Agent: Developer (later)

User: What's the API rate limit?

Agent: According to research, it's 1000 requests per minute.

Task Coordination

Agent: Task Manager

Build #4521 started.
[ANNOUNCE] Build #4521 in progress - expected completion 15 minutes

Agent: Notifier

User: Any builds running?

Agent: Build #4521 is currently in progress.

Alert Broadcasting

Agent: Watchdog

[ANNOUNCE] CRITICAL: Database connection pool exhausted

All agents are now aware of this critical issue.

Architecture

Shared Database

Swarm memory is stored in a shared SQLite database:

~/.moxxy/swarm.db

Schema

CREATE TABLE swarm_facts (
    id INTEGER PRIMARY KEY,
    source_agent TEXT NOT NULL,
    content TEXT NOT NULL,
    embedding BLOB,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    expires_at DATETIME
);

Fact Properties

Property	Description
source_agent	Which agent announced it
content	The fact content
embedding	Vector embedding for search
created_at	When it was announced
expires_at	Optional expiration

Fact Lifecycle

Creation

1. Agent generates response with [ANNOUNCE]
2. Content is extracted
3. Embedding is created
4. Stored in swarm.db

Retrieval

1. Query is embedded
2. Similar facts are found
3. Top-k results are returned
4. Injected into agent context

Expiration

Facts can have an expiration time:

[ANNOUNCE:TTL=3600] Temporary issue resolved - will auto-expire in 1 hour

Expired facts are automatically cleaned up.

Configuration

Enable/Disable

Swarm is enabled by default. To disable:

moxxy run --agent default --prompt "Store 'false' in vault as swarm_enabled"

Fact Retention

Set how long facts are kept:

# Keep facts for 7 days
moxxy run --agent default --prompt "Store '7' in vault as swarm_retention_days"

Maximum Facts

Limit stored facts:

moxxy run --agent default --prompt "Store '1000' in vault as swarm_max_facts"

API Access

Get Swarm Facts

curl http://localhost:17890/api/swarm/facts

Search Swarm

curl -X POST http://localhost:17890/api/swarm/search \
  -H "Content-Type: application/json" \
  -d '{"query": "production issues", "limit": 10}'

Add Fact Manually

curl -X POST http://localhost:17890/api/swarm/facts \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Manual fact entry",
    "source_agent": "admin",
    "ttl_seconds": 86400
  }'

Clear Swarm

curl -X DELETE http://localhost:17890/api/swarm/facts

Agent Delegation

Agents can delegate tasks to other agents:

Using delegate_task

Ask the researcher agent to investigate the API documentation

This triggers:

1. delegate_task skill is invoked
2. Target agent receives the task
3. Target agent processes and responds
4. Result is returned to original agent

Example Flow

User: "Research the competitor's pricing"

Agent A: I'll delegate this to the researcher agent.
<invoke name="delegate_task">["researcher", "Research competitor pricing"]</invoke>

[Agent B (researcher) activates]
Agent B: I'll research the competitor's pricing...
[processes task]
Result: Competitor pricing is $X for basic, $Y for pro...

[Back to Agent A]
Agent A: Based on the research, the competitor charges...

Privacy Considerations

What Gets Shared

• Shared: Facts explicitly announced with [ANNOUNCE]
• Not Shared: Private conversations, secrets, personal data

Agent Isolation

Each agent still maintains:

• Private memory (STM/LTM)
• Private vault
• Private skills

Opt-Out

To prevent an agent from participating in swarm:

moxxy run --agent private_agent --prompt "Store 'false' in vault as swarm_participate"

Best Practices

What to Announce

Good:

• System alerts and status
• Important discoveries
• Team-relevant knowledge
• Task progress updates

Avoid:

• User personal information
• Sensitive credentials
• Temporary/fluid information

TTL Usage

Use appropriate TTLs:

[ANNOUNCE:TTL=300] Server rebooting in 5 minutes
[ANNOUNCE:TTL=3600] Brief outage resolved
[ANNOUNCE:TTL=86400] New deployment version: v2.3.1
[ANNOUNCE] Permanent config change (no expiration)

Naming Conventions

Prefix facts for clarity:

[ANNOUNCE] ALERT: High memory usage
[ANNOUNCE] INFO: Deployment complete
[ANNOUNCE] TASK: Build started
[ANNOUNCE] CONFIG: Rate limit updated

Troubleshooting

Facts Not Appearing

1. Check swarm is enabled:

   sqlite3 ~/.moxxy/swarm.db "SELECT COUNT(*) FROM swarm_facts;"

2. Verify agent participation:

   moxxy run --agent default --prompt "Is swarm participation enabled?"

Old Facts Persisting

1. Check retention settings
2. Manually clean old facts:

   sqlite3 ~/.moxxy/swarm.db "DELETE FROM swarm_facts WHERE created_at < datetime('now', '-7 days');"

Search Not Working

1. Verify embeddings:

   sqlite3 ~/.moxxy/swarm.db "SELECT COUNT(*) FROM swarm_facts WHERE embedding IS NOT NULL;"

2. Check embedding model configuration