> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ollim.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How ollim-bot works

> Understand the agent loop, session persistence, fork model, and context flow.

ollim-bot is a Claude-powered agent that runs as a Discord bot.
Understanding four core concepts — the agent loop, session
persistence, forks, and context flow — will help you get the
most out of it.

## The agent loop

Every message you send follows the same path through the system:

<Steps>
  <Step title="Message received">
    Discord delivers your DM to the bot, which
    acquires a lock to ensure one conversation at a time.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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).
  </Step>

  <Step title="Response streamed">
    The response streams to Discord in real time, with throttled
    edits to stay within rate limits. Messages exceeding 2000
    characters overflow into follow-up messages automatically.
  </Step>
</Steps>

The agent lock ensures messages are processed sequentially — if
you send a new message while the agent is responding, the current
response is interrupted and the new message takes over.

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

Each event records a timestamp and parent session ID, creating a
traceable lineage of conversation branches.

### 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](/core-usage/forks) for interactive fork usage, exit
strategies, and idle timeouts. See
[Background forks](/scheduling/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 via `report_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](/architecture/context-flow) for the full
pending updates cycle, background preamble, and reply-to-fork
mechanics.

## Next steps

<Columns cols={2}>
  <Card title="Design philosophy" icon="lightbulb" href="/architecture/design-philosophy">
    The principles and tradeoffs behind ollim-bot's architecture.
  </Card>

  <Card title="Forks" icon="code-branch" href="/core-usage/forks">
    Deep dive into interactive and background forks.
  </Card>

  <Card title="Real-world examples" icon="lightbulb" href="/scheduling/examples">
    See how routines, reminders, and chains compose into a
    full daily system.
  </Card>

  <Card title="Conversations" icon="comments" href="/core-usage/conversations">
    The DM interface, mentions, and message handling.
  </Card>
</Columns>