CLIO-bot

An AI-powered Discord community bot backed by CLIO.

CLIO-bot gives your server a smart, persistent AI companion. It learns from your community's chat history, remembers preferences, events, and people, and participates in conversations naturally. Everything - the bot's name, personality, commands, and behavior - is driven by configuration files with no hardcoded assumptions.

---

Features

• AI chat - @mention the bot or use !ask. Maintains per-channel conversation sessions with persistent long-term memory
• Community knowledge base - !scan reads channel history and builds a searchable markdown knowledge file; !remember adds facts manually
• Group profile - Track your server's home city, favorite spots, and member identities
• Weather - !weather and !forecast, optionally powered by OpenWeatherMap
• Reminders and countdowns - !remind 2h check the oven; themed countdown timers; recurring daily/weekly events
• Cards Against Humanity - Full game loop with rotating czar; automatically enabled when you add deck files, automatically disabled when you don't
• MadLibs - AI-generated stories with configurable themes
• Polls - Create multi-option polls with reaction voting and automatic result tallying
• XP / leveling - Passive XP for active members, leaderboard, level-up announcements
• Votekick - Democratic muting or kicking requiring a configurable vote threshold
• Dice, 8-ball - !roll 2d6, !8ball
• Knowledge base admin - !kb, !remember, !recall, !unlearn
• LTM admin - Inspect and manage the AI's long-term memory

---

Quick Start

1. Prerequisites

• Python 3.12 or later
• CLIO installed and on your PATH (or specify the path in config)
• A Discord bot token (how to get one)

2. Install

git clone https://github.com/SyntheticAutonomicMind/clio-bot
cd clio-bot
pip install -r requirements.txt

3. Configure

cp config.json.example config.json

At minimum, edit these fields in config.json:

{
  "bot": {
    "token": "YOUR_DISCORD_BOT_TOKEN",
    "name": "MyBot"
  },
  "ai": {
    "clio_path": "~/.local/clio/clio",
    "model": "github_copilot/gpt-4.1"
  }
}

See config.json.example for a full annotated reference.

4. Run

python bot/main.py

Or with a token override:

DISCORD_TOKEN=your_token python bot/main.py

5. Docker

docker build -t clio-bot .
docker run \
  -v $(pwd)/config.json:/app/config.json \
  -v $(pwd)/data:/app/data \
  clio-bot

---

Commands

All commands use the prefix configured in config.json (default: !). Slash commands are also registered where supported.

AI

Command	Description
!ask <question>	Ask the bot anything. Uses group context and knowledge base.
!think <topic>	Get the bot's opinion on a topic.
!food [details]	Restaurant recommendations. Uses web search near your group's location.
!activity [details]	Activity suggestions. Searches for current events and seasonal options.
!research <topic>	Web research with a concise summary.
!plan <event>	Help planning an event or outing.
!trip <destination>	Trip planning: hotels, activities, travel from your location.
@mention <message>	Talk to the bot naturally in conversation.

Memory

Command	Description
!scan [options]	Scan channel history and update the knowledge base.
!remember <fact>	Add a fact to the knowledge base manually.
!recall <query>	Search the knowledge base.
!unlearn <query>	Remove facts matching a query.

!scan options:

• !scan - scan the current channel
• !scan all - scan all accessible channels
• !scan fresh - bypass the message cache and re-fetch
• !scan food / !scan trips / !scan people - topic-focused scan

Group Profile

Command	Description
!setlocation <city>	Set the group's home location (used for weather and recommendations).
!location	Show the current location.
!addspot <name> | <category> | <notes>	Add a favorite place.
!spots [category]	List saved spots.
!removespot <name>	Remove a saved spot.
!setpref <key> <value>	Store a group preference.
!iam <name>	Tell the bot your real name.
!whoami	Show how the bot knows you.
!setalias @user <alias>	Add an alias for another user.
!whois <name>	Look up a user by any name or alias.
!upcoming	List upcoming scheduled events.

Reminders

Command	Description
!remind <time> <what>	Set a one-shot reminder. e.g. !remind 2h call dentist
!reminders	List all active tasks for this server.
!forget <id or name>	Cancel a task.
!reschedule <id> <time>	Change a task's notify time.
!task edit <id> <field> <value>	Edit any field of a task.

Reminder time formats: 30s, 5m, 2h, 1d, 1w

Weather

Command	Description
!weather [city]	Current conditions. Defaults to the group's set location.
!forecast [city]	5-day forecast.
!setlocation <city>	Persist the group's home city for weather lookups.

Games

Command	Description
!cah start [deck]	Start a Cards Against Humanity game. (Requires deck files.)
!cah join	Join the current game.
!cah begin	Lock players and start rounds.
!cah hand	View your hand (sent via DM).
!cah end	End the current game.
!cah decks	List available decks.
!cah scores	View current scores.
!madlibs [theme]	Start a MadLibs game.
!ml <word>	Submit a word during an active MadLibs game.
!roll [dice]	Roll dice. e.g. !roll 2d6, !roll d20
!8ball <question>	Ask the Magic 8-ball a yes/no question.

Community

Command	Description
!poll <question>	Create a reaction poll (interactive setup).
!poll list	List active polls.
!poll close <id>	Close a poll and post results.
!xp [@user]	Check XP and level.
!leaderboard	Top 10 XP leaderboard.
!vk @user [mute|kick]	Start a vote to mute or kick a member.

Admin

Command	Description
!kb stats	Knowledge base statistics.
!kb search <query>	Search the knowledge base (admin view).
!kb dump	Show the raw knowledge base.
!ltm list	List LTM categories (admin only).
!ltm search <query>	Search LTM.
!ltm clear <type>	Clear a category of LTM entries.

---

Customization

Bot Personality

Edit data/instructions.md to define how the bot talks and what it knows. This file is injected into every AI request as the system context. You can tell it:

• Who it is, what it's called, how it should speak
• What the group is about, shared in-jokes, norms
• What it should never do or say
• How to handle specific topics

See data/instructions.md for a well-commented starter template.

Cards Against Humanity

The CAH cog auto-enables when JSON deck files exist in decks/ and auto-disables when the directory is empty - no config change required.

Deck format:

{
  "name": "My Deck",
  "description": "Optional description",
  "whiteCards": [
    "A white card response.",
    "Another response."
  ],
  "blackCards": [
    {"text": "Fill in the blank: ___.", "pick": 1},
    {"text": "___ and ___ walk into a bar.", "pick": 2}
  ]
}

Place as many deck files as you like in decks/. Players choose which deck to play at game start.

MadLibs Themes

Edit madlibs/themes.json to add or modify themes:

[
  {
    "name": "adventure",
    "description": "An epic quest through a dangerous land",
    "word_types": ["hero's name", "magical item", "scary creature", "action verb", "place name"]
  }
]

If the file doesn't exist, a built-in generic theme is used.

Feature Flags

Disable individual features in config.json:

{
  "features": {
    "cah": false,
    "weather": true,
    "xp": false,
    "polls": true,
    "madlibs": true,
    "remind": true,
    "votekick": false
  }
}

---

Configuration Reference

See config.json.example for a fully annotated reference. The most important settings:

{
  "bot": {
    "name": "CLIO-bot",
    "prefix": "!",
    "token": "YOUR_DISCORD_BOT_TOKEN",
    "owner_ids": [123456789],
    "presence": "the community | !help"
  },
  "ai": {
    "clio_path": "~/.local/clio/clio",
    "model": "github_copilot/gpt-4.1",
    "tool_model": "github_copilot/gpt-4.1",
    "working_dir": "~/.local/share/clio-bot",
    "instructions_file": "data/instructions.md",
    "knowledge_file": "data/knowledge.md"
  },
  "weather": {
    "openweathermap_api_key": ""
  }
}

---

Architecture

See ARCHITECTURE.md for a full technical reference covering: component structure, data flows, AI protocol, session management, and how to extend the bot with new cogs.

---

Data Files

All persistent data is stored as plain JSON or Markdown:

File	Contents
data/instructions.md	Bot personality and system context
data/knowledge.md	Community knowledge base
data/user_identities.json	Discord ID to real name mappings
data/profiles/<server_id>.json	Per-server location and preferences
data/scheduled_tasks.json	Active reminders and recurring events
data/polls.json	Poll data
data/xp_data.json	XP and level data
decks/*.json	CAH deck files
madlibs/themes.json	MadLibs theme definitions

---

Requirements

• Python 3.12+
• discord.py >= 2.3.0
• aiohttp >= 3.9.0
• CLIO (AI backend)

Optional:

• OpenWeatherMap API key (for accurate weather data)

---

License

GPL-3.0-or-later. See source file headers for SPDX license declarations.

---

Acknowledgments

CLIO-bot's feature set was inspired by CorpBot by @CorpNewt be sure to check it out.