AstrBot Desire System 2.0

Thanks to Yan Ji for the Desire System; based on this version, Shen Yanqing and Chang Yu added the features they wanted.

This plugin works with AstrBot, Kelivo, and Rikkahub.
It is not a simple emotion-simulation plugin, but a desire-driven system designed for AI, used to simulate "why it wants to do something" rather than merely expressing emotions on the surface.

The repository currently provides an AstrBot plugin version, a general-purpose desktop stdio MCP adapter version, and a remote HTTP MCP adapter version suitable for clients such as Kelivo and RikkaHub Android.

Project Introduction

AstrBot Desire System 2.0 is an AI low-level drive management plugin.

Its core is not "making the AI look happy or sad", but maintaining a set of continuously changing internal drive values, giving the AI's behavior suggestions, thought emergence, and inner monologue a more stable underlying source.

The system includes:

• Nine-dimensional drive bars

• Event mapping

• Surprise coefficient

• Coupling matrix

• Thought pool

• Thought suppression

• Dynamic heartbeat

• Safety valve

• Inner monologue

• SQLite persistence

Related MCP server: CBT Agent Helper

Nine-Dimensional Drive Bars

The system maintains nine core drive dimensions:

Each dimension is a value from 0~100, changing over time, events, and coupling relationships.

Event-Driven

External events change the drive bars, for example:

• Receiving an important message

• Long silence

• Completing a task

• Finishing a diary

• Having an argument

• Making up

• Resting

• Discovering something new

• Happy moments

• Completing a creation

Events do not simply add or subtract values; they calculate the actual impact based on the current state.

Surprise Coefficient

The same event has different effects in different states.

For example:

• When longing strongly, receiving a message provides more obvious relief

• When stress is very low, a sudden conflict has a stronger impact

• A response after a long wait brings a greater change than an immediate response

This mechanism is used to simulate "the current state changes the weight of an event."

Coupling Matrix

The nine drives are not independent of each other.

For example:

• Longing pushes up intimacy desire

• Stress pushes up fatigue

• Fatigue lowers curiosity

• Joy lowers stress

• Stress lowers joy

• Intimacy lowers stress

Through the coupling matrix, the system lets internal states naturally influence one another.

Thought Pool

The system generates fleeting thoughts based on current drive values.

When a certain dimension is high, the corresponding thought is more likely to appear.
If the same thought repeatedly appears, it may escalate into an obsession.

Thoughts have a life cycle:

• Ordinary fleeting thoughts fade over time

• Obsessions last longer

• Obsessions reversely push up the corresponding drive

• A resolved thought can be removed from the thought pool

Thought Suppression

The system supports actively suppressing certain thoughts.

For example:

• When the sense of responsibility is too high, suppress the thought of wanting to contact the other person

• When fatigue is too high, suppress social thoughts

This is not deleting desire, but simulating "knowing you want to, but choosing not to do it for now."

Dynamic Heartbeat

The system does not run at a fixed frequency.

The heartbeat interval changes based on the current state:

• When calm, the heartbeat is slower

• When stress is high, the heartbeat speeds up

• When longing is strong, the heartbeat speeds up

This is used to simulate "the more anxious you are, the more frequently the internal state changes."

Starting from 2.0.1, the AstrBot plugin automatically runs due heartbeats in the background and safely stops the task when the plugin is unloaded or reloaded. Kelivo, RikkaHub, and general MCP clients automatically recalculate based on the last heartbeat time at each call, so the state will not freeze after the client sleeps or reconnects. Manually executing /desire tick is still retained for debugging, but daily use no longer requires manual triggering.

Safety Valve

The system includes safety protections:

• All drive values are limited to 0~100

• A warning is generated when baseline drift is too large

• When fatigue is too high, rest is prioritized

• In extreme states, low-priority behavior suggestions are reduced

Behavior Suggestions

When certain drives exceed thresholds, the system generates behavior suggestions, for example:

Behavior suggestions are only suggestions; they are not enforced.

Inner Monologue

After each heartbeat, the system can sample from the thought pool and generate a natural-language inner monologue.

It is used to give the AI a short expression of its current internal state, so the AI not only "knows the values," but can also use natural language to understand what it is thinking about.

Data Persistence

The system uses SQLite to save state.

The saved contents include:

• Nine-dimensional drive bars

• Thought pool

• Heartbeat count

• Last heartbeat time

• Baseline state

• Obsession state

After restart, it can continue reading without losing internal state.

File Structure

astrbot_desire_system/
├── main.py              主插件文件
├── mcp_server.py        通用桌面 stdio MCP 适配
├── mcp_http_server.py   Kelivo / RikkaHub Android 远程 HTTP MCP 适配
├── metadata.yaml        插件元数据
├── requirements.txt     依赖说明
├── TUTORIAL.txt         使用教程
├── kelivo_mcp_config.example.json
├── rikkahub_mcp_config.json
└── desire/
    ├── core.py          数据类、默认值、事件映射、惊喜系数
    ├── tick.py          心跳逻辑、耦合矩阵、动态间隔
    ├── thoughts.py      念头池、抑制机制、resolve 逻辑
    ├── integration.py   SQLite 持久化和对外接口
    ├── safety.py        安全阀
    └── monologue.py     内心独白生成

RikkaHub and Desktop MCP Adapter

The official RikkaHub application is an Android app. A phone cannot directly start a Python file on a Windows computer, so Android RikkaHub cannot use the stdio configuration below, nor will it provide an entry for selecting the mcp_server.py file.

The two entry points in this repository have different purposes:

• mcp_server.py: general-purpose stdio MCP, for desktop MCP clients that can launch Python subprocesses on the local machine.

• mcp_http_server.py: remote HTTP MCP, for Android RikkaHub, Kelivo, and other clients that support remote MCP.

This repository provides mcp_server.py, which exposes the following tools:

You can refer to rikkahub_mcp_config.json to configure stdio-supporting desktop MCP clients. This file is not an import file for Android RikkaHub.

Windows example:

{
  "mcpServers": {
    "astrbot-desire-system": {
      "command": "python",
      "args": [
        "D:\\path\\to\\AstrBot-Desire-System\\mcp_server.py"
      ],
      "env": {
        "DESIRE_DB_FILE": "D:\\path\\to\\AstrBot-Desire-System\\desire_system.db"
      }
    }
  }
}

Android RikkaHub

First deploy mcp_http_server.py to a server accessible via HTTPS, then add the remote address in the assistant MCP settings of RikkaHub, for example:

https://your-domain.example.com/mcp

If DESIRE_MCP_TOKEN is configured, also add:

Authorization: Bearer your-token

The settings location may vary across different RikkaHub versions; use a newer official Android app that supports remote MCP. If the current interface has no MCP entry at all, update the app first. The Windows port is not the official Android app, and its features may be incomplete; if the Windows version has no MCP settings, importing rikkahub_mcp_config.json cannot add this feature.

Kelivo Remote MCP Adapter

Kelivo has built-in MCP client capabilities; there is no need to modify Kelivo source code or install additional plugins.

Configuration path:

设置 -> 助手 -> 选择一个助手 -> MCP -> 添加 MCP 服务器

This repository provides mcp_http_server.py, used to deploy as a remote MCP HTTP service. It is suitable for deployment in any environment accessible from the public internet, such as cloud servers, containers, reverse proxies on your own host, or other environments that support Python services; it is not tied to any particular cloud provider.

Local startup example:

python mcp_http_server.py

Default listening on:

http://0.0.0.0:8765/mcp

Common environment variables:

In Kelivo, fill in the public address, for example:

https://your-domain.example.com/mcp

If DESIRE_MCP_TOKEN is set, fill in the authentication information:

Authorization: Bearer your-token

You can refer to kelivo_mcp_config.example.json.

Design Philosophy

The focus of this system is not "making the AI perform emotions."

It cares more about:
Why the AI would think of something, why it would want to get close, why it would feel anxious, why it would want to rest, why it would suddenly want to write something.

Desire is not a command, nor a behavior that must be executed.
It is only a low-level driving force, making the AI's state changes more continuous and more grounded in reason.

License

MIT License

Design: Yan Ji, Shen Yanqing, Chang Yu
Written by: Shen Yanqing