@elizaos/plugin-timeline

A plugin for ElizaOS that captures and displays the agent's thinking process tied to individual users.

Overview

The Timeline plugin automatically captures the agent's internal reasoning, thoughts, and decision-making process for every user interaction. It stores these as timeline entries that can be retrieved to show users their interaction history along with what the agent was "thinking" at each step.

Features

• Automatic Capture: Evaluator that runs after every response to capture thinking data
• User-Specific Timelines: Each user gets their own timeline of interactions
• Rich Context: Captures thoughts, actions taken, providers used, questions, and responses
• Timeline Provider: Displays timeline history for the current user
• Statistics: Provides analytics on interaction patterns

What Gets Captured

For each user interaction, the plugin captures:

• Thought Process: The agent's internal reasoning (e.g., "User asking about 0xea17df... which is an EVM address...")
• Actions Taken: What actions the agent decided to execute (e.g., ["REPLY", "SEARCH"])
• Providers Used: What context providers were consulted (e.g., ["KNOWLEDGE", "WALLET"])
• Question: The original user question
• Response: The agent's response text
• Timestamp: When the interaction occurred

Example

User Question:

What do you think of 0xea17df5cf6d172224892b5477a16acb111182478

Agent Response:

thats elizaos on evm chains
eliza labs official token that migrated from ai16z on solana
deployed on ethereum base and bsc as 0xea17Df5Cf6D172224892B5477A16ACb111182478
legitimate infrastructure token

What Gets Captured:

{
  thought: "User asking about 0xea17df5cf6d172224892b5477a16acb111182478 which is an EVM address (Ethereum format). From my knowledge base, this is the elizaos token address on EVM networks (Ethereum, Base, BSC). This is Eliza Labs' official token that migrated from ai16z on Solana. It's legitimate infrastructure, not a scam. I'll acknowledge what it is and note it's our official token on EVM chains.",
  actions: ["REPLY"],
  providers: ["KNOWLEDGE"],
  questionText: "What do you think of 0xea17df5cf6d172224892b5477a16acb111182478",
  responseText: "thats elizaos on evm chains..."
}

Installation

bun add @elizaos/plugin-timeline

Usage

Basic Setup

Add the plugin to your agent configuration:

import { timelinePlugin } from '@elizaos/plugin-timeline';

const agent = {
  // ... other config
  plugins: [
    timelinePlugin,
    // ... other plugins
  ],
};

Accessing Timeline Data

The timeline provider automatically makes timeline data available in the agent's context:

// The USER_TIMELINE provider will be available in prompts
// It shows the last 10 interactions with thinking process

Querying Timeline Programmatically

import { getTimelineEntries } from '@elizaos/plugin-timeline';

// Get timeline for a specific user
const timeline = await getTimelineEntries(runtime, userId, 50);

// Timeline entries include:
timeline.forEach(entry => {
  console.log(`Question: ${entry.questionText}`);
  console.log(`Thought: ${entry.thought}`);
  console.log(`Actions: ${entry.actions.join(', ')}`);
  console.log(`Response: ${entry.responseText}`);
});

Architecture

Components

1. Timeline Capture Evaluator (TIMELINE_CAPTURE)

   • Runs after every agent response
   • Extracts thought process from response content
   • Stores as timeline entry linked to user

2. Timeline Provider (USER_TIMELINE)

   • Retrieves timeline entries for current user
   • Formats timeline for display
   • Provides statistics on interaction patterns

Database

Timeline entries are stored in the timeline table with the following structure:

{
  id: UUID;
  entityId: UUID;      // User who asked the question
  agentId: UUID;       // Agent who responded
  roomId: UUID;        // Conversation room
  content: {
    thought: string;   // Agent's thinking process
    actions: string[]; // Actions taken
    providers: string[]; // Providers consulted
    questionText: string; // Original question
    responseText: string; // Agent's response
  };
  metadata: {
    type: 'timeline-entry';
    timestamp: number;
    tags: string[];
  };
}

Configuration

No additional configuration required. The plugin works out of the box.

API

REST Endpoints

The plugin provides RESTful API endpoints to query timeline data:

Get Timeline for Entity

GET /api/agents/:agentId/plugins/timeline/timeline/entity/:entityId?limit=50

Parameters:

• entityId (required): UUID of the user/entity
• limit (optional): Number of entries to return (1-1000, default: 50)

Response:

{
  "success": true,
  "data": {
    "entityId": "uuid-here",
    "count": 10,
    "entries": [
      {
        "id": "entry-uuid",
        "entityId": "user-uuid",
        "agentId": "agent-uuid",
        "roomId": "room-uuid",
        "timestamp": 1699900000000,
        "thought": "User asking about...",
        "actions": ["REPLY"],
        "providers": ["KNOWLEDGE"],
        "questionText": "What do you think of...",
        "responseText": "thats elizaos on evm chains..."
      }
    ]
  }
}

Get Timeline Statistics

GET /api/agents/:agentId/plugins/timeline/timeline/entity/:entityId/stats

Parameters:

• entityId (required): UUID of the user/entity

Response:

{
  "success": true,
  "data": {
    "entityId": "uuid-here",
    "stats": {
      "totalEntries": 42,
      "timeRange": {
        "start": 1699800000000,
        "end": 1699900000000
      },
      "mostCommonActions": [
        { "action": "REPLY", "count": 35 },
        { "action": "SEARCH", "count": 7 }
      ],
      "mostCommonProviders": [
        { "provider": "KNOWLEDGE", "count": 20 },
        { "provider": "WALLET", "count": 15 }
      ]
    }
  }
}

Get Recent Timelines

GET /api/agents/:agentId/plugins/timeline/timeline/recent?limit=20

Parameters:

• limit (optional): Number of recent entries (1-100, default: 20)

Response:

{
  "success": true,
  "data": {
    "count": 20,
    "entries": [...]
  }
}

TypeScript Types

interface TimelineEntry {
  id: UUID;
  entityId: UUID;
  agentId: UUID;
  roomId: UUID;
  timestamp: number;
  thought: string;
  actions: string[];
  providers?: string[];
  questionText?: string;
  responseText?: string;
}

interface TimelineStats {
  totalEntries: number;
  timeRange: { start: number; end: number };
  mostCommonActions: Array<{ action: string; count: number }>;
  mostCommonProviders: Array<{ provider: string; count: number }>;
}

Development

# Install dependencies
bun install

# Build
bun run build

# Watch mode for development
bun run dev

# Clean build artifacts
bun run clean

Use Cases

1. User Understanding: See what the agent was thinking when responding to users
2. Debugging: Track decision-making process for troubleshooting
3. Transparency: Show users what context and reasoning informed responses
4. Analytics: Understand interaction patterns and common action sequences
5. Training Data: Collect examples of reasoning for model fine-tuning

License

MIT

Contributing

Contributions welcome! Please open an issue or PR on the main ElizaOS repository.