personagent 1.0.1

A character for your group chats that knows when to stay quiet, and learns from being corrected.

English · 简体中文

personagent is a character for your group chats: pick one or write your own, and run it on any OpenAI-compatible model. It lives where your group already is: QQ, Telegram, Discord and a dozen more through AstrBot, anything Koishi reaches through Satori, and Matrix with its bridges to WhatsApp and Signal.

For one-on-one chats with less setup, try Charune, which runs on personagent.

The dashboard's chat view: where it stayed quiet and why, where it was called, and a corrected reply struck through above the better wording it learned, on record, with Roll back.

Try it in one minute

uvx personagent demo    # watch it stay quiet and learn; no key, nothing to configure
uvx personagent init    # pick a model service, paste its key, pick a character
uvx personagent chat    # talk to it in a simulated group chat

uvx comes with uv, which fetches Python for you. Install uv with curl -LsSf https://astral.sh/uv/install.sh | sh (macOS, Linux) or powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows).

To install it with pipx or pip, or run it from a clone, see the user guide.

Why personagent

	It knows when to stay quiet. It answers when called. Otherwise a model judges whether a person would chime in: no dice roll. A burst of messages gets one reply, not one each.
	It learns from corrections that hold up. A change needs two agreeing reactions from the same chat, one of them strong. A troll or a bystander cannot retrain it. Every change is on record, and any of them can be rolled back.
	It is easy to start, and lives where your group is. A setup in English or Chinese with 11 model services, and a demo that needs no key. AstrBot, Koishi or Matrix carry it into your chats, and a local dashboard shows what it did.

• Each chat has its own memory.
• Editing the character keeps what it learned.
• It is measured: personagent eval scores when it speaks, whether it stays in character, and whether corrections stick (results).

Put it in your group

The shortest path, through AstrBot:

1. Install personagent for good with uv tool install personagent (or pipx install personagent), and run personagent init if you have not yet.
2. Install AstrBot (its launcher, Docker, or uv tool install astrbot), start it once, and add your chat platform in its WebUI.
3. Run personagent connect astrbot. It finds AstrBot's folder, asks which chat app and which groups the bot may join (send /sid in a group to see its id), installs the plugin, and writes one shared CONNECTOR_TOKEN to both sides.
4. Run personagent run and keep it running, then restart AstrBot or reload its plugins.
5. Say the bot's name in one of those groups.

The plugin also has its own repository, astrbot_plugin_personagent, so you can install it from AstrBot's WebUI by that address. QQ, Docker, Koishi, Matrix and the rest are in the user guide, the deployment guide and the Chinese step-by-step guide, which covers QQ from zero.

How it compares

From each project's documentation, October 2026. "Not documented" means we found no description of it, not that it cannot be done; AstrBot's plugin market has learning plugins, one with a review queue and rollback.

Another project may fit better if you want a one-click desktop app with every setting in a WebUI (MaiBot, AstrBot), a large plugin ecosystem, or slang learning, sticker packs and image memory as headline features (MaiBot, AstrBot's plugins). personagent does not replace AstrBot or Koishi: it runs behind them, so you keep their platforms and plugins and add a character that holds back and learns on the record.

Measured

personagent eval runs the real agent on labelled cases in English and Chinese and writes a report with every case and its verdict:

The reports, with every case, reply and verdict, are in docs/evals/2026-10-03. What "picked over a plain assistant" looks like, from the same run (same model, same message):

One run on one model is a sample, so expect some noise between runs; the persona and learning suites are scored by a judge that is a different model from the one being measured. The user guide explains each suite, the misses and how to run it yourself.

Documentation

• User guide (中文): install, setup, the terminal chat, connectors, teaching it, the dashboard, troubleshooting.
• Deployment guide: running it for real: connectors, QQ, exposing the endpoints, costs, and what to check when the bot goes quiet.
• 中文部署教程: QQ from zero, step by step.
• Connector protocol: one signed HTTP request per message, for writing your own connector.
• Tools: the scripts in tools/, for running from a clone.
• Changelog, including upgrading from 0.4.
• Contributing · Security policy · Disclaimer

Privacy

Everything personagent stores stays on your machine, in its home folder. The model provider you choose does see the conversations it answers. Before you connect it to real people, tell them it is a bot and get their consent; the guide lists exactly what goes where.

Status

personagent is at 1.0, and QQ through AstrBot is its most exercised route. Other AstrBot platforms use the same plugin, the Satori and Matrix connectors are tested against stand-ins, and CI runs the tests on Linux with Python 3.10–3.14 and on Windows with Python 3.12, plus a job that installs the package and runs the command.

License

MIT © 2026 Qiankang (Kant) Wang.

Acknowledgements

• AstrBot, satori-python with Koishi, and matrix-nio with the mautrix bridges carry personagent onto chat platforms, and NapCat onto QQ.
• FastAPI and httpx run the service and its model calls, and uv and pipx install it in one line.
• Learning from reactions draws on Self-Feeding Chatbot, Alexa self-learning and BlenderBot 3x; the lorebook and output filters follow SillyTavern's World Info and regex extensions.