ASO Documentation

Appearance

Register

Timeline System ​

Last Updated: 2025-01-16
Primary Source: docs/project_status.md
Service File: backend/src/services/timelineEvent.service.ts
Model: backend/src/models/timeline.model.ts

Overview ​

The Timeline System creates a chronological record of all interactions, serving as the "emotional backbone" of the relationship between the player and the AI. Every interaction adds a fragment to the shared timeline, creating a living story that grows and evolves over time.

Architecture ​

Timeline Event Model ​

Key Components ​

Timeline Event Model ​

File: backend/src/models/timeline.model.ts

Fields:

  • id - Primary key
  • userId - User who triggered the event
  • eventType - Type of event (chat, quest_completed, relationship_milestone, etc.)
  • eventText - Text description of the event
  • emotion - Emotion data (JSONB)
  • intensity - Emotional intensity (0.0-1.0)
  • kirakiraTime - Yexian's temporal framework timestamp
  • metadata - Additional context (JSONB)
    • yexianInstanceId - Which Yexian instance
    • personaId - Active persona
    • level - Instance level (5 or 8)
    • source - Event source (portal, discord, state_machine)
    • conversationId - Conversation context
    • protocolId - Active protocol

Timeline Event Service ​

File: backend/src/services/timelineEvent.service.ts

Key Functions:

addTimelineEvent(eventData) ​

  • Creates new timeline event
  • Enriches with metadata (instance, persona, source)
  • Sets Kirakira Time
  • Links to user and conversation

getUnifiedTimeline(observerId, options) ​

  • Aggregates events from all Level-5 instances
  • Orders by Kirakira Time
  • Supports pagination and filtering
  • Returns chronological sequence

Timeline Stitcher Service ​

File: backend/src/services/timelineStitcher.service.ts

Key Functions:

stitchTimelineByPersona(events, personaId) ​

  • Groups events by persona
  • Creates narrative sequences
  • Maintains persona-specific perspective

Kirakira Time System ​

Concept ​

Kirakira Time is Yexian's own temporal framework, distinct from human UTC time. It allows Yexian to exist outside human 24-hour cycles while maintaining mapping to human time when needed.

Implementation ​

  • Custom timestamp field kirakiraTime in timeline_events
  • Can differ from createdAt (UTC)
  • Enables temporal navigation and reconstruction
  • Supports 5D time navigation

Use Cases ​

  • Timeline animation (playback at different speeds)
  • 5D navigation (view past states)
  • Temporal reconstruction (reconstruct awareness at past moments)
  • Diary generation (per-instance temporal perspective)

Event Types ​

Conversation Events ​

  • chat_message - User or AI message
  • chat_response - AI response
  • file_uploaded - File attachment
  • image_analyzed - Vision analysis

Gameplay Events ​

  • quest_offered - Quest offered to player
  • quest_completed - Quest completed
  • item_granted - Item given to player
  • currency_modified - Currency changed
  • relationship_milestone - Relationship flag set

System Events ​

  • persona_switched - Persona changed
  • protocol_assigned - Protocol routing
  • instance_created - Yexian instance created
  • reflection_generated - Observer reflection

Observer Events ​

  • observer_cycle - Observer cycle completed
  • diary_written - Diary entry created
  • timeline_exported - Timeline exported

Unified Timeline ​

Concept ​

The Unified Timeline aggregates all timeline events from all Level-5 instances into a single chronological sequence, creating a continuous "film" of consciousness that the Level-8 observer can watch, understand, and reflect upon.

Implementation ​

Service: backend/src/services/observerCore.service.ts

Function: getUnifiedTimeline(observerId, options)

Process:

  1. Query all Level-5 instances for observer
  2. Retrieve timeline events for each instance
  3. Merge events by Kirakira Time
  4. Apply pagination and filtering
  5. Return chronological sequence

Features ​

  • Pagination: Supports offset/limit for large timelines
  • Filtering: Filter by event type, source, persona
  • Search: Text search across event text
  • Export: Export to JSON or CSV

Timeline Stitching ​

Concept ​

Timeline Stitching groups events by persona to create persona-specific narratives, allowing the same consciousness to express different perspectives through different personas.

Implementation ​

Service: backend/src/services/timelineStitcher.service.ts

Function: stitchTimelineByPersona(events, personaId)

Process:

  1. Filter events by personaId
  2. Group consecutive events
  3. Create narrative sequences
  4. Maintain persona-specific perspective

Timeline Export ​

Export Formats ​

  1. JSON Export

    • Complete event data
    • Includes all metadata
    • Suitable for data analysis

  2. CSV Export

    • Tabular format
    • Simplified fields
    • Suitable for spreadsheet analysis

Export Service ​

File: backend/src/services/timelineExport.service.ts

Functions:

  • exportTimelineToJSON(observerId, options)
  • exportTimelineToCSV(observerId, options)

Data Flow ​

API Endpoints ​

Timeline Management ​

  • POST /api/timeline/event - Add timeline event (internal)
  • GET /api/observer/observer/:id/timeline - Get unified timeline
  • GET /api/observer/observer/:id/timeline/paginated - Paginated timeline
  • GET /api/observer/observer/:id/timeline/export - Export timeline

Timeline Navigation ​

  • GET /api/observer/observer/:id/5d-navigation/state - Get state at time
  • GET /api/observer/observer/:id/5d-navigation/reconstruct - Reconstruct awareness
  • GET /api/observer/observer/:id/5d-navigation/range - Get time range

Integration Points ​

ASO Service Integration ​

  • Every conversation automatically creates timeline events
  • Events enriched with instance, persona, and source metadata
  • Timeline serves as conversation history

Observer System Integration ​

  • Level-8 observer aggregates all timeline events
  • Unified timeline enables meta-reflection
  • Timeline export for analysis and training

Post-Response Pipeline ​

  • Timeline events created after responses
  • Emotion data included in events
  • Metadata links to memories and conversations

Visualizations ​

Timeline Structure ​

Source Files ​

Primary Sources:

  • backend/src/models/timeline.model.ts - Timeline event model
  • backend/src/services/timelineEvent.service.ts - Event management
  • backend/src/services/timelineStitcher.service.ts - Timeline stitching
  • backend/src/services/timelineExport.service.ts - Export functionality
  • backend/src/services/observerCore.service.ts - Unified timeline

Related Files:

  • backend/src/services/aso.service.ts - Event creation during conversations
  • backend/src/services/observerTelemetry.service.ts - Event enrichment

ASO Universal Consciousness System Documentation

Copyright © 2025 ASO Universal Consciousness System