Hiyori — Build Your Own Adventure

Hiyori (日和) is an AI-powered interactive storytelling app built with Tauri v2 and SvelteKit 5. Create intricate stories through an AI-guided world builder, then play through branching narratives with real-time game state tracking, robust memory, and customizable AI pipelines.

Table of Contents

1. Quick Start
2. Features
3. User Guide
4. UI & Accessibility
5. Developer Guide

---

Quick Start

Get Hiyori running in three simple steps:

1. Either:
   • Download: Grab the latest release for Windows (.exe NSIS installer) from the Releases page, or
   • Online: Go to GitHub Pages for the web app version. No data is stored in the server. Or,
   • One of the other options below.
2. Connect AI: Open the app, go to Settings → AI Providers, and add your preferred provider (OpenAI, OpenAI-compatible, Ollama, etc.).
3. Play: Click New Story → World Builder to generate your first universe!

Option	How to Run	Recommendation
Installer	Download and install Hiyori_<version>.exe	Recommended (Windows)
Built SPA	npm install && npm run build, then serve build/	Recommended (Web)
Online	Visit GitHub Pages or self-host	No install needed
Dev server	npm install && npm run dev	For web development
Local desktop	npm install && npm run tauri dev (requires Rust)	For app development
Android	See Building the Android APK below	For Android devices

Note: Running the locally-built executable directly without the installer is not recommended, as the local data cache is not automatically erased between versions and can cause stale data issues. Web App Note: localhost/127.0.0.1 is allowed on HTTP. All other hosts require HTTPS. An HTTPS web app can only call HTTPS providers or localhost providers. See the WISP Proxy section for CORS workarounds.

---

Features

Narrative Engine

• Multi-Phase Pipeline: A sequential orchestration of Writer → Reviewer → Editor → Template Fitter → Game Master ‖ Plot Planner, accompanied by an async Summarizer → Character Profile Compressor → Memory extraction chain.
• Write-Review-Edit Loop: An optional feedback cycle (with detailed or quick review modes) to guarantee writing quality and narrative consistency.
• Branching Narratives: Fork storylines at any point. Each branch is an independent act line sharing messages up to the fork point.
• Act Plots: AI-generated scene-by-scene plot outlines with guided interview creation that drives the storytelling.
• Act Phase System: Event-based plot mode structures stories through narrative phases (introduction → rising action → climax → falling action → resolution) with milestone gating and configurable advancement thresholds.
• Director Notes: Player-initiated directorial guidance to shift the narrative direction dynamically.
• Act Transitions: AI-assisted bridging between acts with strict continuity checks.
• Epilogue Generation: A dedicated pipeline for story-ending epilogues with multiple ending types (good, bad, bittersweet, alternative).
• Risk Evaluation: A dice-roll risk model for determining the outcome of risky actions.
• AI Tools: Pipeline agents have access to tools including scene reading, memory/inventory queries, character introduction, risk evaluation, phase advancement, and act ending.

World Building & Content

• World Builder: An AI-guided interview that generates a comprehensive world document. Supports updating existing world documents via the World Builder.
• Import World: Import chat transcripts (JSON, Markdown, text) as new stories with automatic act and character extraction.
• Character & Act Cards: Extract characters from acts; generate cards detailing personality, appearance, and story arcs. Manageable via the Context Management page.

AI & Memory

• Memory System: Vector-based memory with semantic search (sqlite-vec). The AI recalls past events, locations, and character interactions via the query-memories tool.
• Inventory Tracking: Per-character item, equipment, skill, clothing, and status tracking with change history, queryable by AI agents via the query-inventory tool.
• Character Profiles: Compressed per-character profiles with configurable importance thresholds, maintained by the Character Profile Compressor.
• Important Phrase Highlighting: Background LLM extraction of key narrative phrases, visually emphasized in the prose (gated by Minor Task Agent setting).
• Reviewer: An optional AI reviewer (detailed or quick mode) that validates continuity, character consistency, and narrative quality before the Editor runs.

Configuration & Data

• Wide API Support: Supports OpenAI, OpenAI-compatible, and Ollama endpoints via chat-completions or responses API formats.
• Multi-Provider Assignment: Assign different models to specific pipeline roles (e.g., a fast model for the Reviewer, a creative model for the Writer).
• Per-Provider CORS Bypass: Configure WISP proxy or libcurl-based CORS bypass on a per-provider basis for web app usage.
• Fully User-Customizable Prompts: Edit bundled default prompts or create story-specific overrides via the File Manager. Every AI-facing instruction can be tailored.
• Story Export/Load: Per-story .zip export with selective act line import (overwrite or load as a new story with remapped IDs). Full app data backup/restore is available via Settings.
• Context Management: Generate and manage act cards and character cards for controlling what context is fed to the AI pipeline.

---

User Guide

1. Setting Up Your AI Provider

Nothing works without an AI provider.

1. Go to Settings → AI Providers and click + Add Provider.
2. Choose a provider type: OpenAI Compatible, OpenAI, or Ollama.
3. Fill in the Base URL and Model (use the Fetch Models button to auto-populate if supported).
4. Select the correct API type: chat-completions for most providers, responses only for OpenAI's responses API.
5. Optionally configure a CORS bypass (WISP proxy or libcurl) for web app usage.

Ollama (Local) Users: Set OLLAMA_ORIGINS=* on your Ollama server to allow browser CORS requests.

2. WISP Proxy & Advanced Routing

Since some API providers do not support CORS, API requests from the web app directly to those providers will fail.

• Per-Provider CORS Bypass: Each provider can be individually configured with a WISP proxy URL or the built-in libcurl-based CORS bypass.
• WISP Protocol: This app supports the WISP-protocol proxy. You can easily proxy web app requests by setting up a local server using wisp-server-python.
• Advanced Usage (Cost & Token Management): For power users managing multiple APIs, consider routing your Hiyori requests through an intermediate gateway. Deploying a self-contained Docker Compose stack running LiteLLM on a local NAS is an excellent strategy to bypass CORS restrictions, unify your endpoints, and monitor your overall token usage without relying on a host-machine database.

3. Assigning Provider Roles

All pipeline roles default to your Main Provider. To optimize speed and cost, assign smaller/faster models to minor roles in Settings → Pipeline Roles. Each role is an independent agent that does not share much context with the others, and you can mix providers and models freely across roles.

• Enable the Reviewer to unlock the Editor role. Choose between detailed (thorough analysis) and quick (fast pass/fail) review modes.
• You must assign a Minor Task Agent to enable phrase extraction and template fitting.

Role Recommendations

The "minimum" requirement is a local Gemma 12B class model for everything.

Using open weight/open source frontier models (e.g. DeepSeek V4 Pro, GLM-5, Kimi K2.6) for everything is good, but may also be too slow for a semi-interactive game.

Role	Recommendation	KV-cache
Main Provider	Cloud "Flash"-class models (e.g. DeepSeek V4 Flash, Gemini 3.1 Flash Lite Preview), or local ~24-30B models (e.g. Qwen3.6 27B/35B A3B, Gemma 31b/26B A4B, GPT-OSS 20B)	—
Minor Task Agent	Small, fast non-reasoning models (e.g. Gemma E4B, 12B class). May work with even smaller models.	Not needed
Plot Planner	Strong frontier models with Event-based mode; "Flash"-class with Guidance-based mode. Both modes are token-heavy and slow, but they drive the entire story direction.	Needed for Guidance-based, not for Event-based
Writer	Same as Main Provider, may also opt for frontier models. What you read will mostly be written by this model.	Needed
Reviewer	Reasoning models — quick review with stronger models, or detailed review with local ~24-30B models	Needed
Editor	Fast non-reasoning models, but not too weak — quality still matters (e.g. Gemma E4B/12B class). Depending on the reviewer, the editor will be asked to rewrite stuff.	Needed
Game Master	Same as Main Provider. Primarily generates decisions that drive the plot — weaker models work if decision quality isn't critical	Needed
Summarizer	Same as Main Provider, or a stronger frontier model with reasoning disabled — better summarization means higher-quality context for other agents	Needed

KV-cache note: Roles marked "Needed" benefit significantly from prompt-caching. Using the same provider and model for these roles allows the cache to persist across turns. Conversely, the Minor Task Agent's context shifts every call, so prompt-caching offers no advantage — a different provider can be used without penalty.

4. Playing the Narrative

The core loop: send a message → AI generates narrative → you choose a decision (or enter your own) → repeat.

• Concluding Acts: When an act ends (via the end-act tool or player choice), choosing "Continue to Next Act" creates a new act line. Choosing "End the story here" writes a concluding Epilogue with a selectable ending type (good, bad, bittersweet, or alternative).

  

• Message Actions: Every AI message features buttons to Copy (Markdown), Read (TTS), Fork (branch narrative), Regenerate, or Edit (reveals structured fields like scene title, background, and narrative that aren't visible in standard reading mode).

5. Branching Narratives (Forking)

Forking lets you explore "what if" scenarios. Click Fork on any assistant message and choose:

• Keep current plot: Continue with the identical plot outline from the fork point.
• Tell us what's different: Describe the divergence in an interview, allowing the AI to generate an entirely new act plot for the branch.

6. Plot Planner & Act Plots

Enable the Plot Planner in Settings → Pipeline Roles to shape narrative direction before the Writer runs.

• Event-based mode (Recommended): Structures the story through narrative phases (introduction → rising action → climax → falling action → resolution). The Writer uses the advance-phase tool to progress through phases based on milestone gating (narrative completion score, player divergence score, goal completion). Runs at a configurable reevaluation frequency (default every 10 scenes).
• Guidance-based mode: Runs every turn with strong, Bethesda-style directional guidance.

7. Import Existing Content

You can import chat transcripts, world cards, and character profiles as new stories (supports Open WebUI JSON transcripts, Markdown, and text files).

• The multi-step wizard handles story details, acts, characters, and settings.
• Use the Preview step to review and remove individual messages before committing.
• Note: Importing long chat histories is a token-heavy process.

8. The Memory System (Desktop Only)

An advanced feature disabled by default (unavailable in the web app due to browser SQLite limitations).

• Requires both a Memory provider and an Embedding provider.
• Memory extraction runs automatically after narrative generation.
• Use the Memory Manager page to search past context by character, location, or both.

---

UI & Accessibility

• Dynamic Typography: Use Ctrl+Scroll to adjust text size (70%–150%), or use the Aa slider in the sidebar.

• Themes: Choose from 23 color themes, plus System/Light/Dark modes.

• Localization: Fully supported in English and Traditional Chinese (Hong Kong).

• Text-to-Speech (TTS): Enable Kokoro-based TTS in Settings to read stories aloud (requires a one-time ~300MB WASM model download; English locales only).

• Mobile Navigation:

• Swipe right from the left edge to open the sidebar drawer.

• Use the bottom tab bar to switch between Chat, Choices, and Menu.

• Swipe right-to-left on stories/acts to Delete.

  

• Swipe left-to-right on stories/acts to Rename.

  

---

Developer Guide

Prerequisites

• Node.js v24+
• Rust 1.77.2+

Linux system dependencies: Tauri requires WebKit2GTK and related libraries:

sudo apt install -y libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev

(If developing via WSL2, ensure Rust is installed directly within your WSL environment along with build-essential gcc make).

Building and Running

Start the Vite dev server (http://localhost:1420) and launch the Tauri hot-reload window:

npm install
npm run tauri dev

Build standalone platform binaries:

npm run tauri build

Build the standalone static Web App (SPA):

npm install
npm run build

The resulting build/ directory can be deployed to any static host (Netlify, Vercel, GitHub Pages) or served locally. App data is stored in the browser via OPFS (Origin Private File System). The web app is PWA-enabled and can be installed as a standalone application.

Feature Internals

The preprocessor (src/lib/utils/dialogue-preprocessor.ts) applies highlighting with strict precedence: dialogue > highlighted-phrase > character-name. Each layer masks its regions so subsequent passes cannot match inside them.

When Phrase Highlighting is enabled, the MinorTaskAgent extracts important phrases in the background (fire-and-forget) after the Editor phase. Older messages are sequentially backfilled when an act line is loaded.

The sqlite-vec extension is globally registered via main.rs and available to JS queries.

• Schema Constraints: Requires explicit dimension definitions (e.g., float[768]).
• IPC Limitations: tauri-plugin-sql IPC cannot bind binary BLOBs from JS. You must pass vectors as JSON strings.
• Primary Keys: Use last_insert_rowid() in SQL, as JS numbers bind as REAL and vec0 requires integers.
• KNN Queries: When JOINing with other tables, use a subquery pattern to ensure the LIMIT applies directly to the vec0 virtual table scan.

Add the Windows GNU target and install the MinGW-w64 cross-compiler:

rustup target add x86_64-pc-windows-gnu
sudo apt install -y gcc-mingw-w64-x86-64 nsis

Build the .exe:

npm run tauri build -- --target x86_64-pc-windows-gnu

Building the Android APK

Debug APK

npx tauri android build --debug

Output: src-tauri/gen/android/app/build/outputs/apk/universal/debug/app-universal-debug.apk

For a specific device architecture:

npx tauri android build --debug --target aarch64

Signed release APK

The release keystore and Gradle signing config are already set up. Ensure src-tauri/gen/android/key.properties points to your keystore, then:

npx tauri android build --target aarch64

APK output: src-tauri/gen/android/app/build/outputs/apk/aarch64/release/app-aarch64-release.apk

Install via File Manager or adb install -r <path-to-apk>.

License

AGPL-3.0-or-later. See LICENSE for details.