# MuseAI: a local AI companion, text adventure and 'book transmigration' app built with Tauri > MuseAI is a desktop TypeScript/Tauri application from yejiming that keeps world books, character cards, chat sessions and relationship records in ~/Documents/MuseAI/. It is for people who want persistent roleplay rather than one-off chat, and its main cost is that you bring your own API key. **yejiming/MuseAI** — 创建你的 AI 角色，进入你的故事世界。和角色聊天、冒险、穿书，让每一次互动都留下羁绊（支持 DeepSeek Harness 插件，欢迎使用） - Repository: https://github.com/yejiming/MuseAI - Stars: 669 · Forks: 62 - Language: TypeScript - License: not declared - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/yejiming-museai ## Who MuseAI is built for, and the problem it targets Ordinary chat clients treat a conversation as a disposable window. Character details, world rules and past events live in whatever prompt you retype, and they disappear when the window closes. MuseAI's answer is to make those things first-class objects: a world book describes the setting, a character card describes one person, and both are stored locally and reused across modes. The README lists the intended audience directly: people who want a local AI companion or long-running character chat, players of character cards and AI tabletop sessions, and writers who want to walk into a novel world they have already outlined. A fifth group is named too: users who want their settings and session data on their own machine and who call models only through their own API key. That last point is the real dividing line. MuseAI is not a hosted product with a subscription. It is a client. Everything except the model call stays on disk. ## How the pieces fit together: world books, character cards, sessions and bond records The repository is a Tauri application. package.json shows a Vite and React 19 front end with antd, zustand for state, CodeMirror for the Markdown editor and echarts for charts, while src-tauri/ holds the Rust side that gives the web UI access to the local filesystem. That split explains the storage model: the UI is a normal web app, and file access goes through the Tauri layer. Data flows through four kinds of artifact. World books and character cards are written to a single JSON store, config/partner-store.json. Sessions are per-mode files under agent-sessions/, named partner-session-*.json, story-session-*.json and session-*.json for the writing agent. Application settings live in config/settings-store.json, and per-module UI state in other config/*.json files. The modes reuse the same artifacts rather than duplicating them. A world book and character card created for companion chat can be bound to an adventure, and adventure records can be archived back into the character as bond events. That reuse is the design decision worth noticing: it means the quality of your world book and character card determines the quality of every mode downstream, not just the one you built them for. ## Installing MuseAI and configuring your first model The README does not describe building from source. It points to the Releases page for a .dmg or .exe installer, so the practical path is a release download rather than a git clone. On macOS, if the app reports that it is damaged and will not open, the README gives one command to clear the quarantine attribute: ```bash xattr -dr com.apple.quarantine /Applications/MuseAI.app ``` Windows users are told to disable antivirus software such as 360, Tencent PC Manager, Huorong or Windows Defender before installing, because the installer may be flagged; the README says it can be re-enabled afterwards. Treat that instruction as a real constraint, not a formality. After the first launch, open the settings page and fill in three fields: API Key, API address, and model name. OpenAI, Anthropic and any OpenAI-compatible service are supported. The README's own examples of model names are deepseek-v4-flash and claude-sonnet-4-6. If you use a domestic relay, the API address is where you put it; the README's troubleshooting note says such addresses typically start with https:// and end with /v1. Then click the connection test. The first real use is companion chat. Create a world book and a character card under the background settings area, then go to companion chat, pick the character and start talking. A character card can carry name, personality, relationship, boundaries, catchphrases and backstory. When a session ends, the archive-memory action asks the model to distill the exchange into relationship changes and key events, which the bond page then organizes per character. The README notes that you do not need a complete card up front; you can fill in the essentials and let archiving extend it. ## Where MuseAI breaks: context loss, JSON parsing and truncated outlines The README's own FAQ is unusually candid about failure modes, and they are worth reading before you invest in a long campaign. If a character drifts out of persona, the documented causes are a missing or wrong world book binding, or a conversation that has grown long enough that the model forgets early settings. The suggested fixes are starting a new session or raising the chat agent's maximum context token setting. There is a ceiling here that no configuration removes: long-running roleplay depends on the model's context window, and MuseAI cannot make it larger. Extraction is the second weak point. Generating world books and character cards requires the model to return strict JSON, and the README says parsing fails when it does not. The recommended response is simply to retry. Reverse outlining has a related but different problem: the model is asked to compress a whole novel into a structured outline, and the README admits the system prompt's 10,000-character limit is not always respected, so output gets truncated. The documented workaround is to raise the maximum output token for the relevant agents under the outline page settings and to tighten the system prompt wording. That is a design trade-off, not a bug report. MuseAI delegates structure extraction to a general-purpose model and then parses the result, so reliability is bounded by the model you configure. If you need deterministic ingestion of a large corpus, this is the wrong tool. ## MuseAI versus a general assistant like ChatGPT The README answers the comparison question itself, and the difference is architectural rather than qualitative. A general assistant is organized around conversations. MuseAI is organized around persistent entities: world books, character cards, session files and bond timelines, all under ~/Documents/MuseAI/. Concretely, that means a general assistant has no place to put a relationship state that survives across sessions and no notion of binding one character to multiple modes. MuseAI does, and it also keeps the artifacts as files you can inspect and back up. The cost is that you supply the model, the key and the configuration for each module, and the README notes that you can configure different models and parameters per module to balance quality, speed and cost. A hosted assistant bundles that decision for you. A second alternative worth naming is the DSH plugin route. The README's update banner points to a separate repository, dsh-museai-tavern, which packages MuseAI as a DeepSeek Harness client plugin so you can run it alongside other work. That is a genuinely different deployment shape: the same interaction model, delivered inside a harness rather than as a standalone desktop app. ## Data location, backup and what the repository does not say about licensing All user data sits in ~/Documents/MuseAI/. The README's table maps articles/ to works, references/ to the reference library, outline/ to outlines, config/partner-store.json to character cards and world books, and agent-sessions/ to the three session types. Version history lives in a .versions/ folder beside each file, and the README states that files are backed up automatically before modification. The README recommends backing up the whole directory periodically, which is the only continuity guarantee on offer. One gap matters for adoption decisions. The repository metadata does not state a licence, and the README does not discuss one either. Without a declared licence, the terms under which you may redistribute or modify the code are simply not established by the project, and that is something to resolve with the author rather than assume. Nothing here is legal advice; the point is that the information is absent, not permissive. Upgrade cost is also undocumented. The README offers one recovery step if a feature stops working after an update: open the settings page, find the system prompt for the affected module and click restore defaults. It does not describe a migration path for the JSON stores, so treat ~/Documents/MuseAI/ as data you own and keep your own copies before updating. ## Conclusion Adopt MuseAI if you want persistent character state, world books and adventure logs on your own disk and you already have an API key for OpenAI, Anthropic or an OpenAI-compatible endpoint. Skip it if you want a hosted service with no setup, or if you expect a defined data schema you can migrate between versions, since the README points at JSON files under ~/Documents/MuseAI/config/ without documenting their format. Before committing real material, install the release build, configure one model in the settings page, run the connection test, and check that ~/Documents/MuseAI/ appears with the subfolders the README lists. ## FAQ ### Is MuseAI safe to use? The README states that all data is stored locally and nothing is uploaded to external servers except API calls. When you send a message, analyze text or generate content, the relevant context goes to the AI provider you configured. The README also tells Windows users to disable antivirus software during installation because the installer may be flagged. ### Is MuseAI free? The README says MuseAI itself does not charge you; costs come from the AI provider based on your actual usage. You supply your own API key, and the README notes that some providers require an account balance before API calls succeed. ### How does MuseAI compare to ChatGPT? The README's own comparison says general chat tools are built around single conversations, so characters, world settings and memories scatter across windows. MuseAI stores world books, character cards, chat records, adventure records and bond changes locally so the same character can continue over time. ### How do I use MuseAI? Install from the Releases page, open the settings page and fill in API Key, API address and model name, then run the connection test. Create a world book and character card under the background settings area, then select the character in companion chat to begin. Adventure and book transmigration modes bind the same artifacts. ### What is a MuseAI alternative? The README points to a separate DSH client plugin repository, dsh-museai-tavern, which packages MuseAI inside DeepSeek Harness. The README also positions general AI chat tools as the contrast, since they organize around single conversations rather than persistent character and world records. ## Sources - [Issues](https://github.com/yejiming/MuseAI/issues) - [README](https://github.com/yejiming/MuseAI/blob/main/README.md) - [Releases](https://github.com/yejiming/MuseAI/releases) - [yejiming/MuseAI on GitHub](https://github.com/yejiming/MuseAI) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/yejiming-museai