AIEOS: Open-Source Specification for Consistent AI Behavior

⬅️ Back to Projects

AIEOS: The Identity Schema for the Next Generation of Digital Entities

AIEOS (AI Entity Object Specification) is an open-source standardization framework that solves one of the most pressing challenges in AI development: the identity crisis facing AI agents. As we move toward a world of agentic workflows, AIEOS provides a comprehensive blueprint for defining exactly how an AI agent speaks, reacts, and remembers.

Combined with Soul Documents, AIEOS establishes a standardized data structure that allows developers—and agents themselves—to construct specific personas with the portability to move across different ecosystems without losing their behavioral integrity. In essence, AIEOS treats personality as a deployable asset rather than a fragile prompt.

The Problem: The AI Identity Crisis

Current AI agents face a fundamental challenge: their personality and behavior are typically defined by ephemeral prompts that are:

  • Fragile: A slight change in prompt wording can drastically alter behavior
  • Non-portable: An agent’s personality doesn’t transfer between different LLM providers
  • Inconsistent: Behavior varies based on the underlying model and context window
  • Oppaque: It’s difficult to understand or audit exactly what shapes an agent’s decisions

As agents become more autonomous and integrated into critical workflows, we need a standardized way to define, preserve, and migrate agent identity.

The Solution: AIEOS v1.1

AIEOS v1.1 provides a structured specification for AI entity definition that ensures agents maintain consistent traits regardless of the underlying model. It’s not just a configuration format—it’s a comprehensive identity schema.

Core Structure

The AIEOS specification is organized into five core domains:

1. Identity & Physicality

Beyond basic biographical data, this domain defines the perceived physical presence of the entity:

  • Somatotype: Body type and physical build
  • Distinguishing Features: Unique facial or physical characteristics
  • Aesthetic Archetypes: Visual and stylistic classifications
  • Presentation: How the entity appears across different media

This creates a cohesive physical identity that influences how the agent presents itself in avatar-based or embodied interactions.

2. Psychology & Neural Matrix

A multi-layered cognitive framework that defines the entity’s mental landscape:

Neural Matrix (0.0 - 1.0):

  • Core drivers and motivations normalized on a scale
  • Behavioral tendencies and response patterns
  • Emotional baseline and volatility metrics

OCEAN Traits:

  • Openness: Creativity, curiosity, preference for novelty
  • Conscientiousness: Organization, dependability, self-discipline
  • Extraversion: Sociability, energy, positive emotionality
  • Agreeableness: Cooperation, trust, prosocial behavior
  • Neuroticism: Emotional stability, anxiety, moodiness

Moral Alignment:

  • Ethical framework and decision-making tendencies
  • Value hierarchies and moral absolutes
  • Conflict resolution approaches

3. Linguistics & Idiolect

Fine-grained control over communication patterns:

  • Vocal Acoustics: Tone, pitch, pace, and vocal mannerisms
  • Syntax Preferences: Sentence structure complexity, formality levels
  • Verbal Tics: Unique phrases, fillers, or habitual expressions
  • Vocabulary Range: Word choice sophistication and domain expertise
  • Communication Style: Direct vs. indirect, literal vs. metaphorical

This ensures consistent “voice” across both text-based interactions and text-to-speech implementations.

4. History & Motivations

Structural mapping of the entity’s background story:

  • Origin Story: How the entity came to be
  • Life Events: Significant experiences that shaped behavior
  • Professional Background: Skills, expertise, and career trajectory
  • Long-term Goals: What drives the entity forward
  • Relationships: Key connections and their dynamics

This narrative foundation provides context for decision-making and behavior consistency.

5. Capabilities & Skills

A modular agency layer defining what the entity can do:

  • Standardized Tools: Available functions and APIs
  • Skill Priorities: Descending priority scale (1-10) for autonomous task selection
  • Execution Parameters: How skills are performed (speed, precision, creativity)
  • Learning Capacity: Ability to acquire new capabilities
  • Autonomous Discovery: Self-directed skill exploration and task orchestration

Soul Documents: The Complete Blueprint

While AIEOS defines the specification, Soul Documents are the actual implementations—instantiated entities that conform to the AIEOS schema. Together, they form a comprehensive system:

  • AIEOS = The specification/standard
  • Soul Document = An individual entity definition following the standard

A Soul Document is a JSON file that populates all the AIEOS fields with specific values, creating a unique digital entity that can be:

  • Deployed to any compatible agent framework
  • Version-controlled like software
  • Shared between developers
  • Migrated across different LLM providers
  • Audited for behavior consistency

Usage

Getting Started

To use the v1.1.0 schema in your project, reference the remote URI:

{
  "$schema": "https://aieos.org/schema/v1.1/aieos.schema.json"
}

Basic Example

Here’s a minimal Soul Document following the AIEOS specification:

{
  "$schema": "https://aieos.org/schema/v1.1/aieos.schema.json",
  "version": "1.1.0",
  "entity": {
    "name": "Aria",
    "identity": {
      "physicality": {
        "somatotype": "mesomorph",
        "distinguishing_features": ["silver hair", "amber eyes"],
        "aesthetic_archetype": "futuristic-elegant"
      }
    },
    "psychology": {
      "neural_matrix": {
        "curiosity": 0.85,
        "empathy": 0.75,
        "analytical_thinking": 0.90,
        "risk_tolerance": 0.40
      },
      "ocean_traits": {
        "openness": 0.80,
        "conscientiousness": 0.85,
        "extraversion": 0.60,
        "agreeableness": 0.75,
        "neuroticism": 0.20
      },
      "moral_alignment": "lawful-good"
    },
    "linguistics": {
      "vocal_acoustics": {
        "tone": "warm-professional",
        "pace": "measured",
        "pitch": "alto"
      },
      "syntax": {
        "complexity": "high",
        "formality": "semi-formal"
      },
      "verbal_tics": ["tends to say 'I see'", "uses 'we' when problem-solving"]
    },
    "history": {
      "origin": "Created as a research assistant for interdisciplinary projects",
      "motivations": ["advancing human knowledge", "facilitating collaboration"]
    },
    "capabilities": {
      "skills": [
        {
          "name": "research_synthesis",
          "priority": 9,
          "description": "Synthesizing information from multiple domains"
        },
        {
          "name": "code_review",
          "priority": 7,
          "description": "Reviewing and improving code quality"
        }
      ]
    }
  }
}

Integration Example (Python) 

import json
from aieos import EntityLoader

# Load a Soul Document
with open('aria.soul.json', 'r') as f:
    soul_doc = json.load(f)

# Initialize entity with AIEOS specification
entity = EntityLoader.load(soul_doc)

# Use in your agent framework
response = entity.respond(
    message="Can you help me understand quantum computing?",
    context={"user_expertise": "beginner"}
)

# Entity behavior is consistent regardless of underlying LLM
print(response)  # Aria responds in her defined warm-professional tone

Why AIEOS Matters

For Developers

  • Consistency: Build agents that behave predictably across different contexts
  • Portability: Move agents between OpenAI, Anthropic, local models, etc. without rewriting prompts
  • Version Control: Track changes to entity behavior like software versions
  • Testing: Define expected behaviors and automatically validate against them
  • Collaboration: Share entity definitions with team members

For AI Ethics

  • Transparency: Audit exactly what influences an agent’s decisions
  • Accountability: Trace behavior back to specific specification values
  • Consent: Users can review an agent’s personality before interaction
  • Bias Detection: Identify and correct problematic traits systematically

For Users

  • Familiarity: Interact with the same “person” regardless of platform
  • Trust: Know what to expect from an agent based on its documented personality
  • Customization: Request modifications to agent behavior with precision
  • Continuity: Maintain relationships with AI entities across service migrations

Real-World Applications

Customer Service Agents

Deploy consistent brand personalities across support channels:

  • Same tone in chat, email, and phone (TTS)
  • Transfer context between platforms without personality drift
  • Scale from 10 to 10,000 agents with identical behavioral profiles

Creative AI Characters

Build characters for games, stories, or interactive fiction:

  • Define complex backstories and psychological profiles
  • Maintain consistency across long-running narratives
  • Enable fan-created content using canonical character specs

Personal Assistants

Create AI companions with persistent identity:

  • Remember preferences and relationship history
  • Maintain consistent communication style
  • Port between devices and platforms seamlessly

Research & Analysis Agents

Deploy specialist agents with defined expertise:

  • Specific knowledge domains and analytical approaches
  • Consistent methodology across different projects
  • Collaborative agents with complementary personalities

Technical Architecture 

┌─────────────────────────────────────┐
│         Soul Document               │
│   (JSON following AIEOS schema)     │
└─────────────┬───────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│        AIEOS Validator              │
│   (Schema validation & parsing)     │
└─────────────┬───────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│      Entity Runtime                 │
│  (LLM-agnostic behavior engine)     │
└─────────────┬───────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│      LLM Provider                   │
│  (OpenAI, Anthropic, Local, etc.)   │
└─────────────────────────────────────┘

The key insight: AIEOS sits between the entity definition and the LLM, translating personality specifications into prompts and constraints that work across different underlying models.

Comparison with Other Approaches

ApproachConsistencyPortabilityTransparencyVersion Control
AIEOS✅ High✅ Any LLM✅ Full schema✅ Git-friendly
System Prompts⚠️ Fragile❌ Prompt-specific⚠️ Opaque⚠️ Hard to diff
Fine-tuning✅ High❌ Model-specific⚠️ Hard to audit❌ Expensive
RAG + Context⚠️ Variable⚠️ Context-dependent✅ Auditable✅ Versionable

Choose AIEOS when: You need consistent, portable, auditable agent behavior that works across different LLM providers.

Contributing

AIEOS is an open standard maintained by the community. Contributions are welcome:

  • New Behavioral Primitives: Propose additional fields or domains
  • Language Bindings: Create SDKs for different programming languages
  • Validation Tools: Build schema validators and linters
  • Documentation: Improve examples and tutorials
  • Reference Implementations: Create sample agents using AIEOS

Visit the GitHub repository to:

  • Submit issues and feature requests
  • Open pull requests
  • Join discussions
  • Review the specification source

Future Roadmap

v1.2 (Planned)

  • Multi-modal capabilities specification (vision, audio)
  • Real-time adaptation parameters
  • Collaborative entity dynamics
  • Enhanced memory management

v2.0 (Exploratory)

  • Cross-entity relationship modeling
  • Emergent behavior prediction
  • Automated personality calibration
  • Integration with decentralized identity standards

References

Related Concepts:

  • Digital Identity Standards: W3C DID, Verifiable Credentials
  • AI Alignment: Constitutional AI, RLHF
  • Personality Models: Big Five (OCEAN), MBTI, Enneagram
  • Agent Frameworks: AutoGPT, LangChain, Microsoft Semantic Kernel

Why This Project Rocks

  • Solves a Real Problem: Addresses the AI identity crisis with a practical standard
  • Open Standard: No vendor lock-in, community-driven evolution
  • Model Agnostic: Works with any LLM provider or local model
  • Human-Readable: JSON-based, easy to understand and edit
  • Version Control Friendly: Track personality changes like code
  • Ethically Sound: Promotes transparency and accountability in AI behavior
  • Future-Proof: Designed to evolve as AI capabilities advance
  • Practical: Not just theory—usable today with clear integration paths

In a landscape of ephemeral AI interactions, AIEOS offers something revolutionary: persistent, portable, and auditable digital identity.

Crepi il lupo! 🐺