memory に書き込まずに接続を検証する
以下のすべてのトラブルシューティング手順は verification ステップで終了します。まず読み取りから始めます。何も変更せずに credential と transport を確認できます。
curl -s -o /dev/null -w '%{http_code}\n' \
-H 'X-API-Key: <your-assigned-api-key>' \
'https://xmemo.dev/v1/memories/search?query=connection%20check&limit=1'status code を確認する
Status により credential の問題と空の memory store を区別できます。
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.クライアント接続エラー
AI クライアントやランナーが MCP サーバーに接続できない場合は、トークンをローテーションする前にトランスポートプロトコルのネゴシエーションとホストルーティングを切り分けます。
- /health への直接 GET または /mcp への OPTIONS リクエストでサーバーの健全性を検証します。
- トランスポートの互換性を確認します：ホスト型クライアントは Streamable HTTP (/mcp) を使用し、ローカル CLI ツールは stdio を使用します。
- 企業のプロキシまたはファイアウォールがチャンクの切り捨てなしにストリーミング SSE 応答を許可していることを確認します。
curl -I -s 'https://xmemo.dev/mcp'認証エラー
認証エラーでは、認証情報の欠落（401 Unauthorized）と、権限不足またはテナント境界違反（403 Forbidden）が明確に区別されます。
- OAuth クライアント：ホストアプリ経由で再接続し、memory:read および memory:write 権限を付与します。
- Direct MCP クライアント：git でシークレットを公開することなく、プロセス環境に XMEMO_KEY が設定されていることを確認します。
- 403 Forbidden：トークンがアクティブなテナントと project scope に属していることを確認します。
curl -s -o /dev/null -w '%{http_code}\n' \
-H 'Authorization: Bearer <your-token>' \
'https://xmemo.dev/v1/memories/search?query=auth%20check&limit=1'空の想起結果
想起で結果が返されない場合は、エンジンの障害ではなく境界またはクエリの不一致を示しています。一致するメモリがない場合でも、読み取りは 200 OK で正常終了します。
- Project scope の不一致：クエリを実行するエージェントが保存されたメモリと同じ project 境界内にあることを確認します。
- エージェントインスタンス境界：XMEMO_AGENT_INSTANCE_ID でフィルタリングする Direct クライアントは、異なるインスタンス識別子で保存されたメモリを読み取ることはできません。
- ステータス確認：Memory Console でメモリがコミットされ、論理削除や廃止ではなく active 状態であることを確認します。
curl -s -H 'Authorization: Bearer <your-token>' \
'https://xmemo.dev/v1/memories/search?query=test&limit=5&scope=project:demo'書き込みロックのタイムアウト
複数のランナーからの同時書き込みまたは並行したツール実行により、共有 memory path で書き込みロックの競合が発生する可能性があります。
- 書き込みリクエストでロック競合が返された場合、クライアント側でランダムジッターを伴う指数バックオフを実装します。
- 重複するメモリレコードの作成を防ぐため、書き込みの再試行時にクライアント側で冪等性キー（idempotency key）を指定します。
- 高頻度のワークフローでは、タスクキューやバッチ API を使用してメモリ変更操作を直列化します。
curl -s -X POST 'https://xmemo.dev/v1/memories' \
-H 'Authorization: Bearer <your-token>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: <generate-a-uuid-v4>' \
-d '{"content":"Durable convention fact","path":"projects/demo/conventions"}'FAQ / トラブルシューティング
まずAIアシスタントを使うユーザー向けの回答を確認し、その後で接続と運用の詳細についてdeveloperおよびintegrator向けの回答を確認してください。すべての回答にactionとsafety boundaryが含まれています。
AIアシスタントを使うユーザー向け
connectionを自分で設定せず、AIアシスタントを通じてXMemoを使う人向けの日常的な回答です。
なぜAIアシスタントは、以前伝えたことを覚えていないのですか？
- 現象
- 大切な設定や詳細を保存したのに、後のchatでAIアシスタントが初めて見るかのように振る舞います。
- 原因
- アシスタントが、保存先とは別のXMemo account、project、device contextに接続されているか、元のmemoryが保存されていない可能性があります。
- 操作:
- アシスタントに小さく機密性のないテスト用の詳細を保存するよう頼み、Memory Consoleで使用中のaccountとprojectに表示されることを確認します。
- 検証
- 同じアシスタントで新しいchatを開始し、テスト用の詳細について尋ねます。終わったらテスト項目を削除します。
- 安全:
- 作り話のテスト用詳細を使い、他人のprivate informationは使わないでください。
なぜAIアシスタントはprojectやconversationを混同するのですか？
- 現象
- あるprojectの詳細が別のprojectに現れたり、2つのconversationが関連しているかのようにアシスタントが答えたりします。
- 原因
- アシスタントが、memoryを保存した場所とは異なるprojectまたはaccount contextを使っている可能性があります。
- 操作:
- アシスタントで意図したXMemo accountとprojectを選び、必要なら再接続して、明確なlabelを付けたテスト用詳細で再試行します。
- 検証
- Memory Consoleでmemoryのprojectとsourceを確認し、関係のないprojectからそのテスト用詳細を見られないことを確認します。
- 安全:
- 表示させるためだけにprivate informationをproject間で移動しないでください。
AIアシスタントに何かを完全に忘れさせるにはどうすればよいですか？
- 現象
- 1つのmemoryを削除したいのですが、本当に消えたか確認したいです。
- 原因
- memoryの表示、復元可能な削除、完全削除、exportは、それぞれ異なるaccount操作です。
- 操作:
- Memory Consoleでmemoryを開き、deleteまたはforgetのcontrolを使います。controlが見つからなければ、memory referenceを添えてSupportに連絡します。
- 検証
- もう一度memoryを検索し、Memory Consoleに表示されるstateを確認します。exportには自分のaccountのdataだけが含まれることも確認します。
- 安全:
- 意図したmemoryだけを削除し、Supportへのmessageにprivate contentを決して含めないでください。
computerやAIアシスタントを変えても、XMemoは私を覚えていますか？
- 現象
- deviceを変えた、アシスタントを再起動した、hostを切り替えた後に、古いmemoryと新しいmemoryが分かれたように見えます。
- 原因
- 新しいアシスタント接続がdeviceやassistantを新しいsourceとして識別しているか、別のaccountにサインインしている可能性があります。
- 操作:
- 使いたいアシスタントでXMemoに再接続し、同じaccountにサインインします。appに選択肢がある場合は、connectionのdevice labelを一定に保ちます。
- 検証
- 作り話のテスト用詳細を1つ保存し、同じアシスタントで新しいchatを開始して、accountを変えずにその詳細が表示されることを確認します。
- 安全:
- 共有computerで個人的な情報を保存する前に、accountを確認してください。
なぜAIアシスタントは同じことを2回保存したのですか？
- 現象
- retryや再接続の後、同じmemoryに見える項目が2つあります。
- 原因
- アシスタントに結果が表示されなくても最初の保存は成功していて、requestを繰り返したことで別のcopyが作られた可能性があります。
- 操作:
- Memory Consoleで2つのentryを比較し、dateとsourceを確認してからduplicateだけを削除します。
- 検証
- 新しく明確なlabelを付けたテスト用詳細を1回だけ保存するようアシスタントに頼み、新しいentryが1つだけ現れることを確認します。
- 安全:
- 残すcopyを特定するまで、該当するmemoryをすべて削除しないでください。
なぜAIアシスタントは過去のcontextを多すぎたり少なすぎたりして返すのですか？
- 現象
- 関係のない詳細を持ち出す、必要なdecisionを見落とす、または回答が情報過多に感じられます。
- 原因
- requestのtopicや期間が広すぎるか、conversationに必要な量を超える保存済みcontextをアシスタントが使おうとしている可能性があります。
- 操作:
- topic、project、期間を狭めて尋ね、最も重要なdecisionまたは詳細をアシスタントに伝えます。
- 検証
- 回答を依頼したtopicと比較し、続行する前に関係のない詳細をconversationから取り除きます。
- 安全:
- conversationを埋めるためだけに、関係のないprivate memoryをアシスタントに開示させないでください。
XMemoの接続を解除した後、古いアシスタントが使えないことを確認するには？
- 現象
- アシスタントからconnectionを削除しましたが、まだmemoryにアクセスできるのか不安です。
- 原因
- appからconnectionを削除しても、accountのconnection permissionが取り消されるとは限りません。
- 操作:
- XMemo accountのconnected-appまたはsecurity controlを開き、古いassistant connectionをrevokeして、信頼するものだけを再接続します。
- 検証
- 安全な場合に限って古いconnectionを試し、拒否されることを確認してから新しいconnectionを使います。
- 安全:
- 削除するconnectionだけをrevokeし、accountのサインイン情報は共有しないでください。
なぜAIアシスタントでXMemoを使えなくなったのですか？
- 現象
- 以前はassistantでXMemoを使えたのに、memory actionが表示されなくなったか、使えないと表示されます。
- 原因
- アシスタントのXMemo connectionを更新する必要があるか、別のaccountにサインインしている可能性があります。
- 操作:
- assistantのconnected-app settingを開き、XMemoをdisconnectしてからreconnectし、新しいchatを開始します。
- 検証
- XMemoが接続されているかアシスタントに確認し、保存する前に無害なreadを試します。
- 安全:
- secretのaccount detailsやprivate memoryをchatまたはSupport requestに貼り付けないでください。
AIアシスタントでは、どのXMemo connectionを使えばよいですか？
- 現象
- assistantのsettingにどのXMemo pageまたはconnectionを登録すべきか分かりません。
- 原因
- guided setup pageとassistant connectionは用途が異なり、hosted setupとself-managed setupではboundaryも異なります。
- 操作:
- Hosted serviceでは https://xmemo.dev/product/docs から始め、assistant向けに表示されるconnection linkに従います。組織から別のsetup pageを指定されている場合はSupportに確認します。
- 検証
- 個人的な詳細を保存する前に、pageが意図したXMemo accountとhosted serviceを使っていることを確認します。
- 安全:
- local development addressを使ったり、public chatにprivate credentialを貼り付けたりしないでください。
AIアシスタントがまだXMemoに接続できない場合はどうすればよいですか？
- 現象
- connection手順を再試行しても、アシスタントでXMemoを使えません。
- 原因
- 問題がassistant app、account、またはpublic instructionでは調査できない古いconnectionにある可能性があります。
- 操作:
- assistant名、おおよその時刻、確認した内容の短い説明をSupportに送り、詳細はredactしたものだけを含めます。
- 検証
- private memoryやaccount secretを送らなくてもreportを再現できることを確認します。
- 安全:
- サインイン情報、one-time code、cookie、private memory textは決して送らないでください。
Developerとintegrator向け
XMemoをintegrateする人向けに、connection、account boundary、client、運用に関する回答をまとめています。
OAuthに失敗するか、同意windowが完了しません。
- 現象
- clientに401が表示される、OAuth browserが開かない、または同意後に使えるconnectionなしでclientへ戻ります。
- 原因
- hosted grantが古い、browser handoffがblockされている、またはclientが古いserver registrationを使っている可能性があります。
- 操作:
- host appでXMemo MCP serverからsign outし、hosted MCP URLに再接続して、memory:readとmemory:writeをもう一度承認します。
- 検証
- clientがactive authorizationを報告するまで再接続し、memoryを書き込む前に無害なrecallを実行します。
- 安全:
- 古いOAuth sessionを回避するためだけに、OAuth client内でXMEMO_KEYへ切り替えないでください。
requestが403 Forbiddenを返します。
- 現象
- serverには到達できcredentialも認識されますが、指定したproject、tool、memory actionが拒否されます。
- 原因
- grantに必要なscopeがない、accountが選択したprojectのboundary外にある、またはresourceが別のtenantに属している可能性があります。
- 操作:
- 選択したaccountとprojectを確認し、OAuthを再接続するか必要なscopeをrequestしてから、resourceを変えずに同じ操作を再試行します。
- 検証
- writeまたはdeleteを再試行する前に、意図したprojectでread-only requestが成功することを確認します。
- 安全:
- 403を消すためにscopeを広げたり、別ユーザーのtokenをcopyしたりしないでください。
MCP serverには接続できますが、toolが表示されません。
- 現象
- hostではserverが接続済みなのに、tools/listが空か、modelのtool pickerにXMemo toolがありません。
- 原因
- clientがdiscoveryを更新していない、誤ったMCP profileを使っている、または古いURLやregistrationに接続している可能性があります。
- 操作:
- serverをreconnectし、clientが対応するMCP profileを使っていることを確認してから、credentialを変更せずにtool discoveryをもう一度実行します。
- 検証
- writeやmarketplace demonstrationを始める前に、少なくともremember、recall、search_memoryが表示されることを確認します。
- 安全:
- bearer tokenをscreenshot、Support ticket、marketplace review noteに貼り付けないでください。
direct MCP clientがtoken missingと報告します。
- 現象
- machineのどこかにvariableを追加したのに、direct clientがXMEMO_KEYがunset、empty、または利用できないと報告します。
- 原因
- client processがenvironmentを継承していない、別のshellにvariableを追加した、またはconfigがsecret-store referenceを求めている可能性があります。
- 操作:
- local environmentまたはsecret storeにXMEMO_KEYを設定してclientを再起動し、attributionが必要な場合はXMEMO_AGENT_INSTANCE_IDを一定に保ちます。
- 検証
- variableの存在metadataだけを確認し、clientを再起動して無害なauthenticated recallを実行します。token valueは決して表示しません。
- 安全:
- 実際のtokenはgitにcommitするconfig fileの外で管理し、public exampleではenvironment variableだけを参照してください。
restartするたびにagent instance IDが変わります。
- 現象
- 同じlocal runnerが複数のagentとして現れたり、restartやredeployの後にrecallがinstance間で分かれたりします。
- 原因
- XMEMO_AGENT_INSTANCE_IDがrunnerのlocal secretまたはenvironment configurationに保存されず、process start時に生成されています。
- 操作:
- runnerごとにsecretではないinstance labelを1つ生成し、gitの外に保存して、すべてのdirect MCP connectionで送信します。
- 検証
- runnerを2回restartし、credentialを公開せずにsource attributionに同じinstance labelが現れることを確認します。
- 安全:
- instance labelはattribution metadataでありauthorization credentialではありません。accountとtokenのboundaryが引き続きaccessを制御します。
Recallがempty memoryを返します。
- 現象
- userがcontextを保存した後、recallまたはsearchは成功するのに該当するrecordが返りません。
- 原因
- readがwriteと異なるaccount、project、scope、agent boundary、memory typeを使っているか、test recordがcommitされていない可能性があります。
- 操作:
- synthetic test memoryを作成し、Memory Consoleでpathとmemory typeを確認してから、同じaccountまたはtenant boundaryでrecallを再試行します。
- 検証
- 同じprojectとscopeで新しいsynthetic recordをreadし、意図したdelete pathから削除します。
- 安全:
- synthetic review dataを使い、marketplace demoにcustomerのprivate memoryを使わないでください。
Recallまたはwriteが誤ったproject scopeを使います。
- 現象
- あるprojectではrecordが見えるのに別のprojectでは見えない、または意図しないprojectにwriteが現れます。
- 原因
- clientが別environmentのproject identifierを再利用した、project boundaryを省略した、または古いaccount sessionが残っている可能性があります。
- 操作:
- 意図したaccountとprojectを明示的に選び、client contextを更新してから、synthetic recordで操作を繰り返します。
- 検証
- Memory Consoleでrecordのprojectとsource attributionを確認し、関係のないprojectから読めないことを確認します。
- 安全:
- scopeの不一致を解決するために、より広いtokenを付与したりproject間でdataをcopyしたりしないでください。
同じmemoryが2回保存されます。
- 現象
- retryまたはreconnectで、1つのdurable memoryではなくduplicate recordが作られます。
- 原因
- clientがtimeout後にidempotency boundaryなしでretryしたか、capture flowが最初のresponseを確認する前にwriteした可能性があります。
- 操作:
- まず既存recordとsource attributionを確認し、client retry policyまたはstable idempotency keyを使ってから再度writeします。
- 検証
- 同じcontrolled captureを1回だけ繰り返し、新しいrecordが1つとreadbackが1つだけで、2つの新規recordではないことを確認します。
- 安全:
- 意図したrecordとaccount scopeを確認するまで、該当するmemoryを一括削除しないでください。
Recall contextが大きすぎる、または小さすぎます。
- 現象
- agentが関係のないcontextを受け取る、必要なdecisionを見落とす、またはhostで有効なcontext budgetを超えます。
- 原因
- queryが広すぎる、scopeやtime windowがない、またはcallerがtaskに合わないresult limitを指定している可能性があります。
- 操作:
- project、agent、time、topicのboundaryでqueryを狭め、limitを広げる前に少数の関連結果をrequestします。
- 検証
- 返されたcontextをtarget questionと比較し、含まれるすべてのrecordが認可済みで有用なことを確認します。
- 安全:
- context windowを埋めるためだけにscopeを広げたり無関係なmemoryをexportしたりしないでください。
memoryをdeleteまたはexportするにはどうすればよいですか？
- 現象
- operatorがrecordの削除、forget actionの確認、account-scoped exportを必要としています。
- 原因
- delete、recoverable forget、permanent delete、exportは、confirmationとrecovery semanticsが異なる別々のworkflowです。
- 操作:
- まずMemory Consoleまたはaccount workflowを使います。self-service pathがなければSupportに連絡し、requestをaccount scope内に保ちます。
- 検証
- forgetまたはdeleteの後にrecord referenceで検索し、期待するrecoverableまたはpermanent stateを確認します。exportがaccount scopeだけを含むことも確認します。
- 安全:
- exportとSupport bundleからtoken hash、API key、session secret、provider credential、無関係なtenant dataを除外してください。
clientをdisconnectした後、accessをrevokeするには？
- 現象
- clientをlocalでは削除したものの、operatorはOAuth grantを無効化するかdirect credentialをrotateする必要があります。
- 原因
- client configをdisconnectしてもserver-side grantがrevokeされるとは限らず、direct tokenがrotateされるとも限りません。
- 操作:
- account securityまたはconnected-client controlを開き、指定したOAuth grantをrevokeします。direct credentialが露出した、または信頼できなくなった場合はrotateします。
- 検証
- 古いconnectionでauthenticated readをretryして拒否されることを確認し、その後は意図したconsentまたはsecret-store pathだけでreconnectします。
- 安全:
- 意図したclientまたはgrantだけをrevokeし、accessを調査する間に古いtoken、OAuth code、session detailsを公開しないでください。
XMemoはGA、certified、またはmarketplace listedですか？
- 現象
- listingやdocumentで、動作するconfigurationがGA、certification、marketplace approvalを証明するか尋ねられます。
- 原因
- configuration support、OAuth readiness、pilot evidence、marketplace approvalは別々の主張です。
- 操作:
- 特定のmarketplace approvalまたはcertification artifactがない限り、public wordingはbeta/config-supportedとして扱います。
- 検証
- status claimを公開する前に、canonical client capability matrixと指定されたapproval artifactを確認します。
- 安全:
- 動作するconfigurationだけを根拠に、GA、certified、stable、listedと主張しないでください。
どのURLを使えばよいですか？
- 現象
- hosted userがpublic quickstart、MCP endpoint、self-hosted developer instructionのどれに従うべきか分かりません。
- 原因
- hosted onboardingとself-hostedまたはlegacy deployment pathでは、URL、credential、data boundaryが異なります。
- 操作:
- Hosted userはMCP clientにhttps://xmemo.dev/mcpを使い、guided setupはhttps://xmemo.dev/product/docsから始めます。
- 検証
- 接続前にhost URL、authentication mode、account boundaryが意図したhostedまたはself-hosted deploymentと一致することを確認します。
- 安全:
- public hosted userの最初のpathとしてlocalhost、Supabase、Docker、self-hosted Python instructionを使わないでください。
Memoryが誤ったagentまたはdeviceの下に表示されます。
- 現象
- client updateやrestartの後、memoryが別のrunnerにattributionされたり、device間で分かれたように見えたりします。
- 原因
- clientが秘密ではないagentまたはinstance headerを変更したか、複数のrunnerが同じcredentialを共有している可能性があります。
- 操作:
- 秘密ではないagent/device headerまたはclient profileを確認し、再生成するのではなくlocal instance IDを保存します。
- 検証
- 意図したrunnerからsynthetic recordを1つwriteし、reconnect後もsource attributionが安定していることを確認します。
- 安全:
- Attribution labelはsource確認に役立ちますがsecurity boundaryではありません。accessはaccount credentialが決めます。
手順に従っても接続できません。
- 現象
- client固有のOAuthまたはdirect-secret pathをretryしてもconnectionが利用できません。
- 原因
- 残る問題はclient固有、account固有、またはlocal docsでは調査できない古いregistrationやenvironment boundaryが原因かもしれません。
- 操作:
- client名、config path、おおよそのtimestamp、clientがOAuthとXMEMO_KEYのどちらを使うかをSupportに伝えます。
- 検証
- Support reportに再現可能なsymptomとredacted metadataが含まれることを確認し、account-scoped diagnosisを待ちます。
- 安全:
- redacted diagnosticだけを共有し、bearer token、OAuth code、cookie、customer memory contentは決して送らないでください。