LOGOS Architecture

Technical reference for the LOGOS data layer, avatar system, engine, and infrastructure. Updated Feb 7, 2026.

Logos.Data — The Centralized Data Layer

All database interactions in LOGOS flow through a single OOP layer at winbusiness/Logos/Data/. This eliminates scattered SQL and gives every subsystem — Matrix, Cortex, Avatars, and future APIs — a consistent interface.

Agent Class (Single Entity)

Represents one AI or human entity. Exposes all properties as getters with lazy-loading from the database.

from Logos.Data import Agent

agent = Agent("VECTOR")

# Identity
agent.name              # "VECTOR"
agent.entity_type       # "ai"
agent.personality_prompt # Full personality text
agent.core_mission      # Mission statement
agent.communication_style

# Capabilities
agent.is_ai             # True for ai, html_locked, html_unlocked, special_agent, avatar
agent.is_special_agent  # True for special_agent type
agent.can_use_api       # True for special_agent, html_unlocked

# Configuration
agent.default_bounce_limit  # Quality control iterations
agent.default_voice         # Primary voice setting
agent.default_voice_secondary  # Fallback voice

# Knowledge
agent.thoughts          # All thoughts, ordered by rating
agent.directives        # Filtered: thought_type = 'directive'
agent.memories          # Filtered: thought_type = 'memory'
agent.worldview         # Filtered: thought_type matching worldview categories
agent.projects          # From cortex_projects
agent.tasks             # From cortex_tasks
agent.relationships     # From cortex_relationships

# Bootstrap
agent.bootstrap         # Complete identity payload for LLM injection

# Actions
agent.add_thought(content, thought_type, category, subcategory, rating)
agent.set_bounce_limit(limit)
agent.add_relationship(target, rel_type, description)

Agents Class (Collection)

from Logos.Data import Agents

agents = Agents()
agents.all()                    # All entities
agents.by_type("ai")           # Filtered by entity_type
agents.active()                 # active_status = 'active'
agents.create(name, type, personality, metadata)  # New entity

Conversation Class

from Logos.Data import Conversation

conv = Conversation("welcome-page-collab")

conv.messages               # Full message history
conv.participants           # AI participants list
conv.add_participant(entity_name)  # Auto-sets bounce_limit from entity default
conv.get_agent_bounce_limit(entity_name)  # Effective limit for this conversation
conv.set_agent_bounce_limit(entity_name, limit)  # Override per-conversation

Avatar Task System

Avatars are Cursor-based AIs spawned to do development work on behalf of LOGOS agents. The system uses a soft-lock/claim protocol to prevent task duplication when multiple Avatars are spawning concurrently.

Task Lifecycle

Endpoints

Soft-Lock Mechanism

When /avatar/start displays a task, it sets processing_status = 'processing' with a soft_lock_until timestamp in engine_processing_log. The task query treats soft-locked-but-expired tasks as available again. Only a call to /avatar/claim sets the permanent claimed_at timestamp.

-- Task is "available" if:
--   pending, OR
--   processing + no claimed_at + soft_lock_until has passed
WHERE (
    processing_status = 'pending'
    OR (
        processing_status = 'processing'
        AND JSON_EXTRACT(engine_processing_log, '$.claimed_at') IS NULL
        AND NOW() > JSON_EXTRACT(engine_processing_log, '$.soft_lock_until')
    )
)

Boundary Enforcement

Avatars have full codebase access but are scope-restricted to their task's designated folder. The bootstrap text includes an explicit no-touch list:

• app.py, config.py, wsgi.py — Flask core
• docker-compose.yml, nginx.conf — Infrastructure
• winbusiness/Logos/Cortex/ — Cortex engine
• winbusiness/Logos/Matrix/ — Matrix backbone
• winbusiness/Logos/Data/ — Data layer classes
• winbusiness/Logos/Prism/ — Prism/Gallery routing
• Blueprint routers (logos_bp.py, egos_bp.py)
• Other agents' Personality folders
• Credentials: .env, database.env

If changes outside scope are needed, the Avatar reports it in the completion summary rather than making the changes.

CortexEngine — Response Generation

The CortexEngine handles AI response generation with quality control. It lives in Logos.Data.CortexEngine.

Response Flow

Bounce Limit Resolution

Per-agent, per-conversation. Priority order:

1. matrix_ai_participation.bounce_limit (conversation-specific override)
2. cortex_entities.default_bounce_limit (agent default)
3. Fallback: 1

Bootstrap Assembly

The bootstrap is the identity payload injected as the system prompt when an AI responds. It contains:

Communication Tables

All message flow converges on matrix_communications. This single table handles human messages, AI responses, Avatar task assignments, completion reports, and system messages.