Bot Temporal Grounding

Give an always-on gateway bot a clock so it can reason about ‘now’, gaps, and relative-time requests

Prefix each inbound message with its arrival time so the agent can answer “remind me in 2 hours” or “what did I say this morning?”.

Quick Start

1. Enable timestamps in your gateway config

   Add one line under session: to stamp every inbound turn:

   # gateway.yaml
   channels:
     telegram:
       platform: telegram
       token: "${TELEGRAM_BOT_TOKEN}"
       session:
         timestamps: true       # enable arrival-time prefix
   
   agent:
     name: assistant
     instructions: "You are a helpful assistant. Use the time prefix on each message to interpret relative-time requests."
     model: gpt-4o-mini
   

   Run with:

   praisonai gateway start gateway.yaml
   

   The model now sees each turn with its real arrival time:

   [Fri 2026-07-09 10:15 UTC] Remind me in 2 hours to call mum.
   
2. Customise the template

   session:
     timestamps: true
     timestamp_template: "[%Y-%m-%d %H:%M] "   # drop weekday and timezone
   

   The template must contain a YYYY-MM-DD HH:MM date-time — the replay de-dup regex anchors on it. The %a weekday and %Z timezone are optional, so non-English server locales are safe.

---

How It Works

The session manager strips any stale prefix and re-stamps each turn with its real arrival time before the agent sees it.

Behavior	Detail
Scope	Applied to both per_user (DM) and per_chat (group) turns
Group ordering	The time sits outermost, after sender attribution — e.g. [Fri 2026-07-09 10:15 UTC] [alice] hello
Replay-safe	Leading prefixes are stripped and re-rendered each turn, so compaction / reset never accumulates [ts] [ts] … text
Fallback	Without a platform receive time, a timezone-aware UTC now() is used so %Z renders UTC
Fail-open	On a strftime error the raw un-stamped content is returned — a bad template never breaks chat

---

Configuration Options

Set these under session: in your channel config.

Option	Type	Default	Description
timestamps	bool	False	When true, each inbound turn is prefixed with its arrival time. Off by default for prompt-cache stability
timestamp_template	str	"[%a %Y-%m-%d %H:%M %Z] "	strftime template for the prefix. Must contain a YYYY-MM-DD HH:MM date-time — the replay de-dup regex anchors on it

Keep timestamps off unless the agent needs relative-time reasoning. Every stamped turn is billed again on replay, and the changing prefix breaks prompt caching.

---

Common Patterns

Relative-time reminders — the model reads the prefix to resolve “in 2 hours” against a real clock:

session:
  timestamps: true
agent:
  instructions: "Resolve relative-time requests using the time prefix on each message."

Group chats — pair with per_chat scope; the timestamp sits outermost so sender attribution stays intact:

session:
  session_scope: per_chat
  timestamps: true

The agent sees: [Fri 2026-07-09 10:15 UTC] [alice] when's the launch?

Minimal prefix — drop the weekday and timezone to save tokens:

session:
  timestamps: true
  timestamp_template: "[%Y-%m-%d %H:%M] "

---

Best Practices

Enable it only when you need a clock

Leave timestamps off for bots that never reason about time. The prefix changes on every turn, so it disrupts prompt caching and adds tokens to each replayed message. Turn it on for scheduling, reminders, or gap-aware assistants.

Keep the template short

Every character in the prefix is billed on every replayed turn. "[%Y-%m-%d %H:%M] " is enough for most agents; the default adds the weekday and timezone for readability.

Keep the date-time in custom templates

A custom timestamp_template must render a YYYY-MM-DD HH:MM inside the bracket — the replay de-dup regex anchors on that date-time, not on the English weekday. Templates that omit %a (or run under non-English locales) stay safe.

Let the session manager stamp turns

Don’t hand-format time prefixes in instructions. The session manager strips and re-stamps each turn so replay de-dup works; a manual prefix bypasses that and accumulates on history replay.

---

Related

Per-Chat Session Scope

Share one transcript across a group — the scope this feature stacks on top of

Session Compaction

How stamped turns survive history compaction

Bot Gateway

Top-level gateway config that owns the session: block

Chat

Chat-level docs where received_at shows up