Troubleshooting a box

When a box is unreachable or shows you the wrong person, in the order worth checking.

"The app shows no content" for a box

Most likely your token on that box belongs to a user with no memberships and who isn't admin. Non-admins see only workspaces where they're a member.

Check who you are on each box this Mac knows:

rememd instances

It lists every home - this Mac and every box - with the credential each uses and who you are there. If a box says you are the wrong user (an old "TestUser" from setup, say), redeem a fresh invite to it with rememd join <admin-invite>, or register it as your own with rememd add-instance if you run it. Either way the new token replaces the old one for that box and that box only. Or grant the user a focus area by right-clicking it and choosing Invite.

The box is listed as unreachable in the tree

The home row says so in place, with the reason and a Try again. Workspaces that live there are not listed until it answers; nothing has been lost. Your other homes keep working - a laptop off the network still has everything on its own disk.

Your agent writes to a different box than the app shows

There is no storage mode. Where a workspace lives is recorded per workspace, and a terminal is bound to one workspace with rememd connect - so the agent writes wherever that workspace lives. If its notes land somewhere you did not expect, run rememd where in that terminal: it names the workspace the terminal is bound to, and the tree in the app shows which home that workspace sits under.

A leftover "env": {"REMEMD_MODE": ...} in ~/.claude.json from an older install is ignored on a machine with more than one home, and says so on stderr. Remove it.

"Version conflict" alert on PRD save

Someone else saved the same PRD between your fetch and your save. Three choices in the dialog:

  • Keep mine - overwrites the server copy at the latest version. Their edits are replaced by yours.
  • Discard mine - loads the server's current body into the editor. Your in-flight edits are lost.
  • Cancel - closes the dialog, leaves you unresolved. Save again to re-try.

The resolution goes to the box the conflict came from, whichever box that is.

Live updates not arriving

rememd watch tails the event stream of the box your terminal is bound to, or of every box when it is not bound to one. If it prints PRESENCE and nothing after a known change, the box is up and the client is not decoding the event; check the app's console for decode errors on the payload.

To check the stream by hand:

curl -N -H "Authorization: Bearer <your-token>" https://your-box/events
# should print: ": connected" and then ": ping" every 15s

Backend crashed / Docker reset

cd backend/
make backup-list                                  # find the latest dump
docker compose up -d                              # or `make up`
make restore FILE=backups/rememd-<latest>.sql.gz

Everything back, including tokens. No re-join needed.

"I deleted a feature but the PRD is still searchable"

Happened before migration 004 was applied. Run:

curl -X POST -H "Authorization: Bearer <admin-token>" \\
  https://your-box/admin/cleanup-orphans
# → {"deleted": N}

Or just delete + recreate the workspace (cleanup is now automatic on workspace delete).