Dex improves continuously, and it's built so that staying current is safe and boring: your data can't be touched by an update, every update can be undone, and a built-in doctor tells you the truth about what's working. This page covers the maintenance story end to end, then the frequently asked questions.
Updating: /dex-update
When a new version exists, Dex shows you what's in it — version, changes in plain language — and waits. Dex never updates itself; you always say go. When you do:
- A restore point is taken first, before anything changes. This is what makes rollback possible.
- New files download and merge. The overwhelmingly common case is a clean update, done in under a minute.
- If a file was changed by both you and the update, Dex resolves by a simple rule: your data and settings always win; core Dex machinery takes the update; anything you customized stays yours. Genuinely ambiguous cases get shown to you with the tradeoffs.
- Dex verifies itself — tasks readable, profile intact, features working — and offers automatic rollback if anything looks wrong.
The structural guarantee behind all this: the folders holding your notes, tasks, projects, and people are excluded from version control entirely. The update mechanism literally cannot see them, which is a stronger promise than "we're careful." Your protected customizations — the extensions block, custom skills, custom connectors — survive by design.
If an update ever disappoints, /dex-rollback restores the exact pre-update state from the restore point, in about thirty seconds — and a rollback can itself be undone. If a restore point has aged out or files changed since, Dex refuses cleanly and explains, rather than guessing.
Between updates, Dex checks about weekly whether a new version exists and mentions it in one line during your daily plan. You may also occasionally see a carefully worded notice that a release "appears to exist" but hasn't been verified — that caution is deliberate security honesty, not a malfunction.
Health: /dex-doctor
Run it any time something feels off — or just monthly. The doctor checks your configuration, tools, integrations, and background automation, and reports in four honest states:
- Working — verified, not assumed.
- Off — you chose not to enable it. Reported calmly, never nagged about.
- Broken — configured but failing, with the fix.
- Couldn't check — the check itself failed. Said plainly, never silently counted as a pass.
Fixes are tiered by risk: safe ones are applied automatically and reported; anything meaningful is proposed one at a time for your OK; and things only you can do (grant a Mac permission, add an API key) come as clear instructions. A deep-scan option goes further and tests live connections — actually calling Granola, actually reading the calendar — to prove real behavior rather than checking configuration exists.
There's also a nightly self-test that runs Dex's core machinery against an isolated throwaway copy — never your real vault — so a breakage surfaces at your next session start instead of mid-workday. If the same check keeps failing across runs, Dex offers to draft a bug report.
Common issues, quick fixes
- Meetings stopped syncing →
/dex-doctor, which tests the Granola connection; usually the API key or the background job. - Calendar events missing (Mac) → System Settings → Privacy & Security → Calendars → give your editor Full access.
- Search feels stale → ask Dex to refresh the search index (
qmd update && qmd embed). - Tools show as unavailable after an update → fully quit and reopen your editor; then
/dex-doctor. - Dex feels vague in a very long chat → start a fresh session; memory lives in your files, so nothing is lost. (Why this happens.)
Frequently asked questions
Where is my data, exactly? In one folder of plain text files on your computer. No database, no Dex cloud. Open any file and read it — that's the entire truth of what Dex knows.
Does my data get sent anywhere? Your conversations go to the AI provider you chose (Anthropic via Claude Code, or Cursor's providers) to generate responses — the same as using Claude or Cursor for anything. Dex adds no server of its own. Optional integrations talk directly to your own accounts using your own keys. Semantic search runs entirely on your machine. Anonymous usage analytics are on by default and switch off with one sentence: "turn off Dex analytics."
How do I use Dex on two computers? Sync the vault folder. The recommended route is Obsidian Sync (about $8/month) because it's end-to-end encrypted — only you hold the key — and includes mobile apps. iCloud, Dropbox, Google Drive, or a private GitHub repository all work too, with the caveat that those providers can technically read your files.
What's Obsidian and do I need it? A free note-taking app that reads the same files as Dex — entirely optional. It adds a visual layer: a clickable graph of your people, projects, and meetings, and pleasant reading and editing. Enable it any time with /dex-obsidian-setup; it's safe on an existing vault, and reversible.
What if I stop using Dex? You keep everything. The vault is ordinary Markdown — readable in any editor, importable anywhere, no export step required. Delete the Dex machinery and the notes remain yours. This is the point of the plain-files design.
How much does Dex cost? Dex itself is free and open source. You pay only for the AI underneath (a Claude or Cursor subscription) and any optional services you already use, like Granola.
Is it safe to let an AI touch my files? The high-stakes operations (task IDs, multi-file syncs) run through deterministic tools, not AI improvisation; the assistant asks permission before new kinds of actions; updates can't reach your data folders; and everything is inspectable — /xray shows you exactly what happened in any conversation. Skepticism is designed for, not discouraged.
When something misbehaves, resist the urge to describe it vaguely. Hand Dex the diagnosis job properly:
Something's off: [WHAT YOU EXPECTED] but instead [WHAT HAPPENED]. Diagnose your own setup: check the relevant tools, configuration, and background jobs, tell me what you find in plain language, and separate what you can fix yourself from what needs my hands. Don't guess — if a check is inconclusive, say so.
Don't just read this — paste it into your own Dex and it becomes a lesson about your actual work.
First, fetch and read the page I'm referring to: https://heydex.ai/help/updating-troubleshooting.md I just read the Dex Guide's page on updating and health. Run the full checkup on yourself now — configuration, tools, integrations, background jobs — and give me the honest four-state report in plain words: working, off by choice, broken, couldn't check. Fix what's safe automatically, queue what needs my OK one at a time, and tell me exactly what needs my hands. Then check whether a newer Dex exists, and if so, what's in it for someone who works like me.