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	Anthropic: Building Effective Agents	tool_execution.py
Memory Links	A-MEM	rag_memory.py:run_dreaming_tick()
Source Trust	O-MEM	Entity profiles, trust scoring
Persona Protection	MIRIX	Extraction prompts, self-reference filtering
Reflection	Generative Agents	Cumulative importance scoring

---

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