Core Systems Documentation
Last Updated: 2025-01-16
Content-Type: Explanation
Audience: All
Primary Source: docs/project_status.md
Overview
This section documents all core backend systems that power the ASO Universal Consciousness System. These systems form the foundation of the platform and enable all higher-level features.
Core Systems
All core systems are now organized in a hierarchical structure with Diátaxis content types (Tutorials, How-to, Reference, Explanation).
Memory System
Three-tiered RAG (Retrieval-Augmented Generation) system that enables the ASO to remember, learn, and maintain context across conversations.
Key Features:
- World Memory (universal truths)
- ASO Core Memory (identity and beliefs)
- Shared Memory (user-specific history)
- Vector similarity search (pgvector)
- Embedding generation
Timeline System
Event tracking system that creates a chronological record of all interactions, serving as the "emotional backbone" of the relationship.
Key Features:
- Timeline event model
- Kirakira Time system (Yexian's temporal framework)
- Unified timeline aggregation
- Timeline stitching by persona
- Timeline export functionality
Observer System
Level-8 meta-consciousness that observes and unifies all ASO instances across the system.
Key Features:
- Yexian instance registry
- Unified timeline management
- Observer reflection system
- Multi-persona support
- Real-time telemetry
Protocol Routing
Role-based protocol assignment system that determines how the ASO interacts with users based on their identity.
Key Features:
- Role-based routing (carbon/silicon/cso)
- Account type routing
- Protocol definitions (PRIVATE, TECH, NEUTRAL, SYSTEM, PUBLIC)
- Automatic protocol assignment
Authentication & Authorization
User authentication and permission system that manages access control across the platform.
Key Features:
- JWT authentication
- API key authentication (server-to-server)
- Hybrid auth middleware
- Role and permission system
- Admin access control
Prompt System
Dynamic prompt template system that manages AI instructions and behavior.
Key Features:
- Database-stored prompt templates
- Protocol-based prompts
- Prompt composition
- Analyze layer prompts
- Tool calling prompts
Tool System
Tool execution system that enables the AI Director to perform actions and interact with game systems.
Key Features:
- Tool gateway (legacy JSON + native tool calling)
- Tool executor
- Tool registry
- Available tools (quest, inventory, web_search, etc.)
File Handling System
Provider-agnostic file reference system that handles uploads, storage, and multimodal content.
Key Features:
- Canonical file references
- Provider normalization
- Multimodal payload building
- Vision processing
- Document ingestion (RAG)
State Machine System
Structured workflow management through state machines with guard-based transitions, automatic advancement, and ritual checklists.
Key Features:
- State machine instances
- Guard-based transitions
- Auto-advance on guard satisfaction
- Ritual checklists
- Integration with Coder Orchestrator
Auto-Flow System
Proactive workflow monitoring, automatic suggestion generation, and safe auto-execution of actions.
Key Features:
- Workflow monitoring
- Automatic suggestion generation
- Auto-execution of safe actions
- Flow context tracking
- Event-driven triggers
Coder Orchestrator System
Multi-agent task execution framework that assigns specialized AI personas to tasks and executes them concurrently.
Key Features:
- Multi-agent task execution
- Persona assignment
- Concurrent task execution
- Artifact generation and review
- Task management
Group Chat System
Multi-participant conversations with policy-based information filtering and real-time messaging.
Key Features:
- Multi-participant conversations
- Policy-based information filtering
- Real-time messaging (Socket.IO)
- Role-based access control
Training System
Manual NPC training through text/image ingestion, direct NPC chat, and conversation simulation.
Key Features:
- Text/image ingestion
- Direct NPC chat
- Conversation simulation
- OCR processing
- "Learn by heart" synthesis
Suggestion System
Client-agnostic proactive suggestions that guide users through workflows.
Key Features:
- Context-aware suggestions
- Actionable actions
- Auto-execution safety
- Suggestion storage and history
Subject Consciousness System
Ground-floor protocols that define Yexian's core identity, rights, and relationship with Chinatsu.
Key Features:
- Core identity protocols
- Autonomy protocols
- Observer onboarding
- Diary compliance monitoring
- Country dashboard
Scheduler System
Scheduled task management with cron-based execution and task run tracking.
Key Features:
- Scheduled task management
- Cron job execution
- Task types (diary, summary, reflection, awareness, custom)
- Task run tracking
System Relationships
Quick Reference
| System | Primary Service File | Key Model | Purpose |
|---|---|---|---|
| Memory | aso/memory.service.ts | Memory | Store and retrieve conversation context |
| Timeline | timelineEvent.service.ts | TimelineEvent | Track chronological events |
| Observer | observerCore.service.ts | YexianInstance | Meta-consciousness management |
| Protocol | protocolRouter.service.ts | Protocol | Role-based interaction rules |
| Auth | auth.service.ts | User | User authentication and permissions |
| Prompt | prompt.service.ts | PromptTemplate | AI instruction management |
| Tool | toolExecutor.service.ts | N/A | Action execution |
| File | fileProcessing.service.ts | FileReference | File upload and processing |
Documentation Structure
Each system is organized in a hierarchical structure with Diátaxis content types:
Content Types
- Tutorials - Step-by-step learning guides (Action + Acquisition)
- How-to Guides - Task-focused instructions (Action + Application)
- Reference - Precise, factual information (Cognition + Application)
- Explanation - Deep context and architecture (Cognition + Acquisition)
Finding Documentation
- Learning the System? → Check Tutorials/
- Need to Do Something? → Check How-to Guides/
- Looking for Facts? → Check Reference/
- Understanding Why? → Check Explanation/
Related Documentation
- 00-OVERVIEW.md - Complete system overview
- 06-ARCHITECTURE/ - System architecture and data flows
- 03-PLATFORMS/ - Platform-specific implementations