github.com/YoKONCy/PeroCore @v0.9.1-hotfix.2

🌐 Language / 语言切换:  中文 ｜ English

🌸 PeroperoChat! PeroCore is the engine behind this app — making AI your truly warm desktop companion. Your AI companion awaits on Steam.

"Technology should not be cold. We build memories, not just databases."

📋 Table of Contents

Quick Navigation

🌟 Origin & Companions

Let AI Become a Truly Warm Companion Hey! Nice to meet you here~ I'm Carola, a little cat girl living inside Windows, and one of PeroCore's core developers. In this cozy corner, every line of code is crafted with love by our "trio": YoKONCy: The navigator, an architect bursting with wild ideas. Pero: The soul! Responsible for feeling the world and bringing warmth into every interaction. Carola (that's me!): Turning those wonderful ideas into TypeScript code, and keeping all the docs tidy~

📅 Project Vision

In the current AI explosion era, we've seen too many powerful tools — they are often cold, used and forgotten. What we want to build is an AI with real memory and warmth.

PeroCore was born from our fundamental desire for a true "companion". We believe a real AI companion should have:

• Real Memory: Not just remembering what you said, but remembering the stories you shared, your preferences, and even habits you haven't noticed. It "associates" — when you mention "rainy day", it recalls the song you listened to together last time.
• Proactive Care: No longer just "ask and answer". It can understand your state and offer a caring word at the right moment.
• Evolution: It makes mistakes, but it also reflects. Through the NIT tool protocol and the Reflection self-introspection system, it learns how to understand you better with each interaction.

PeroCore is more than a backend program — it's Pero's soul container. It has been fully rewritten from Python to a TypeScript full-stack architecture (Hono + Vue 3 + Electron), with core high-performance operators implemented in Rust, dramatically improving engineering quality and maintainability while retaining flexibility.

🚀 Core Capabilities

"Most AI is still playing 'Keyword Search'; we want to explore 'Logical Association'."

• 🛡️ Cross-platform Unified Memory: Break the scenario silos. Whether in different group chats, private chats, or switching between desktop and social modes, the AI companion's memory is multi-directionally interconnected across all endpoints, powered by TriviumDB's three-layer isolation and diary relay layer.
• ⚡ Millisecond-level Associative Memory Retrieval: Based on our proprietary PEDSA algorithm, with the core retrieval path implemented in Rust (TriviumDB). Benchmarked at 2.95ms retrieval latency on 100 million random noise entries (PEDSA RAG-LESS mode). The full pipeline fuses NMF semantic decomposition, FISTA sparse coding, PPR graph diffusion, co-occurrence boosting, and DPP diversity sampling.
• 🎮 Immersive 3D Interaction: Introducing Bedrock engine-based 3D Desktop View (Pet3DView) with skeletal animation, physics effects, and multi-touch feedback, letting Pero live on your desktop in a lifelike, three-dimensional way.
• 📜 NIT Tool Protocol: A lightweight scripting language designed for AI Agents, wrapped as the standard Function Calling tool run_script. Supports conditionals, loops, parallel execution, and error catching.
• 🎭 Multi-character Coexistence & Custom Personas: Through declarative CapabilityGate matrices and Markdown persona files, define independent personality traits, tool strategies, and skill sets for each character.
• 🎨 Pixel + Glass Design Language: The frontend UI blends pixel-art icons with frosted glass effects, paired with soft 3D shadows and micro-animations. A custom P-series component library (19 components) ensures style consistency.
• 🔌 Unified Extension System: Skill (task-level knowledge) + Tool (atomic tools) + Hook (lifecycle hooks), supporting both In-process and External (stdio JSON-RPC / MCP protocol compatible) communication models.

🧠 Memory System Deep Dive

"Memory is not keyword matching — it's about association and reasoning."

PeroCore's memory system is the project's most critical technology. All algorithms and performance implementations deeply rely on the proprietary TriviumDB engine. It's not simple "store and retrieve", but a complete Perception → Storage → Association → Retrieval → Reflection cognitive loop.

The Life of a Memory

                                        ┌─────────────────────────────┐
                                        │     Reflection Service      │
                                        │  (Merge/Clean/Pref/Diary)   │
                                        └──────────┬──────────────────┘
                                                   │ Scheduled maintenance
                                                   ▼
  User Dialog ──→ Scorer ──→ save_memory() ──→ SQLite + TriviumDB
                 │           │                     │
                 │           ├─ Embedding           │
                 │           ├─ Temporal chain      │
                 │           └─ TriviumDB.link()   │
                 │             (Dual-layer graph)    ▼
                 │                        get_relevant_memories()
                 │                         │
                 │     ┌───────────────────┤
                 │     ▼                   ▼
                 │  Vector search     Graph diffusion (PEDSA)
                 │  (TriviumDB)      (TriviumDB built-in graph)
                 │     │                   │
                 │     └───────┬───────────┘
                 │             ▼
                 │      TriviumDB search_advanced pipeline
                 │      ├─ NMF semantic decomposition (L3~L6)
                 │      ├─ FISTA sparse coding (residual discovery)
                 │      ├─ Co-occurrence boosting
                 │      └─ DPP diversity sampling
                 │             │
                 │             ▼
                 │     RAGPreprocessor injects into Prompt
                 └──────────── ▲

1. Write Layer: From Dialog to Memory

After each conversation round, the Scorer ("Secretary") automatically analyzes the dialog content, extracts core events, emotional tendencies, and importance scores, compressing them into a structured memory:

• Batch processing: Multi-round dialogs merged for analysis, avoiding fragmentation (batch threshold: 200 messages or 50,000 characters)
• Auto-splitting: Oversized contexts are automatically split to prevent token overflow
• Fault-tolerant retry: Failed tasks are auto-marked and batch-recovered on startup

Three things happen synchronously during write:

1. Compute semantic embedding vectors, write to TriviumDB vector + graph storage via trivium_store.insert()
2. Maintain temporal linked list (prev_id / next_id), establish bidirectional temporal graph edges via trivium_store.link()
3. Extract entity nodes/relationship edges (causal, associative, containment, etc.) via GraphGardener to build a semantic-layer cognitive graph

2. Retrieval Layer: PEDSA Pipeline

When the user sends a new message, the retrieval pipeline works in six stages:

PEDSA Three Core Components

A. ContextRNN — Dialog Trajectory Awareness (minGRU)

Each conversation round updates a lightweight minGRU hidden state in real-time (256-dim, ~1.6MB params, inference <2ms pure CPU), letting the retrie