https://github.com/sixtdreanight/companion-engine
AI companion core engine -- personality, relationship, memory, safety, and pipeline
https://github.com/sixtdreanight/companion-engine
ai-companion chatbot llm personality-engine typescript
Last synced: 27 days ago
JSON representation
AI companion core engine -- personality, relationship, memory, safety, and pipeline
- Host: GitHub
- URL: https://github.com/sixtdreanight/companion-engine
- Owner: sixtdreanight
- License: gpl-3.0
- Created: 2026-05-23T05:53:47.000Z (about 2 months ago)
- Default Branch: master
- Last Pushed: 2026-05-23T06:51:36.000Z (about 2 months ago)
- Last Synced: 2026-05-23T08:26:06.731Z (about 2 months ago)
- Topics: ai-companion, chatbot, llm, personality-engine, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@sixtdreamnight/companion-engine
- Size: 81.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
**Language:** [English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-Hant.md) | [日本語](README.ja.md)
# @sixtdreamnight/companion-engine
**AI companion core engine — personality, relationship, memory, safety, and pipeline.**
Powers [Yumema](https://github.com/sixtdreanight/Yumema).
[](https://www.npmjs.com/package/@sixtdreamnight/companion-engine)
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://www.typescriptlang.org/)
---
## Installation
```bash
npm install @sixtdreamnight/companion-engine
```
## Quick Start
```typescript
import { loadConfig, processMessage, processMessageStream } from "@sixtdreamnight/companion-engine";
import "dotenv/config";
const config = loadConfig();
// Standard pipeline
const reply = await processMessage("Hello!", { userId: "user-1", config });
console.log(reply);
// Streaming pipeline (token-level)
for await (const chunk of processMessageStream("Hello!", { userId: "user-1", config })) {
process.stdout.write(chunk);
}
```
## API Overview
| Module | Description |
|--------|-------------|
| **Config** | Load and manage app configuration, profiles, environment variables |
| **Pipeline** | 5-stage message pipeline with streaming support + persistent checkpoints |
| **Personality** | Character engine — mood, topic suggestion, emotional support, session management |
| **Emotion** | Stateful emotion model — 7 emotions with probabilistic transitions |
| **Relationship** | Affection system, relationship stages, confession/breakup, affection decay, multi-character |
| **Memory** | Short-term / long-term memory, summarization, forgetting curve, semantic search |
| **Safety** | Multi-layer safety — regex, LLM-based, composite checker. Profile validation |
| **Scheduler** | Cron-based background task scheduler |
| **Search** | Web search and conversation history search |
| **Checkpointer** | Persistent session state (JSON default) |
| **Embedding** | Text vectorization for semantic memory (TF-IDF default) |
| **Validation** | Zod runtime schema validation |
| **MBTI** | Conversation-based MBTI inference |
| **Card Import** | SillyTavern V1/V2/V3 + Character.AI character card import |
## Key Features (v0.2.0)
- **Persistent sessions**: `JsonCheckpointer` survives process restarts
- **Streaming pipeline**: `processMessageStream()` token-level async generator
- **Emotion model**: 7-state emotional system with intensity tracking
- **Affection decay**: Gradual affection loss after 7 days of inactivity
- **Multi-character relationships**: Each character gets independent state
- **Semantic memory**: `TfIdfEmbeddingProvider` for vector-based retrieval
- **Zod validation**: Runtime type validation for Profile and AppConfig
- **LLM safety checker**: Optional LLM-based safety layer
- **MBTI inference**: Personality type detection from conversation
- **C.AI import**: Character.AI export format support
## Peer Dependencies
- `@ai-sdk/anthropic` ^3.0.0
- `@ai-sdk/openai` ^3.0.0
- `ai` ^6.0.0
- `dotenv` ^17.0.0
- `node-cron` ^3.0.0
- `zod` ^3.0.0
Full API docs: [API_REFERENCE.md](API_REFERENCE.md)
## License
GPL-3.0 — see [LICENSE](./LICENSE).
---
**Language / 语言 / 言語**
[**English**](README.md) | [**简体中文**](README.zh-CN.md) | [**繁體中文**](README.zh-Hant.md) | [**日本語**](README.ja.md)