Predicates

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

engine.set(reminder('Stay concise', { when: everyNTurns(3) }), user('hello'));

interface WhenContext {
  turn: number;
  content: string;
  lastMessageAt?: number;
  lastMessage?: UIMessage;
  currentMessage: UIMessage;
  chat: StoredChatData;
  usage?: LanguageModelUsage;
  branch: string;
  elapsed?: number;
  messageCount: number;
  lastAssistantMessage?: UIMessage;
  lastAssistantMessages?: UIMessage[];
  lastAssistantReplies?: UIMessage[];
  toolOutcome?: ToolOutcome;
  firedOnceIds?: ReadonlySet<string>;
  onceCollector?: Set<string>;
}

everyNTurns(3); // fires on turns 3, 6, 9, 12, ...

first(); // fires on turn 1 only

firstN(5); // fires on turns 1, 2, 3, 4, 5

afterTurn(2); // fires on turns 3, 4, 5, ...

contentIncludes(['deploy', 'release', 'ship']);
// fires when user says "let's deploy" or "ship it"

contentPattern(/\b(SELECT|INSERT|UPDATE|DELETE)\b/i);
// fires when user includes SQL keywords

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

engine.set(
  reminder('Consider indexing strategies', {
    when: contentMatches(['database optimization', 'query performance']),
  }),
);

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

const classifier = new BM25Classifier([
  { name: 'auth', description: 'authentication and authorization' },
  { name: 'data', description: 'database and data modeling' },
]);

engine.set(
  reminder('Check related skills', {
    when: classifies(classifier, { threshold: 0.1 }),
  }),
);

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

lastAssistantLength({ gte: 2_000 }); // assistant reply is at least 2,000 chars
lastAssistantLength({ eq: 0 }); // assistant reply is empty

type CountSpec = { gte?: number; lte?: number; eq?: number };

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

engine.set(
  reminder('Recover from the failed command', {
    target: 'tool-output',
    when: toolOutput({
      name: 'bash',
      state: 'output-error',
      errorText: (text) => text.includes('permission denied'),
    }),
  }),
);

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

toolCalled('bash');
toolCalled((name) => name.startsWith('http_'));

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

toolFailed('bash');

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

anyToolCalled();

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

toolCall({
  name: 'bash',
  state: 'output-error',
  errorText: (text) => text.includes('permission denied'),
});

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

toolCallCount('bash', { gte: 3 });
toolCallCount('sql', { eq: 1 });

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

engine.set(
  reminder('`bash` keeps failing — change the command, do not retry it.', {
    when: toolFailedStreak('bash', { gte: 3 }),
    target: 'tool-output',
  }),
);

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

engine.set(
  reminder(
    (ctx) => {
      const failures = toolFailureStreak(ctx, 'bash');
      return failures > 3
        ? `\`bash\` has failed ${failures} times in a row. Stop and explain the blocker.`
        : `\`bash\` failed ${failures} times in a row. Change the command.`;
    },
    { when: toolFailedStreak('bash', { gte: 1 }), target: 'tool-output' },
  ),
);

import { and, once, reminder, toolOutput } from '@deepagents/context';

engine.set(
  reminder('Explain the first tool failure', {
    target: 'tool-output',
    when: and(toolOutput({ state: 'output-error' }), once('first-tool-error')),
  }),
);

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

usageExceeds(10_000);

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

elapsedExceeds(60_000); // one minute

import { dayChanged, hourChanged } from '@deepagents/context';

dayChanged(); // resolves tz from message metadata, else UTC
dayChanged({ tz: 'America/New_York' }); // explicit Eastern time
hourChanged({ tz: 'Asia/Tokyo' }); // explicit JST

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

engine.set(
  localeReminder({ language: 'Japanese', timeZone: 'Asia/Tokyo' }),
  reminder('Day rolled over', { when: dayChanged() }),
  user('hello'),
);

import { toolFailed, withinLastN } from '@deepagents/context';

withinLastN(5, toolFailed('bash'));

import { anyToolCalled, everyOfLastN, not } from '@deepagents/context';

everyOfLastN(3, not(anyToolCalled()));

import { afterTurn, and, dayChanged } from '@deepagents/context';

and(dayChanged(), afterTurn(3));
// day changed AND past turn 3

import { dayChanged, hourChanged, or } from '@deepagents/context';

or(dayChanged(), hourChanged());
// day OR hour changed

import { dayChanged, not } from '@deepagents/context';

not(dayChanged());
// day has NOT changed

and(or(dayChanged(), hourChanged()), not(first()), afterTurn(2));

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

const businessHours: WhenPredicate = (ctx) => {
  const hour = new Date().getHours();
  return hour >= 9 && hour < 17;
};

engine.set(
  reminder('User is likely at work — keep responses professional', {
    when: businessHours,
  }),
);

const isHighPriority: WhenPredicate = async (ctx) => {
  const priority = await classifyPriority(ctx.content);
  return priority === 'high';
};

import { contentIncludes, hint, reminder, workflow } from '@deepagents/context';

// Inject a workflow as a reminder when the user mentions errors
engine.set(
  reminder(
    workflow({
      task: 'Error recovery',
      steps: ['Read error message', 'Check schema', 'Fix query'],
    }),
    { when: contentIncludes(['error', 'fail']) },
  ),
  user('my query failed'),
);

// Works with any fragment type
engine.set(
  reminder(hint('Check indexes for slow queries'), {
    when: contentIncludes(['slow']),
  }),
  user('this query is slow'),
);

// Always-on fragment reminder (no `when`): a user-target reminder with no
// predicate fires on every turn.
engine.set(
  reminder(workflow({ task: 'Greet', steps: ['Say hi'] })),
  user('hello'),
);

engine.set(
  reminder(
    (ctx) => {
      if (!ctx.lastMessageAt) return 'Session started.';
      const hours = Math.floor((Date.now() - ctx.lastMessageAt) / 3600000);
      return `${hours}h since last message.`;
    },
    { when: dayChanged(), asPart: false },
  ),
);