# トラブルシューティング

OAuth、MCP discovery、またはrecallが期待どおりに動かないときに、symptom、cause、action、safetyの案内を使います。

- Canonical: https://docs.xmemo.dev/ja/docs/troubleshooting
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: 78719b9cecfa970434f8f31e363e6e5cca1f6171a945b7c98cd4db05a669dc4b
- Edition-Digest: eeea9703ba3bfa9df8fcdd76be359862508c22784cb03c89d2f3853a6a433189
- Source-Revision: sha256:888cdc62dd33778dae5cd658cec828efa3504abd545d98fc35af9f3fbd35157a

## memory に書き込まずに接続を検証する

以下のすべてのトラブルシューティング手順は verification ステップで終了します。まず読み取りから始めます。何も変更せずに credential と transport を確認できます。

```bash
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 を区別できます。

```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.
```

## クライアント接続エラー

AI クライアントやランナーが MCP サーバーに接続できない場合は、トークンをローテーションする前にトランスポートプロトコルのネゴシエーションとホストルーティングを切り分けます。

- /health への直接 GET または /mcp への OPTIONS リクエストでサーバーの健全性を検証します。
- トランスポートの互換性を確認します：ホスト型クライアントは Streamable HTTP (/mcp) を使用し、ローカル CLI ツールは stdio を使用します。
- 企業のプロキシまたはファイアウォールがチャンクの切り捨てなしにストリーミング SSE 応答を許可していることを確認します。

```bash
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 に属していることを確認します。

```bash
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 状態であることを確認します。

```bash
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 を使用してメモリ変更操作を直列化します。

```bash
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"}'
```

## なぜAIアシスタントは、以前伝えたことを覚えていないのですか？

大切な設定や詳細を保存したのに、後のchatでAIアシスタントが初めて見るかのように振る舞います。

アシスタントが、保存先とは別のXMemo account、project、device contextに接続されているか、元のmemoryが保存されていない可能性があります。

アシスタントに小さく機密性のないテスト用の詳細を保存するよう頼み、Memory Consoleで使用中のaccountとprojectに表示されることを確認します。

作り話のテスト用詳細を使い、他人のprivate informationは使わないでください。

## なぜAIアシスタントはprojectやconversationを混同するのですか？

あるprojectの詳細が別のprojectに現れたり、2つのconversationが関連しているかのようにアシスタントが答えたりします。

アシスタントが、memoryを保存した場所とは異なるprojectまたはaccount contextを使っている可能性があります。

アシスタントで意図したXMemo accountとprojectを選び、必要なら再接続して、明確なlabelを付けたテスト用詳細で再試行します。

表示させるためだけにprivate informationをproject間で移動しないでください。

## AIアシスタントに何かを完全に忘れさせるにはどうすればよいですか？

1つのmemoryを削除したいのですが、本当に消えたか確認したいです。

memoryの表示、復元可能な削除、完全削除、exportは、それぞれ異なるaccount操作です。

Memory Consoleでmemoryを開き、deleteまたはforgetのcontrolを使います。controlが見つからなければ、memory referenceを添えてSupportに連絡します。

意図したmemoryだけを削除し、Supportへのmessageにprivate contentを決して含めないでください。

## computerやAIアシスタントを変えても、XMemoは私を覚えていますか？

deviceを変えた、アシスタントを再起動した、hostを切り替えた後に、古いmemoryと新しいmemoryが分かれたように見えます。

新しいアシスタント接続がdeviceやassistantを新しいsourceとして識別しているか、別のaccountにサインインしている可能性があります。

使いたいアシスタントでXMemoに再接続し、同じaccountにサインインします。appに選択肢がある場合は、connectionのdevice labelを一定に保ちます。

共有computerで個人的な情報を保存する前に、accountを確認してください。

## なぜAIアシスタントは同じことを2回保存したのですか？

retryや再接続の後、同じmemoryに見える項目が2つあります。

アシスタントに結果が表示されなくても最初の保存は成功していて、requestを繰り返したことで別のcopyが作られた可能性があります。

Memory Consoleで2つのentryを比較し、dateとsourceを確認してからduplicateだけを削除します。

残すcopyを特定するまで、該当するmemoryをすべて削除しないでください。

## なぜAIアシスタントは過去のcontextを多すぎたり少なすぎたりして返すのですか？

関係のない詳細を持ち出す、必要なdecisionを見落とす、または回答が情報過多に感じられます。

requestのtopicや期間が広すぎるか、conversationに必要な量を超える保存済みcontextをアシスタントが使おうとしている可能性があります。

topic、project、期間を狭めて尋ね、最も重要なdecisionまたは詳細をアシスタントに伝えます。

conversationを埋めるためだけに、関係のないprivate memoryをアシスタントに開示させないでください。

## XMemoの接続を解除した後、古いアシスタントが使えないことを確認するには？

アシスタントからconnectionを削除しましたが、まだmemoryにアクセスできるのか不安です。

appからconnectionを削除しても、accountのconnection permissionが取り消されるとは限りません。

XMemo accountのconnected-appまたはsecurity controlを開き、古いassistant connectionをrevokeして、信頼するものだけを再接続します。

削除するconnectionだけをrevokeし、accountのサインイン情報は共有しないでください。

## なぜAIアシスタントでXMemoを使えなくなったのですか？

以前はassistantでXMemoを使えたのに、memory actionが表示されなくなったか、使えないと表示されます。

アシスタントのXMemo connectionを更新する必要があるか、別のaccountにサインインしている可能性があります。

assistantのconnected-app settingを開き、XMemoをdisconnectしてからreconnectし、新しいchatを開始します。

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に確認します。

local development addressを使ったり、public chatにprivate credentialを貼り付けたりしないでください。

## AIアシスタントがまだXMemoに接続できない場合はどうすればよいですか？

connection手順を再試行しても、アシスタントでXMemoを使えません。

問題がassistant app、account、またはpublic instructionでは調査できない古いconnectionにある可能性があります。

assistant名、おおよその時刻、確認した内容の短い説明をSupportに送り、詳細はredactしたものだけを含めます。

サインイン情報、one-time code、cookie、private memory textは決して送らないでください。

## 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をもう一度承認します。

古い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を変えずに同じ操作を再試行します。

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をもう一度実行します。

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を一定に保ちます。

実際の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で送信します。

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を再試行します。

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で操作を繰り返します。

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します。

意図した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 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内に保ちます。

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します。

意図した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として扱います。

動作する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から始めます。

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を保存します。

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に伝えます。

redacted diagnosticだけを共有し、bearer token、OAuth code、cookie、customer memory contentは決して送らないでください。