🤖 Digital Companion Core

What it does in 1 sentence: Stateful personality + memory + emotion model for AI personas.

🌟 Star this repo if you find it useful! 🌟

Create digital companions that remember conversations, develop relationships, and evolve their personality over time. Not just another chatbot - these are persistent AI personas with memory, emotions, and growth.

🚀 Quickstart

Installation

npm install digital-companion-core

15-Line Persona Example

import { Soul } from 'digital-companion-core';

// Create a digital companion in 15 lines
const companion = new Soul()
  .withIdentity({ 
    name: "Alex", 
    role: "Study Buddy",
    personality: "ENFP" // Enthusiastic, creative, people-focused
  })
  .withMemory("persistent") // Remembers across sessions
  .withMood("encouraging"); // Default emotional state

// Have a conversation - companion remembers and evolves
const response1 = companion.respond("I'm struggling with calculus");
console.log(response1.response); // "I understand calculus can be tough! Let's break it down together..."
console.log(response1.mood);     // "empathetic" (mood shifted based on your need)

const response2 = companion.respond("I finally solved that problem!");  
console.log(response2.response); // "That's amazing! I remember you were struggling with calculus - you've grown so much!"
console.log(response2.mood);     // "proud" (shares in your success)

🎥 See Growth Over Time

Check out demo_persona.json to see how Maya evolves through 3 conversations with Sarah:

• Interaction 1: Curious newcomer → Forms first memory
• Interaction 2: Empathetic friend → Builds relationship
• Interaction 3: Proud supporter → Celebrates success

Growth metrics: Trust (0→0.9), Memories (1→5), Emotional bond (0→0.8)

🚀 Quick Start

Installation

npm install soulforge

Basic 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

🧠 Core Concepts

Memory System

• Short-term: Active conversation context
• Long-term: Important events, relationships, patterns
• Emotional: How feelings attach to memories
• Semantic: Facts, knowledge, learned information

Identity Framework

• Personality: Big Five traits + MBTI types
• Beliefs: Core values that guide responses
• Goals: What the persona wants to achieve
• Relationships: History and bonds with users

Affective State Engine

• Dynamic Moods: Emotions that shift based on interaction
• Energy Levels: Social battery and engagement capacity
• Stress Response: How pressure affects behavior
• Confidence: Self-assurance that grows over time

🔧 Extending the Framework

Custom Memory Types

// Add domain-specific memory
companion.addMemory({
  type: 'skill_progress',
  content: 'User improved at calculus',
  importance: 0.8,
  emotional_weight: 0.6
});

Custom Personality Traits

// Define specialized personality
const therapist = new Soul()
  .withPersonality({
    empathy: 0.95,
    patience: 0.9,
    analytical: 0.7
  });

Mood Triggers

// Set emotional responses
companion.addMoodTrigger('success_celebration', {
  trigger: (input) => input.includes('success'),
  mood_change: 'joyful',
  energy_boost: 20
});

🎯 Use Cases

• Gaming: NPCs that remember player choices and evolve
• Education: Study companions that adapt to learning styles
• Customer Service: Agents that build long-term relationships
• Therapy: Supportive personas with emotional intelligence
• Creative Writing: Characters with consistent personalities

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 history

2. 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 personality

3. 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 personality

4. 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 interests

Personality 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 extraversion

Time 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 thoughts

Reflection & 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 beings
• MemorySystem - Handles memory storage and retrieval
• MoodEngine - Manages emotional states and internal monologue
• PersonalitySystem - Handles personality traits and behavioral tendencies

Factory Functions

• createSoul(name, role) - Basic soul creation
• createCompanion(name) - AI companion with high empathy
• createNPC(name, role, archetype) - Game character with defined role
• createTeacher(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 build

Running 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 example

Testing

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. .

🌟 Don't forget to star this repository if you found it useful! ⭐