hersona

# hersona [**English**](./README.md) · [日本語](./README.ja.md) > **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. [](https://pypi.org/project/hersona/) [](https://pepy.tech/project/hersona) [](./LICENSE) [](./LICENSE-CC0.txt) [](#use-as-an-mcp-server-optional) [](https://shiro-0x.github.io/hersona/) [Docs](https://shiro-0x.github.io/hersona/) · [PyPI](https://pypi.org/project/hersona/) · [Repository](https://github.com/shiro-0x/hersona)  ## Quick start (30 seconds) ```bash 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](https://shiro-0x.github.io/hersona/app/)** 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: | `tsundere` + `keigo` | mild | moderate | strong | |---|---:|---:|---:| | Injection cost (measured) | 1751 chars (~437 tok) | 1931 chars (~482 tok) | 2039 chars (~509 tok) | - **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. 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`](./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: | Target | Writes | Used by | |---|---|---| | `--target claude` | `CLAUDE.md` | Claude Code | | `--target codex` (alias `agents`) | `AGENTS.md` | Codex / AGENTS.md-compatible agents | | `--target cursor` | `.cursorrules` | Cursor | | `--target gemini` | `GEMINI.md` | Gemini CLI | `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**. | You need | Reach for | |---|---| | One fixed persona, never switched | A hand-written system prompt — hersona adds no value here | | Several personas, swapped per session/user, with intensity control | **hersona** (`blend` / `soul` / `persistent`) | | To *know* whether a persona held up over a long conversation | **hersona** (`measure` / `verify_intensity` — deterministic, not vibes) | | Conflict-free trait combinations at scale (many attributes × many combos) | **hersona** (`compatible_archetypes` / `conflicts_with` matrix) | | Better reasoning, retrieval, or tool-calling | LangGraph, OpenAI Agents SDK, LlamaIndex, Semantic Kernel — hersona's `export` formats hand a persona *into* these, it doesn't replace them | | A one-off character for a single project | Your own YAML/prompt is fine too — hersona helps once you have more than one persona, or need to reuse the same ones across projects | See [`docs/BENCHMARKS.md`](./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 ```bash 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`](./docs/PUBLIC_API.en.md). ## Guides Cross-persona playbooks (not attribute templates): - [Self-introduction](./docs/guides/self-introduction.md) — public intro rules, privacy, checklist - [日本語](./docs/guides/self-introduction.ja.md) · [Index](./docs/guides/README.md) ```bash 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: ```bash 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: | Scope | License | Notes | |---|---|---| | `scripts/`, `schema/`, `pyproject.toml`, etc. (code) | **MIT** | `LICENSE` | | `attributes/**/*.yaml` (general attribute templates) | **CC0 1.0** | `LICENSE-CC0.txt` — public domain dedication | | `personas/**/*.yaml` (persona packs, recipes of named blends) | **CC0 1.0** | `LICENSE-CC0.txt` — public domain dedication | ## 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: | Phase | Count | What | Examples | |---|---:|---|---| | **Phase 0/8** (pre-existing) | 26 | Foundational Japanese speech + English registers + `archaic_otaku` | `kansai_ben`, `keigo`, `gyaru`, `british_en` | | **Phase 1: regional dialects** | 36 | All major Japanese regions including Kyushu/Okinawa | `hokkaido_ben`, `nagoya_ben`, `osaka_ben`, `okinawa_ben` | | **Phase 3: character voices** | 25 | Era, Z-gen, subculture, classic character roles | `warawa`, `vtuber`, `yankee`, `business`, `akuma_oujo` | | **Phase 4: foreign languages** | 24 | English dialects (10) + translation-style registers (14) | `aussie_en`, `valley_girl_en`, `mandarin`, `korean`, `french` | | **Phase 5: anime-genre voices** | 18 | School-romcom, isekai, fantasy, subculture-isekai | `osananajimi`, `imouto`, `mesugaki`, `densetsu_no_yuusha`, `villainess` | | **v1.5.0: native zh/ko** | 6 | `content_lang` zh/ko speech (not ja-flavored translation) | `mandarin_casual`, `keigo_zh`, `taiwan_mandarin`, `banmal`, `jondaetmal`, `seoul_casual` | 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](./skills/hersona/SKILL.md) for Hermes skill behavior notes, and [skills/hersona/REFERENCE.md](./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`](./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. ```bash 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. ```bash 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): | Pack | Blend | Use case | |---|---|---| | `keigo_support` | diligent + keigo | customer_support | | `kansai_marketer` | genki + kansai_ben | marketing | | `tsundere_reviewer` | tsundere + blunt | qa_reviewer | | `kuudere_analyst` | kuudere + soft | data_analyst | | `genki_planner` | genki + casual_en | planner | | `sensei_writer` | intellectual + sensei | tech_writer | | `butler_assistant` | diligent + butler | executive_assistant | | `onee_recruiter` | sociable + onee_kotoba | hr_recruiter | | `samurai_devops` | stoic + samurai_lol | devops_engineer | | `vtuber_streamer` | playful + vtuber | streamer_copilot | | `miko_tutor` | serious + miko | tutor | | `british_pm` | pragmatist + british_en | product_manager | | `gyaru_community` | sociable + gyaru | community_manager | | `warawa_gamemaster` | mysterious + warawa | game_master | **What sets persona packs apart from generic agent catalogs:** | Generic agent catalogs | hersona persona packs | |---|---| | Role only, no personality control | Persona × use-case × **intensity dial** | | Static templates | Conflict-checked blends, **measurable maintenance** (incl. lock resistance under persona-override attacks) via `hersona bench` | | Generic tool plumbing | **Native for Hermes' multi-personality registry** | 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 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](./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: ```bash 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: | Tool | What it does | |---|---| | `list_attributes` / `show_attribute` | Browse the catalog | | `blend` / `export` | Compose and hand off a persona (`export` supports all 5 formats) | | `recommend_blend` | Diagnostic-quiz recommendation (`export_format` skips the second call) | | `compatibility` | Conflict / compatible lookup | | `measure_intensity` | Score one response against a blend's intensity band — deterministic, no LLM | | `bench_transcript` | Score a whole conversation transcript for persona-maintenance rate + lock resistance | | `list_personas` | Browse the 14 bundled persona packs | | `install_persona` | Preview a pack's rendered injection block (dry-run — writes nothing) | `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`](./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](./schema/attribute.schema.json). It currently defines 346 in total: personality 43 / speech 140 / archetype 66 / visual 46 / hobby 51 (see under [attributes/](./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 | category | count | attributes included | |---|---|---| | personality (ja-base) | 35 | airhead / battle_junkie / chuunibyou / crybaby / dandere / deadpan / deredere / diligent / genki / gluttonous / himedere / hinedere / hot_blooded / intellectual / kamidere / klutz / kuudere / laid_back / menhera / mysterious / narcissist / optimist / pessimist / playful / pragmatist / protective / puppyish / sadodere / scheming / serious / socially_anxious / stoic / switch / tsundere / yandere | | personality (ja-base, Phase 8) | 2 | hautaine / sociable | | personality (en-native) | 5 | sassy / rebel / charmer / drama_queen / go_getter | | speech (ja) | 25 | archaic / blunt / boku_girl / burikko / gyaru / hakata_ben / hiroshima_ben / kansai_ben / keigo / kyoto_ben / mischievous / mixed_dialect / onee_kotoba / ore_boy / princess_speech / robotic / seductive / soft / stutter / theatrical / third_person / tohoku_ben / tomboy / washi / whispery | | speech (ja, Phase 8) | 1 | archaic_otaku | | speech (ja, Phase 1: regional dialects) | 36 | akita_ben / ehime_ben / gifu_ben / gunma_ben / hokkaido_ben / hyogo_ben / ibaraki_ben / kagoshima_ben / kanagawa_ben / kanazawa_ben / kochi_ben / kumamoto_ben / mie_ben / miyazaki_ben / nagoya_ben / nagasaki_ben / nara_ben / niigata_ben / oita_ben / okayama_ben / okinawa_ben / osaka_ben / saga_ben / saitama_ben / sanuki_ben / sendai_ben / shimane_ben / shizuoka_ben / tochigi_ben / tokushima_ben / tokyo_ben / toyama_ben / tsugaru_ben / wakayama_ben / yamagata_ben / yamaguchi_ben | | speech (ja, Phase 3: character & subculture voices) | 25 | akuma_oujo / business / butler / chuunibyou_speech / kawaii / mahou_shoujo / mama / miko / musuko / obaachan / ojisan / ol / ryoushi / sage / samon / sensei / shouwa_retro / streamer / taishou_retro / vtuber / wagahai / warawa / yankee / yuuusha / z_jidai_slang | | speech (ja-translation, Phase 4: Asian & European languages) | 14 | mandarin / taiwanese / cantonese / korean / french / german / italian / spanish / russian / arabic / hindi / vietnamese / thai / tagalog | | speech (ja, Phase 5: anime-genre voices) | 18 | boin_girl / bokukko / dark_hero / densetsu_no_yuusha / hero_yamero / imouto / isekai_cheat / kuudere_girl / kuukichou / mesugaki / onee_san / osananajimi / oujo / samurai_lol / sensei_goroshi / tsukkomi / villainess / wizard | | speech (en) | 15 | formal_en / casual_en / blunt_en / southern_us_en / british_en / aussie_en / scottish_en / irish_en / valley_girl_en / brooklyn_en / new_york_en / midwestern_en / pidgin_en / jamaican_en / punjabi_en | | speech (zh/ko native, v1.5.0) | 6 | mandarin_casual / keigo_zh / taiwan_mandarin / banmal / jondaetmal / seoul_casual | | archetype | 66 | alien / angel / antihero / apprentice / artist / assassin / bartender / best_friend / big_brother / big_sister / bodyguard / chef / childhood_friend / chosen_one / commander / cyborg / delinquent / demon / doctor / dragon / engineer / entrepreneur / fairy / fallen_hero / gakkyuu_iinchou / gamer_otaku / ghost / goddess / heroine / hikikomori / honor_student / idol / journalist / kitsune / knight / kouhai / little_brother / little_sister / lone_wolf / maid / mediator / mentor / mercenary / mother_figure / noble / nurse / office_worker / ojou_sama / oni / prince / rival / robot_android / school_nurse / scientist / seitokaicho / senpai / shrine_maiden / sidekick / soldier / teacher / tenkousei / twin / underdog / vampire / villain / witch | | visual | 46 | ahoge / androgynous / animal_ears / black_hair / blonde / blue_hair / blunt_bangs / blush / bob_cut / braids / chubby / drill_hair / droopy_eyes / eyebags / eyepatch / freckles / glamorous / glasses / golden_eyes / gradient_hair / hair_bun / heterochromia / hime_cut / inner_color / jitome / kimono / long_hair / messy_hair / mole / muscular / pale_skin / petite / pink_hair / ponytail / red_eyes / red_hair / scar / sharp_eyes / short_hair / side_ponytail / silver_hair / slender / tall / tan / twintails / white_hair | | hobby | 51 | art / astronomy / baking / board_games / cafe_hopping / calligraphy / camping / coffee / collecting / cooking / cosplay / crafting / cycling / dance / fashion / fishing / flower_arrangement / fortune_telling / gamer / gardening / hiking / history_buff / karaoke / knitting / languages / makeup / martial_arts / meditation / model_building / movies / music / occult / pet_care / photography / pottery / programming / puzzles / reading / running / sado / shopping / singing / skateboarding / sports / surfing / swimming / trains / travel / wine / writing / yoga | #### Required fields (attribute.schema.json) | field | type | required | description | |---|---|---|---| | `attribute_category` | enum | ✓ | one of `personality` / `speech` / `archetype` / `visual` / `hobby` | | `attribute_name` | string (snake_case) | ✓ | unique ID matching the file name | | `weight_dimension` | enum | ✓ | `none` / `mild` / `moderate` / `strong` | | `examples` | string[] (1+) | ✓ | AI-agent usage examples. No proper nouns or specific works | Metadata must use **one** of the schema's two accepted shapes: | shape | required fields | notes | |---|---|---| | Current i18n metadata | `display_name`, `description` | BASE language is English; localized labels/descriptions go under `i18n.<lang>` (for example `i18n.ja.display_name`) | | Legacy suffix-pair metadata | `display_name_ja`, `display_name_en`, `description_ja`, `description_en` | Still accepted for backward compatibility, but new attributes should prefer the current i18n shape | #### Optional fields | field | type | description | |---|---|---| | `core_traits` | string[] (3-7) | personality trait list; the core the AI agent interprets at injection time | | `speech_style` | string | overall description of the speech style (1 line); injected into the blend | | `first_person` | string | first-person pronoun(s), mainly for speech attributes; injected into the blend and used for intensity measurement | | `second_person` | string | second person (e.g. "貴方", "お前"); may include the user's role name | | `sentence_endings` | string[] (1+) | sentence-ending patterns (ja speech, e.g. "〜の", "〜のね") | | `lexical_markers` | string[] | characteristic words/phrases (en speech, e.g. "gonna", "y'all"); injected into the blend and used for en intensity | | `register` | enum | speech register: `formal` / `neutral` / `casual` / `vulgar` (mainly en speech) | | `catchphrases` | string[] or `{phrase, when}` objects | catchphrases; each entry may be a plain string or an object with an optional trigger condition | | `tone` | string | atmosphere of the voice (1 line) | | `image_prompt_tags` | string[] | English image-generation tags, mainly for visual attributes | #### Relationship and localization fields | field | type | description | |---|---|---| | `compatible_archetypes` | string[] | list of archetype attribute_names expected to pair well | | `conflicts_with` | string[] | list of other attribute_names expected to be mutually exclusive | | `tags` | string[] | tags for cross-cutting search | | `typical_value_range` | string | typical value when used with weighting (e.g. `0.4-0.7`) | | `content_lang` | enum (`ja`/`en`/`zh`/`ko`) | language of the persona-content fields; drives response-language directives and intensity. Absent ⇒ `ja` | | `content_i18n` | object | per-language native persona content (`<lang>.{catchphrases,tone,core_traits,examples}`); keeps injected catchphrases in the persona's language | | `i18n` | object | localized metadata (`display_name` / `description`) keyed by language code | | `has_catchphrase` | bool | whether catchphrases exist | | `variant` | string (snake_case) | variant label of the same attribute_name | | `notes` | string | supplementary / operational notes | #### 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: ```bash # 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 ```bash 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](./DISCLAIMER.md) - Security / threat model: see [SECURITY.md](./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](./CONTRIBUTING.md) for details. Using hersona in a project? Add yourself to [USED_BY.md](./USED_BY.md). The implementation guide for agents / developers ("what to build next") is at [docs/IMPLEMENTATION_GUIDE.md](./docs/IMPLEMENTATION_GUIDE.md).