Skip to main content

queryEvents

codebolt.episodicMemory.queryEvents(params: IQueryEventsParams): Promise<IQueryEventsResponse>

Queries events from an episodic memory with optional filters for time range, type, agent, tags, and more.

Parameters​

Returns​

  • Promise<[IQueryEventsResponse](/docs/reference/codeboltjs/type-reference/codeboltjs/interfaces/IQueryEventsResponse)>: A promise that resolves to filtered events.

Examples​

Query All Events​

import codebolt from '@codebolt/codeboltjs';

// Wait for connection
await codebolt.waitForReady();

// Get all events from a memory
const result = await codebolt.episodicMemory.queryEvents({
    memoryId: 'memory-123'
});

if (result.success) {
    console.log(`✅ Found ${result.data.events.length} events`);
    console.log('Total events in memory:', result.data.total);
    console.log('Filtered:', result.data.filtered);
}

Query Recent Events​

import codebolt from '@codebolt/codeboltjs';

await codebolt.waitForReady();

// Get events from the last hour
const result = await codebolt.episodicMemory.queryEvents({
    memoryId: 'memory-123',
    lastMinutes: 60
});

console.log(`Events in the last hour: ${result.data.events.length}`);

// Get events from the last 24 hours
const dayResult = await codebolt.episodicMemory.queryEvents({
    memoryId: 'memory-123',
    lastMinutes: 1440 // 24 hours
});

Query Last N Events​

import codebolt from '@codebolt/codeboltjs';

await codebolt.waitForReady();

// Get the 10 most recent events
const result = await codebolt.episodicMemory.queryEvents({
    memoryId: 'memory-123',
    lastCount: 10
});

console.log('Last 10 events:');
result.data.events.forEach((event, index) => {
    console.log(`${index + 1}. [${event.event_type}] ${event.timestamp}`);
});

Query by Event Type​

import codebolt from '@codebolt/codeboltjs';

await codebolt.waitForReady();

// Get only error events
const errors = await codebolt.episodicMemory.queryEvents({
    memoryId: 'memory-123',
    event_type: 'error'
});

console.log(`Found ${errors.data.events.length} error events`);

// Get only task completion events
const completed = await codebolt.episodicMemory.queryEvents({
    memoryId: 'memory-123',
    event_type: 'task_completed'
});

Query by Tags​

import codebolt from '@codebolt/codeboltjs';

await codebolt.waitForReady();

// Get events tagged with 'backend'
const backendEvents = await codebolt.episodicMemory.queryEvents({
    memoryId: 'memory-123',
    tags: ['backend']
});

// Get events with multiple tags (AND logic)
const criticalBackendEvents = await codebolt.episodicMemory.queryEvents({
    memoryId: 'memory-123',
    tags: ['backend', 'critical']
});

console.log(`Critical backend events: ${criticalBackendEvents.data.events.length}`);

Query by Agent​

import codebolt from '@codebolt/codeboltjs';

await codebolt.waitForReady();

// Get events from a specific agent
const agentEvents = await codebolt.episodicMemory.queryEvents({
    memoryId: 'memory-123',
    emitting_agent_id: 'agent-001'
});

console.log(`Agent activity: ${agentEvents.data.events.length} events`);

Query Since Timestamp​

import codebolt from '@codebolt/codeboltjs';

await codebolt.waitForReady();

// Get events since a specific time
const result = await codebolt.episodicMemory.queryEvents({
    memoryId: 'memory-123',
    since: '2024-01-15T10:00:00Z'
});

console.log(`Events since Jan 15: ${result.data.events.length}`);

Complex Query with Multiple Filters​

import codebolt from '@codebolt/codeboltjs';

await codebolt.waitForReady();

// Complex query: backend errors from last hour by specific agent
const result = await codebolt.episodicMemory.queryEvents({
    memoryId: 'memory-123',
    event_type: 'error',
    tags: ['backend', 'production'],
    emitting_agent_id: 'agent-003',
    lastMinutes: 60
});

console.log('Filtered results:');
result.data.events.forEach(event => {
    console.log(`- [${event.timestamp}] ${event.payload}`);
});

Query Swarm Events​

import codebolt from '@codebolt/codeboltjs';

await codebolt.waitForReady();

// Query events at the swarm level
const result = await codebolt.episodicMemory.queryEvents({
    swarmId: 'swarm-123',
    team_id: 'team-456',
    lastCount: 20
});

console.log('Swarm team events:', result.data.events.length);

Response Structure​

{
    success: boolean,
    requestId?: string,
    data?: {
        events: Array<{
            id: string,
            event_type: string,
            emitting_agent_id: string,
            team_id?: string,
            tags?: string[],
            payload: string | Record<string, any>,
            timestamp: string
        }>,
        total: number,
        filtered: boolean
    },
    error?: {
        code: string,
        message: string,
        details?: any
    }
}

Common Use Cases​

1. Recent Activity Get the most recent events for dashboards.

2. Error Analysis Query and analyze error events.

3. Agent Monitoring Track specific agent activity over time.

4. Tag-Based Filtering Find events by topic or category.

5. Time Windows Analyze events within specific time ranges.

Notes​

  • Either memoryId or swarmId must be provided
  • Filters are combined with AND logic (all must match)
  • Multiple tags means the event must have all specified tags
  • Events are returned in chronological order (oldest first)
  • lastCount and lastMinutes are mutually exclusive
  • total reflects the count before filtering
  • filtered indicates if any filters were applied
  • For pagination, combine filters with count limits
  • Timestamps should be in ISO 8601 format
  • Empty result is returned if no events match