ajarbot/docs

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	30-second setup and basic agent usage	5 min
Pulse & Brain Quick Start	Set up efficient monitoring in minutes	5 min

Core Systems

Document	Description	Best For
Pulse & Brain Architecture	Cost-effective monitoring (92% savings)	Production monitoring, homelab
Memory System	SQLite-based memory management	Understanding context/memory
Scheduled Tasks	Cron-like task scheduling	Daily briefings, reports
Heartbeat Hooks	Proactive health monitoring	System health checks

Platform Integration

Document	Description	Best For
Adapters Guide	Multi-platform messaging (Slack, Telegram)	Running bots on chat platforms
Skills Integration	Claude Code skills from messaging platforms	Advanced bot capabilities

Advanced Topics

Document	Description	Best For
Control & Configuration	Configuration management	Customizing behavior
Monitoring Comparison	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
2. Run example_usage.py
3. Explore Memory System

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
2. Read Adapters Guide
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
2. Read Pulse & Brain Architecture
3. Run example_bot_with_pulse_brain.py
4. Create custom pulse checks
5. Read Monitoring Comparison

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
3. Read Skills Integration
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 for details.

Q: Can I run my bot on multiple platforms?

A: Yes! See Adapters Guide.

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 for details.

Q: How do I schedule recurring tasks?

A: Use TaskScheduler. See Scheduled Tasks.

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.

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 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 and explore from there.