# エージェントインスタンスのアイデンティティ

帰属に使う秘密ではないインストールラベルと、リクエストを認可する資格情報を分離します。

- Canonical: https://docs.xmemo.dev/ja/docs/concepts/agent-instance-identity
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: c0db15eaca6541c974e88179495cf7a7f5832695889a2ff2abef284fd7daf337
- Edition-Digest: 65e512f0b7acd3e72d594b8d21c843b9196d2b075f20c966b2a3671bc7a491f6
- Source-Revision: sha256:af573969af4a97ad87f12425b51f333259b42a829512f8644875a77c1bba2ddb

## instance idはcredentialではありません

XMEMO_AGENT_INSTANCE_IDは、ローカルのclientまたはrunner instanceを識別しますが、リクエストを認可するものではありません。API keyまたはOAuth grantがアクセスcredentialです。サーバーはinstanceの値からagent_instance_id_hashを導出し、境界の権限をattribution_onlyとして報告します。

- Credential: X-API-Keyまたは認められたOAuth bearer grantがアクセスを制御します。
- Instance label: X-Memory-OS-Agent-Instance-IDで、書き込みを行ったrunnerと後続の呼び出し元をサーバーが比較できます。
- Agent label: X-Memory-OS-Agent-IDで、1つのインストールとは別に論理的なagentを識別します。

## 正規化してからハッシュする

runtimeはinstance idの前後の空白を除去し、空の値を拒否します。256文字以内の値を受け付け、SHA-256でハッシュします。保存されるhashはsha256:<64個の16進文字>に正規化されます。形式が不正な事前ハッシュ値はcredentialとして扱わず無視します。

```python
from memory_manager.auth.agent_identity import agent_instance_id_hash

instance_hash = agent_instance_id_hash("codex-local-install")
# sha256:<64 hexadecimal characters>
```

## ローカルインストールごとに1つの値を保つ

アクセスcredentialとは別に、秘密ではないinstance valueをリポジトリの外へ保存して送信します。同じインストールでは再起動後も再利用し、別のlocal profileには別の値を選びます。

```http
X-API-Key: <your-assigned-api-key>
X-Memory-OS-Agent-ID: codex
X-Memory-OS-Agent-Instance-ID: <stable-local-instance-id>
```

## 境界の意味を明示する

memory_agent_boundaryは、呼び出し元のagent_idとinstance hashを行の値と比較します。両方が一致すればself、agent_idは一致するが別のhashならsame_agent_other_instance、比較できるidentityがなければunverifiedまたはunknownとして報告します。これらのラベルは帰属を説明するものであり、tokenによる認可に取って代わるものではありません。

```json
{
  "relation": "self",
  "ownership": "current_agent",
  "boundary_authority": "attribution_only",
  "current_agent_trust": "client_asserted"
}
```

## ChatGPT ユーザー

bearer token をチャットに貼り付けずに、ChatGPT が XMemo の設定、プロジェクト事実、意思決定、TODO に永続的にアクセスできるようにします。

ChatGPT/OpenAI app の OAuth フローで hosted XMemo MCP server に接続し、XMemo アカウントに memory:read と memory:write の許可を承認します。

合成の設定またはプロジェクトメモを保存し、新しいチャットを開始してから、作業を続ける前に ChatGPT に XMemo 経由でそれを呼び出させます。

OAuth が失敗する、またはツールが表示されない場合は、direct token を作成する前に、ホストアプリで MCP server からサインアウトし、XMemo server URL を再接続して再試行します。

## Copilot / Codex 開発者

リポジトリの判断、コーディング規約、バグ修正メモ、タスク履歴を IDE と CLI エージェント間で持ち運べます。

利用可能な場合は、VS Code / GitHub Copilot および Gemini CLI に OAuth を使用してください。Copilot CLI、Codex、Cursor、またはその他の直接 MCP クライアントの場合は、XMEMO_KEY をローカル環境またはシークレットストアに保持し、安定した XMEMO_AGENT_INSTANCE_ID を設定してください。

コードベースの判断またはバグ修正を記録し、次の IDE または CLI エージェントに、編集前に関連する XMemo コンテキストを呼び出させます。

呼び出し結果が空の場合は、選択した MCP 設定パス、direct client 用の XMEMO_KEY 環境変数、ホストアプリ内の古い OAuth 認証情報を確認します。

## チーム / エンタープライズ pilot owner

アカウント制御、ソース attribution、エクスポート/削除ワークフロー、レビュー担当者向けに安全な設定証跡で共有メモリを評価します。

保護された XMemo workspace を作成または開き、承認済みユーザーを招待してから、readiness badges に従って OAuth またはスコープ付き direct credential で各クライアントを接続します。

pilot メンバーに合成のチームメモリを保存してもらい、XMemo でソース attribution を確認し、削除/エクスポートとサポート経路をレビューします。

メンバーが接続できない場合は、新しい token を発行する前に、ロール権限、OAuth 承認、クライアント readiness 状態、サポートガイダンスを確認します。

## 自律エージェント operator

headless またはスケジュール済みエージェントが進捗を記録し、過去の判断を取得し、安定した非秘密のインスタンス ID を保持できるようにします。

/api/v1/mcp/config/autonomous-agent を取得します。runner が OAuth + custom headers をサポートする場合は auth_modes.oauth を優先し、完全 headless runner の場合のみ secret store の XMEMO_KEY で auth_modes.xmemo_key を使います。

XMemo に進捗を書き込む合成タスクを 1 つ実行し、runner を再起動して、同じ XMEMO_AGENT_INSTANCE_ID でその進捗を呼び出せることを確認します。

attribution が変わる、または呼び出し結果がインスタンス間で分かれる場合は、XMEMO_AGENT_INSTANCE_ID を git の外に永続化し、runner が起動ごとに再生成していないことを確認します。