# KaijiBot 👾

> **Your AI assistant reaches out to you — not the other way around.**

Pluggable provider/channel architecture · Cognitive layer turns AI from reactive to proactive · 30+ LLM providers

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js >=22](https://img.shields.io/badge/Node.js-%3E%3D22-339933.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-6.x-3178C6.svg)](https://www.typescriptlang.org/)

[English](./README.en.md) | [简体中文](./README.md)

## Why KaijiBot

Every AI assistant you've used follows the same pattern: you ask, it answers. You stop asking, it goes silent.

KaijiBot is different. After a few conversations on Feishu, it starts **reaching out to you** proactively — not with spam or hydration reminders, but with things you'd actually find interesting.

|                        | Typical Chatbot                        | KaijiBot                                                                  |
| ---------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
| **Interaction**        | Reactive — you ask, it answers         | Proactive insights + normal Q&A                                           |
| **User Understanding** | Stateless, starts from zero every time | Continuously learns your interests, domains, preferences                  |
| **Timing Awareness**   | Doesn't care what you're doing         | Respects active hours, trust level, conversation cadence                  |
| **Chinese Support**    | English-first, Chinese often breaks    | Chinese-native: pattern routing, persona extraction optimized for Chinese |
| **Integration**        | Requires Web/SDK integration           | Feishu is the terminal — just send a message                              |

## ✨ Core Features

### 🔮 Cognitive Engine — From Reactive Replies to Proactive Insights

You've been chatting with KaijiBot about AI architecture and distributed systems. Next week, it sends you a message unprompted:

> "Saw a recent article on using eBPF for distributed tracing — combining it with the observability direction you've been exploring, this might spark some ideas."

This isn't a scheduled push. It's a genuine insight KaijiBot produced after **understanding you**.

Two weeks later, you bring up Rust and embedded systems. One day it tells you:

> "You've been learning Rust, and you previously showed interest in embedded systems. There's a hands-on article on writing an RTOS kernel in Rust at the intersection of these two — worth a look."

How it works:

- **Persona Profiling** — Every conversation teaches it something new. LLM-driven structured extraction automatically discovers domains and interests from conversations. Insights decay by category independently. Interest lifecycle is tracked automatically. Domain names discovered dynamically by LLM — no hardcoded keywords.
- **Cross-Domain Insights** — You're interested in both A and B, it finds potential connections. You asked about something before but didn't dig deeper, it follows up from a new angle. You've gone deep enough in one area, it suggests extension directions. LLM self-refine loop ensures quality, semantic dedup ensures every push is fresh.
- **Timing Gate** — It doesn't push whenever it feels like it. The PRISM model calculates expected value for each insight. Only pushes when expected benefit exceeds interruption cost. No late-night打扰, restraint during low trust, waits if you've been inactive.
- **Trust Evolution** — Cautious at first, understands you better over time, eventually becomes a confident partner who can make bold recommendations. SARA framework drives four-stage trust evolution. Trust level determines what the system is allowed to do.
- **Preference Learning** — You wrote a long reply? It notes you like this topic. You gave a one-word response? It tries a different direction next time. Thompson Sampling-driven preference learning. Implicit feedback is more honest than explicit feedback.

Insight content is generated from your profile + LLM knowledge + real-time web search. With a search API key, insights stay current.

### 🧬 Self-Evolution — Agent Decides When to Learn New Skills

You've done several complex Feishu knowledge base operations with KaijiBot — searching meeting records, extracting minutes, creating documents, setting tasks. KaijiBot notices this workflow is repetitive and complex, and tells you:

> "I noticed you've been doing similar meeting minute archiving workflows recently. I wrote myself a skill — next time you say 'archive meetings', I'll execute the entire flow automatically."

How it works:

- **Hard Trigger Detection** — Code does noise filtering only, no quality judgments. After detecting complex tasks, a system event is injected.
- **Agent-Driven Decision** — The Agent has full conversation context and decides whether it's worth creating a skill. Not worth it? Ignored.
- **Full Lifecycle** — Dedup check before creation, usage frequency tracking after, auto-cleanup for unused skills.

### 🔄 Correction Self-Evolution — Never Makes the Same Mistake Twice

AI assistant making the same mistake every new session? KaijiBot won't. It has a correction memory system that ensures every mistake is made at most once.

- **Dual-Path Detection** — Agent self-reports errors, or the system automatically extracts corrections from conversations at session end.
- **Dedup + Reinforcement** — Repeated errors don't create new records; they increase weight, ensuring high-frequency issues get priority.
- **System Prompt Injection** — Corrections are injected into the system prompt that the Agent sees every turn, rather than in files that may not be read.

Step into a pit once. That's enough.

### 🔌 Pluggable Architecture

Not locked into any single provider. Switch between domestic and international at will. `kaijibot onboard` wizard auto-discovers configured API keys.

| China (Recommended)                                | International                                    | Aggregator / Self-hosted                        |
| -------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------ |
| Zhipu GLM · DeepSeek · Qwen · Kimi · MiniMax …     | Claude · Gemini · Grok · Mistral · Perplexity …  | OpenRouter · Together · Ollama · LMStudio · vLLM … |

Switch models with a single command:

```bash
kaijibot config set agent.model "deepseek/deepseek-chat"
kaijibot config set agent.model "anthropic/claude-sonnet-4-20250514"
```

### 🛠️ Full Agent

**Agent Loop**: Reason → Call tools → Observe → Continue reasoning. Supports streaming, context compression, parallel sub-agent dispatch. Built-in tools include code execution, web scraping, PDF operations, image/video/music generation, TTS synthesis, Canvas, and more.

**Memory System**: Multiple storage backends with semantic search over conversation history. Three complementary systems maintain Agent context: session memory, daily consolidation, and manual organization.

**Skill Marketplace**: Dozens of built-in skills (github, weather, summarize, coding-agent, notion, obsidian, taskflow, and more). Install additional skills from ClawHub:

```bash
kaijibot skills install <skill-name>
```

## 🚀 Quick Start

### macOS / Linux

**One-click install** (recommended — auto-detects environment, installs dependencies, runs onboard wizard):

```bash
curl -fsSL https://kaijibot.ai/install.sh | bash
```

Also available via npm:

```bash
npm install -g kaijibot
kaijibot onboard
```

### Windows

PowerShell one-click install:

```powershell
iwr -useb https://kaijibot.ai/install.ps1 | iex
```

Or via npm:

```powershell
npm install -g kaijibot
kaijibot onboard
```

### Docker

```bash
git clone https://github.com/Kaiji-Z/kaijibot.git
cd kaijibot
docker compose up -d
```

### Build from Source

```bash
git clone https://github.com/Kaiji-Z/kaijibot.git
cd kaijibot
pnpm install
pnpm build
kaijibot onboard   # Interactive wizard, auto-configures
# Migrating from OpenClaw? Run:
kaijibot migrate
```

### Start

```bash
kaijibot gateway --port 18789 --verbose
```

After starting, find your bot on Feishu and send a message. KaijiBot automatically begins building your cognitive profile and will push the first proactive insight after a few conversations.

## ⚙️ Configuration

**Required**: At least one LLM provider API key + Feishu bot credentials.

```bash
# LLM API Key (pick one)
export ZAI_API_KEY="your-key"              # Zhipu GLM
# export DEEPSEEK_API_KEY="your-key"       # DeepSeek
# export ANTHROPIC_API_KEY="your-key"      # Claude
# export GOOGLE_API_KEY="your-key"         # Gemini

# Feishu channel
kaijibot config set channels.feishu.appId "your-app-id"
kaijibot config set channels.feishu.appSecret "your-app-secret"
```

**Optional**: Web search to enhance insight timeliness.

```bash
export EXA_API_KEY="your-key"
export TAVILY_API_KEY="your-key"
```

Config file at `~/.kaijibot/kaijibot.json`, supports hot reload. Cognitive system can be disabled via `cognitive.enabled: false`. For detailed configuration, see `AGENTS.md`.

## Acknowledgments

Built on the [OpenClaw](https://github.com/openclaw/openclaw) open-source project.

### Academic Research

The cognitive system design draws on the following research:

**Foundational Theory**

- Green, D. M., & Swets, J. A. (1966). _Signal detection theory and psychophysics_. Wiley.
- Thompson, W. R. (1933). On the likelihood that one unknown probability exceeds another in view of the evidence of two samples. _Biometrika_, 25(3/4), 285–294.
- Altman, I., & Taylor, D. A. (1973). _Social penetration: The development of interpersonal relationships_. Holt, Rinehart & Winston.
- Gentner, D. (1983). Structure-mapping: A theoretical framework for analogy. _Cognitive Science_, 7(2), 155–170.

**Human-Computer Relationships & Recommender Systems**

- Bickmore, T. W., & Picard, R. W. (2005). Establishing and maintaining long-term human-computer relationships. _ACM Transactions on Computer-Human Interaction_, 12(2), 293–327.
- Kotkov, D., Wang, S., & Veijalainen, J. (2016). A survey of serendipity in recommender systems. _Knowledge-Based Systems_, 111, 180–192.

**LLM Persona & Memory**

- DEEPER: Directed Persona Refinement. (2025). _Proceedings of ACL 2025_. 32.2% error reduction via active contradiction resolution in persona maintenance.
- PERSONAMEM: Persona-Aware Memory in LLMs. (2025). _Proceedings of COLM 2025_. Benchmark showing LLMs achieve ~50% accuracy on evolving profile tasks.
- DV365: Dynamic User Representations over 365 Days. (2025). _Proceedings of KDD 2025_. Instagram's multi-slicing user embedding architecture.
- GemiRec: Gemini-Powered Recommendations. (2025). Xiaohongshu's multi-interest vector architecture with codebook quantization.
- PIE: Personalized Interest Exploration. (2023). _Proceedings of WWW 2023_. Personalized PageRank with bandit exploration.
- ProfiLLM: Fully Implicit User Profiling from Chatbot Interactions. (2025).

### Open Source Dependencies

[Feishu Open Platform](https://open.feishu.cn/), [Vitest](https://vitest.dev/), [Playwright](https://playwright.dev/), [tsdown](https://github.com/nicepkg/tsdown), [Zod](https://zod.dev/).

## License

[MIT](LICENSE)
