Jordan Ramos
a99799bf3d
Features: - Multi-platform bot (Slack, Telegram) - Memory system with SQLite FTS - Tool use capabilities (file ops, commands) - Scheduled tasks system - Dynamic model switching (/sonnet, /haiku) - Prompt caching for cost optimization Optimizations: - Default to Haiku 4.5 (12x cheaper) - Reduced context: 3 messages, 2 memory results - Optimized SOUL.md (48% smaller) - Automatic caching when using Sonnet (90% savings) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
285 lines
8.3 KiB
Markdown
285 lines
8.3 KiB
Markdown
# Ajarbot Documentation
|
|
|
|
Complete documentation for Ajarbot - a lightweight, cost-effective AI agent framework.
|
|
|
|
## Quick Navigation
|
|
|
|
### Getting Started (Start Here)
|
|
|
|
| Document | Description | Time to Read |
|
|
|----------|-------------|--------------|
|
|
| [Quick Start Guide](QUICKSTART.md) | 30-second setup and basic agent usage | 5 min |
|
|
| [Pulse & Brain Quick Start](QUICK_START_PULSE.md) | Set up efficient monitoring in minutes | 5 min |
|
|
|
|
### Core Systems
|
|
|
|
| Document | Description | Best For |
|
|
|----------|-------------|----------|
|
|
| [Pulse & Brain Architecture](PULSE_BRAIN.md) | Cost-effective monitoring (92% savings) | Production monitoring, homelab |
|
|
| [Memory System](README_MEMORY.md) | SQLite-based memory management | Understanding context/memory |
|
|
| [Scheduled Tasks](SCHEDULED_TASKS.md) | Cron-like task scheduling | Daily briefings, reports |
|
|
| [Heartbeat Hooks](HEARTBEAT_HOOKS.md) | Proactive health monitoring | System health checks |
|
|
|
|
### Platform Integration
|
|
|
|
| Document | Description | Best For |
|
|
|----------|-------------|----------|
|
|
| [Adapters Guide](README_ADAPTERS.md) | Multi-platform messaging (Slack, Telegram) | Running bots on chat platforms |
|
|
| [Skills Integration](SKILLS_INTEGRATION.md) | Claude Code skills from messaging platforms | Advanced bot capabilities |
|
|
|
|
### Advanced Topics
|
|
|
|
| Document | Description | Best For |
|
|
|----------|-------------|----------|
|
|
| [Control & Configuration](CONTROL_AND_CONFIGURATION.md) | Configuration management | Customizing behavior |
|
|
| [Monitoring Comparison](MONITORING_COMPARISON.md) | Choosing monitoring approaches | Optimizing costs |
|
|
|
|
## Learning Paths
|
|
|
|
### Path 1: Simple Agent (10 minutes)
|
|
|
|
Perfect for quick prototypes or single-user use:
|
|
|
|
1. Read [Quick Start Guide](QUICKSTART.md)
|
|
2. Run `example_usage.py`
|
|
3. Explore [Memory System](README_MEMORY.md)
|
|
|
|
**What you'll learn:**
|
|
- Basic agent setup
|
|
- Memory operations
|
|
- Task management
|
|
- Model switching
|
|
|
|
### Path 2: Multi-Platform Bot (20 minutes)
|
|
|
|
For running bots on Slack, Telegram, or both:
|
|
|
|
1. Read [Quick Start Guide](QUICKSTART.md)
|
|
2. Read [Adapters Guide](README_ADAPTERS.md)
|
|
3. Run `bot_runner.py --init`
|
|
4. Configure platforms in `config/adapters.local.yaml`
|
|
5. Run `bot_runner.py`
|
|
|
|
**What you'll learn:**
|
|
- Platform adapter setup
|
|
- Multi-platform message routing
|
|
- User mapping across platforms
|
|
- Custom preprocessors/postprocessors
|
|
|
|
### Path 3: Production Monitoring (30 minutes)
|
|
|
|
For cost-effective production deployments:
|
|
|
|
1. Read [Pulse & Brain Quick Start](QUICK_START_PULSE.md)
|
|
2. Read [Pulse & Brain Architecture](PULSE_BRAIN.md)
|
|
3. Run `example_bot_with_pulse_brain.py`
|
|
4. Create custom pulse checks
|
|
5. Read [Monitoring Comparison](MONITORING_COMPARISON.md)
|
|
|
|
**What you'll learn:**
|
|
- Pulse checks (zero-cost monitoring)
|
|
- Conditional brain tasks (only when needed)
|
|
- Scheduled brain tasks (daily summaries)
|
|
- Cost optimization (92% savings)
|
|
|
|
### Path 4: Advanced Features (45 minutes)
|
|
|
|
For full-featured production bots:
|
|
|
|
1. Complete Path 2 and Path 3
|
|
2. Read [Scheduled Tasks](SCHEDULED_TASKS.md)
|
|
3. Read [Skills Integration](SKILLS_INTEGRATION.md)
|
|
4. Run `example_bot_with_skills.py`
|
|
5. Create custom skills
|
|
|
|
**What you'll learn:**
|
|
- Task scheduling with cron syntax
|
|
- Skills from messaging platforms
|
|
- Custom skill creation
|
|
- Security best practices
|
|
|
|
## Document Summaries
|
|
|
|
### QUICKSTART.md
|
|
30-second setup guide covering:
|
|
- Installation (pip install)
|
|
- Basic agent usage
|
|
- Memory operations
|
|
- Task tracking
|
|
- Context retrieval
|
|
|
|
**Key takeaway:** Get an agent running with memory in under a minute.
|
|
|
|
### PULSE_BRAIN.md
|
|
Comprehensive guide to the Pulse & Brain architecture:
|
|
- Why continuous polling is expensive ($0.48/day)
|
|
- How Pulse & Brain saves 92% ($0.04/day)
|
|
- Default pulse checks and brain tasks
|
|
- Custom configuration examples
|
|
- Real-world use cases (homelab, Docker monitoring)
|
|
|
|
**Key takeaway:** Run proactive monitoring at 1/10th the cost.
|
|
|
|
### README_ADAPTERS.md
|
|
Multi-platform adapter system:
|
|
- Architecture overview
|
|
- Slack setup (Socket Mode)
|
|
- Telegram setup (polling)
|
|
- User mapping across platforms
|
|
- Adding new adapters
|
|
- Comparison with OpenClaw
|
|
|
|
**Key takeaway:** Run one bot on multiple platforms simultaneously.
|
|
|
|
### SKILLS_INTEGRATION.md
|
|
Claude Code skills in messaging platforms:
|
|
- Architecture overview
|
|
- Enabling skills in bots
|
|
- Creating custom skills
|
|
- Security best practices
|
|
- Skill arguments and metrics
|
|
|
|
**Key takeaway:** Invoke local Claude Code skills from Slack/Telegram.
|
|
|
|
### SCHEDULED_TASKS.md
|
|
Cron-like task scheduling:
|
|
- Task scheduler setup
|
|
- Schedule syntax (daily, weekly, cron)
|
|
- Recurring vs one-time tasks
|
|
- Task callbacks and error handling
|
|
- Multi-platform task routing
|
|
|
|
**Key takeaway:** Schedule recurring bot activities (reports, briefings, etc.).
|
|
|
|
### HEARTBEAT_HOOKS.md
|
|
Proactive health monitoring:
|
|
- Heartbeat system overview
|
|
- Built-in checks (memory, disk, logs)
|
|
- Custom health checks
|
|
- Alert conditions
|
|
- Integration with adapters
|
|
|
|
**Key takeaway:** Traditional monitoring approach (consider Pulse & Brain for better cost efficiency).
|
|
|
|
### README_MEMORY.md
|
|
SQLite-based memory system:
|
|
- Memory architecture
|
|
- SOUL (personality) management
|
|
- User preferences
|
|
- Task system
|
|
- Full-text search (FTS5)
|
|
- Conversation history
|
|
|
|
**Key takeaway:** Automatic context loading with fast retrieval.
|
|
|
|
### CONTROL_AND_CONFIGURATION.md
|
|
Configuration management:
|
|
- Configuration file structure
|
|
- Environment variables
|
|
- Adapter configuration
|
|
- Pulse & Brain configuration
|
|
- Security considerations
|
|
|
|
**Key takeaway:** Centralized configuration for all components.
|
|
|
|
### MONITORING_COMPARISON.md
|
|
Choosing the right monitoring:
|
|
- Heartbeat vs Pulse & Brain
|
|
- Cost comparison
|
|
- Use case recommendations
|
|
- Migration guide
|
|
|
|
**Key takeaway:** Decision matrix for monitoring approaches.
|
|
|
|
## Common Questions
|
|
|
|
### Q: Which monitoring system should I use?
|
|
|
|
**A:** Use **Pulse & Brain** for production. It's 92% cheaper and more flexible.
|
|
|
|
- **Pulse & Brain**: ~$1-2/month (recommended)
|
|
- **Heartbeat**: ~$15/month (legacy)
|
|
|
|
See [Monitoring Comparison](MONITORING_COMPARISON.md) for details.
|
|
|
|
### Q: Can I run my bot on multiple platforms?
|
|
|
|
**A:** Yes! See [Adapters Guide](README_ADAPTERS.md).
|
|
|
|
Example: Run the same bot on Slack and Telegram simultaneously with unified memory.
|
|
|
|
### Q: How does memory work?
|
|
|
|
**A:** Agent automatically loads:
|
|
1. SOUL.md (personality)
|
|
2. users/{username}.md (user preferences)
|
|
3. Search results (top 3 relevant chunks)
|
|
4. Recent conversation (last 5 messages)
|
|
|
|
See [Memory System](README_MEMORY.md) for details.
|
|
|
|
### Q: How do I schedule recurring tasks?
|
|
|
|
**A:** Use TaskScheduler. See [Scheduled Tasks](SCHEDULED_TASKS.md).
|
|
|
|
```python
|
|
task = ScheduledTask("morning", "Daily brief", schedule="08:00")
|
|
scheduler.add_task(task)
|
|
scheduler.start()
|
|
```
|
|
|
|
### Q: Can I use skills from messaging platforms?
|
|
|
|
**A:** Yes! See [Skills Integration](SKILLS_INTEGRATION.md).
|
|
|
|
From Slack: `@bot /code-review src/agent.py`
|
|
|
|
### Q: Which LLM providers are supported?
|
|
|
|
**A:** Currently:
|
|
- Claude (Anthropic) - Primary
|
|
- GLM (z.ai) - Alternative
|
|
|
|
Model switching: `agent.switch_model("glm")`
|
|
|
|
## File Organization
|
|
|
|
```
|
|
docs/
|
|
├── README.md # This file - navigation hub
|
|
├── QUICKSTART.md # Start here
|
|
├── QUICK_START_PULSE.md # Pulse & Brain quick start
|
|
├── PULSE_BRAIN.md # Detailed Pulse & Brain guide
|
|
├── README_ADAPTERS.md # Multi-platform adapters
|
|
├── README_MEMORY.md # Memory system
|
|
├── SKILLS_INTEGRATION.md # Skills from messaging
|
|
├── SCHEDULED_TASKS.md # Task scheduling
|
|
├── HEARTBEAT_HOOKS.md # Legacy heartbeat
|
|
├── CONTROL_AND_CONFIGURATION.md # Configuration guide
|
|
└── MONITORING_COMPARISON.md # Monitoring approaches
|
|
```
|
|
|
|
## Getting Help
|
|
|
|
If you can't find what you're looking for:
|
|
|
|
1. Check the [main README](../README.md) for overview
|
|
2. Run the examples in the project root
|
|
3. Review test files (`test_*.py`)
|
|
4. Open an issue on GitHub
|
|
|
|
## Contributing to Documentation
|
|
|
|
When adding new documentation:
|
|
|
|
1. Add entry to this index
|
|
2. Update relevant learning paths
|
|
3. Add to common questions if applicable
|
|
4. Follow existing document structure
|
|
5. Include code examples
|
|
6. Add to appropriate section
|
|
|
|
---
|
|
|
|
**Happy building!** Start with the [Quick Start Guide](QUICKSTART.md) and explore from there.
|