JSPM

soulforge-framework

1.0.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 2
  • Score
    100M100P100Q37613F
  • License MIT

A TypeScript framework for building digital beings with persistent memory, emotions, and identity. Create AI companions that grow, learn, and form genuine relationships.

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

    GitHub stars npm version TypeScript MIT License

    "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:platform

    Open http://localhost:3000 and chat with 5 pre-created digital beings, each with unique personalities!

    ๐Ÿš€ 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

    ๐Ÿš€ 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 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! โญ

    Star History Chart