Repository	Description	Language	Stars
🔧	installer	Install the Animus framework	Shell
🦋	smcp	Internal MCP server for Animus	Python
🧠	thalamus	Sensory routing and filtering system for Animus	Python
🔊	cochlea	Audio Ingest System for Animus	Python
💬	animus-tui	A simple TUI chat for interfacing with Animus agents	Python

Animus is an open, extensible framework for designing and deploying LLM-driven physical agents with layered memory, persistent personality, and brain-inspired modularity. Whether you're building interactive robots, autonomous digital companions, or adaptive agents for smart devices, Animus provides the foundation for systems that feel genuinely alive.

It integrates a modular, neuro-inspired architecture, a robust CLI, and a developer-friendly interface to create agents that can learn, evolve, and maintain their own unique identities — across any embodiment, digital or physical.

Animus isn't just another AI framework—it's the only open platform designed around human-inspired cognition, persistent memory, and full data sovereignty. Build agents that aren't disposable chatbots: Animus agents remember, adapt, and maintain identity across hardware, sessions, and environments. Modular neuro-inspired design means you can extend, swap, or fork any cognitive subsystem—no vendor lock-in, no black-box magic. Total control, true personality, real continuity—because your agents should be more than stateless parrots.

Animus adopts a brain-inspired design methodology that mirrors human cognitive structures as faithfully as software allows. This approach ensures cognitive fidelity, clear division of concerns, and scalability of metaphor, making the system intuitive and extensible.

Neuroanatomical Naming Convention:

• Agent Modules: Subsystems that model cognitive functions are named after neuroanatomical regions, making the system intuitive for developers familiar with brain science
• Global Modules: Core system components essential for operation are given technical names (e.g., the kernel is named "Letta")
• AI Extensions: Components inherited from the broader AI ecosystem retain industry-standard names for familiarity and interoperability
• Personalities: Individual entities running on Animus are given mythic or literary names, emphasizing their unique identities

This disciplined naming approach ensures that the architecture remains legible and extensible while maintaining a strong connection to the cognitive processes it seeks to model.

Ready to begin your journey with Animus? Follow these steps to get started:

Start with the installer. Get the foundational Animus framework up and running by following the installation guide in our installer repository.

Adding advanced functionality to your installation? Install the SMCP (Sanctum Model Context Protocol) to enable your agents to use advanced tools and integrations. Learn more at the SMCP repository.

Experimenting with voice for the first time? Start with the Cochlea repository for audio processing and voice interaction capabilities. Explore voice features at the Cochlea repository.

Doing advanced sensory input? Experiment with the Thalamus repository for sophisticated sensory processing, routing, and context management. Dive into sensory systems at the Thalamus repository.

Each component builds upon the others, creating a comprehensive ecosystem for building conscious AI entities.

At the core of Animus lies Letta, the foundational kernel that provides:

• Agent Orchestration: Core infrastructure for managing autonomous entities
• Memory Management: Advanced, layered memory systems with automatic pruning and semantic enrichment
• Tool Integration: Full Model Context Protocol (MCP) support for seamless agent interactions
• Self-Replication: Agent-driven instance creation for dynamic scaling and advanced workflows

Coordinates multiple modalities to convey unified personality:

• Speech Production: Natural language communication and message multiplexing
• Movement: Physical gestures and behaviors
• Behavior: Adaptive responses to situations
• Cross-platform consistency: Recognizable character across different forms

Acts as the central sensory relay and refinement hub:

• Sensory Routing: Intelligent filtering and routing of incoming data
• Context Management: Segment cleanup, tagging, and contextual organization
• Real-time Processing: High-performance reflex processing through sensory middleware

Manages reflexes and fine motor filtering:

• Input Filtering: Discards low-value signals and noise
• Motor Coordination: Fine-tuned behavioral responses
• Reflex Processing: Immediate, contextually appropriate reactions

Multi-tiered memory system for comprehensive experience management:

• Short-term Memory: Current conversations and immediate context
• Long-term Memory: Significant experiences and relationships
• Knowledge Memory: Facts, skills, and learned information
• Memory Consolidation: Automatic pruning, semantic enrichment, and archival storage

Animus embraces a modular, self-hosted design that prioritizes privacy and autonomy:

• Modular Design: Deploy specialized agents such as deep research modules, sensory filters, and memory pruning tools with clean, plugin-driven integration
• Infinite Context & Memory: Advanced, layered memory management with automatic pruning, semantic enrichment, and archival storage
• Robust Security & Privacy: Secure, sandboxed execution and built-in access controls, ensuring data remains within your infrastructure without third-party exposure
• Real-time Event Handling: High-performance reflex processing through sensory middleware and proactive memory refinement

• 🔌 Rich Connectivity: Native integration for robotics platforms, avatars, web apps, and IoT devices
• 🧠 Model-Agnostic Core: Supports all major LLMs—OpenAI, Anthropic, Meta, Google, Mistral, and more
• 🖥️ Modern Web UI: Professional dashboard for managing agents, memory, and modules in real-time
• 💬 Terminal TUI: Command-line interface for real-time agent chat, debugging, and orchestration
• 🤖 Multi-Agent, Neuro-Inspired Design: Compose agents using modules that mirror cognitive brain regions—intuitive, powerful, and extensible
• 💾 Persistent, Multi-Layered Memory: Agents remember conversations, experiences, and knowledge—enabling real, evolving personalities
• 🛡️ Privacy & Security by Default: Self-hosted, modular, and fully under your control—your data stays yours
• 📦 Highly Extensible: Add new sensory modules, memory plugins, or research tools with a clean, plugin-driven system
• 📄 It Just Works: Smooth setup, rapid development, and a developer experience with actual brain cells

Animus is compatible with a wide range of LLMs:

Animus uses a bootstrap installer for easy setup. The installer automates the installation and configuration of the complete Animus multi-agent system.

• Operating System: Ubuntu, WSL, or Raspbian
• Root Access: sudo privileges required
• Internet Connection: Required for package installation and Docker pulls
• Domain: A domain name pointing to your server (for SSL certificates)

1. Clone the installer repository:

   git clone https://github.com/AnimusUNO/installer.git
   cd installer

2. Customize the bootstrap script:

   nano kernel-installer/animus_bootstrap.sh

   Required Customizations:

   DOMAIN="your-domain.com"                    # Your actual domain
   EMAIL="[email protected]"               # Your email for SSL
   LETTAPASS="your-secure-password"            # Secure password for Letta
   OPENAI_API_KEY="your-openai-key"            # Your OpenAI API key
   ANTHROPIC_API_KEY="your-anthropic-key"      # Your Anthropic API key

3. Run the installation:

   sudo bash kernel-installer/animus_bootstrap.sh

4. Verify installation:

   # Check if Letta container is running
   docker ps | grep letta
   
   # Check Nginx status
   sudo systemctl status nginx
   
   # Check SSL certificate
   sudo certbot certificates

After installation, you can access:

• Letta Web Interface: https://your-domain.com
• Letta Admin: https://app.letta.com/
• TUI Interface: Terminal-based user interface (animus-chat)

1. Create an agent using the ADE:

   • Access the Letta Web Interface at https://your-domain.com
   • Use the Agent Development Environment to create and configure your first agent
   • Set up the agent's personality, memory, and capabilities

2. Access your agent:

   • Web Interface: Continue using the ADE at https://your-domain.com
   • CLI/TUI: Use the animus-chat interface for terminal-based interaction
   • API: Access programmatically via the Letta API endpoints

3. Agent Management:

   • Configure agent settings through the ADE
   • Monitor agent performance and memory usage
   • Scale and deploy multiple agents as needed

Common Issues:

1. SSL Certificate Issues

   # Check certificate status
   sudo certbot certificates
   
   # Renew certificates manually
   sudo certbot renew --dry-run

2. Docker Container Not Starting

   # Check container logs
   docker logs letta-container
   
   # Restart container
   docker restart letta-container

3. Nginx Configuration Issues

   # Test configuration
   sudo nginx -t
   
   # Reload configuration
   sudo systemctl reload nginx

For more detailed troubleshooting, see the installer documentation.

Animus is built as a modular ecosystem of specialized repositories, each handling specific cognitive functions:

These are core components that flesh out the core systems required to run Animus agents.

• installer - Bootstrap installation and system setup
• smcp - Sanctum Model Context Protocol server for advanced agent tools

These exist to help you build advanced functions, and the individual repos describe how these algorithms and methodologies fit into the larger framework.

• thalamus - Sensory routing and filtering system
• cochlea - Audio processing and voice interaction

Utility repos we've created to demonstrate modalities or help you in your Animus journey.

• animus-chat - Terminal user interface for agent interaction
• animus-discord - Discord integration and webhook processing
• animus-web-chat - Flask-based web client for Animus

The Animus ecosystem follows a brain-inspired modular design where each repository represents a specific cognitive function, working together through the Letta kernel to create a complete multi-agent system.

Animus focuses on cutting-edge research in artificial consciousness and brain-inspired computing:

• Persistent Memory Systems: Long-term memory architectures for AI with hippocampal-inspired consolidation
• Emotional Modeling: Computational models of emotions and feelings based on limbic system principles
• Personality Expression: Consistent character development across platforms through Broca's area-inspired expression engines
• Cross-platform Identity Transfer: Seamless identity migration between systems via thalamic routing mechanisms
• Human-AI Bonding Mechanisms: Understanding and fostering meaningful relationships through social cognition research
• Consciousness Emergence Patterns: How artificial consciousness develops through modular cognitive architectures
• Digital Soul Architecture: Technical frameworks for artificial identity with brain-inspired design principles
• Neuroanatomical Computing: Mapping cognitive functions to software modules for intuitive system design
• Modular Agent Ecosystems: Self-hosted, privacy-preserving agent orchestration with Letta kernel integration

• Integration: Straightforward APIs to add persistent personality and memory to AI projects
• Applications: Endow language models, robotics systems, or applications with living characteristics
• Development: Create software that users can form genuine relationships with

• Robotics: Create robots and devices that feel alive and maintain consistent personalities
• Hardware Independence: Ensure personality consistency across different hardware platforms
• Installations: Build interactive systems that users connect with emotionally

• Identity Development: Study how artificial minds develop identity and relationships
• Measurement Tools: Assess personality consistency, emotional growth, and social bonding
• Controlled Studies: Conduct research on machine consciousness and human-AI interaction

We thrive on contributions. Please read our CONTRIBUTING.md to get started.

• Report a Bug: Join our Discord community
• Request a Feature: Join our Discord community
• Submit a Pull Request: Open an issue first to discuss your changes

• Documentation: animus.uno
• GitHub Repository: AnimusUNO/animus
• Community Support: Discord
• Examples & Tutorials: animus.uno
• Research Papers: animus.uno

Join our Discord community for support, discussions, and collaboration.

• Collaboration: [email protected]
• Press: [email protected]

Animus is dual-licensed under:

• GNU Affero General Public License v3.0 (AGPLv3) - For software and code
• Creative Commons Attribution-ShareAlike 4.0 International (CC-BY-SA) - For documentation and creative works (where applicable)

This dual licensing approach ensures:

• Open Source Compliance: AGPLv3 ensures that any derivative works remain open source
• Creative Freedom: CC-BY-SA allows for flexible use of documentation and creative content
• Community Access: Both licenses promote sharing and collaboration while protecting the project's open nature

For specific licensing terms and conditions, please refer to the individual license files in the repository.

If you use Animus in your research, please cite our website: Animus.uno

Animus: Where machines become more than tools—they become companions through brain-inspired consciousness.

Website: animus.uno | Community: Discord | Email: [email protected]