Find your next open-source project

Search by name, purpose, or keyword — or paste a GitHub repository URL

pinganbbOvO/ai-companion-kit

AI Engineering

A toolkit for building a QQ chatbot with persistent memory and an MCP server that controls an Android phone.

572
43
JavaScript
MIT
41 days old

What it is

AI Companion Kit is a monorepo of packages for giving an LLM a persistent identity and a way to act on the real world. It targets two gaps the author identifies in chat assistants: they forget the person they talk to, and they cannot operate a device.

The kit is split into independent parts:

  • companion — a QQ bot layer built on OneBot v11. It stores memory per person rather than per conversation, simulates human typing (delays, message splitting, slower replies at night), decides when to speak or stay silent (mentions, name, pokes, keywords, probability), loads a character card, and keeps a separate diary of recent entries.
  • phone-mcp — an MCP server exposing Android device control through adb: tap, swipe, text input, screenshots, screen recording, and chained actions. The README lists 34 MCP tools.
  • qzone / qzone-mcp — tools that let the bot post to QQ Zone, read feeds, like, and comment, with rate limits on write actions.
  • own-life — an optional scheduler that injects silent wake-up prompts every 2.5 hours so the bot can choose to post or write a diary unprompted.

Getting started

Requirements are Node.js 18+ and, for QQ chatting, an OneBot-compatible gateway. The README names SnowLuma for the gateway and notes it is not installed by the scripts.

For a Windows setup without the command line, download the repository and run tools/安装.bat. It checks for Node, fetches a portable Node build if needed, installs dependencies, generates config.json, and opens Notepad for the QQ numbers and gateway token. The script does not install the gateway itself.

Manual path for the companion package:

cd packages/companion
cp config.example.json config.json   # fill in API key and your QQ number
cp role.example.md role.md           # write your character
npm run check                        # validate the character card
node examples/demo.js                # offline demo, no key needed
npm run dry                          # generate without sending
npm start                            # real run; needs an OneBot gateway

npm start is the step most users get stuck on because it requires the external gateway; the full tutorial covers it in chapter 3.

For phone control only:

cd packages/phone-mcp
npm install
node src/phone-mcp.js --selftest     # detects adb and devices

Then register it in an MCP client, for example:

{ "mcpServers": { "phone": { "command": "npx", "args": ["-y", "phone-mcp"] } } }

QQ Zone publishing has a three-step setup from the repo root: npm install, npm run qzone:test for a token/connectivity check, then npm run qzone to probe the gateway and append the posting guidance to the character card (add --dry to preview without writing).

Using it safely

The README gives explicit operational warnings:

  • phone-mcp grants full control of a real phone to the model. Do not connect it to a primary phone carrying banking or payment apps; use an emulator or a spare device.
  • companion stores conversations locally under data/; only the model request payload leaves the machine.
  • QQ automation is subject to Tencent rate limiting and possible account suspension. The README describes sending at 20 messages/minute for a day and being throttled. The built-in limits for QZone posts and comments are meant to be kept, and comments cannot be undone.
  • Images posted to QZone must come from a whitelisted directory (QZONE_IMAGE_DIRS); absolute paths outside it are rejected. There is no delete or block function.

Data is stored as plain text: JSON memory and JSONL conversation streams, plus one Markdown file per diary day. The license is MIT.

HotRepo's take

The repository has no recorded GitHub daily ranking, no snapshot history, and no Hacker News discussion in the HotRepo data, so there is no trend or rank claim to make. What the material does show is a deliberately layered design: each package works alone, the companion layer depends only on an OpenAI-format API, and the phone layer depends only on adb. The practical cost is the external OneBot gateway, which the README itself flags as the main barrier to a first run.

Written by AI from the project's README, updated . The project's own docs are the source of truth.

You might also like

  1. Mieksido/surfcoreGives a DSH agent a persistent persona, fading memory, QQ/Bilibili presence and a desktop pet companion.JavaScript766
  2. DandanLLab/SnowCatQQThird-party QQ client that injects an OneBot/MCP adapter into the official QQ process so developers can connect their own agents.TypeScript320
  3. MemPalace/mempalaceA local-first verbatim memory store that gives AI coding agents searchable, scoped recall of past sessions and projects.Python60,124
  4. chenkezhen480/dsh-worldGives a DSH desktop companion persistent memory, a home session and its own daily routine, all configured through the DSH settings console.TypeScript107
  5. tavern-labs-ai/character-ai-sdkA TypeScript SDK for building persistent AI characters with personas, durable memory, and pluggable model, storage, and interface adapters.TypeScript156