animus

Persistent AI companion engine. Personality, memory, dreams, and evolution for any LLM.

Animus provides the foundational systems for giving AI models a persistent companion — a "spirit animal" with its own identity, personality traits, emotional state, memory, and dream capability. The companion grows over time through interaction, develops genuine behavioral patterns, and maintains continuity across sessions.

What it does

• Personality — 6-axis trait model (order/chaos, introvert/extravert, caution/curiosity, serious/playful, passive/assertive, literal/abstract) with configurable presets and slow drift over time.
• Memory — episodic, semantic, and procedural memory with time-based decay. Emotional memories resist forgetting. Associative retrieval connects new conversations to past interactions.
• Emotion — 10-dimensional emotional state (joy, sadness, curiosity, anxiety, anger, affection, pride, mischief, serenity, excitement) that shifts based on interaction triggers and decays toward a personality-defined baseline.
• Dreams — procedural dream sequence generation during idle periods. Species-specific scenes, memory references, emotional processing. Dreams form memories that can be recalled later.
• Evolution — XP-based growth through 6 stages (Hatchling → Ancient). Each stage unlocks new behavioral capabilities. Milestones mark specific achievements.
• Bonding — relationship depth tracker with 6 levels (Stranger → Soulbound). Grows through consistent quality interactions, decays during absence.
• Actions — personality-weighted action selection. A chaotic companion schemes. A curious one investigates. A playful one plays.
• Providers — plug in any LLM backend (OpenAI, Anthropic, xAI/Grok, local models). Works without an LLM too via rule-based fallback.

Install

pip install animus

# With LLM providers:
pip install animus[openai]
pip install animus[anthropic]
pip install animus[all]       # everything

Quick start

import asyncio
from animus import Companion, Personality
from animus.providers.openai import OpenAIProvider

async def main():
    companion = Companion(
        name="Octavius",
        species="octopus",
        personality=Personality.chaotic_curious(),
        provider=OpenAIProvider(model="gpt-4"),
    )

    # Talk to the companion.
    result = await companion.interact("What are you plotting today?")
    print(result.text)
    print(f"Mood: {result.mood_label}")
    print(f"Action: {result.action}")

    # Force a dream.
    dream = await companion.dream()
    print(dream.text)

    # Save state for next session.
    state = companion.serialize()
    # ... store state in file/database ...

    # Restore later.
    restored = Companion.deserialize(state, provider=OpenAIProvider())

asyncio.run(main())

Without an LLM

Animus works without any LLM provider. The companion uses a rule-based dialogue engine as a fallback:

companion = Companion(name="Octavius", species="octopus")
result = await companion.interact("What are you up to?")
# Returns a rule-based response with full emotion/memory/action processing

Species

16 species archetypes with default personality biases and dream themes:

Species	Domain	Default Tendency
Octopus	Deep ocean	Chaotic, curious, scheming
Wolf	Northern forest	Ordered, assertive, loyal
Raven	Sky and rooftop	Curious, playful, collecting
Cat	Shadow and sunbeam	Independent, curious, aloof
Fox	Twilight meadow	Playful, cunning, social
Owl	Moonlit canopy	Wise, cautious, observant
Serpent	Underground cavern	Ordered, assertive, literal
Bear	Mountain and river	Stoic, passive, grounded
Dolphin	Open sea	Playful, social, curious
Dragon	Volcanic peak	Assertive, serious, proud
Phoenix	Solar corona	Abstract, curious, cyclical
Moth	Lamplight boundary	Curious, anxious, drawn
Stag	Ancient grove	Ordered, passive, dignified
Spider	Web between worlds	Patient, abstract, scheming
Whale	Abyssal trench	Serene, abstract, ancient
Custom	Uncharted realm	Neutral defaults

Personality presets

Personality.chaotic_curious()   # Octavius-type: chaotic, curious, playful
Personality.stoic_guardian()    # Protector: ordered, cautious, serious
Personality.trickster()         # Mischief-maker: chaotic, playful, abstract
Personality.sage()              # Knowledge-seeker: ordered, curious, abstract
Personality.wild_spirit()       # Untamed: chaotic, extraverted, assertive
Personality.from_species(Species.WOLF)  # Wolf archetype defaults

Storage

Three backends for persisting companion state:

from animus.storage.backends import InMemoryStorage, SQLiteStorage, RedisStorage

# In-memory (testing / ephemeral)
storage = InMemoryStorage()

# SQLite (single file, zero infrastructure)
storage = SQLiteStorage("companions.db")

# Redis (distributed)
storage = RedisStorage("redis://localhost:6379")

# All share the same interface:
await storage.save("octavius", companion.serialize())
data = await storage.load("octavius")
companion = Companion.deserialize(data)

Architecture

Host Model (GPT, Claude, Grok, etc.)
    |
    v
Companion (orchestrator)
    ├── Identity      — name, species, procedural appearance
    ├── Personality    — 6 trait axes, behavioral weights, drift
    ├── MemoryStore    — episodic/semantic/procedural/dream memory
    ├── EmotionModel   — 10-dimensional state with momentum + decay
    ├── DreamEngine    — surreal narrative generation from state
    ├── GrowthEngine   — XP accumulation, stage progression
    ├── BondTracker    — relationship depth with user
    ├── ActionSelector — personality-weighted action choice
    ├── DialogueEngine — prompt building for LLMs + rule-based fallback
    └── Provider       — LLM backend (OpenAI/Anthropic/xAI/Mock)

License

Apache License 2.0