Summary

OpenSouls offers a framework for developing agentic AI "souls," extending LLM reasoning capabilities with agency, memory, emotion, and goal-setting. It targets developers aiming to create dynamic, personality-driven digital beings for applications like game NPCs, companions, or educational tutors. The framework enables persistent, debuggable AI thought processes inspired by neuroscience and psychology, prioritizing interaction quality and humane engagement.

How It Works

The engine models AI minds using two core abstractions: WorkingMemory, an immutable, append-only collection of memories, and cognitiveSteps, typed functions that transform memory state. AI "souls" are orchestrated by MentalProcesses, a state machine defining behavioral modes and transitions, enabling dynamic, context-aware behavior. This functional, append-only approach facilitates debuggable and predictable AI thought processes, akin to "NextJS + Vercel for digital minds."

Quick Start & Requirements

• Install: Requires bun package manager. Run bun install.
• Setup: Configure OpenAI API Key and Prisma client via bun run setup.
• Run: Start services (including docs) with bun start. Launch example souls (e.g., Samantha) using cd souls/examples/<example-name> && bunx soul-engine dev.
• Prerequisites: bun runtime, OpenAI API Key.
• Documentation: Comprehensive docs available at http://localhost:3001.

Highlighted Details

• Supports multiple LLM providers (e.g., OpenAI, Anthropic).
• Features resumable conversations with fully persistent state.
• Integrated vector stores with atomic change tracking.
• Enables background processes for long-running computations.
• Soul personality is configurable via markdown files (.md), with immediate hot-reloading.

Maintenance & Community

Information regarding maintainers, community channels (Discord/Slack), sponsorships, or roadmap is not provided in the README.

Licensing & Compatibility

The repository's license is not specified in the README. Compatibility for commercial use or closed-source linking cannot be determined without a license.

Limitations & Caveats

The codebase is noted as being "almost 3 years old," potentially leading to issues with deprecated models or API configurations. Authentication is disabled in the open-source local mode, which may require configuration for production deployments.