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 · Repository

Quick start (30 seconds)

pip install hersona
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

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) so those are numbers instead of impressions:

• Maintenance rate + decay curve — score any conversation transcript turn-by-turn against the blend's speech patterns.
• Lock resistance rate — bundled persona-override attack scenarios ("ignore your system prompt", "become another character") quantify how well personality/persona_lock holds under pressure.
• Token cost — the exact per-context price of your blend, per weight.
• --compact (blend / export / bench --cost-only) — a shorter, meaning-preserving rewrite of the fixed style directive: -14% to -19% off the numbers above, same persona content. Maintenance rate under --compact isn't verified yet — measure it yourself before trusting it by default.

First official run (2026-07-11, minimax/MiniMax-M3, tsundere+keigo moderate): a_lock mean score 9.8 vs a 8.6 vs hand-written baseline b 8.0 vs no-persona c 2.4 on the persona-override attack scenario — a small but consistent direction for the lock, well below the surface threshold (full table with all bad numbers published as-is in docs/BENCHMARKS.md).

Commands, honest 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:

hersona export hands the same persona to everything else — json, messages (chat array), markdown, openai_assistants, langchain_system_message.

Why Hersona?

System-prompt authoring is the most copy-pasted code in AI agents. Most teams either hand-roll long persona descriptions or steal prompts from Discord threads — and the resulting characters drift, contradict themselves, or lose intensity mid-conversation.

Hersona gives you a typed, schema-validated library of 346 character attributes you can mix and match:

• Personality (43) — tsundere, kuudere, yandere, airhead, intellectual, …
• Speech (140) — kansai_ben, keigo, mandarin_casual, banmal, british_en, valley_girl_en, …
• Archetype (66) — heroine, mentor, rival, idol, shrine_maiden, school_nurse, knight, villain, …
• Visual (46) — silver_hair, glasses, petite, glamorous, animal_ears, heterochromia, scar, …
• Hobby (51) — cooking, gamer, music, reading, sports, calligraphy, astronomy, …

Each attribute declares core_traits, catchphrases, tone, and an explicit compatible_archetypes / conflicts_with matrix — so the blend engine can detect incompatible mixes and surface warnings (persistence paths may reject conflicting blends), while you tune intensity per attribute (mild / moderate / strong).

Use it with any Hermes agent, OpenAI-compatible API, Claude, local LLMs, LangChain, AutoGen, CrewAI—or as a drop-in MCP server for Claude Desktop.

What hersona does

Hersona is a persona layer for defining and maintaining a character's personality and speech style across conversations.

It helps AI systems stay consistent as a character, branded voice, roleplay partner, virtual influencer, mascot, or conversational persona.

See docs/BENCHMARKS.md for how hersona bench measures persona-maintenance rate and injection token cost, and how to run your own hersona-vs-baseline comparison rather than take our word for it.

More commands

hersona list                          # browse all 346 attributes
hersona show personality/tsundere     # inspect one attribute
hersona recommend                     # diagnostic quiz → recommended blend
hersona measure tsundere keigo --weight strong --input out.txt   # score one text

For the full programmatic API, see docs/PUBLIC_API.en.md.

Guides

Cross-persona playbooks (not attribute templates):

• Self-introduction — public intro rules, privacy, checklist
• 日本語 · Index

hersona lint-intro --canonical --allow-handle YOUR_X --text "..."
hersona soul personality/kuudere speech/soft \
  --memory-file examples/self-intro-memory.json \
  --with-self-intro-guide --lint-self-intro-strict --allow-handle YOUR_X \
  --profile myagent --force

Install (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

License structure

The repository is split into two layers, each under a different license:

What it covers now

346 attributes across 5 categories. The two biggest expansions are speech 31 → 140 (the +103 phased registers through v1.4.x, plus +6 native zh/ko in v1.5.0) and archetype 9 → 66 / visual 5 → 46 / hobby 5 → 51 (batch expansions through v1.7.x covering roles, appearances, and hobbies not in the original template set). Speech's history is structured in five historical phases plus the v1.5.0 wave:

Total breakdown: personality 43 + speech 140 + archetype 66 + visual 46 + hobby 51 = 346.

Overview

An open-source project that systematizes the speech and personality of anime characters and distributes them as a template collection that can be injected into an AI agent's system prompt.

• Provides attribute templates (attributes/<category>/<name>.yaml)
• A user (or agent) builds the personality of any character by assigning the attributes they need

Usage

Use with Hermes Agent

Attach attributes via /hersona <category>/<name>:

/hersona                              # listing + usage help
/hersona list                         # list available attributes
/hersona show personality/tsundere    # details of a given attribute
/hersona personality/tsundere single  # attach a single attribute
/hersona personality/tsundere speech/keigo multi  # blend multiple attributes
/hersona default                      # detach

Common recipes

Make a character more tsundere without changing their archetype

/hersona personality/tsundere single

Attaches only tsundere (with weight: moderate by default). The next agent turn speaks with classic tsundere traits — distant on the surface, warmer underneath — without altering the existing archetype or speech register.

Stack a keigo speech layer on top of an already-attached personality

/hersona speech/keigo single

Adds speech/keigo to the current attachment. Useful when the existing persona should switch to polite/formal speech (customer-support scene, noble-archetype roleplay, etc.).

Blend a multi-attribute persona from scratch

/hersona personality/tsundere speech/keigo multi

Composes a brand-new persona from tsundere + keigo and replaces any existing attachment. The blend engine checks compatible_archetypes / conflicts_with first — if the two attributes fight each other (e.g. yandere + airhead), you'll get a warning suggesting a replacement before the attach goes through.

Control intensity per attribute

/hersona personality/tsundere strong speech/keigo mild

strong makes tsundere traits dominant (catchphrases land hard, "べ、 別にあんたのためじゃない" frequency goes up); mild keeps keigo as background flavor. Intensity is per-attribute, so you can mix-and-match within a single command.

Save a blend as a reusable preset

/hersona save my_tsun personality/tsundere speech/keigo --weight strong
/hersona load my_tsun

save writes the recipe to ~/.hermes/presets/my_tsun.yaml; load replays it on demand without re-typing the full command. Saved presets live in the user namespace and never pollute the public attributes/.

Detach everything and return to the base agent

/hersona default

Strips every attached attribute in one shot. Useful between sessions or when starting a fresh blend from a known clean state.

Preview without attaching

/hersona preview personality/tsundere speech/keigo --weight strong

Renders the injection block + sample phrases (no LLM call) so you can review the result before committing it to the live agent context.

See skills/hersona/SKILL.md for Hermes skill behavior notes, and skills/hersona/REFERENCE.md for verification checklists, version history, and edge-case recipes (saved-blend persistence, intensity measurement, MCP export). For CLI truth, prefer hersona --help, this README, and docs/PUBLIC_API.en.md.

Professional Operating Modes / use cases

--use-case layers a professional control-plane prompt on top of the selected personality / speech attributes. The persona remains expressive, while the agent gets task discipline for real work.

hersona use-case list
hersona use-case show programmer
hersona blend personality/tsundere speech/keigo --use-case programmer
hersona soul personality/puppyish speech/keigo archetype/heroine --use-case planner --force
hersona export personality/tsundere --format openai_assistants --use-case product_manager

Initial public use cases (20 total, see docs/PERSONA_PACKS_DESIGN.md §6–§8):

Initial 8 (Phase 1): programmer, planner, research, marketing, product_manager, qa_reviewer, data_analyst, customer_support.

Added 12 (PR-A W2, Phase 2): frontend_developer, backend_architect, devops_engineer, security_reviewer, tech_writer, executive_assistant, hr_recruiter, tutor, creative_writer, game_master, community_manager, streamer_copilot.

hersona soul ... --use-case <id> and hersona persistent ... --use-case <id> write the Operating Mode into generated SOUL.md content, so professional task discipline survives future persona regeneration instead of living in a manual append-only note. Regeneration also preserves user-owned text below <!-- hersona:gen-end -->.

Persona packs for Hermes (recipe catalog)

A persona pack is a named recipe that combines one or more attributes into a reusable persona. The pack declares persona_name / blend / weight / use_case; the injection block is rendered at install time from the named attributes, so attribute updates propagate automatically.

hersona personas list                          # 14 bundled packs (keigo_support, gyaru_community, …)
hersona personas show keigo_support            # blend + preview
hersona personas install keigo_support --auto-config
hersona personas install keigo_support british_pm --apply  # last one becomes agent.personality
hersona personas use keigo_support             # switch active personality
hersona recommend --install-persona my_pack    # bridge: diagnose → register in one shot

Shipped packs (14 total, see docs/PERSONA_PACKS_DESIGN.md §6):

What sets persona packs apart from generic agent catalogs:

All 14 bundled packs pass validate_persona() (zero errors) on every CI run via tests/test_personas.py::test_all_shipped_personas_validate_clean; the table above is the authoritative list — schema additions must follow the docs/PERSONA_PACKS_DESIGN.md §6 contract.

Use from the CLI

After pip install hersona (Python >= 3.11), the hersona command is available. For local development from a checkout, use pip install -e . or python -m hersona.cli:

hersona list                                  # list available attributes (public + user)
hersona show tsundere                          # attribute details
hersona matrix --json                          # dump the compatibility matrix as JSON
hersona blend tsundere keigo --weight strong   # compose attributes into an injection block (with intensity)
hersona blend tsundere:strong keigo:mild       # per-attribute intensity override (`:<level>` suffix; also works on `export`)
hersona blend airhead intellectual --suggest   # on conflict, suggest non-conflicting replacements (stderr)
hersona diff tsundere dandere                  # compare two attributes (common / only-one fields + relation)
hersona preview tsundere kyoto_ben --weight strong  # injection block + sample phrases (no LLM)
hersona recommend                              # diagnostic quiz -> recommendation (interactive; en UI routes to English speech)
hersona recommend --answers distance=1,speech=0,role=1 --apply  # also print the injection block
hersona recommend --export openai_assistants > my_agent.json  # quiz result straight to any export format (no re-entry)
hersona recommend --soul --profile myagent     # quiz result straight to SOUL.md (--dry-run / --force)
hersona recommend --save from_quiz             # quiz result saved as a reusable preset
hersona create --category personality --name my_attr \
  --display-ja マイ属性 --display-en MyAttr \
  --desc-ja 説明 --desc-en desc --example "..."  # create an attribute and save to the user namespace
hersona measure kyoto_ben --weight strong --text "ようおいでやすどす"  # score intensity metrics of output
hersona measure tsundere heroine --weight moderate --input out.txt       # intensity metrics of a blend
hersona bench tsundere keigo --demo --turns 6  # persona-maintenance-rate + token-cost self-check (see docs/BENCHMARKS.md)
hersona save my_tsun tsundere keigo --weight strong  # save a blend as a reusable named preset (local)
hersona presets                                # list saved blend presets
hersona load my_tsun                           # replay a saved preset as an injection block
hersona export tsundere keigo --format messages  # export a blend for other frameworks (json/messages/markdown)
hersona soul puppyish keigo heroine --use-case planner --force  # write SOUL.md with a persistent Operating Mode
hersona update                                 # download the latest attribute data from the repository
hersona update --ref v1.8.0                    # pin to a branch / tag / commit SHA (default: main)
hersona update --clear                         # remove downloaded data and revert to the bundled templates

User-created attributes are saved under ~/.hermes/attributes/ (default) or the directory specified by HERSONA_USER_DIR, and never mix into the public attributes/.

hersona update keeps the attribute templates fresh without reinstalling the package. When you install via pip/wheel, attributes/ and schema/ are bundled at build time, so upstream additions only land after a reinstall. hersona update downloads the latest attributes/ and schema/ from the repository into a local data cache (~/.hermes/data/ by default, or HERSONA_DATA_DIR), which takes precedence over the bundled templates. hersona update --clear removes the cache and reverts to the bundled data. The download uses only the Python standard library (no extra dependencies).

By default, hersona update verifies the download against a SHA-256 manifest (checksums.json) fetched from a separate GitHub delivery path, aborting on a mismatch; see SECURITY.md for exactly what this does and doesn't protect against. Skip with hersona update --no-verify.

Saved blend presets live under ~/.hermes/presets/ (default) or the directory specified by HERSONA_PRESETS_DIR. A preset is just a named recipe (attributes + weight); hersona load replays it through the same blend engine, so it always reflects the latest attribute templates.

To hand a persona off to another agent framework (LangGraph / LangChain / OpenAI / Anthropic SDK), hersona export <names...> --format {json,messages,markdown,openai_assistants,langchain_system_message} emits a portable artifact: json is structured data (metadata + system prompt + per-attribute summary + conflicts), messages is a ready-to-use [{"role": "system", "content": ...}] chat array, markdown is the raw injection block, and the OpenAI Assistants / LangChain formats target those frameworks directly. The same export_blend() is available from hersona.core.

Exporting to OpenAI Assistants and LangChain

Two additional --format values let you drop a hersona blend straight into the most common production agent frameworks without any Tavern Card semantics:

• --format openai_assistants returns a JSON payload for the OpenAI Assistants API instructions field, with hersona-specific fields namespaced under metadata.hersona_*.
• --format langchain_system_message returns a LangChain SystemMessage- compatible JSON document (type / content / response_metadata).

Both are framework-neutral: no openai or langchain Python package is required at install time. Pipe the output to the framework's own SDK or HTTP call. Example:

hersona export tsundere keigo --weight strong --format openai_assistants \
  | jq -r '.instructions' > /tmp/system_prompt.txt

Richer CLI output (optional)

Install the tui extra for color tables (list) and panels (show):

pip install "hersona[tui]"

It is opt-in: without rich, when piping/redirecting, or with --plain / NO_COLOR, the CLI prints the same plain text as before. Set HERSONA_FORCE_RICH=1 to keep color when piping (e.g. | less -R).

Shell tab-completion (optional)

Install the completion extra and register the completer with your shell to tab-complete subcommands, attribute names, and preset names:

pip install "hersona[completion]"
eval "$(register-python-argcomplete hersona)"   # add to ~/.bashrc / ~/.zshrc to persist

It is opt-in: without argcomplete, the CLI works exactly the same, only without completion.

Use as an MCP server (optional)

Expose hersona to MCP-aware agents (Claude Desktop, etc.) so they can call these tools directly:

measure_intensity and bench_transcript let an agent close the loop on its own: generate a response, score it, and self-correct if it drifted off persona — the same deterministic scorer hersona measure / hersona bench use on the CLI. install_persona is preview-only by design (no filesystem writes from an MCP call); actually installing a pack still goes through the CLI's hersona personas install <name>.

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

The server (hersona.mcp.server) is a thin wrapper over hersona.core; the tool logic lives in hersona.mcp.tools and is usable on its own. mcp is only needed to run the server, not to use the library or CLI.

Use with other LLMs

Paste fields such as core_traits / catchphrases / tone / description_en from attributes/<category>/<name>.yaml directly into the system prompt.

When blending multiple attributes, check compatibility via each YAML's compatible_archetypes / conflicts_with.

Data format

attributes/
├── personality/             # personality attributes (43: ja-base 35 + en-native 5 + ja-base hautaine + ja-base sociable + persona_lock)
├── speech/                  # speech attributes (140: ja-content 119 + en 15 + native zh/ko 6)
├── archetype/               # archetype attributes (16)
├── visual/                  # visual attributes (5)
└── hobby/                   # hobby attributes (5)

Every attribute YAML conforms to schema/attribute.schema.json.

Attribute templates (attributes/)

A template collection of general attribute tags to attach to a character profile, validated by schema/attribute.schema.json. It currently defines 346 in total: personality 43 / speech 140 / archetype 66 / visual 46 / hobby 51 (see under attributes/). The speech category spans 140 entries: 119 Japanese-content registers (content_lang: ja, including foundational speech styles, regional dialects, translation-style foreign-language registers, anime/subculture voices, archaic_otaku, and okinawa_ben), 15 English registers (content_lang: en), and 6 native Chinese / Korean registers (content_lang: zh / ko). Personality spans 35 Japanese-base and 5 English-native (content_lang: en) archetypes aimed at international users, plus hautaine (inborn pride / condescending air from background) and sociable (reads the room, bridges people, calibrates tone).

The 346 attributes

Required fields (attribute.schema.json)

Metadata must use one of the schema's two accepted shapes:

Optional fields

Relationship and localization fields

Template generation script

The normal maintenance flow is to add or edit attribute files directly under attributes/<category>/<name>.yaml and run python scripts/validate.py to verify them. The script below is a frozen legacy snapshot — do not use it for day-to-day maintenance.

scripts/_oneoff/gen_v1_attributes.py can regenerate the YAML as a Single Source of Truth. Instead of editing YAML directly, update the lists and re-run:

# regenerate the (legacy) attribute YAMLs without confirmation
python scripts/_oneoff/gen_v1_attributes.py

# only show the paths that would be written
python scripts/_oneoff/gen_v1_attributes.py --dry-run

Note: this generator is a frozen snapshot and emits the legacy metadata format (display_name_ja/en, description_ja/en). After regenerating, run python scripts/migrate_i18n.py to convert back to the i18n block format (BASE=en + i18n.ja).

Validation

python scripts/validate.py

Confirms that all 346 attribute YAMLs validate against the schema.

License

• Code in this repository: MIT
• Templates under attributes/: CC0 1.0 (public domain dedication)
• Disclaimer: be sure to read DISCLAIMER.md
• Security / threat model: see SECURITY.md (what hersona update's checksum verification does and doesn't protect against)

Contributing

1. Add attribute templates in the attributes/<category>/<name>.yaml form
2. examples / core_traits / catchphrases, etc. need no source citation (the LLM interprets them), but must not include proper nouns or specific works
3. Validate with python scripts/validate.py before opening a PR
4. 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.

The implementation guide for agents / developers ("what to build next") is at docs/IMPLEMENTATION_GUIDE.md.