Hugging Face's logo

Spaces:
VirtualKimi
/
Virtual-Kimi
Running

App Files Community
Virtual-Kimi / README.md
VirtualKimi's picture
VirtualKimi
Update README.md
12f7734 verified
preview code
|
raw
history blame contribute delete
14.3 kB
metadata
license: openrail
title: Virtual Kimi - AI Companion App 💖
sdk: static
emoji: 😻
colorFrom: indigo
colorTo: purple
pinned: true
short_description: AI companion girlfriends with adaptive personalities

Virtual Kimi

Open Source No Commercial Use

Virtual Kimi - AI Companion Application 💖

Web-based AI companion girlfriends featuring adaptive personalities, intelligent memory systems, and immersive conversational experiences.

Overview

Virtual Kimi is an advanced virtual companion application that combines modern web technologies with state-of-the-art AI models to create meaningful, evolving relationships between users and AI girlfriend personalities.

  • Lightweight: ~600 KB of pure JavaScript, HTML, and CSS (no frameworks)
  • Local-first: All data is stored in your browser's IndexedDB (managed by Dexie.js)
  • No tracking: The only external calls are to FontAwesome (for icons) and the OpenRouter API (for AI)

Built with vanilla JavaScript and modern web APIs, it offers a rich, responsive experience across devices.

🌐 Support & Links

Key Features

🤖 Advanced AI Integration

Available recommended models and pricing for Openrouter (per 1M tokens):

  • Mistral-small-3.2: 0.05$ input, 0.1$ output (128k context)
  • Nous Hermes Llama 3.1 70B: 0.1$ input, 0.28$ output (131k context)
  • Cohere Command-R-08-2024: 0.15$ input, 0.6$ output (131k context)
  • Qwen3-235b-a22b-think: 0.13$ input, 0.6$ output (262k context)
  • Grok 3 mini: 0.3$ input, 0.5$ output (131k context)
  • Nous Hermes Llama 3.1 405B: 0.7$ input, 0.8$ output (131k context)
  • Anthropic Claude 3 Haiku: 0.25$ input, 1.25$ output (131k context)
  • Local Model (Ollama): 0$ input, 0$ output (4k context, runs offline — experimental, not fully functional yet)

👥 Multiple AI Personalities

  • Kimi: Cosmic dreamer and astrophysicist with ethereal sensibilities
  • Bella: Nurturing botanist who sees people as plants needing care
  • Rosa: Chaotic prankster thriving on controlled chaos
  • Stella: Digital artist transforming reality through pixelated vision

Personality Trait Ranges

All personality traits operate on a 0-100 scale:

  • Affection: Emotional warmth and attachment
  • Playfulness: Fun-loving and spontaneous behavior
  • Intelligence: Analytical and thoughtful responses
  • Empathy: Understanding and emotional support
  • Humor: Wit and lighthearted interactions
  • Romance: Romantic and intimate expressions

🧠 Intelligent Memory System

  • Automatic extraction and categorization of conversation memories
  • Seven memory categories: Personal, Preferences, Relationships, Activities, Goals, Experiences, Events
  • Persistent memory across sessions with search and management capabilities
  • Character-specific memory isolation

💫 Dynamic Personality Evolution

  • Six personality traits that evolve based on interactions:
  • Affection, Playfulness, Intelligence, Empathy, Humor, Romance
  • Real-time trait adjustments based on conversation tone and content
  • Visual personality indicators and progression tracking
  • Intelligent model selection and switching
  • Real-time emotion detection and analysis
  • Contextually-aware responses

🎬 Emotion-Driven Visual Experience

  • Real-time video responses matching detected emotions
  • Smooth transitions between emotional states
  • Character-specific visual libraries with 50+ video clips
  • Context-aware video selection system

🎨 Customizable Interface

  • Five professionally designed themes
  • Adjustable interface transparency
  • Responsive design optimized for desktop, tablet, and mobile
  • Accessibility features and keyboard navigation

🌍 Multilingual Support

  • Full localization in 7 languages: English, French, Spanish, German, Italian, Japanese, Chinese
  • Automatic language detection from user input
  • Culturally-aware responses and emotion keywords

🔌 Extensible Plugin System

  • Theme plugins for visual customization (currently, only the color theme plugin is functional)
  • Voice plugins for speech synthesis options (planned)
  • Behavior plugins for personality modifications (planned)
  • Secure plugin loading with validation

🛡️ Security & Privacy

  • Input validation and sanitization
  • Secure API key handling
  • Local data storage with IndexedDB
  • No server dependencies for core functionality

🏗️ Technical Architecture

🧩 Core Technologies

  • Frontend: Vanilla JavaScript (ES6+), HTML5, CSS3
  • Database: IndexedDB with Dexie.js
  • AI Integration: OpenRouter API
  • Speech: Web Speech API
  • Audio: Web Audio API

✨ Inspiration & Assets

This project was originally inspired by the JackyWine GitHub repository. @Jackywine on X (Twitter)

The four main characters are visually based on images from four creators on X (Twitter):

  • @JulyFox33 (Kimi)
  • @BelisariaNew (Bella)
  • @JuliAIkiko (Rosa and Stella)

All character videos were generated using the image-to-video AI from Kling.ai, specifically with the Kling v2.1 model.

Get 50% bonus Credits in your first month with this code referral 7BR9GT2WQ6JF - link: https://klingai.com

🗂️ Module Structure 


├── Core System
│ ├── kimi-script.js # Main initialization
│ ├── kimi-database.js # Data persistence layer
│ ├── kimi-config.js # Configuration management
│ └── kimi-security.js # Security utilities
├── AI & Memory
│ ├── kimi-llm-manager.js # LLM integration
│ ├── kimi-emotion-system.js # Emotion analysis
│ ├── kimi-memory-system.js # Intelligent memory
│ └── kimi-memory-ui.js # Memory interface
├── Interface & Media
│ ├── kimi-appearance.js # Theme management
│ ├── kimi-voices.js # Speech synthesis
│ ├── kimi-utils.js # Utility classes
│ └── kimi-module.js # Core functions
├── Localization
│ └── kimi-locale/ # Translation files
└── Extensions
└── kimi-plugins/ # Plugin system

Data Flow

  1. Input Processing: User input → Security validation → Language detection
  2. AI Analysis: Emotion detection → Memory extraction → LLM processing
  3. Response Generation: Personality-aware response → Emotion mapping → Visual selection
  4. Memory Update: Trait evolution → Memory storage → UI synchronization

Installation & Setup

Prerequisites

  • Modern web browser (Chrome, Edge, Firefox recommended)
  • OpenRouter API key (optional but recommended for full functionality)

Quick Start

  1. Clone the repository

    git clone https://github.com/virtualkimi/virtual-kimi.git
cd virtual-kimi

  2. Open the application

    • Open index.html in your web browser
    • Or serve via local web server for optimal performance:
      python -m http.server 8000
# Navigate to http://localhost:8000

  3. Configure API access

    • Open Settings → AI & Models
    • Add your OpenRouter API key
    • Select preferred AI model

  4. Customize your experience

    • Choose a character in Personality tab
    • Enable memory system in Data tab
    • Adjust themes in Appearance tab

Production Deployment

For production deployment, ensure:

  • HTTPS is enabled (required for microphone access)
  • Gzip compression for assets
  • Proper cache headers
  • CSP headers for enhanced security

⚙️ Configuration

API Integration

The application supports multiple AI providers through OpenRouter:

  • Mistral models
  • Nous Hermes models
  • Qwen3 models
  • Open-source alternatives

Memory System Configuration 

// Memory categories can be customized
const memoryCategories = [
    "personal", // Personal information
    "preferences", // Likes and dislikes
    "relationships", // People and connections
    "activities", // Hobbies and activities
    "goals", // Aspirations and plans
    "experiences", // Past events
    "important" // Significant moments
];

🛠️ Development

Project Structure 

virtual-kimi/
├── index.html              # Main application
├── virtualkimi.html         # Landing page
├── kimi-*.js               # Core modules
├── kimi-locale/            # Localization
├── kimi-plugins/           # Plugin examples
├── kimi-videos/            # Character videos
├── kimi-icons/             # Character assets
└── docs/                   # Documentation

Adding New Features

Creating a New Plugin 

// manifest.json
{
    "name": "Custom Theme",
    "version": "1.0.0",
    "type": "theme",
    "style": "theme.css",
    "main": "theme.js",
    "enabled": true
}

Note: As of version 1.0, only the color theme plugin is fully functional. Voice and behavior plugins are planned for future releases. See kimi-plugins/sample-theme/ for a working example.

Extending Memory Categories 

// Add to kimi-memory-system.js
const customCategory = {
    name: "custom",
    icon: "fas fa-star",
    keywords: ["keyword1", "keyword2"],
    confidence: 0.7
};

Health Check System

The application includes a comprehensive health check system:

// Run health check
const healthCheck = new KimiHealthCheck();
const report = await healthCheck.runAllChecks();
console.log(report.status); // 'HEALTHY' or 'NEEDS_ATTENTION'

Browser Compatibility

Browser Voice Recognition Full Features Notes
Chrome 90+ ✅ ✅ Recommended
Edge 90+ ✅ ✅ Optimal voice performance
Firefox 88+ ⚠️ ✅ Limited voice support
Safari 14+ ⚠️ ✅ iOS limitations

Performance

Optimization Features

  • Lazy loading of non-critical modules
  • Efficient batch database operations
  • Debounced UI interactions
  • Memory management with cleanup
  • Optimized video preloading

Resource Usage

  • Memory footprint: ~15-30MB active usage
  • Storage: Scales with conversation history
  • Network: API calls only, no tracking
  • CPU: Minimal background processing

Privacy & Security

Data Handling

  • All data stored locally in browser
  • No telemetry or analytics
  • API keys encrypted in local storage
  • User content never sent to external servers (except chosen AI provider)

Security Measures

  • Input validation and sanitization
  • XSS protection
  • Safe plugin loading
  • Secure API communication

Troubleshooting

Common Issues

  • Microphone not working: Ensure HTTPS and browser permissions
  • API errors: Verify OpenRouter key and model availability
  • Performance issues: Clear browser cache, check available memory
  • Memory system not learning: Ensure system is enabled in Data tab

Contributing

We welcome contributions! Please see our contributing guidelines:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes with appropriate tests
  4. Submit a pull request with detailed description

Development Guidelines

  • Follow existing code style and patterns
  • Add comments for complex functionality
  • Test across multiple browsers
  • Update documentation for new features

🔄 TODO / Roadmap

  • Full support for local models (Ollama integration, offline mode)
  • Voice plugin system (custom voices, TTS engines)
  • Behavior plugin system (custom AI behaviors)
  • Better advanced memory management UI
  • More character personalities and backgrounds
  • In-app onboarding and help system
  • Enhanced mobile experience (UI/UX)
  • More granular privacy controls
  • User profile and persistent settings sync (optional)
  • Community plugin/theme sharing platform
  • Improved error reporting and diagnostics
  • Accessibility improvements (screen reader, contrast, etc.)
  • Automated testing and CI/CD pipeline
  • Documentation in multiple languages
  • Performance profiling and optimization for large histories
  • Create new character videos better matching specific contexts
  • Improve emotion and context logic
  • Enhance memory management and logic

📜 License

This project is distributed under a custom license. Any commercial use, resale, or monetization of this application or its derivatives is strictly prohibited without the explicit written consent of the author.

See the LICENSE file for details.

Open Source No Commercial Use

Virtual Kimi - Creating meaningful connections between humans and AI, one conversation at a time.

"Love is the most powerful code" 💕

— 2025 Virtual Kimi - Created with 💜 by Jean & Kimi