Skip to main content
Context in ollim-bot moves through a cycle: the main session feeds into forks, forks produce pending updates, and pending updates flow back into the main session. Background forks receive additional context through a preamble that includes ping budgets, forward schedules, and tool restrictions.

​
Overview

Every interaction starts in the main session. When a fork branches off, it inherits the main session’s conversation history. When a background task fires, it receives an assembled preamble with scheduling awareness. When either type of fork finishes, it can feed results back to the main session through pending updates — short summaries that get prepended to the next interaction. The flow forms a loop:
  1. Main session receives user messages with any pending updates prepended
  2. Interactive forks branch from main, peek at pending updates (read-only)
  3. Background forks branch from main (or start fresh if isolated), receive a preamble with budget and schedule context
  4. Forks write back to the main session via report_updates
  5. Main session pops those updates on the next interaction

​
Pending updates

Pending updates are the primary channel for passing context from forks back to the main session. They are stored in ~/.ollim-bot/state/pending_updates.json as a JSON array of timestamped messages. Each entry is a PendingUpdate with two fields:
FieldTypeDescription
tsstrISO 8601 timestamp in the configured timezone
messagestrSummary text written by the agent

​
Write path

Any fork can write a pending update by calling the report_updates MCP tool. The write is protected by an async lock for concurrent background fork safety — multiple forks can safely append updates without corruption. Whether a background fork is allowed or required to call report_updates depends on its update_main_session mode:
ModeBehavior
on_pingReport if the agent sent a ping or embed (default)
alwaysMust call report_updates before fork exits
freelyReporting is optional
blockedreport_updates returns an error
A stop hook (require_report_hook) enforces these modes. In always mode, the hook blocks the fork from terminating if report_updates wasn’t called. In on_ping mode, it blocks if the agent pinged but didn’t report.

​
Read path

The main session and forks read pending updates differently:
The main session pops pending updates — reads and clears the file atomically. The updates are prepended to the next message the agent sees, giving it context about what happened in the background.After the pop, the file is deleted. Each update is consumed exactly once.

​
Prompt tags

Every scheduled task and fork injects a tag at the start of its prompt. These tags tell the agent what type of session it’s in and which task triggered it.
Tag patternSession type
[routine:ID]Foreground routine (runs in main session)
[routine-bg:ID]Background routine (runs in a fork)
[reminder:ID]Foreground reminder (runs in main session)
[reminder-bg:ID]Background reminder (runs in a fork)
[fork-started]Interactive fork resumed from a bg session
The agent’s system prompt documents how to interpret these tags. For foreground tasks, only the tag and the task’s markdown body are injected. For background tasks, the tag is followed by the full preamble.

​
Background fork preamble

Background forks receive an assembled preamble between the prompt tag and the task’s markdown body. The preamble is built by build_bg_preamble in scheduling/preamble.py and contains several sections.

​
Preamble sections

Tells the agent whether ping_user and discord_embed are available. When allow_ping is false, the agent is told these tools are disabled.
Based on the update_main_session mode, tells the agent when and whether to call report_updates. Each mode has specific instructions (must report, report if pinged, optional, or blocked).
If the user is mid-conversation (the agent lock is held), the preamble instructs the agent to use report_updates instead of direct pings — unless critical=True. This prevents interruptions during active conversations.
Included only when allow_ping is true. Contains:
  • Current ping budget status (available tokens, capacity)
  • Upcoming schedule: a list of tasks within the schedule window, each with fire time, label, description, and file path
  • Refill estimation before the last scheduled task
  • Guidance on when to ping vs. report (the “regret test”)
  • Note about critical=True bypass
Listed only when allowed_tools or disallowed_tools are configured. Shows which tools are available or excluded.

​
Forward schedule

The budget section includes a forward schedule built by build_upcoming_schedule. This gives the agent awareness of what other background tasks are coming, so it can make informed decisions about whether to spend a ping budget token now or save it. Schedule construction uses a dynamic window:
ParameterValuePurpose
Grace window15 minutesIncludes recently-fired routines
Base window3 hoursInitial forward-looking window
Min forward count3Extends window if fewer than 3 tasks found
Maximum window12 hoursHard upper limit on lookahead
Each entry in the schedule includes:
FieldDescription
fire_timeWhen the task fires
labelDisplay name (e.g., “Chain reminder (2/4)“)
descriptionFrom YAML or truncated message (60 char limit)
file_pathRelative path (e.g., routines/daily-review.md)
silentWhether allow_ping=False for this task
tag"this task", "just fired", or None

​
Reply-to-fork context

Replying to a message sent by a background fork starts an interactive fork that resumes from that background fork’s session. This is how context flows from a background task back into an interactive conversation. The mechanism relies on fork session tracking in sessions.py:
  1. Before a background fork runs, start_message_collector() initializes a contextvar-scoped list
  2. When streamer.py, ping_user, or discord_embed sends a Discord message, track_message(message_id) records it
  3. After the fork completes, flush_message_collector(fork_id, parent_id) writes the mapping to ~/.ollim-bot/state/fork_messages.json
  4. When a user replies to one of those messages, lookup_fork_session(message_id) returns the fork session ID
  5. The bot creates an interactive fork that resumes from that session
Records in fork_messages.json have a 7-day TTL and are pruned on read.
Replying to a non-fork message works differently — the replied-to message’s content is quoted and prepended as context (plain text from .content, or title + description + fields from the first embed, truncated to 500 characters).

​
Chain reminder context

Chain reminders inject additional context into their prompts. When a reminder has max_chain > 0, the preamble includes:
  • The current check number and total (e.g., “check 2/4”)
  • Whether follow_up_chain(minutes_from_now=N) is available
  • On the final check: a warning that this is the last chance and no follow-up can be scheduled
Chain reminders inherit tool restrictions from the parent via ChainContext, so allowed_tools and disallowed_tools propagate through the entire chain.

​
Next steps

Session management

Session IDs, lifecycle events, and compaction.

Background forks

Isolated mode, model overrides, and tool restrictions.

Forks

Interactive forks, exit strategies, and idle timeout.

Ping budget

Refill-on-read budget for background fork pinging.