Plugin OpenClaw Ecosystem

Time Awareness

Give your AI agents a real sense of time — what day it is, how long things take, and what happened before the context was compacted.

The Problem

LLMs are temporally blind

Language models have no built-in clock. They don't know today's date, can't tell how long a background job has been running, and lose their entire event history the moment the context window compacts. Time Awareness fixes all three problems with a 3-layer architecture exposed entirely over MCP.

Capabilities

Key Features

Temporal Context Injection

Auto-generates a rich time block for your agent's system prompt — current date, time, day of week, week number, and timezone — so every session starts time-aware.

Task Lifecycle Tracker

Register background tasks by name, poll for status with smart backoff intervals, detect stalls via configurable timeouts, and mark completion — all through MCP tool calls.

Temporal Event Log

Every significant event is appended to a persistent JSONL timeline on disk. The log survives context compaction, restarts, and agent swaps, giving you an immutable audit trail.

MCP Integration

All 10 tools are exposed over the Model Context Protocol at localhost:18070/mcp. Drop a single entry into claude_desktop_config.json and any MCP-compatible agent can call them natively.

Smart Polling

Built-in adaptive backoff prevents agents from hammering APIs while waiting for slow jobs. Polling intervals scale automatically with elapsed time, saving tokens and API quota.

Context-Compaction Survival

The event timeline lives outside the LLM context window. Even after compaction wipes short-term memory, agents can query_timeline to reconstruct exactly what happened and when.

Architecture

How It Works

Three independent layers, each solving a distinct piece of the time-blindness problem. Together they give agents complete temporal situational awareness.

Temporal Context Injection

Before any task runs, TCS generates a structured time block injected directly into the agent's system prompt. The agent always knows the current date, time, timezone, and week — no hallucination possible.

tcs context

Task Lifecycle Tracker

Long-running background jobs are registered by name. TCS tracks their start time, last poll time, and expected duration. Smart polling intervals prevent busy-loops; timeout detection surfaces stalled jobs.

tcs task start / poll / finish

Temporal Event Log

Every noteworthy event is appended to an on-disk JSONL timeline with a precise timestamp. The log is queryable by time range, event type, or full-text search — and survives context compaction intact.

tcs log / timeline

10 MCP Tools

All tools available at http://localhost:18070/mcp

get_temporal_context Get current time context — date, time, timezone, week number

start_task Register a background task for lifecycle tracking

poll_task Check if a task should be polled and record the check

finish_task Mark a task as completed or cancelled

list_tasks List all tasks, optionally filtered by status

check_timeouts Scan all running tasks for stalled or timed-out jobs

log_event Append an event to the persistent timeline

query_timeline Query events by time range, type, or source

search_events Full-text search across the event timeline

get_stats Get aggregate statistics on agent activity

Architecture Layers

MCP Tools

Persistent Timeline

Time Blindness

Coverage

What Gets Tracked

Six categories of temporal information that agents need but never had access to — until now.

Current Time & Date

Exact timestamp, day, week, and timezone injected into every agent context

Task Duration

Wall-clock elapsed time for every tracked task from start to finish

Background Jobs

Running tasks with smart polling intervals and timeout thresholds

Event History

Persistent JSONL timeline of every significant agent event

Polling Intervals

Adaptive backoff so agents don't hammer APIs waiting for results

Timeout Detection

Automatic alerting when a task exceeds its expected runtime

Quick Start

Up in 30 Seconds

Start the MCP server, then wire it into any MCP-compatible agent.

terminal

# Start the MCP server
./start-mcp.sh

# Or use the CLI directly
tcs context
tcs task start my-task --desc "Running analysis"
tcs timeline --since "1h ago"

~/.claude/claude_desktop_config.json

{
  "mcpServers": {
    "tcs": {
      "url": "http://localhost:18070/mcp"
    }
  }
}

Coming Soon

Join the Waitlist

Be the first to know when the managed Time Awareness plugin launches.

Join the Waitlist

Back to Plugins