SoulEngine

SoulEngine is designed to transform NPCs into evolving, autonomous actors within a game or simulation. It provides a dual-instance mind architecture where a Speaker handles immediate, low-latency responses while a Mind analyzes context and coordinates tool use in the background. The system supports modular providers for language, voice, and speech-to-text, along with a flexible MCP tool system that lets you define actions an NPC can perform in the game world. With per-NPC memory retention controls, social graphs, and a configurable knowledge base, SoulEngine enables NPCs to remember players, adapt personalities over time, and perform world actions through defined game events or tool calls. The web UI (NPC Editor, Mind history, and dashboards) allows you to create and customize NPCs, set Core Anchors, personality traits, tools, networks, and schedules, and then test interactions in a playground environment.

To use the MCP capabilities, install the server package, start the runtime, and access the UI or API. You can define NPCs, assign MCP Tools with appropriate permissions, select LLM/TTS/STT providers per project, and configure memory retention thresholds. When a conversation occurs, the Mind can recall NPC details or knowledge, issue game-event tools, or prompt the Speaker to respond immediately. This separation helps reduce prompt bloat and enables scalable, agent-driven NPC behavior across games or simulations.

Prerequisites:

• Node.js and npm (or npx available via npm 5.2+)
• Internet access to fetch the MCP server package

Installation steps:

1. Ensure you have Node.js and npm installed
2. Install or run SoulEngine via npx (no global install required)

Code:

# Install and run SoulEngine using npx
npx -y pranavmishra17-soulengine

If you prefer a persistent local install, you could install the package globally (optional):

npm install -g pranavmishra17-soulengine
soulengine  # or the CLI entry point specified by the package

Configuration:

• After starting, configure your NPCs, MCP Tools, and memory settings through the Web UI provided by SoulEngine.
• Set provider preferences (LLM, TTS, STT) per project as needed.

Notes:

• Ensure API keys for your chosen providers are supplied securely (environment variables or secrets management supported by the UI).
• Review and adjust memory retention thresholds to balance performance and NPC richness.

Tips and common issues:

• If the UI cannot connect, verify network access to the server and ensure the correct runtime command is being used (npx path as shown).
• When enabling MCP Tools, assign per-NPC permissions carefully to avoid unintended actions in-game.
• Use the Knowledge and Schedule tabs to tailor NPC behavior and routines for specific scenarios.
• Check Mind State History for previous configurations or changes when debugging NPC behavior.
• If you switch providers (LLM, TTS, STT), ensure API keys and quotas are configured to avoid interruptions during conversations.
• Start with a simple NPC definition (Basic Info, Core Anchor, Personality) and gradually layer in MCP Tools and Social Graph to observe how responses evolve.