JSPM

digital-companion-core

1.1.1
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 6
  • Score
    100M100P100Q35256F
  • License MIT

Stateful personality + memory + emotion model for AI personas. Create digital companions that remember, feel, and evolve through conversations.

Package Exports

  • digital-companion-core
  • digital-companion-core/dist/src/index.js

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 (digital-companion-core) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

๐Ÿค– Digital Companion Core

GitHub stars npm version npm downloads TypeScript MIT License

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! โญ

Star History Chart