# Troubleshooting Use symptom, cause, action, and safety guidance when OAuth, MCP discovery, or recall does not behave as expected. - Canonical: https://docs.xmemo.dev/docs/troubleshooting - Locale: en-US - Content-Locale: en-US - Canonical-Content-Digest: 78719b9cecfa970434f8f31e363e6e5cca1f6171a945b7c98cd4db05a669dc4b - Edition-Digest: 3b686a72a08e9d92a9049bfe2077f0eaf24428319dcc5306d73423a541b01b78 - Source-Revision: sha256:888cdc62dd33778dae5cd658cec828efa3504abd545d98fc35af9f3fbd35157a ## Verify a connection without writing memory Every troubleshooting path below ends in a verification step. Start with a read: it proves the credential and the transport without changing anything. ```bash curl -s -o /dev/null -w '%{http_code}\n' \ -H 'X-API-Key: ' \ 'https://xmemo.dev/v1/memories/search?query=connection%20check&limit=1' ``` ## Reading the status code The status separates a credential problem from an empty memory store. ```text 200 — authorized; an empty results array just means nothing matched. 401 — the credential is missing or not valid. 403 — the credential is valid but lacks the required scope. ``` ## Client connection errors When an AI client or runner cannot reach the MCP server, isolate transport protocol negotiation and host routing before rotating tokens. - Verify server health with a direct GET to /health or OPTIONS to /mcp. - Check transport compatibility: hosted clients use Streamable HTTP (/mcp); local CLI tools use stdio. - Ensure corporate proxies or firewalls permit streaming SSE responses without chunk truncation. ```bash curl -I -s 'https://xmemo.dev/mcp' ``` ## Auth failures Authentication failures distinguish missing credentials (401 Unauthorized) from insufficient permissions or tenant boundary violations (403 Forbidden). - OAuth clients: Reconnect via host app and grant memory:read and memory:write. - Direct MCP clients: Verify XMEMO_KEY is populated in the process environment without exposing secrets in git. - 403 Forbidden: Confirm the token belongs to the active tenant and project scope. ```bash curl -s -o /dev/null -w '%{http_code}\n' \ -H 'Authorization: Bearer ' \ 'https://xmemo.dev/v1/memories/search?query=auth%20check&limit=1' ``` ## Empty recall results Recall returning zero results indicates a boundary or query mismatch rather than an engine failure. Reads succeed with 200 OK when no memories match the criteria. - Project scope mismatch: Verify the querying agent operates in the same project as the stored memory. - Agent instance boundary: Direct clients filtering by XMEMO_AGENT_INSTANCE_ID cannot read memories saved under different instance identifiers. - Status check: Verify the memory was committed and has status active, not soft-deleted or superseded. ```bash curl -s -H 'Authorization: Bearer ' \ 'https://xmemo.dev/v1/memories/search?query=test&limit=5&scope=project:demo' ``` ## Write lock timeouts Concurrent writes from multiple runners or parallel tool executions can trigger write lock contention on shared memory paths. - Implement exponential backoff with randomized jitter when write requests return lock contention. - Supply a client-side idempotency key on write retries to prevent duplicate memory entries. - Serialize memory mutations for high-frequency workflows using task queues or batch APIs. ```bash curl -s -X POST 'https://xmemo.dev/v1/memories' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{"content":"Durable convention fact","path":"projects/demo/conventions"}' ``` ## Why does my AI assistant not remember something I told it earlier? I saved an important preference or detail, but in a later chat my AI assistant acts as if it has never seen it. The assistant may be connected to a different XMemo account, project, or device context, or the original memory was not saved. Ask the assistant to save a small, non-sensitive test detail, then open Memory Console and check that it appears under the account and project you use. Use a made-up test detail; do not use another person's private information. ## Why is my AI assistant mixing up my projects or conversations? A detail from one project shows up in another, or the assistant answers as though two conversations belong together. The assistant may be using a different project or account context than the one where the memory was saved. In the assistant, choose the intended XMemo account and project, reconnect it if needed, and retry with a clearly labeled test detail. Do not move private information between projects just to make it appear. ## How can I make my AI assistant forget something completely? I want one memory removed and need to know whether it is gone. Viewing, recoverably removing, permanently deleting, and exporting memory are different account actions. Open Memory Console, find the memory, and use its delete or forget control; if you cannot find the control, contact Support with the memory reference. Delete only the intended memory and never include private content in a support message. ## I changed computers or AI assistants; will XMemo still remember me? My old memories seem split from new ones after I changed devices, restarted an assistant, or switched hosts. The new assistant connection may identify the device or assistant as a new source, or it may be signed into a different account. Reconnect XMemo in the assistant you want to use, sign into the same account, and keep the connection's device label stable when the app offers that option. Check the account before saving anything personal on a shared computer. ## Why did my AI assistant save the same thing twice? I see two copies of what looks like the same memory after a retry or reconnect. The first save may have succeeded even though the assistant did not show the result, so repeating the request created another copy. Open Memory Console, compare the two entries, and remove only the duplicate after confirming their dates and source. Do not delete all matching memories until you identify the copy you want to keep. ## Why is my AI assistant giving me too much or too little of my past context? The assistant brings up unrelated details, misses the decision I need, or gives an answer that feels overloaded. The request covers too broad a topic or time period, or the assistant is trying to use more saved context than the conversation needs. Ask for a narrower topic, project, or time period, and tell the assistant which decision or detail matters most. Do not ask the assistant to reveal unrelated private memories just to fill the conversation. ## I disconnected XMemo; how do I make sure the old assistant cannot use it? I removed the connection from an assistant, but I am unsure whether it can still access my memories. Removing a connection from the app may not cancel the account's connection permission. Open your XMemo account's connected-app or security controls, revoke the old assistant connection, and reconnect only the one you trust. Revoke only the connection you intend to remove and do not share account sign-in details. ## Why cannot my AI assistant use XMemo anymore? XMemo used to be available in my assistant, but its memory actions no longer appear or the assistant says it cannot use them. The assistant may need its XMemo connection refreshed, or it may be signed into a different account. Open the assistant's connected-app settings, disconnect and reconnect XMemo, then start a new chat. Never paste secret account details or private memories into a chat or support request. ## Which XMemo connection should I use in my AI assistant? I am unsure which XMemo page or connection belongs in my assistant's settings. The guided setup page and the assistant connection serve different purposes, and hosted and self-managed setups have different boundaries. For the hosted service, start at https://xmemo.dev/product/docs and follow the connection link shown for your assistant; ask Support if your organization gave you a different setup page. Do not use local development addresses or paste private credentials into a public chat. ## What should I do if my AI assistant still cannot connect to XMemo? I retried the connection steps, but the assistant still cannot use XMemo. The problem may belong to the assistant app, my account, or a stale connection that public instructions cannot inspect. Contact Support with the assistant name, approximate time, and a short description of what you saw; include only redacted details. Never send sign-in details, one-time codes, cookies, or private memory text. ## OAuth failed or the consent window never completes. The client shows 401, the OAuth browser does not open, or consent returns to the client without a usable connection. The hosted grant may be stale, the browser handoff may be blocked, or the client may be using an old server registration. Sign out of the XMemo MCP server in the host app, reconnect the hosted MCP URL, and approve memory:read plus memory:write again. Do not switch to XMEMO_KEY inside OAuth clients just to bypass a stale OAuth session. ## The request returns 403 Forbidden. The server is reachable and the credential is recognized, but the requested project, tool, or memory action is refused. The grant lacks the required scope, the account is outside the selected project boundary, or the resource belongs to another tenant. Check the selected account and project, reconnect OAuth or request the intended scope, then retry the same operation without changing the resource. Do not broaden scopes or copy a different user's token to make a 403 disappear. ## The MCP server connects but no tools appear. The host shows a connected server, but tools/list is empty or the XMemo tools are missing from the model's tool picker. The client has not refreshed discovery, is using the wrong MCP profile, or is connected to a stale URL or registration. Reconnect the server, verify the client is using the supported MCP profile, and run tool discovery again before changing credentials. Do not paste bearer tokens into screenshots, support tickets, or marketplace review notes. ## A direct MCP client says the token is missing. A direct client reports that XMEMO_KEY is unset, empty, or unavailable even though the variable was added somewhere on the machine. The client process did not inherit the environment, the variable was added to a different shell, or the config expects a secret-store reference instead. Set XMEMO_KEY in the local environment or secret store, restart the client, and keep XMEMO_AGENT_INSTANCE_ID stable when attribution matters. Keep the real token outside config files committed to git; public examples should reference environment variables only. ## The agent instance ID changes after every restart. The same local runner appears as several agents or recalls split across instances after a restart or redeploy. XMEMO_AGENT_INSTANCE_ID is generated at process start instead of persisted in the runner's local secret or environment configuration. Generate one non-secret instance label per runner, persist it outside git, and send it with every direct MCP connection. The instance label is attribution metadata, not an authorization credential; account and token boundaries still control access. ## Recall returns empty memory. A recall or search succeeds but returns no relevant records after the user has saved context. The read is using a different account, project, scope, agent boundary, or memory type than the write, or the test record was never committed. Create a synthetic test memory, verify the path and memory type in Memory Console, then retry recall from the same account or tenant boundary. Use synthetic review data; do not use private customer memory as a marketplace demo. ## Recall or write uses the wrong project scope. A record is visible in one project but not another, or a write appears under a project the operator did not intend. The client reused a project identifier from another environment, omitted the project boundary, or retained a stale account session. Select the intended account and project explicitly, refresh the client context, and repeat the operation with a synthetic record. Never solve a scope mismatch by granting a broader token or copying data between projects. ## The same memory is saved twice. A retry or reconnect produces duplicate records instead of one durable memory. The client retried after a timeout without an idempotency boundary, or the capture flow writes before confirming the first response. Inspect the existing record and source attribution first, then use the client retry policy or a stable idempotency key before writing again. Do not bulk-delete matching memories until the intended record and account scope have been confirmed. ## Recall context is too large or too small. The agent receives irrelevant context, misses the needed decision, or exceeds the host's useful context budget. The query is too broad, the scope or time window is missing, or the caller requested an unsuitable result limit for the task. Narrow the query with project, agent, time, or topic boundaries and request a small relevant set before expanding the limit. Do not widen scope or export unrelated memory just to fill a context window. ## How do I delete or export memory? The operator needs to remove a record, confirm a forget action, or obtain an account-scoped export. Delete, recoverable forget, permanent delete, and export are distinct workflows with different confirmation and recovery semantics. Use Memory Console or account workflows first; if a self-service path is unavailable, contact Support so the request stays account-scoped. Exports and support bundles must exclude token hashes, API keys, session secrets, provider credentials, and unrelated tenant data. ## How do I revoke access after a client is disconnected? A client was removed locally, but the operator needs to invalidate its OAuth grant or direct credential. Disconnecting a client config does not necessarily revoke the server-side grant or rotate a direct token. Open account security or connected-client controls, revoke the named OAuth grant, and rotate the direct credential if one was exposed or no longer trusted. Revoke only the intended client or grant; do not publish old tokens, OAuth codes, or session details while diagnosing access. ## Is XMemo GA, certified, or marketplace listed? A listing or document asks whether a working configuration proves GA, certification, or marketplace approval. Configuration support, OAuth readiness, pilot evidence, and marketplace approval are separate claims. Treat public wording as beta/config-supported unless a specific marketplace approval or certification artifact is present. Do not claim GA, certified, stable, or listed status from a working config alone. ## Which URL should I use? A hosted user is unsure whether to follow the public quickstart, MCP endpoint, or self-hosted developer instructions. Hosted onboarding and self-hosted or legacy deployment paths have different URLs, credentials, and data boundaries. Hosted users should start with https://xmemo.dev/mcp for MCP clients and https://xmemo.dev/product/docs for guided setup. Do not use localhost, Supabase, Docker, or self-hosted Python instructions as the first path for public hosted users. ## Memory appears under the wrong agent or device. A memory is attributed to another runner or appears split across devices after a client update or restart. The client changed its non-secret agent or instance headers, or a shared credential is being used by multiple runners. Check the non-secret agent/device headers or client profile, then persist the local instance ID instead of regenerating it. Attribution labels help review source, but they are not a security boundary; account credentials still decide access. ## I still cannot connect after following the steps. The connection remains unavailable after the client-specific OAuth or direct-secret path has been retried. The remaining issue may be client-specific, account-specific, or caused by a stale registration or environment boundary that local docs cannot inspect. Open Support with the client name, config path, approximate timestamp, and whether the client uses OAuth or XMEMO_KEY. Share redacted diagnostics only; never send bearer tokens, OAuth codes, cookies, or customer memory content.