Docs / Troubleshooting
The issues people actually hit, and the fix for each. If nothing here covers it, send a report with your platform and what you tried: that's more useful to us than a generic "it's broken."
Claude Desktop only reads its list of MCP servers on startup. ModelBrain registers itself the moment it launches, but Claude Desktop won't see that until it's fully restarted: closing just the window isn't enough, the app keeps running underneath on every platform. Make sure ModelBrain's tray icon is actually present first, then fully quit and reopen Claude Desktop: on Windows, open the app's menu (☰) and choose File → Exit, or right-click the Claude icon in the system tray and choose Exit; on macOS, ⌘Q or Claude → Quit Claude from the menu bar. Full steps: connecting Claude Desktop.
This can happen right after a release. The installer is signed by NexSpark LLC, but SmartScreen also weighs how many people have downloaded a file, and a new installer starts with none. Click More info, check that the publisher reads NexSpark LLC, then click Run anyway. If the publisher is missing or different, do not run it: download it again from this site. To verify the file yourself first, its SHA-256 is on the download page. Details: installing on Windows.
Only one ModelBrain process can hold your vault open at a time. This usually means two copies of the tray app are running, or a command-line tool (connector_sync sync, a backup) tried to run while the tray already had the vault open. Quit any duplicate ModelBrain instances and try again; a genuinely stuck lock clears itself the moment the process holding it exits, so a full quit-and-reopen of ModelBrain always resolves this.
This means ModelBrain couldn't open your memory store when it started. Run modelbrain_admin status to see the reason it recorded. If the reason says the disk is full or there is no space left on the device, free some space, then quit ModelBrain and open it again. For any other reason, try quitting and reopening it once. If the store still won't open, restore the latest daily snapshot by following Local backups and restore, and keep the old data folder until you've checked the restored memories.
Indexing runs in the background and a large folder takes a little while on its first pass: give it a few minutes before assuming something's wrong. If it still doesn't show up, check whether the file type or its folder is one of the ones ModelBrain automatically skips (build folders, secret-shaped filenames, unsupported file types): see what gets read.
ModelBrain picks a reasoning model automatically based on your machine's RAM and CPU cores (see hardware requirements & tiers). Plain search (the default, non-reasoning path) is always fast regardless of tier; reasoning is the slower, deliberate path used only for questions that need facts connected across notes. If reasoning specifically feels slow:
diagnostics to see which tier and model are actually selected.A reasoning question can come back saying it isn't available right now instead of an answer. This is a normal, honest response, not an error: here's what each reason means: