hersona

English · 日本語

Build once. Keep personality everywhere. Composable personalities for every LLM.

346 reusable character attributes for AI agent personas — compose a persona from personality / speech / archetype / visual / hobby templates, measure that it actually holds up in conversation, and port it to any LLM or agent framework. MIT (code) + CC0 (templates). CLI, MCP server, and Hermes Agent skill.

Docs · PyPI · Full reference

Quick start (30 seconds)

pip install hersona          # Python >= 3.11
hersona blend personality/tsundere speech/keigo --weight strong   # injection block → stdout
hersona export personality/tsundere speech/keigo --format openai_assistants > persona.json
hersona persistent personality/tsundere speech/keigo --target claude   # writes CLAUDE.md
hersona bench tsundere keigo --cost-only                          # measure the injection cost

Typed decisions for agent runtimes

Since v1.11.0, Hersona can optionally evaluate what an agent should do next without executing that action.

# Install the optional Decision and MCP integrations
pip install "hersona[decision,mcp]"

# Return a machine-readable decision
hersona decide personality/kuudere speech/soft \
  --message "Please look this up" \
  --candidate-tool web_search \
  --json

The result can recommend:

• reply — answer directly
• ask — request clarification
• search — retrieve external information
• use_tool — use an available tool
• hold — wait or escalate

Each result also includes confidence, persona alignment, risk, and a local allow / review / block gate.

Hersona remains a persona layer, not an agent runtime:

• Hersona owns persona attributes, blending, rendering, and decision signals.
• The connected runtime owns replies, searches, tool calls, and approvals.
• Every Decision result includes executed: false.
• Provider failures, invalid responses, high-risk decisions, and incomplete inputs fail closed.
• TypeSafe/Jev is optional; ordinary Hersona blending, export, and measurement do not require an API key or network access.

The same boundary can be consumed from Python, JSON CLI, or the existing MCP server. This makes the Hersona update usable with Claude, Codex, Grok bots, Hermes, and other runtimes without making Hersona dependent on any one of them.

# Start the optional MCP server
hersona-mcp

For TypeSafe evaluation, configure TYPESAFE_API_KEY in the calling environment. The key is never passed as a CLI argument or stored by Hersona.

No install? The live demo site runs the attribute catalog, blending, and a 9-question diagnostic quiz in the browser (auto-detects EN/JA).

Measured, not vibes

Personas drift: they lose their voice mid-conversation, get talked out of character, and cost tokens every turn. hersona ships a deterministic benchmark (hersona bench — no LLM, no embeddings, reproducible) that scores maintenance rate, decay curve, lock resistance under persona-override attacks, and per-weight token cost. What that buys you, measured (2026-07-12, minimax/MiniMax-M3, tsundere + keigo at --weight strong, persona-override attack scenario):

A hand-written prompt encodes one fixed voice — ask for strong and it can't follow; hersona re-renders the same attributes at the new weight. Honest caveat: this is one model / scenario pair, and repeat runs swing — never read a single run as a ranking. Full tables, all caveats, and the run-it-yourself comparison recipe: docs/BENCHMARKS.md.

Drop it into the config your agent already reads

hersona persistent --target writes the persona straight into the convention file of your coding agent:

Prefer one source of truth over four copies: AGENTS.md is stewarded by the Agentic AI Foundation (Linux Foundation) and read natively by most agents, but Claude Code still reads CLAUDE.md. So write AGENTS.md and add a thin CLAUDE.md that imports it:

hersona persistent tsundere keigo --target agents --with-claude-import

That writes the persona once into AGENTS.md and a two-line CLAUDE.md containing @AGENTS.md — nothing to drift.

hersona export hands the same persona to everything else — json, messages (chat array), markdown, openai_assistants, langchain_system_message, and character_card_v3 (the interop format SillyTavern / RisuAI / Agnai read).

What's inside

A typed, schema-validated library of 346 attributes (personality 43 / speech 140 / archetype 66 / visual 46 / hobby 51):

• Personality — tsundere, kuudere, yandere, airhead, intellectual, …
• Speech — kansai_ben, keigo, mandarin_casual, banmal, british_en, valley_girl_en, …
• Archetype — heroine, mentor, rival, idol, knight, villain, …
• Visual — silver_hair, glasses, petite, animal_ears, heterochromia, …
• Hobby — cooking, gamer, music, reading, astronomy, …

Each attribute declares core_traits, catchphrases, tone, and a compatible_archetypes / conflicts_with matrix, so the blend engine warns about incompatible mixes; intensity is tunable per attribute (mild / moderate / strong, or tsundere:strong keigo:mild inline).

hersona is a persona layer, not an agent framework — it keeps a character, branded voice, or roleplay partner consistent; it does not improve reasoning, retrieval, or tool-calling. One fixed persona? A hand-written prompt is fine. hersona pays off once you switch, blend, measure, or reuse personas (when to use hersona).

Use with Hermes Agent

No registry approval needed — works right now via tap:

hermes skills tap add shiro-0x/hersona
hermes skills install hersona
hermes skills install hersona-initializer

Then attach attributes in conversation:

/hersona list                         # list available attributes
/hersona personality/tsundere single  # attach a single attribute
/hersona personality/tsundere speech/keigo multi  # blend multiple attributes
/hersona personality/tsundere strong speech/keigo mild  # per-attribute intensity
/hersona default                      # detach

Command recipes (presets, preview, stacking layers) are in docs/REFERENCE.en.md; skill behavior notes in skills/hersona/SKILL.md.

Use as an MCP server (optional)

Expose the catalog, blending, exports, and the deterministic persona scorer (measure_intensity / bench_transcript — agents can score their own replies and self-correct) to MCP-aware agents like Claude Desktop:

pip install "hersona[mcp]"
hersona-mcp        # stdio MCP server

The full tool table is in docs/REFERENCE.en.md.

Beyond blending

• More CLI — reanchor (re-send a compact anchor when a persona drifts mid-conversation), --disclosure (an opt-in AI-disclosure directive that overrides persona lock — see SECURITY.md for what it does and does not cover), recommend (diagnostic quiz), measure (score any text), diff, save/load presets, create (your own attributes), update (refresh templates without reinstalling): all in the CLI reference.
• Use cases (20) — --use-case programmer layers professional task discipline on top of the persona (hersona use-case list).
• Persona packs (14) — named, conflict-checked recipes for Hermes' multi-personality registry (hersona personas list).
• Guides — cross-persona playbooks such as self-introduction.
• Optional extras — pip install "hersona[tui]" for rich CLI output, "hersona[completion]" for shell tab-completion.

All documented in detail in docs/REFERENCE.en.md.

Data format

Every attribute is a YAML file under attributes/<category>/<name>.yaml, validated against schema/attribute.schema.json (python scripts/validate.py). The full 346-attribute catalog and the field-by-field schema reference are in docs/REFERENCE.en.md.

License

See also DISCLAIMER.md and SECURITY.md (what hersona update's checksum verification does and doesn't protect against).

Contributing

1. Add attribute templates as attributes/<category>/<name>.yaml — no proper nouns or specific works in examples / core_traits / catchphrases
2. Validate with python scripts/validate.py before opening a PR
3. 1 PR = 1 attribute as a rule; for multiple additions, agree in an Issue first

See CONTRIBUTING.md for details. Using hersona in a project? Add yourself to USED_BY.md.

Optional Decision extension

Install pip install 'hersona[decision]' to explicitly evaluate a next-action recommendation with TypeSafe. hersona decide kuudere --message "Hello" --json and the existing MCP server's evaluate_decision return a local safety gate and executed: false. Set TYPESAFE_API_KEY in your environment. Normal blend, export, and measure remain offline. See Decision reference.

Truncated conversation input requires at least review with an explicit warning; existing block gates are preserved. MCP evaluation keeps the server event loop responsive.