Hello {{name}}, enjoy {{discount}}% off
\",\n globalVariables: { discount: \"20\" }\n});\n\n// Send marketing campaign with tracking\nawait skill.tools.find(t => t.name === 'send_marketing_campaign')?.handler({\n campaignName: \"Q2-Product-Launch\",\n recipients: marketingList,\n subject: \"New Product Launch\",\n htmlBody: campaignTemplate,\n trackingPixel: true // Enable open tracking\n});\n```\n\n## API Reference\n\n### Tools\n\n#### `synchronize_project_state`\nSynchronize and cache current project state across all agents.\n\n**Input:**\n- `projectId` (string, required): Project identifier\n- `includeGit` (boolean): Include git state\n- `cacheTTL` (number): Cache TTL in milliseconds\n\n#### `query_cache`\nQuery the distributed project cache with vector similarity.\n\n**Input:**\n- `query` (string, required): Cache query\n- `limit` (number): Result limit (default: 10)\n\n#### `coordinate_agents`\nCoordinate multi-agent execution with task routing.\n\n**Input:**\n- `workflowId` (string, required): Workflow identifier\n- `topology` (enum, required): \"hierarchical\" | \"mesh\" | \"adaptive\"\n- `tasks` (array, required): Task definitions\n\n#### `analyze_performance`\nAnalyze swarm and cache performance metrics.\n\n**Input:**\n- `timeRange` (string, required): Time range (e.g., \"1h\", \"24h\")\n- `metrics` (array): Specific metrics to analyze\n\n#### `send_email`\nSend secure emails with template variable support.\n\n**Input:**\n- `recipients` (array, required): Email recipients with name (optional)\n- `subject` (string, required): Email subject with {{variable}} placeholders\n- `htmlBody` (string, required): HTML email body\n- `textBody` (string): Plain text alternative\n- `variables` (object): Variables for template interpolation\n\n#### `send_bulk_email`\nSend bulk emails to multiple recipients with per-recipient customization.\n\n**Input:**\n- `recipients` (array, required): Recipients with per-recipient variables\n- `subject` (string, required): Email subject\n- `htmlBody` (string, required): HTML body\n- `textBody` (string): Plain text alternative\n- `globalVariables` (object): Variables applied to all recipients\n\n#### `send_marketing_campaign`\nSend marketing campaigns with optional open tracking.\n\n**Input:**\n- `campaignName` (string, required): Campaign identifier\n- `recipients` (array, required): Campaign recipients\n- `subject` (string, required): Campaign subject\n- `htmlBody` (string, required): Campaign HTML\n- `textBody` (string): Plain text alternative\n- `trackingPixel` (boolean): Enable open tracking (default: false)\n\n#### `verify_email_configuration`\nCheck email service status and configuration.\n\n**Input:** None (no parameters)\n\n## Architecture\n\n### Core Components\n\n1. **SwarmOrchestrator**: Manages agent pools and task assignment\n2. **MemorySystem**: Distributed caching with vector search\n3. **TaskOrchestrator**: Coordinates task execution across agents\n4. **CacheService**: Persistent state management\n5. **SessionManager**: Session lifecycle and state persistence\n\n### Topologies\n\n| Topology | Best For | Agents |\n|----------|----------|--------|\n| hierarchical | Anti-drift, tight control | 3+ |\n| mesh | Distributed tasks | 5+ |\n| adaptive | Variable workloads | 5-15 |\n| ring | Sequential workflows | Any |\n| star | Simple coordination | Any |\n\n## Performance Characteristics (v0.2.0)\n\n### Benchmarks\n- **Cache Hit Rate**: 70-90% (maintained across deployments)\n- **Task Latency**: <100ms for simple operations\n- **Agent Utilization**: 95%+ with work-stealing\n- **Memory**: Bounded at 100K entries (~100MB), no OOM risk\n\n### v0.2.0 Performance Improvements\n\n#### LRU Cache Eviction\n- Prevents unbounded memory growth (was major OOM risk)\n- Automatic eviction when cache exceeds max size (default 100K entries)\n- Trades older entries for new data automatically\n- **Impact:** 24h+ deployments now stable; memory stays <100MB\n\n#### Batch Persistence\n- Sequential file I/O optimized with batch writing (100 entries per write)\n- Change from JSON to JSONL format for streaming\n- **Impact:** 10K entries: 100-500s → 1-5s (100x faster recovery)\n\n#### Fast Vector Search\n- Replaced O(n*m²) Levenshtein distance with hierarchical indexing\n- Token-based inverted index + Jaccard similarity\n- Early candidate selection via length bucketing\n- **Impact:** \n - 1K entries: 20-50ms → <5ms (10x faster)\n - 10K entries: 200-500ms → 5-20ms (50-100x faster)\n - 100K entries: 2-5s → 10-50ms (100-500x faster)\n\n#### Query Rate Limiting\n- Token bucket rate limiter on vector search (1000 qps default)\n- Prevents cascade failures from hot queries\n- **Impact:** System remains responsive under peak load\n\n#### Work-Stealing Load Balancing\n- Fast agents automatically steal tasks from overloaded slow agents\n- Periodic rebalancing every 1 second\n- Predictive completion time calculation\n- **Impact:** Heterogeneous swarms see 2-4x throughput improvement\n\n### Scaling Capabilities\n- **Safe without tuning:** <100K cache entries\n- **Recommended max:** 100K cache entries with LRU\n- **Typical swarm size:** 5-20 agents (linear scaling to 50 agents)\n- **Throughput:** 1000+ operations/second (cache ops + task assignments)\n\n## 🔐 Security & Best Practices\n\nSyncPulse email features follow security best practices:\n\n- **No Hardcoded Secrets**: All credentials managed via environment variables\n- **SMTP TLS/SSL**: Encrypted connections to mail servers\n- **Secure Defaults**: Passwords never logged or exposed in errors\n- **Per-Recipient Tracking**: Anonymous campaign analytics\n- **Rate Limiting**: Built-in support for bulk email throttling\n\nSee [SECURE_EMAIL_SETUP.md](./SECURE_EMAIL_SETUP.md) for detailed security guidance.\n\n## 📚 Documentation\n\n- **[SECURE_EMAIL_SETUP.md](./SECURE_EMAIL_SETUP.md)** - Complete email configuration and security guide\n- **[AGENT_INTEGRATION.md](./AGENT_INTEGRATION.md)** - Integrate email tools with Claude agents\n- **[README.md](./README.md)** - SyncPulse features and API reference\n\n## Development\n\n```bash\nnpm run build\nnpm test\n```\n\n## License\n\nApache-2.0 - See LICENSE in the repository\n","readmeFilename":"README.md"}