The things that actually go wrong, and what to do about them.
Connecting
The assistant can't see any Kythene tools. The MCP server isn't registered, or the client hasn't restarted. Check the server is listed in the client's MCP settings and that the URL ends /mcp/kythene. Restart the client - several only read their MCP config at startup.
It asks me to sign in every time. The client isn't persisting the OAuth token. Check it isn't running in a sandbox or private mode that clears storage between sessions.
The browser opens but the authorisation doesn't complete. Usually a redirect that can't get back to a local client. Try the connection again from a fresh browser session, and if you self-host, check KYTHENE_URL exactly matches the URL you actually reach the app on - including scheme, and no trailing slash. Almost every self-host auth oddity is a KYTHENE_URL mismatch.
Tools appear, but every call returns unauthorised. You're authenticated but the workspace didn't resolve, or you're not a member of the one being targeted. Ask the instance to list your workspaces, then name one explicitly.
Recall and memory
Recall returns nothing. In order of likelihood:
- The project name doesn't match the tag. They're exact - ask for the project list and check.
- Wrong workspace. Name it explicitly.
- The memory is deprecated, so it's hidden by default. Ask for deprecated ones included.
- It really was never written. Session ended, nobody said "remember that".
Recall returns far too much. Narrow it: a project, a type, a search term, a smaller limit. Untargeted recall on a busy workspace is a firehose by design - it doesn't know what you care about unless you say.
A memory keeps coming back after I superseded it. Superseding needs the same title in the same project. A different title creates a second memory rather than replacing the first. Check the titles, and merge the duplicate by deprecating it with replaced_by pointing at the good one.
An instance is applying something that's wrong. Verify against the live system first, then supersede or deprecate. Don't work around it - a false memory left in place will be applied again by someone else's instance next week.
A memory came back marked restricted and I didn't ask for that. Derived-memory provenance did its job: the memory was written after reading restricted content, so it inherited that restriction rather than becoming an open summary of private material. See Memory.
Publishing
Publishing fails on a self-host install. Object storage almost certainly isn't configured. Blob storage is disabled when the endpoint is blank and publishing then refuses. Check the MinIO/S3 settings, and that the bucket exists - the app doesn't create it.
Two collections where I wanted one. Push a version rather than publishing again. Same link, one history, one comment thread. See Versions and revisions.
Approvals vanished. A new version landed. Approvals are derived from the pinned revision, so they clear when the work moves - that's the design, not a bug. Ask for review again on the new revision.
Sharing
A guest can't see anything. The work isn't carrying the tag their share code is scoped to. Check the collection's tags rather than the code.
A guest can still get in after I revoked the code. They shouldn't - revocation is enforced server-side and immediate. Check you revoked the code they're actually using; list_share_codes shows which are live.
Someone got added as a member when I meant to give them a code. Members count towards your plan; guests don't. Remove the member and mint a code instead. See Sharing and guests.
Self-hosting
Semantic recall isn't working. It needs an embedding server. Without KYTHENE_MEMORY_EMBED_URL set, recall uses full-text alone - working as configured, just without the meaning-based match. See Self-hosting.
The app won't start after an upgrade. Check the logs for a migration failure, and that the database role can create extensions - CREATE EXTENSION vector runs on boot. Migrations are forward-only, so restore from a backup rather than trying to roll one back.
Sign-ins are being refused. The seat cap. An unlicensed install is free for a single user; further sign-ins are refused until a licence lifts the cap. See Plans, seats and billing.
Still stuck
Tell us: [email protected]. Include what you asked the instance, what it did, and which client you're on - it's usually enough to spot it immediately.
If you've found a security issue, there's a disclosure route at /.well-known/security.txt.