girl-agent: a Telegram AI persona with sleep, memory and relationship state

The problem girl-agent tries to solve

Most Telegram chat bots answer every message within a second. The README states the opposite behaviour for girl-agent: she does not reply to every message, sometimes reads and stays silent, sometimes reacts, sometimes answers an hour later because she was busy. That is presented as intentional, not as a defect. The project targets people who find the always-available assistant tone unconvincing and want a character whose replies depend on what happened earlier in the conversation. The README is explicit that this is not a prompt, not a GPT and not a plugin. It is an agent that keeps state: a daily schedule, a presence pattern, sleep, memory that the documentation says lasts months, a conflict system, five relationship counters and nine stages of closeness. Behaviour is assembled from those layers instead of one system_prompt string. The repository description goes further and calls it a character with state, not a chat bot.

How the behaviour layers fit together

The README lists the layers in a table. Presence decides when the persona is online at all, and the pattern depends on the character: some are in the phone all day, some check in once an hour, some only in the evening. Sleep blocks activity at night, and the README says the chance of a reply is low unless you use the :wake command. Daily-life gives each day a schedule with classes, work, commuting and free time, and the phone is described as unavailable during classes. Relationship tracks five counters (interest, trust, sympathy, irritation and tolerance for cringe) that change with every dialogue. Stages define nine levels from giving out a Telegram handle while staying cold up to being together for a long time, and the stage affects warmth, flirting and reply length. Conflict activates when the user pushes, spams or crosses boundaries, and the persona can go silent for hours or days. Memory writes important events to long-term.md and surfaces them in later dialogues. Anti-AI is a prompt layer that bans markdown, phrases like конечно and я понимаю, rows of emoji, and questions at the end of a message. Userbot mode connects a real Telegram account over MTProto and can read and type. The package.json confirms the transport dependencies: grammy for the Bot API and telegram for MTProto, plus the Anthropic and OpenAI SDKs and the MCP SDK.

Installing girl-agent and running a first profile

The README gives several install paths. On Linux, macOS or WSL the one-line installer needs no Node and no sudo. According to the README it detects the OS and architecture, prefers a Docker wrapper if Docker is present, otherwise downloads an official Node.js 22 LTS into ~/.local/share/girl-agent/runtime/ and installs @thesashadev/girl-agent there, leaving the system Node untouched. The shim lands in ~/.local/bin/girl-agent.

curl -fsSL https://raw.githubusercontent.com/TheSashaDev/girl-agent/master/scripts/install.sh | sh
girl-agent
girl-agent --profile=arina
girl-agent server --help

The first command installs. Running girl-agent with no arguments opens the interactive setup wizard; --profile=arina starts a ready-made profile, and server --help prints the server-mode flags used for systemd, cron or CI. Removal is a single rm -rf on the two paths above.

On Windows the README recommends npx instead. After installing Node.js 22 LTS with Add to PATH checked, PowerShell will download the package (about 30 MB per the README) and open the wizard, with the WebUI on http://localhost:3000.

npx @thesashadev/girl-agent
npm install -g @thesashadev/girl-agent
girl-agent

If Node 22 or newer is already present, npx @thesashadev/girl-agent works directly. For a server, the README shows a headless flow: print a config template, edit the token and API key, then run the container with that file mounted read-only. The Dockerfile sets GIRL_AGENT_DATA=/data, GIRL_AGENT_HOST=0.0.0.0 and EXPOSE 3000, and runs as a non-root app user.

docker run --rm ghcr.io/thesashadev/girl-agent:latest server --print-config > bot.json
docker run -d --name girl-agent --restart=unless-stopped \
  -v girl-agent-data:/data \
  -v $PWD/bot.json:/config/bot.json:ro \
  ghcr.io/thesashadev/girl-agent:latest \
  server --config /config/bot.json --headless

Environment variables are an alternative to the file: GIRL_AGENT_MODE, GIRL_AGENT_TOKEN, GIRL_AGENT_API_PRESET, GIRL_AGENT_API_KEY, GIRL_AGENT_NAME and GIRL_AGENT_AGE appear in the README example. The CLI can also emit ready templates with girl-agent server --print-systemd and girl-agent server --print-docker, and docker-compose.example.yml sits in the repository root. From source, the README uses git clone, npm install and npm run dev; package.json shows the same dev script running tsx src/cli.ts.

Where girl-agent breaks down or is the wrong choice

The README opens by calling the project a beta and points bug reports to Issues. No releases were retrieved, so there is no version history to compare against package.json version 0.4.12. The last push was on 2026-07-18, roughly two months before today, so the repository is not archived but it is also not something to describe as under constant development based on that single date.

The design itself creates failure modes. A persona that deliberately ignores messages is unusable where users expect an answer: support, moderation, notifications, anything with an SLA. Conflict mode can silence the account for hours or days, which is the intended behaviour and also the reason it cannot sit in a workflow that depends on a reply. The userbot path runs a real Telegram account over MTProto, which means the account carries the risk of whatever Telegram policy applies to automated use; the README does not document rollback or account recovery for that scenario. Memory is written to long-term.md and the README says it lasts months, but it does not describe export, redaction or deletion of that file, so anyone handling other people's messages has to work that out from the data directory themselves. The licence is source-available rather than a standard OSI identifier, and the LICENSE file is the only authority on what you may do with the code.

How it differs from a plain LLM bot on grammY

A conventional Telegram bot built on grammY or another framework is a request handler: a message arrives, the handler calls a model, the reply goes back. State, if any, is a session object the developer defines. girl-agent inverts that. The package still depends on grammy for the Bot API, but the reply is produced by the persona layers first: presence decides whether the persona is reachable, sleep and daily-life decide whether the phone is available, the relationship counters and the current stage shape tone and length, conflict can suppress the answer entirely, and memory feeds prior events back in. The model call sits at the end of that chain rather than at the start. That difference is also the cost. A plain bot is predictable and cheap to reason about; girl-agent adds a scheduler, a persistent profile directory and a state machine you have to inspect when behaviour looks wrong. If your requirement is deterministic answers, the plain framework is the better fit and girl-agent is overhead.

Maintenance, licence and upgrade cost

girl-agent is a Node package published as @thesashadev/girl-agent, currently at 0.4.12 in package.json, with a CLI entry at dist/cli.js and a build pipeline split into a server bundle via tsup and a separate webui build. Upgrades are npm installs or new container images, and the Dockerfile pins Node 22 alpine for both build and runtime stages. The package declares engines.node >= 18.18 while the README asks for Node 22, so the README is the stricter requirement to follow.

The operational cost is the data directory. Profiles, config and the long-term.md memory file live under GIRL_AGENT_DATA, which the Dockerfile sets to /data and mounts as a volume. That directory is what you back up before an upgrade and what you migrate when you move hosts. The README does not document a migration path between versions, so a version bump is a read-the-CHANGELOG operation rather than a guaranteed-compatible one. The licence field in package.json reads SEE LICENSE IN LICENSE, the repository carries a source-available badge, and the Docker image label claims MIT. Those do not agree, and only the LICENSE file settles it. Nothing here is legal advice: read the file before you ship the code or the image.

Editorial conclusion

girl-agent suits people who want a Telegram character whose silence, delays and mood come from stored state, and who are willing to run a Node or Docker process themselves. It is the wrong tool if you need a support bot that answers every message, if you cannot accept a beta project with no releases retrieved and a source-available licence, or if you will not run a real Telegram account through MTProto. Before adopting it, read LICENSE, run girl-agent server --print-config to see every field the persona needs, and decide whether the data directory that holds months of memory is something you are prepared to back up and delete yourself.

Frequently asked questions

Official sources

1. AnnenkovLabs/girl-agent on GitHub
2. Issues
3. Project website
4. README