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	30-second setup and basic agent usage	5 min
Complete Setup Guide	Comprehensive setup with API keys, config, troubleshooting	10 min

Core Systems

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

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

Configuration

Document	Description	Best For
Control & Configuration	Configuration management	Customizing behavior
Windows Deployment	Complete Windows setup guide	Windows users

---

⚠️ Note on Heartbeat System: The Heartbeat monitoring system is legacy and disabled by default. Use Pulse & Brain instead for 92% cost savings. Heartbeat documentation has been removed - see PULSE_BRAIN.md for the recommended approach.

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 (20 minutes)

For cost-effective production deployments:

1. Read Pulse & Brain Architecture - includes Quick Start section
2. Run example_bot_with_pulse_brain.py
3. Create custom pulse checks
4. Configure custom brain tasks

What you'll learn:

• Pulse checks (zero-cost monitoring)
• Conditional brain tasks (only when needed)
• Scheduled brain tasks (daily summaries)
• Cost optimization (92% savings vs traditional monitoring)

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:

• Quick Start section for immediate setup
• Why continuous polling is expensive ($0.48/day)
• How Pulse & Brain saves 92% ($0.04/day)
• Comparison with traditional monitoring (Heartbeat)
• 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 with Quick Start included.

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

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.

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, disabled by default)

See PULSE_BRAIN.md for details including comparison and migration guide.

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 (30 seconds)
├── PULSE_BRAIN.md                     # Monitoring guide (includes Quick Start & comparison)
├── README_ADAPTERS.md                 # Multi-platform adapters
├── README_MEMORY.md                   # Memory system
├── SKILLS_INTEGRATION.md              # Skills from messaging
├── SCHEDULED_TASKS.md                 # Task scheduling
├── CONTROL_AND_CONFIGURATION.md       # Configuration guide
├── WINDOWS_DEPLOYMENT.md              # Windows-specific setup
└── SECURITY_AUDIT_SUMMARY.md          # Security audit report

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.