Cipher features a sophisticated two-tier event system that provides comprehensive monitoring, debugging, and integration capabilities. The system tracks both service-level events (global to the Cipher instance) and session-level events (scoped to individual conversations).

​
Architecture Overview

The event system consists of multiple interconnected components:

​
Event Types

​
Service Events (Global)

Service events track the lifecycle and operations of the Cipher instance:

​
Cipher Lifecycle

  • cipher:started - Cipher instance started
  • cipher:stopped - Cipher instance stopped
  • cipher:error - Critical error occurred

​
Service Management

  • cipher:serviceStarted - Individual service initialized
  • cipher:serviceError - Service encountered an error
  • cipher:allServicesReady - All services are ready

​
Tool Operations

  • cipher:toolRegistered - Tool registered successfully
  • cipher:toolUnregistered - Tool unregistered
  • cipher:toolError - Tool execution error

​
MCP Connections

  • cipher:mcpClientConnected - MCP client connected
  • cipher:mcpClientDisconnected - MCP client disconnected
  • cipher:mcpClientError - MCP connection error

​
Memory Operations

  • cipher:memoryOperationStarted - Memory operation initiated
  • cipher:memoryOperationCompleted - Memory operation completed
  • cipher:memoryOperationFailed - Memory operation failed

​
Vector Store

  • cipher:vectorStoreConnected - Vector store connected
  • cipher:vectorStoreDisconnected - Vector store disconnected
  • cipher:vectorStoreError - Vector store error

​
LLM Providers

  • cipher:llmProviderRegistered - LLM provider registered
  • cipher:llmProviderError - LLM provider error

​
Session Events (Conversation-Scoped)

Session events track individual conversation interactions:

​
Session Lifecycle

  • session:created - New session created
  • session:activated - Session activated
  • session:deactivated - Session deactivated
  • session:expired - Session expired
  • session:deleted - Session deleted

​
Tool Execution

  • tool:executionStarted - Tool execution started
  • tool:executionCompleted - Tool execution completed
  • tool:executionFailed - Tool execution failed

​
LLM Interactions

  • llm:thinking - LLM processing started
  • llm:responseStarted - LLM response generation started
  • llm:responseCompleted - LLM response completed
  • llm:responseError - LLM response error

​
Memory Operations

  • memory:stored - Memory item stored
  • memory:retrieved - Memory items retrieved
  • memory:searched - Memory search performed

​
Conversation Management

  • conversation:messageAdded - Message added to conversation
  • conversation:messageUpdated - Message updated
  • conversation:cleared - Conversation cleared

​
Context Management

  • context:updated - Context updated
  • context:truncated - Context truncated

​
Configuration

​
Environment Variables

The event system supports environment variables for configuration: 
# Enable event filtering
EVENT_FILTERING_ENABLED=true

# Filter specific event types (comma-separated)
EVENT_FILTERED_TYPES=cipher:error,tool:executionFailed,llm:responseError

# Event persistence configuration
EVENT_PERSISTENCE_ENABLED=true
EVENT_PERSISTENCE_PATH=/custom/events/path

# Node environment (affects event manager behavior)
NODE_ENV=production

​
YAML Configuration

Event system settings can be configured in your cipher.yml under the eventPersistence section: 
eventPersistence:
  enabled: true
  storageType: file
  filePath: ./data/events
  maxEvents: 50000
  rotationSize: 10485760
  retentionDays: 7
Configuration Options:
  • enabled: Enable/disable event persistence (default: true)
  • storageType: Storage backend type - ‘file’ or ‘memory’ (default: ‘file’)
  • filePath: Path for file storage (default: ’./data/events’)
  • maxEvents: Maximum number of events to store (optional)
  • rotationSize: File size before rotation in bytes (optional)
  • retentionDays: Number of days to retain events (optional)
Configuration Precedence:
  1. Environment variables take highest priority
  2. YAML configuration is used as fallback
  3. Default values are used if neither is specified

​
Event Schema

​
JSON Schema

Events are stored in JSONL format (events-YYYY-MM-DD.jsonl) with this structure: 
{
  "id": "uuid-string",
  "type": "event:type",
  "data": { /* event-specific payload */ },
  "metadata": {
    "timestamp": 1234567890,
    "sessionId": "session-123",
    "source": "service-name",
    "priority": "normal",
    "tags": ["tag1", "tag2"],
    "eventManagerId": "manager-uuid"
  }
}

​
Event Filtering

Control which events are processed via environment variables or programmatic filters: 
# .env file
EVENT_FILTERING_ENABLED=true
EVENT_FILTERED_TYPES=cipher:error,tool:executionFailed,llm:responseError,session:expired