The agent loop
Every message you send follows the same path through the system:Message received
Discord delivers your DM to the bot, which
acquires a lock to ensure one conversation at a time.
Context prepended
Before your message reaches the agent, a timestamp and any
pending background updates are prepended. Main session messages
clear the pending updates file after reading; fork messages
peek without clearing.
Agent processes
The agent sends the enriched message to Claude. It has access
to Discord tools (
discord_embed, ping_user, save_context,
report_updates, enter_fork, exit_fork, follow_up_chain,
update_names, add_reminder, list_reminders, cancel_reminder),
a docs server for self-referencing documentation,
Bash commands (ollim-bot tasks, ollim-bot cal, etc.),
file operations, web tools, and five subagents (ollim-bot-guide, gmail-reader,
history-reviewer, responsiveness-reviewer, user-proxy).Session persistence
ollim-bot maintains a single persistent conversation with Claude across restarts. This is the foundation of its contextual understanding.How sessions work
The Claude Agent SDK assigns a session ID to each conversation. ollim-bot persists this ID to~/.ollim-bot/state/sessions.json (a
plain text file containing just the session ID string). On
restart, the bot resumes from this saved session using
resume=session_id.
When the conversation context grows too large, the SDK
auto-compacts it — summarizing older messages while preserving
meaning. The session ID changes on compaction, and ollim-bot
detects and logs this automatically.
Session lifecycle events
Every session state change is logged to~/.ollim-bot/state/session_history.jsonl as an append-only record:
| Event | Trigger |
|---|---|
created | First message (no prior session exists) |
compacted | Auto-compaction (session ID changed) |
swapped | Fork promoted to main via save_context |
cleared | /clear command resets conversation |
interactive_fork | Interactive fork created |
bg_fork | Background fork created |
isolated_bg | Isolated background fork (no history) |
restarting | Bot is restarting (recorded before exit) |
Key commands
/clear— resets the conversation entirely (drops client, deletes session ID)/compact [instructions]— manually triggers context compaction with optional guidance
The fork model
Forks let the agent branch off the main conversation to handle separate tasks without polluting the primary context. ollim-bot has two types: interactive forks that you enter and exit manually, and background forks that run routines and reminders autonomously. After a fork ends, you choose what happens to the context — save it to the main session, report a summary, or discard it entirely. This keeps the main conversation clean while enabling deep tangential work. See Forks for interactive fork usage, exit strategies, and idle timeouts. See Background forks for routine and reminder configuration.Context flow
Context flows between the main session and forks through a file-based bridge. Background forks can report summaries back to the main session viareport_updates, which are prepended to the
next user message. This ensures background work surfaces naturally
without requiring the user to check anything.
Every message the agent receives is also enriched with a timestamp
in the configured timezone (OLLIM_TIMEZONE), giving the agent
consistent time awareness.
See Context flow for the full
pending updates cycle, background preamble, and reply-to-fork
mechanics.
Next steps
Design philosophy
The principles and tradeoffs behind ollim-bot’s architecture.
Forks
Deep dive into interactive and background forks.
Real-world examples
See how routines, reminders, and chains compose into a
full daily system.
Conversations
The DM interface, mentions, and message handling.