Text2SQL - Natural Language to SQL

Atomic reminders that inject time-aware context into user messages, each firing only when its value has actually changed

Temporal reminders inject date, time, and locale context into user messages on a need-to-know basis. Each atom has its own temporal schedule and only fires when its value crosses a boundary — so dateReminder skips if the day hasn't changed, seasonReminder skips if the season hasn't changed, and so on.

Temporal Atoms

Five atoms cover time-derived facts. Each accepts { tz?: string }, renders inline, and computes diffs purely from lastMessageAt — no metadata storage. When tz is omitted, the atom resolves the timezone from message metadata; see Timezone resolution.

dateReminder

Fires when dayChanged(tz). Outputs the current date and day of week.

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

dateReminder(); // UTC
dateReminder({ tz: 'America/New_York' });

Output on first turn:

Date: 2026-04-03
Day of Week: Thursday

Output when day changes:

date: 2026-04-02 -> 2026-04-03
day of week: Wednesday -> Thursday

Date: 2026-04-03
Day of Week: Thursday

timeReminder

Fires when hourChanged(tz). Outputs the current time with an hour-level diff.

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

timeReminder();
timeReminder({ tz: 'Asia/Tokyo' });

Output when hour changes:

hour: 14 -> 15

Time: 15:05:00

monthReminder

Fires when monthChanged(tz).

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

monthReminder();

Diff: month: March -> April

yearReminder

Fires when yearChanged(tz).

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

yearReminder();

Diff: year: 2026 -> 2027

seasonReminder

Fires when seasonChanged(tz). Seasons: Winter (Dec-Feb), Spring (Mar-May), Summer (Jun-Aug), Fall (Sep-Nov).

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

seasonReminder();

Diff: season: Spring -> Summer

localeReminder

Unlike temporal atoms, locale (language + timezone) is user configuration that can't be derived from a timestamp. localeReminder renders a "Language / Timezone" line into the user message and stores those values in message metadata for next-turn diffs.

It is not the source of truth for timezone resolution on the current turn — see Timezone resolution below.

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

localeReminder(); // defaults: English (US), UTC
localeReminder({ language: 'Arabic (SA)', timeZone: 'Asia/Riyadh' });

Parameter	Type	Default	Description
`language`	`string`	`English (US)`	User's language
`timeZone`	`string`	`UTC`	User's timezone

Fires on the first turn (no previous locale) or when the config changes. Skips if unchanged.

Output when locale changes:

language: English (US) -> Arabic (SA)
timezone: UTC -> Asia/Riyadh

Language: Arabic (SA)
Timezone: Asia/Riyadh

Timezone resolution

When a temporal atom is constructed without { tz }, it resolves the timezone in this order:

options.tz passed to the atom
metadata.locale.timeZone on the current user message (visible on turn 1)
metadata.locale.timeZone on the last persisted user message (kept for backward continuity)
'UTC' fallback

To make turn-1 timezone work, attach metadata.locale to the user message itself:

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

engine.set(
  dateReminder(),
  user({
    role: 'user',
    parts: [{ type: 'text', text: 'hi' }],
    metadata: { locale: { language: 'Japanese', timeZone: 'Asia/Tokyo' } },
  }),
);

language and timeZone flow through identically — user-defined reminders can read either off ctx.currentMessage.metadata.locale (current turn) or ctx.lastMessage.metadata.locale (prior turn).

localeReminder alone won't propagate tz on turn 1

localeReminder({ timeZone: 'Asia/Tokyo' }) writes locale metadata at resolution time, after whenCtx has already been built and other reminders have evaluated. On the very first turn this means tz-less temporal atoms still see UTC. Put metadata.locale on the user message directly when you need turn-1 visibility.

temporalReminder

Convenience wrapper that returns all 5 temporal atoms as a ContextFragment[]. Does not include localeReminder — add it separately if needed.

import { temporalReminder, localeReminder } from '@deepagents/context';

// Temporal only
engine.set(...temporalReminder({ tz: 'UTC' }), user('hello'));

// Temporal + locale
engine.set(
  ...temporalReminder({ tz: 'Asia/Riyadh' }),
  localeReminder({ language: 'Arabic (SA)', timeZone: 'Asia/Riyadh' }),
  user('hello'),
);

Parameter	Type	Default	Description
`tz`	`string`	`UTC`	Timezone passed to all 5 atoms

Predicates and Custom Reminders

Each temporal atom uses a predicate from the when scheduling system (e.g., dayChanged, hourChanged). These predicates — along with turn-based, content-based, and boolean combinators — are documented in Predicates.

Temporal Reminders