MuseAI: A Local Desktop App for AI Companion Chat, Text Adventure and Story Re-entry

The problem MuseAI targets: character state that survives a closed window

The README's own comparison is direct. Ordinary chat tools, it says, treat each conversation as a single exchange, and characters, world settings and memories scatter across separate windows. MuseAI's answer is to keep a world book, a character card, chat logs, adventure logs and relationship changes in one local directory so the same character can continue over time. The intended audience is listed explicitly: people who want a local AI companion or long-term character chat, players of character cards and AI tabletop sessions, creators who want to enter a novel world they have already organised, and anyone who wants settings and session data on their own machine with only their own API key leaving it. The last group matters most. Everything except the model call stays on disk, and the README states that data is not uploaded to any external server apart from API calls. That is a positioning choice, not a feature list, and it explains why the storage layout is documented in as much detail as the feature set.

How the pieces fit: world books, character cards and four separate session types

The data model rests on two artefacts. A world book describes the setting: era, geography, rules, factions and central conflict. A character card describes one person: name, personality, speech style, relationship to you, boundaries and key events. One world book can be shared by several character cards, and the README states that the same pair can be reused across companion chat, adventure, story re-entry and the relationship archive. Sessions are separate per mode. Companion chat binds exactly one character card. Adventure binds multiple character cards plus one world book, and the model acts as a narrator or DM, accepting input in three forms: speech, action and plot instruction. Story re-entry assembles an outline, a world book and character cards into a playable world, with an entry director generating the entry point and playable identities, plus scene, beat, state and summary memory to keep long arcs moving. The relationship archive is downstream of all of this: after a chat or adventure you can ask MuseAI to analyse the session and write relationship changes, important events and interaction patterns back into the character file. Sessions land as JSON files under ~/Documents/MuseAI/agent-sessions/, split by prefix into partner-session-*.json, story-session-*.json and session-*.json for the writing agent. Character cards and world books live together in config/partner-store.json. That single-file store is worth noting: the README does not describe any locking or merge behaviour, so concurrent edits from the desktop window and a phone browser on the same LAN are not something the documentation addresses.

Getting it running: installer, quarantine flag, API key and a connection test

Installation is a download from the Releases page, with .dmg and .exe packages listed. Two platform notes come straight from the README. Windows users are told to disable antivirus software before installing, because the installer may be flagged and either blocked or left in a broken state; it can be re-enabled afterwards. macOS users who see a damaged-app warning are given a Terminal command: xattr -dr com.apple.quarantine /Applications/MuseAI.app. Model configuration happens on the settings page and is provider-agnostic: an API key, an API base URL, and a model name, with OpenAI, Anthropic and any OpenAI-compatible endpoint supported. The README gives deepseek-v4-flash and claude-sonnet-4-6 as example model names, and notes that relay services should have a URL starting with https:// and ending in /v1. A test connection button confirms the configuration. Models and parameters can be set per module, so companion chat, adventure, story re-entry, the de-AI-flavour rewrite and the outline tools can each run on a different model. MuseAI itself does not charge; the README states costs are billed by the provider. The README also documents a recovery step for post-upgrade breakage: open the settings page, find the system prompt for the affected module, and click restore defaults.

The DeepSeek Harness plugin and what it changes

MuseAI ships a DSH client plugin, hosted in a separate repository at yejiming/dsh-museai-tavern, which the README describes as letting you run MuseAI inside DeepSeek Harness so you can work in DSH and run an adventure alongside it. The topics list on the main repository includes dsh and dsh-plugin, and the README's own update banner is the only description of the integration. That is thin. The README does not explain how the plugin reaches the same local data, whether it shares the ~/Documents/MuseAI/ store, or how configuration is handled inside DSH. Anyone whose reason for adopting MuseAI is the DSH plugin should treat the linked repository, not this README, as the source of truth, because nothing in the supplied material answers those questions.

Documented failure modes: token ceilings, JSON parsing and context drift

The FAQ is unusually candid about where things break, and the failures cluster around model output rather than the app itself. Reverse outlining, which condenses a whole novel into a structured outline, can be truncated when the output token budget runs out. The README notes that even when the system prompt caps the result at 10000 characters, the model does not always comply, so failure is expected at some rate. The documented fix is manual: go to settings, open the outline page settings, and raise the maximum output token for the relevant agent (short-form, long-form segmented summary, or long-form final outline), and tighten the wording of the system prompt. World book and character card extraction fails for two stated reasons: unstable model service, or a model that does not return strict JSON. The remedy is to click retry, and for character cards the README's answer continues past the point where the supplied text is truncated. A third failure mode is character drift in long chats. The README attributes it to unbounded context causing the model to forget early settings, and offers three levers: check that the correct world book and character card are bound, start a new session, or adjust the chat agent's maximum context token. System prompt and temperature for the chat agent are also exposed. None of these are bugs with a patch; they are the cost of running role-play on top of a general chat completion API.

What MuseAI is not: the writing modules are auxiliary by the author's own framing

The repository contains a real writing toolset: a workspace file tree with a Markdown editor, live preview and highlighting, per-file version history with automatic backup before edits under a .versions/ folder, a reference library that the AI reads when analysing style, outline evaluation with scoring and suggestions, outline generation, reverse outlining, distributed parallel analysis for long novels, and a de-AI-flavour module that detects machine-sounding prose and produces a rewritten version without overwriting the original. The README nonetheless answers its own FAQ question plainly: MuseAI is currently better suited as a local AI companion, character chat, text adventure and story re-entry app, and the writing features exist to help you organise the story world and interaction material. If your primary need is drafting a novel, the honest comparison is a dedicated writing environment. The difference in approach is structural. A tool like Obsidian with a chat plugin keeps your prose as the centre of the workspace and treats character notes as attachments. MuseAI inverts that: the character card and world book are the load-bearing artefacts, and prose files are one more thing stored under ~/Documents/MuseAI/articles/. Both keep files on your disk. Only one of them was designed around a relationship timeline.

Storage, backup and the licence question

The README states that all user data lives under ~/Documents/MuseAI/, with articles, references and outline files in their own subdirectories, version history in per-directory .versions/ folders, character cards and world books in config/partner-store.json, application settings in config/settings-store.json, and per-module UI state in other config/*.json files. It recommends backing up that directory periodically. There is no cloud sync, no account and no server-side copy, which means backup is entirely your responsibility and a lost Documents folder is a lost relationship archive. The repository metadata supplied here lists the licence as unknown. That is a real gap: without a licence file, the default position is that no rights are granted beyond what the hosting platform's terms allow, and redistribution or bundling into another product is not something you can assume. This is not legal advice, and anyone planning to ship MuseAI inside a commercial product should read the actual repository for a LICENSE file rather than rely on this summary. For personal use the practical effect is small. For anything else, resolve the licence before writing code against it.

Editorial conclusion

MuseAI suits people who want a single local store for character cards, world books and long-running chat or adventure sessions, and who are willing to manage their own API keys and back up ~/Documents/MuseAI/ themselves. It is the wrong tool if you want a hosted service with no API key, or if your main need is novel drafting rather than character interaction, since the writing modules are described in the README as auxiliary. Before committing, verify one thing first: run a character card extraction on a short outline and confirm the model returns parseable JSON, because the README identifies format failure as a known extraction problem and the retry button is the only remedy it documents.

Official sources

1. Issues
2. README
3. Releases
4. yejiming/MuseAI on GitHub