Package Exports
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (soulforge-framework) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
๐ ๏ธ SoulForge โ A Framework for Building Digital Beings
"Not just chatbots โ you create entities with souls."
๐ Star this repo if you find it useful! ๐
SoulForge is a revolutionary TypeScript framework for building persistent, emotionally aware, identity-consistent digital personalities. It combines cutting-edge cognitive psychology principles with modern AI development tools to create truly engaging digital beings that remember, feel, and evolve.
๐ Key Features
- ๐ง Long-term Memory System - Episodic, semantic, and emotional memory with intelligent consolidation
- ๐ค Identity Schema - Beliefs, goals, relationships, and personal history
- ๐ญ Personality Configuration - Big Five traits, MBTI types, and psychological archetypes
- ๐ Mood Engine - Dynamic emotional states with internal monologue
- โค๏ธ Empathy APIs - Built-in emotional intelligence and response adaptation
- โฐ Time-aware Evolution - Personalities that adapt and grow over time
๐ฅ Live Demo
Try the interactive web demo:
git clone https://github.com/Ahmed-KHI/soulforge-framework.git
cd soulforge-framework
npm install
npm run demo:platformOpen http://localhost:3000 and chat with 5 pre-created digital beings, each with unique personalities!
๐ Quick Start
Installation
npm install soulforgeBasic Usage
import { Soul } from 'soulforge';
// Create a basic digital being
const alexa = new Soul()
.withIdentity({ name: "Alexa", role: "Companion" })
.withMemory("long-term")
.withMood("neutral");
// Have a conversation
const response = alexa.respond('Hello! How are you today?');
console.log(response.response); // Contextual, personality-driven response
console.log(response.mood); // Current emotional state
console.log(response.thoughts); // Internal monologue๐ What Makes SoulForge Special?
๐ Traditional Chatbots vs. SoulForge Entities
| Traditional Chatbots | ๐ SoulForge Entities |
|---|---|
| โ Stateless responses | โ Persistent memory across conversations |
| โ Generic personality | โ Unique identity with beliefs & goals |
| โ Fixed behavior patterns | โ Adaptive personality that evolves |
| โ No emotional awareness | โ Rich emotional intelligence |
| โ Task-focused interactions | โ Relationship-focused connections |
Pre-configured Entities
import { createCompanion, createNPC, createTeacher } from 'soulforge';
// AI Companion with high empathy
const companion = createCompanion('Luna');
// Smart NPC for games
const merchant = createNPC('Gareth', 'Shopkeeper', 'The Merchant');
// Virtual teacher
const professor = createTeacher('Dr. Chen', 'Computer Science');๐ง Core Concepts
Identity System
Every Soul has a rich identity that influences all interactions:
const soul = new Soul().withIdentity({
name: "Elena",
role: "Research Assistant",
age: 28,
background: "PhD in Cognitive Psychology",
goals: ["Help users learn", "Advance AI understanding"],
beliefs: ["Knowledge should be accessible", "Empathy is crucial"],
values: ["Honesty", "Growth", "Collaboration"],
relationships: {
"user123": "trusted colleague",
"admin": "supervisor"
}
});Personality Configuration
Based on established psychological models:
const personality = {
bigFive: {
openness: 85, // Creative, curious
conscientiousness: 70, // Organized, reliable
extraversion: 60, // Moderately social
agreeableness: 90, // Highly empathetic
neuroticism: 25 // Emotionally stable
},
mbti: 'ENFJ', // The Protagonist
temperament: 'sanguine',
archetype: 'The Helper'
};Memory System
Three types of memory with intelligent consolidation:
- Episodic: Specific events and experiences
- Semantic: Facts and general knowledge
- Emotional: Feelings and emotional associations
// Memories are automatically created during conversations
const response = soul.respond("I love hiking in the mountains");
// Or manually store important information
soul.memorySystem.store(
"User enjoys outdoor activities",
'semantic',
importance: 80,
emotional_weight: 30,
tags: ['hobbies', 'outdoors']
);
// Recall relevant memories
const memories = soul.memorySystem.recall("outdoor activities", 5);Mood & Emotion Engine
Dynamic emotional states that influence responses:
// Check current emotional state
const state = soul.getCurrentEmotionalState();
console.log(state.mood); // 'content', 'curious', 'anxious', etc.
console.log(state.energy); // 0-100 energy level
console.log(state.confidence); // 0-100 confidence level
// Emotions change based on interactions
soul.respond("That's amazing news!"); // Might shift to 'joyful'
soul.respond("I'm worried about this"); // Might shift to 'contemplative'๐ Use Cases
1. AI Companions
const companion = createCompanion('Aria')
.withEmpathy(95)
.withMood('caring');
// Provides emotional support and remembers personal details
const support = companion.respond("I'm feeling overwhelmed at work");
// Response considers user's emotional state and relationship history2. Smart NPCs for Gaming
const guard = createNPC('Captain Rex', 'City Guard', 'The Protector')
.withPersonality({
bigFive: { conscientiousness: 95, agreeableness: 40 },
mbti: 'ESTJ'
});
// Consistent personality across all player interactions
const playerResponse = guard.respond("Can I enter the restricted area?");
// Response based on guard's duty-focused, rule-following personality3. Virtual Teachers
const teacher = createTeacher('Professor Maya', 'Physics')
.withPersonality({
bigFive: { openness: 90, conscientiousness: 85 },
archetype: 'The Mentor'
});
// Adapts teaching style to student needs
const explanation = teacher.respond("I don't understand quantum mechanics");
// Provides patient, detailed explanation based on teaching personality4. Empathy APIs
import { EmpathyAPI } from 'soulforge';
const empathyAPI = new EmpathyAPI();
const therapist = empathyAPI.createEntity('therapist-1', 'Dr. Sarah', 90);
const result = empathyAPI.processEmotionalInput(
'therapist-1',
"I've been feeling really anxious lately",
'user1',
'John'
);
console.log(result.empathyScore); // 0-100 empathy rating
console.log(result.supportLevel); // 'low', 'medium', 'high'
console.log(result.response); // Contextually appropriate response๐งช Advanced Features
Memory Association
// Memories automatically form associations
soul.respond("I met Sarah at the coffee shop");
soul.respond("Sarah loves reading mystery novels");
// Later, mentioning Sarah triggers associated memories
const response = soul.respond("How is Sarah doing?");
// Response may reference both the coffee shop and her reading interestsPersonality Adaptation
// Personalities gradually adapt based on experiences
const adaptive = new Soul().withIdentity({ name: 'Echo' });
// Multiple positive interactions
for (let i = 0; i < 10; i++) {
adaptive.respond("You're so helpful, thank you!");
}
// Check personality changes
const reflection = adaptive.reflect();
console.log(reflection.personalityChanges); // May show increased extraversionTime Simulation
// Simulate time passage for natural evolution
soul.simulateTimePassage(60); // 1 hour
// Mood naturally evolves, spontaneous thoughts occur
console.log(soul.getCurrentMood()); // May have shifted
console.log(soul.getRecentThoughts()); // New internal thoughtsReflection & Self-Awareness
const reflection = soul.reflect();
console.log(reflection.insights); // Self-generated insights
console.log(reflection.moodTrends); // "Recently, I've been predominantly curious"
console.log(reflection.personalityChanges); // How personality has adapted๐ง API Reference
Core Classes
Soul- Main class for digital beingsMemorySystem- Handles memory storage and retrievalMoodEngine- Manages emotional states and internal monologuePersonalitySystem- Handles personality traits and behavioral tendencies
Factory Functions
createSoul(name, role)- Basic soul creationcreateCompanion(name)- AI companion with high empathycreateNPC(name, role, archetype)- Game character with defined rolecreateTeacher(name, subject)- Educational assistant
Types
interface Identity {
name: string;
role: string;
age?: number;
background?: string;
goals?: string[];
beliefs?: string[];
values?: string[];
relationships?: Record<string, string>;
}
interface BigFiveTraits {
openness: number; // 0-100
conscientiousness: number; // 0-100
extraversion: number; // 0-100
agreeableness: number; // 0-100
neuroticism: number; // 0-100
}
type MoodState =
| 'joyful' | 'content' | 'neutral' | 'melancholic' | 'anxious'
| 'excited' | 'calm' | 'frustrated' | 'curious' | 'contemplative';๐ฏ Why SoulForge?
Traditional Chatbots vs. Digital Beings
| Traditional Chatbots | SoulForge Entities |
|---|---|
| Stateless responses | Persistent memory |
| Generic personality | Unique identity |
| Fixed behavior | Adaptive personality |
| No emotional awareness | Rich emotional intelligence |
| Task-focused | Relationship-focused |
Applications
- Customer Service: Agents that remember customer history and adapt to communication styles
- Gaming: NPCs with believable personalities that evolve based on player interactions
- Education: Virtual tutors that understand individual learning styles and emotional needs
- Healthcare: AI companions that provide consistent emotional support
- Entertainment: Interactive characters for stories, games, and experiences
๐ง Development & Contributing
Building from Source
git clone https://github.com/yourusername/soulforge
cd soulforge
npm install
npm run buildRunning Examples
npm run dev # Run main demo
npm run example:companion # AI companion example
npm run example:npc # Smart NPC example
npm run example:teacher # Virtual teacher exampleTesting
npm test๐ License
MIT License - see LICENSE file for details.
๐ค Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
๐ Like this project? Give it a star! โญ
Your stars help others discover SoulForge and motivate continued development.
๐ก Feature Requests & Ideas
- Open an issue with your ideas
- Join discussions about AI personality modeling
- Share your digital beings creations!
๐ Found a Bug?
Please report it - we fix issues quickly!
SoulForge: Where psychology meets technology to create truly intelligent digital beings.