blightbow/evennia_ai
2
0
Fork 0
Code Issues 9 Pull requests Projects Releases Packages Wiki Activity Actions
Page: Architecture Overview
Pages
Architecture Commands and API Architecture Context System Architecture Core Engine Architecture Event Sourcing Architecture Generative Reflection Architecture Helpers Architecture Journal System Architecture LLM Interaction Architecture LLM Providers Architecture Logging Architecture Memory and Sleep Architecture Overview Architecture Persona Protection Architecture Prompt System Architecture RAG Implementation Architecture Resilience System Architecture Safety System Architecture Self Management Architecture Sub Agent Delegation Architecture Task Assessment Architecture Token Management Architecture Tool System Configuration Reference Context and Memory Flow Analysis Data Flow 01 Context Compaction Data Flow 02 ReAct Loop Data Flow 03 Memory Consolidation Data Flow 04 Message Classification Data Flow 05 Entity Profile System Data Flow 06 Tool Execution Data Flow 07 Sleep Mode Transitions Data Flow 08 LLM Provider Interaction Data Flow 09 Self Management Operations Home LLM Decision Patterns Research Foundations User Guide 00 Index User Guide 01 Getting Started User Guide 02 Configuration and Customization User Guide 03 Advanced Capabilities User Guide 04 Troubleshooting
4 Architecture Overview
Blightbow edited this page 2026-09-21 05:12:35 -04:00
Table of Contents

Architecture Overview

AI Assistant System - Architectural Reference

Five-Layer Architecture

The AI assistant builds on five distinct layers, each with specific responsibilities:

+-------------------------------------------------------------------------+
|                        LAYER 5: Web Views                               |
|  Django templates + JavaScript (dashboard, workbench, configuration)   |
+------------------------------------+------------------------------------+
                                     | renders data from
+------------------------------------v------------------------------------+
|                        LAYER 4: REST API                                |
|  DRF ViewSets + Mixins (11 domain mixins for execution, memory, etc.)  |
+------------------------------------+------------------------------------+
                                     | queries/mutates
+------------------------------------v------------------------------------+
|                        LAYER 3: In-Game Commands                        |
|  MuxCommands with mixin pattern (aisetup has 7 domain mixins)          |
+------------------------------------+------------------------------------+
                                     | controls
+------------------------------------v------------------------------------+
|                        LAYER 2: Core Engine                             |
|  AssistantScript (tick loop, execution patterns, tool dispatch)        |
|  AssistantCharacter (message classification, entity memory)            |
|  Memory System (semantic, entity profiles, episodic)                   |
|  Tool System (categories, registry, validation)                        |
|  Helpers (package of centralized utilities)                            |
+------------------------------------+------------------------------------+
                                     | built on
+------------------------------------v------------------------------------+
|                        LAYER 1: Core Evennia                            |
|  DefaultScript, DefaultCharacter, DefaultChannel, TICKER_HANDLER        |
+-------------------------------------------------------------------------+

Component Relationships

Layer 2: Core Engine Components

                    +---------------------+
                    | AssistantRegistry   |
                    | (singleton script)  |
                    +----------+----------+
                               | references
            +------------------+------------------+
            v                  v                  v
+-------------------+ +-------------------+ +-------------------+
| AssistantScript   | | AssistantCharacter| | AssistantChannel  |
| (per-assistant)   | | (per-assistant)   | | (optional)        |
|                   |<|                   | |                   |
| Tick loop         | | Message classify  | | Routes to script  |
| Execution config  | | Entity memory     | |                   |
| Conversation hist | | Journal           | +-------------------+
| Operating mode    | | Session memory    |
+-------------------+ +-------------------+
         |                    |
         v                    v
+-------------------+ +-------------------+
| tool_execution.py | | rag_memory.py     |
| ReAct loop        | | Sleep operations  |
| Retry logic       | | Consolidation     |
| Caching           | | Compaction        |
+-------------------+ +-------------------+
         |                    |
         +--------+-----------+
                  v
         +-------------------+
         | helpers/          |
         | (package)         |
         | Cross-layer utils |
         +-------------------+

Key Design Principles

1. Delegation Pattern

The AssistantScript delegates to specialized modules rather than implementing everything inline:

  • llm_interaction.py - Message building and LLM calls
  • tool_execution.py - ReAct loop and tool dispatch
  • rag_memory.py - Memory and sleep operations
  • operating_mode.py - Mode transitions

2. Three-Layer Execution

Execution patterns compose three layers with restrictive semantics:

Layer 1 (Static)  ⊇  Layer 2 (Context)  ⊇  Layer 3 (LLM)

Each layer can only restrict, never expand, what higher layers allow.

3. Mixin Patterns

Both Commands (L3) and API (L4) use domain-specific mixins:

  • Groups related functionality together
  • Reduces file sizes
  • Enables independent testing

4. Centralized Helpers

The helpers/ package provides utilities used across all layers:

  • Entity memory (profiles, relationships, observations)
  • Execution pattern composition
  • Defensive NDB access
  • Context formatting
  • Service health monitoring

5. Three-Tier Memory

Memory is organized in three tiers with different lifespans:

  1. Semantic (Mem0) - Long-term world facts
  2. Entity Profiles (DB) - Per-entity knowledge
  3. Working Memory (NDB) - Active conversation state

Quick Reference: Where Does X Live?

Concept Primary Location Layer
Tick loop assistant_script.py::at_tick() L2
ReAct loop tool_execution.py::execute_react_loop() L2
Message classification messaging/classification.py::classify_message() L2
Context types (7) prompt_contexts.py L2
Prompt components prompt_components.py L2
Sleep operations rag_memory.py::run_sleep_tick() L2
Mode transitions operating_mode.py L2
Tool categories tools/base.py::ToolCategory L2
Tool registry tools/__init__.py::TOOL_REGISTRY L2
Entity memory helpers/entity_profiles.py L2
Relationship scoring helpers/entity_profiles.py::update_relationship_metric() L2
Persona protection rag_memory.py, generative_reflection.py L2
aisetup command commands/setup/ (7 mixins) L3
API viewset api/views/assistants.py (11 mixins) L4

Key Files and Packages

Location Purpose
helpers/ Package: Cross-layer utilities (9 modules)
messaging/ Package: Message classification and trust (4 modules)
assistant_script.py Main orchestrator, tick loop
assistant_character.py In-game presence, entity memory
rag_memory.py Memory and sleep coordination
prompt_contexts.py Context type definitions
tool_execution.py ReAct loop implementation
operating_mode.py Mode transitions
prompt_components.py Component assembly
generative_reflection.py Reflection pipeline

Documentation Index

Page Topics
Architecture-Core-Engine Tick loop, ReAct, message classification
Architecture-Context-System 7 context types, 3-layer execution
Architecture-Memory-and-Sleep Three-tier memory, sleep operations
Architecture-Persona-Protection Perspective bleed defenses, self-reference filtering
Architecture-Tool-System Categories, registry, validation
Architecture-Resilience-System Circuit breaker, caching
Architecture-Safety-System Emergency stop, error recovery
Architecture-Commands-and-API Mixin patterns for L3/L4
Architecture-Helpers Cross-layer utilities

Research Foundations

This architecture incorporates patterns from recent AI agent research:

Concept Source Implementation
ReAct Loop ReAct tool_execution.py
Memory Links A-MEM sleep/dreaming.py:run_dreaming_tick()
Entity Profiles O-Mem helpers/entity_profiles.py
Sleep-Time Consolidation LightMem sleep/__init__.py:run_sleep_tick()
Source Trust Project-original, see Research-Foundations messaging/trust.py
Persona Protection Project-original; persona/world separation from MemGPT Extraction prompts, self-reference filtering
Reflection Generative Agents Cumulative importance scoring

Citation metadata lives in one place: references.yaml in the AI contrib, rendered into Research-Foundations and CREDITS.md. Other pages cite by name and link there.

Last updated: 2025-12-09 - Updated references to helpers/ and messaging/ packages