ajarbot/docs/README.md

# 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.