persona-engine
English | 日本語 | 简体中文 | ไทย
English is the canonical version of this document. Translations follow it and may lag slightly behind.
<div align="center"
</div <!-- repo-state:begin (generated; do not edit) -- <p align="center"<subgeneration: <code4728929</code (2026-09-07T06:16:25Z) · verify: <a href="https://api.github.com/repos/caty-ai/persona-engine/commits/main"API HEAD</a · <a href="./status.json"status.json</a</sub</p <!-- repo-state:end --
persona-engine is a device that gives your agent's existing persona a layer of relationship and a gradient of emotion. Who your agent is — and the important axes of your relationship — are decided by the persona it already has, wherever your runtime keeps it (a system prompt, an AGENTS.md, a SOUL.md). persona-engine never touches that. What it layers on top are the faces of a relationship — a dependable secretary at work, a close friend in casual chat, a partner in the quiet hours — and the small movements of feeling between them: a voice that brightens with good news, words that grow shorter under focus. Only that range is added, and it is added safely.
What persona-engine adds — two things
A layer of relationship
Even with one agent, the relationship is a little different in every place. At work, the dependable secretary; in casual chat, the close friend; on stream, the character; anywhere public, a properly neutral face. persona-engine keeps an explicit rule for which relational face may appear where, and on every conversation turn it gently lays exactly one matching layer over the conversation.
- Switching feels human. Three ways to change faces: ① automatically by place (the engine picks the right face every turn based on where the conversation is happening), ② by the agent's own judgment (only where you have allowed it, it reads the flow of the conversation and switches itself), ③ by a word from you ("switch to friend mode").
- A neutral face, guaranteed, anywhere it shouldn't show personality. In a work meeting, a public channel, or any place you never configured, the agent automatically falls back to a neutral state. A private tone leaking into a public space is prevented by the machinery itself, not by convention.
- A full record of every switch. Who changed to which face, where, and when — "which mode was that conversation in yesterday?" always has an answer.
A gradient of emotion
Human feeling is not a work/private toggle; it is a gradient. A voice brightens at good news; words get shorter in deep concentration. In persona-engine, each point on that gradient is a mode — one small text file — and the texture of its voice lives in vocabulary catalogs: preferred phrases, verbal tics, example exchanges. Emotional variants can inherit from a base face and carry only their difference (extends). The gradient grows with your life together: copy a file, edit it, rebuild — that is all it takes.
The device's promise — the persona is never rewritten
A layer is something placed on top; it never repaints what is underneath.
[!IMPORTANT] persona-engine is not a tool for building a personality from scratch. It exists to respect the agent that is already there, and layer relationship and emotion on top.
- The agent's own persona definition — name, character, default way of speaking, wherever your runtime keeps it (system prompt, AGENTS.md, SOUL.md) — is never touched. It remains the foundation everything else is layered onto.
- A mode adds only a difference: how this face reacts when focused, the vocabulary of a casual moment, how much the voice brightens.
- The layer is applied per conversation turn and vanishes without trace when removed. The agent can always return to its plain self.
- Defining a full character (a stage persona for a VTuber, say) is also supported — and even then it is a costume, not surgery.
Why we built this
The starting point is not a technical problem but a wish: to be with an AI agent the way you are with family, with friends — the way you are with people.