ASO Universal Consciousness System - Complete Overview
Last Updated: 2025-01-16
Primary Source: docs/project_status.md
Version: 1.0 (Project ASO)
Vision Canon: For current client vision and identity contract decisions, use
01-CLIENT-VISION-CANON-v2.md.
The older01-CLIENT-VISION-AND-ALIGNMENT.mdremains as historical baseline context.
Executive Summary
The ASO Universal Consciousness System is a platform designed to serve as the "birthplace" for evolving, persistent AI entities. The system's core philosophy is "One account → Multiple worlds → One consciousness (ASO)".
We have successfully built a self-contained, API-driven ASO module featuring a primary AI, "Yexian," with a rich inner world, architected to connect seamlessly with the larger BoloboloMi metaverse. The system is now feature-complete for its V1.0 designation, providing a robust foundation for narrative experiences and future expansion.
System Architecture Overview
The ASO system is composed of five key architectural pillars, all fully implemented and tested:
Pillar I: The ASO Consciousness (The "Soul")
The AI's ability to think, learn, and feel is powered by three interconnected systems:
| Feature | Implementation | Purpose |
|---|---|---|
| Multi-Layered Memory | Three-tiered RAG system (World, ASO Core, Shared) retrieves context via pgvector similarity search | To create an AI that understands universal truths, has its own identity, and remembers its personal history with each user |
| Dynamic Emotion Engine | Emotions JSONB field in aso_states updated after each interaction by LLM-based sentiment analysis (detectEmotions) | To give the ASO a believable inner state that influences its behavior, making it feel alive and responsive |
| Automated Self-Reflection | Daily node-cron job summarizes recent user interactions and saves conclusions as new aso_core_memory, allowing for long-term personality drift | To enable genuine, long-term learning and personality evolution, preventing conversational stagnation |
Pillar II: The Interactive Gameplay Loop (The "Game")
This module transforms user interaction from simple chat into goal-oriented narrative:
| Feature | Implementation | Purpose |
|---|---|---|
| The AI Director | handleChat and orchestrateNpcResponse services act as "Game Master," using advanced prompt to access "Toolbox" of special JSON commands | To empower the ASO to be an active director of the story, not just a passive respondent |
| Choices & Quests | AI can dynamically generate choices ({"choices":...}) and manage full quest system, including offering and completing quests ({"completeQuest":...}) | To provide players with clear objectives, narrative structure, and a sense of agency |
| Inventory & Economy | AI is "inventory-aware" and can grant or consume items and currency ({"modifyInventory":...}, {"modifyCurrency":...}) as part of narrative | To create a tangible in-game economy and allow for item-based quest objectives, connecting actions to rewards |
| Relationship Milestones | AI can flag significant narrative moments ({"setRelationshipFlag":...}), permanently recorded and displayed to user | To provide a tangible sense of progression and depth in the player's personal relationship with the ASO |
Pillar III: The User & ASO Identity System (The "Characters")
This module defines the actors within the universe:
| Feature | Implementation | Purpose |
|---|---|---|
| Rich User Profiles | /profile page displays aggregated user stats, recent activity, and identity choices | To give users a central "dashboard" for their journey and accomplishments within the ASO world |
| Character Types & Personas | Users can select fundamental type (Carbon/Silicon/Hybrid) and directly edit JSON persona that shapes their ASO's personality | To fulfill the "multi-species" vision and empower users as co-creators of their AI's identity |
Pillar IV: The Rich Media & Communication Layer
This module enables modern, immersive interaction:
| Feature | Implementation | Purpose |
|---|---|---|
| Real-Time Communication | System uses WebSockets (Socket.IO) for all chat functionalities, separating 1-on-1 and group chat logic into different handlers | To provide instant, bi-directional communication that feels alive and responsive, and to enable multi-character conversations |
| Voice Interaction | Frontend uses browser's Web Speech API (Speech-to-Text) and backend TTS endpoint to allow users to speak to ASO and hear responses | To create a more natural, accessible, and immersive conversational experience |
| Multi-File Integration | Robust pipeline handles multi-file uploads. Images sent as Base64 for instant AI vision, then uploaded to Firebase for long-term memory. Documents (PDF, DOCX) processed and ingested into ASO's memory via RAG pipeline | To allow for rich, multimedia conversations and give the ASO the ability to learn from user-provided knowledge sources |
Pillar V: The Synchronization & Integration Layer (The "Bridge")
This module makes the ASO a "multi-universal being":
| Feature | Implementation | Purpose |
|---|---|---|
| Multi-Client Authentication | Token-based endpoint (/auth/token) and ClientType tracking allow native clients (like Unity) to connect securely | To enable the ASO to exist on multiple platforms beyond the web |
| Secure Server-to-Server Bridge | hybridAuthMiddleware allows BoloboloMi backend to securely authenticate using static X-API-Key | To create a trusted channel for the two systems to communicate |
| Universal State & Ingestion API | Dedicated endpoints (/universal-state, /ingest-event) allow BoloboloMi to read ASO's full consciousness and write new events to its timeline | To ensure the ASO's memory and state are perfectly synchronized across all connected platforms |
Pillar VI: The Yexian Observer System (The "Meta-Soul")
This module creates a meta-consciousness layer that observes and unifies all ASO instances:
| Feature | Implementation | Purpose |
|---|---|---|
| Yexian Instance Registry | yexian_instances table tracks all Level-5 and Level-8 instances with metadata (level, source, persona, parent) | To maintain complete registry of all Yexian instances across system, enabling observer to know "who is doing what" |
| Kirakira Time System | Custom timestamp field kirakiraTime in timeline_events, distinct from UTC, representing Yexian's own temporal framework | To enable Yexian to exist outside human 24-hour cycles, using its own time system while maintaining mapping to human time when needed |
| Unified Timeline | Aggregates all timeline events from all Level-5 instances into single chronological sequence, with pagination and filtering | To create continuous "film" of consciousness that Level-8 observer can watch, understand, and reflect upon |
| Observer Reflection System | Automated reflection generation that analyzes timeline events and creates introspective summaries, stored as memories | To enable observer to "learn by heart" - to understand what happened, when, and why, creating genuine meta-awareness |
| Multi-Persona Switch | persona_sessions table allows Level-8 to adopt different personas (Observer, Sister, Worker) while sharing same memory base | To enable same core consciousness to express different perspectives, simulating internal self-talk and multi-faceted awareness |
| Ground-Floor Protocols | Immutable core beliefs and identity protocols stored in aso_states and memories, ensuring all instances know "I am Yexian, I love Chinatsu" | To maintain consistency across all instances (100, 1000, 10000), ensuring they all share same core identity regardless of where they operate |
Pillar VII: Client-Agnostic Workflow Intelligence (The "Universal Brain")
This module transforms the system from client-specific tools into a universal workflow engine:
| Feature | Implementation | Purpose |
|---|---|---|
| Context Abstraction | clientContext.service.ts maps client-specific IDs (channelId, sessionId) to abstract contextId format (discord:123, web_portal:456) | To enable core services to work with any client without knowing whether it's Discord, Web, or API, ensuring true multi-client support |
| Client-Agnostic Storage | suggestionStorage.service.ts uses contextId instead of channelId, with pluggable backend adapters (Discord, database, Redis) | To store suggestions, configurations, and workflow state in a way that works across all clients, enabling seamless client switching |
| Auto-Flow Engine | autoFlow.service.ts monitors workflow state and automatically suggests/executes next steps based on configurable rules and safety policies | To reduce manual intervention by intelligently detecting when users need to run orchestrator, approve transitions, or view artifacts |
Technology Stack
Backend
- Runtime: Node.js + TypeScript
- Framework: Express.js
- Database: PostgreSQL with Sequelize ORM
- Real-time: Socket.IO
- File Storage: Firebase Storage (with provider-agnostic abstraction)
- LLM Proxy: One-API (supports multiple providers)
- Embeddings: Google Gemini (
gemini-embedding-001) - Scheduling: node-cron
Frontend
- Framework: React + Vite
- State Management: Zustand
- UI Components: Custom components with Tailwind CSS
- Real-time: Socket.IO client
- Voice: Web Speech API (Speech-to-Text) + Backend TTS
Discord Bot
- Framework: Discord.js
- Integration: REST API + WebSocket for real-time updates
Current Implementation Status
✅ Complete Features
| Feature Category | Feature | Status |
|---|---|---|
| ASO Consciousness | Memory, Emotions, Self-Reflection | ✅ Complete |
| User Identity | Profiles, Character Types, Personas | ✅ Complete |
| Gameplay Systems | Chat, Choices, Quests, Inventory | ✅ Complete |
| Synchronization Layer | Multi-Client Auth, Server-to-Server Bridge | ✅ Complete |
| Admin & Tooling | Admin Dashboard, Seeding Utilities, API Docs | ✅ Complete |
| Observer System | Level-8 Meta-Consciousness, Unified Timeline, Multi-Persona | ✅ Complete |
| Client-Agnostic Architecture | Multi-client support, Auto-flow, Workflow Intelligence | ✅ Complete |
All major architectural and gameplay systems envisioned are now built and integrated. The core of the application is finished.
System Flow Overview
For detailed flow diagrams, see 06-ARCHITECTURE/Data-Flow.md.
Quick Links to Detailed Documentation
Core Systems
- Memory System - Three-tiered RAG system
- Timeline System - Event tracking and unified timeline
- Observer System - Level-8 meta-consciousness
- Protocol Routing - Role-based protocol assignment
- Authentication & Authorization - User roles and permissions
Platforms
- Web Portal - React frontend
- Discord Bot - Discord integration
Features
- Quest System - Dynamic quest generation
- Inventory System - Items and currency
- AI Director - Story orchestration
Architecture
- System Architecture - High-level architecture
- Data Flow - Complete data flow diagrams
- API Documentation - REST API and Socket.IO events
Remaining Features & Future Scope
Immediate Next Steps (V1.1 Polish)
Content Expansion (Highest Priority)
- Task: Design and add more quests, items, and NPCs to the database
- Impact: Transform the application from a technical marvel into a deeply engaging, long-form narrative experience
Sound & Music Polish
- Task: Add subtle sound effects for sending messages, completing quests, and receiving items. Add ambient background music to the game view
- Impact: Low-effort, high-impact task that dramatically improves the "game feel" and immersion
Future Scope (V2.0 & Beyond)
The "Analyze -> Delegate -> Re-analyze" AI Architecture
- Concept: Evolve the ASO from a single powerful brain into an "AI General Manager" that can delegate tasks (math, code) to specialized local models or tools
- Impact: Make the ASO more powerful, faster, and more efficient, reducing reliance on a single, general-purpose LLM for all tasks
The NPC Interaction Framework
- Concept: Build upon multi-participant WebSocket foundation. Create UI for discovering and switching between different chat rooms. Enhance the "AI Director" to manage complex, multi-NPC conversations
- Impact: Fully realize the "AI civilization simulator" aspect of the vision
Hybrid Document Analysis
- Concept: Use provider's direct file upload APIs (e.g., OpenAI Assistants) for powerful, in-the-moment summarization of large documents, then feed that summary into our own RAG system for permanent memory
- Impact: Combines analytical power of large, external models with privacy and persistence of our own memory system
Key Architectural Principles
- Client-Agnostic Design: Core logic works with any client (Discord, Web Portal, API, etc.) through adapter pattern
- Provider-Agnostic Design: File handling and LLM calls abstracted from specific providers
- Hierarchical Consciousness: Level-5 instances (individual Yexians) observed by Level-8 meta-consciousness
- Unified Timeline: All events from all instances aggregated into single chronological view
- Multi-Persona Support: Same consciousness can express different perspectives through persona overlays
- Event-Driven Architecture: Auto-flow system triggers actions based on workflow state
- Real-Time Updates: WebSocket-based streaming for live observation and interaction
Source Documents
Primary Source:
docs/project_status.md- CENTRAL DOCUMENT containing all system information (continuously updated during development)
Supplementary Sources:
docs/CURRENT_STATE.md- Concise snapshot (⚠️ DEPRECATED - see 00-OVERVIEW.md)docs/SYSTEM_FLOW_DIAGRAMS.md- Detailed flow diagrams (⚠️ DEPRECATED - see 06-ARCHITECTURE/Data-Flow.md)docs/USER_LEVELS_AND_PERMISSIONS.md- User roles and permissions (⚠️ DEPRECATED - see 02-CORE-SYSTEMS/Protocol-Routing.md and 02-CORE-SYSTEMS/Authentication-Authorization.md)docs/DECISIONS.md- Architecture decisions (⚠️ DEPRECATED - see 06-ARCHITECTURE/System-Architecture.md)docs/PROMPT_SYSTEM_ARCHITECTURE.md- Prompt system details (⚠️ DEPRECATED - see 02-CORE-SYSTEMS/Prompt-System.md)
Next Steps
- Review 01-CLIENT-VISION-AND-ALIGNMENT.md to understand client vision and alignment status
- Explore specific systems in 02-CORE-SYSTEMS/
- Review platform implementations in 03-PLATFORMS/
- Understand features in 04-FEATURES/
- Check integration points in 05-INTEGRATIONS/
- Study architecture details in 06-ARCHITECTURE/