grambot

A minimal, composable AI agent framework with plugin-driven architecture.

Features

• Plugin system - Connectors, inference providers, tools, and image generators as plugins
• Session management - Per-channel message sequencing with persistent state
• Memory plugin - Searchable conversation history across sessions
• Cron scheduler - Timed message dispatch and scheduled actions
• Multi-provider inference - Anthropic Claude, OpenAI, and more
• Dashboard - React SPA for monitoring and control

Architecture

flowchart LR
  CLI[gram CLI] --> Engine[Engine]
  Engine --> Plugins[Plugin Manager]
  Plugins --> Connectors[Connectors]
  Plugins --> Inference[Inference Providers]
  Plugins --> Tools[Tool Resolver]
  Connectors -->|message| Sessions[Session Manager]
  Cron[Cron Scheduler] -->|message| Sessions
  Sessions --> InferenceRouter[Inference Router]
  InferenceRouter --> Tools
  Sessions --> Memory[Memory Plugin]
  Engine --> Socket[HTTP Socket API]
  Socket --> Dashboard[gram-dashboard]

Loading

Quick Start

# Install dependencies
yarn install

# Build the project
yarn build

# Start the engine
yarn gram start

Configuration

Grambot uses two configuration files in .scout/:

settings.json - Engine and plugin configuration

{
  "engine": { "socketPath": ".scout/scout.sock", "dataDir": ".scout" },
  "plugins": [
    { "instanceId": "telegram", "pluginId": "telegram", "enabled": true },
    { "instanceId": "anthropic", "pluginId": "anthropic", "enabled": true },
    { "instanceId": "memory", "pluginId": "memory", "enabled": true }
  ],
  "inference": {
    "providers": [{ "id": "anthropic", "model": "claude-sonnet-4-20250514" }]
  }
}

auth.json - API keys and tokens

{
  "telegram": { "type": "token", "token": "..." },
  "openai": { "type": "apiKey", "apiKey": "..." }
}

Plugins

Plugin	Type	Description
telegram	Connector	Telegram bot with long polling
openai	Inference	GPT models via OpenAI API
brave-search	Tool	Web search integration
gpt-image	Image	OpenAI image generation
nanobanana	Image	Alternative image provider
memory	Tool	Conversation memory and search

Tools

The AI agent has access to these tools:

• add_cron - Schedule recurring tasks
• memory_search - Query conversation history (memory plugin)
• web_search - Search the web (Brave)
• generate_image - Create images
• set_reaction - React to messages

CLI Commands

gram start                    # Launch the engine
gram status                   # Check engine status
gram add                      # Add a provider or plugin
gram plugins load <id>        # Load a plugin
gram plugins unload <id>      # Unload a plugin
gram auth set <id> <key> <value>         # Store a credential

Development

yarn install      # Install dependencies
yarn build        # Compile TypeScript
yarn test         # Run tests
yarn typecheck    # Type check without emit
yarn dev          # Run with tsx (no build)

Workspace

• packages/gram - Core engine, plugins, and tools
• packages/gram-dashboard - React dashboard + API proxy

Documentation

See docs/ for detailed documentation:

• Architecture - System overview
• Plugins - Plugin system
• Sessions - Session management
• Memory - Memory plugin
• Cron - Scheduled tasks
• Config - Configuration reference
• CLI - Command reference

License

MIT