The agent loop
Every message you send follows the same path through the system:Message received
Discord delivers your DM to
bot.py, which
acquires the agent 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
agent.py sends the enriched message to the Claude Agent SDK
client. The agent has access to MCP tools (discord_embed,
ping_user, save_context, report_updates, enter_fork,
exit_fork, follow_up_chain), Bash commands
(ollim-bot tasks, ollim-bot cal, etc.), file operations,
web tools, and three subagents (gmail-reader,
history-reviewer, responsiveness-reviewer).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 | SDK 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) |
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 scheduled tasks 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 scheduled task 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 Pacific time, giving the agent consistent time awareness.
See Context flow for the full
pending updates cycle, background preamble, and reply-to-fork
mechanics.