Reminders

Reminders inject hidden text into user messages to give the LLM situational awareness — current date, active skills, recent tool behavior, recurring instructions. The text is invisible to the user but visible to the model.

How Reminders Work

Every reminder attaches text to a user message. Two decisions control when and how:

1. When — immediate (at message creation) or conditional (at engine.save(), gated by a predicate)
2. How — inline (appended as a <system-reminder> tag inside the last text part) or as a separate text part

Immediate Reminders

Pass reminders directly to user(). They resolve at message creation time and receive the message content.

import { user, reminder } from '@deepagents/context';

// Static text
user('Hello', reminder('Keep responses under 100 words'));

// Factory — receives message content
user(
  'Explain polymorphism',
  reminder((ctx) => `User said: "${ctx.content}". Tailor to their level.`),
);

A factory that returns an empty string skips injection entirely — useful for conditional logic without the full predicate system.

user(
  'deploy to prod',
  reminder((ctx) =>
    ctx.content.includes('prod') ? 'Ask for confirmation before destructive actions' : ''
  ),
);

Inline vs Part Mode

Reminders render in one of two modes:

• Inline — appended as <system-reminder> tags to the last text part.
• Part — added as a separate text part on the user message.

The default depends on the input type:

Reminders default inline so the model sees the context next to the user's words. Set asPart to true when structured content needs to stay in a standalone text part:

const partMode = true;

reminder('hint'); // inline
reminder(workflow({ task: 'Deploy', steps: ['…'] })); // inline
reminder(workflow({ task: 'Deploy', steps: ['…'] }), { asPart: partMode }); // forced part

Use part mode for structured data (dates, skill lists, fragments) to keep reminder text separate from the user's message.

Conditional Reminders

Add a when predicate to create reminders that fire based on turn count, message content, assistant/tool history, token usage, or time. Pass them to engine.set(); the engine evaluates them at save() time.

import { reminder, everyNTurns, user } from '@deepagents/context';

engine.set(
  reminder('Remember to cite sources', { when: everyNTurns(3) }),
  user('Tell me about quantum computing'),
);

The engine applies conditional reminders to the last pending user message during save(). It builds a WhenContext with the current turn count, message content, usage totals, message counts, and recent assistant history, then evaluates each predicate.

import { reminder, contentIncludes, afterTurn, and, user } from '@deepagents/context';

// Only fires when user mentions code AND after the first 2 turns
engine.set(
  reminder('Include code examples in your response', {
    when: and(contentIncludes(['code', 'example', 'snippet']), afterTurn(2)),
  }),
  user('Show me how to use async/await'),
);

See Predicates for the full predicate catalog and composition rules.

Built-in Reminders

The library ships with pre-built reminders for common needs:

ReminderContext

Both immediate and conditional reminder factories receive a context object:

interface ReminderContext {
  content: string;            // Plain text of the user message
  turn?: number;              // Current user turn count
  lastMessageAt?: number;     // Timestamp of last persisted user message
  lastMessage?: UIMessage;    // Last persisted user message (with metadata)
  currentMessage?: UIMessage; // Pending user message for the current turn
  chat?: StoredChatData;      // Active chat record
  usage?: LanguageModelUsage; // Accumulated usage metadata
  branch?: string;            // Active branch name
  elapsed?: number;           // Milliseconds since last persisted user message
  messageCount?: number;      // Total message count across all roles
  lastAssistantMessage?: UIMessage; // Last persisted assistant message
}

Conditional reminders populate these fields at save() time. Immediate reminders receive only content.

Stripping Reminders

stripReminders() removes all reminder text and metadata from a message. Use it to display clean message history or export conversations.

import { stripReminders } from '@deepagents/context';

const clean = stripReminders(message);
// No <system-reminder> tags, no reminder metadata