Context flow

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.

​

Context by execution mode

What the agent sees depends on which mode it’s running in. This matters for both understanding agent behavior and configuring background tasks effectively. The default background fork tool set (DEFAULT_BG_TOOLS) includes read-only file tools (Read, Glob, Grep scoped to ./**.md), the ollim-bot help and ollim-bot tasks * CLI commands, and the three reminder MCP tools (add_reminder, list_reminders, cancel_reminder). Discord MCP tools (ping_user, discord_embed, report_updates, follow_up_chain) are not in this static list — they are dynamically gated at runtime based on the job’s allow-ping and update-main-session flags. Jobs can expand the tool set via the allowed-tools YAML field — see Background forks.

​

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:

​

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. Updates are capped at 10 entries (MAX_PENDING_UPDATES). When a new update would exceed this limit, the oldest entries are dropped and a sentinel is prepended so the agent knows omission occurred — for example, “(3 earlier update(s) omitted — cap reached)”. The sentinel occupies one slot, leaving 9 slots for real entries. Whether a background fork is allowed or required to call report_updates depends on its update-main-session mode: When blocked is combined with allow-ping: true, reporting is disabled but direct pings remain available — see Background forks for when this combination is useful. A stop hook (require_report_hook) enforces these modes — see the enforcement table for details. 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 injected header varies by context to guide the agent’s behavior: When pending updates are injected into the main session, the bot also sends a user-visible note — “catching up on background activity…” — so you know background context is being included.

​

Prompt tags

Every routine, reminder, 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. 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

​

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: Each entry in the schedule includes:

​

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 a ForkLookup with the session ID (or None if expired/unknown) and an expired flag
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. When a reply targets an expired record, the bot signals this to the user (“this session has expired — starting fresh with quoted context”) and falls back to quoting the message content instead. If the user replies to a fork message while already in an interactive fork, the reply is added as context to the current fork rather than opening a new one.

​

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
• Instruction to acknowledge the follow-up nature in pings (e.g. “checking in again”) so the user knows it is intentional
• On the final check: the preamble warns that follow_up_chain is not available and applies a regret heuristic — the agent pings only if the task is still unresolved and the user would regret missing it, otherwise it calls report_updates. If follow_up_chain is called anyway, the tool returns an error with recovery guidance prompting escalation via ping_user.

Chain reminders inherit tool restrictions and skills from the parent via ChainContext, so allowed-tools and skills propagate through the entire chain.

​

Next steps