# ナレッジベースガイド

ナレッジベースを作成し、技術ドキュメントをアップロードし、バージョン管理されたアイテムを公開して、エージェントが来歴付きの引用された事実を取得できるようにします。

- Canonical: https://docs.xmemo.dev/ja/docs/guides/knowledge-bases
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: 1867d8b68c37e8f52cb96a448217aeea61bf2b42608d8931313472d77f22d9c6
- Edition-Digest: 8922403c1df21e7d5740dc55b2a91c0b227e88c8f9c3f35ce6b6480de825b117
- Source-Revision: sha256:c0d24fff7e465ea3dbb6daf903fbcba1cab87eecc6514e3b935a312cafc20ddd

## ユーザーの目標

個人またはチームのワークスペースで構造化されたナレッジベースを維持し、Markdown やフォーマットされたドキュメントを取り込み、検証された不可変リビジョンを公開して、自律型エージェントが出典帰属付きで引用された事実を取得できるように構成します。

## 利用資格と前提条件

ナレッジベースの作成と検査は、アカウントで Knowledge が有効化されている場合、Web コンソールの https://xmemo.dev/me#knowledge (個人ワークスペース) または https://xmemo.dev/me?space=<team_id>#knowledge (チームワークスペース) で利用できます。開始する前に、次の前提条件を確認してください:

- 認証要件: アクティブなユーザーセッションが必要です。未認証のアクセスは /login (サインインページ) にリダイレクトされます。
- トークンスコープ: プログラムによるアクセスには、検索および個別読み取り用の knowledge:read と、アイテムの作成または編集用の knowledge:write が必要です。
- サポートされているファイル形式: ブラウザ内のテキスト/コードリーダーは、.md、.markdown、.txt、.json、.csv、.py、.js、.ts、.tsx、.html、.yaml、.yml、および .toml をサポートしています。ドキュメント抽出は、.pdf、.docx、.pptx、および .xlsx をサポートしています。
- ドラッグ＆ドロップインターフェース: コンソールには "Drag & drop files here" と、補足テキスト "Supports PDF, Word, PowerPoint, Excel, Markdown, and text files (.pdf, .docx, .pptx, .xlsx, .md, .txt, .csv, .json, etc.)" が表示されます。

## 1. Web コンソールでナレッジベースを作成する

ブラウザで https://xmemo.dev/me#knowledge に移動します。"Create Knowledge Base" をクリックして作成ダイアログを開きます。Name に "Engineering Runbooks" を入力し、Description に "Operational runbooks and deployment procedures." を入力します。作成を確認してアクティブなベースを初期化します。

```bash
# Access personal knowledge workspace
https://xmemo.dev/me#knowledge

# Access team knowledge workspace with explicit space parameter
https://xmemo.dev/me?space=<team_id>#knowledge
```

## 2. 合成ナレッジアイテムを追加して公開する

新しく作成された "Engineering Runbooks" ベースを開き、"Create Knowledge item" をクリックして Markdown またはローカルファイルからエントリを作成します。Title に "Deployment Guidelines" を入力し、初期の合成手順を貼り付けます。アイテムはステータス "draft" で初期化されます:

```markdown
## Deployment Guidelines

Production deployments require two peer approvals, clean migration dry-runs, and verified canary health.
```

## 3. エージェント取得用に下書きアイテムを公開する

ステータスが "draft" の間、アイテムは人間の編集者にのみ公開されたままです。エージェントが発見できるようにするには、"Publish" をクリックします。コンソールには "Published content becomes eligible for authorized Knowledge search." というヒントが表示されます。確認されると、アイテムはステータス "published" に進み、リビジョン 1 が現在の検索可能なリビジョンとして確立されます。

- 下書きのプライバシー: 下書きアイテムはエージェントの検出およびクエリ検索から除外されます。
- 公開アクション: 公開すると、アイテムのステータスが "published" に更新され、current_revision_id がリビジョン 1 に設定されます。
- 不可変リビジョン: リビジョン 1 の正規コンテンツ、ハッシュ、およびメタデータは不可変に保持されます。

## 4. エージェントの引用付きで知識を取得する

search_knowledge を公開しているクライアント環境 (cursor-plugin や ordinary-full など) の承認されたエージェントは、公開されたランブックをクエリできます。このツールは、明示的な引用参照ポインタを含むランク付けされた抜粋を返します:

```bash
# Query knowledge via standalone Skill CLI
node scripts/xmemo-skill.mjs recall-context --query "production deployments" --include_knowledge true
```

## 5. コンテンツを更新して不可変な新規リビジョンを公開する

技術的な手順が変更されたら、"Deployment Guidelines" を開き、"Edit Knowledge item" をクリックします。新しい運用要件を反映するようにコンテンツを更新します。"Save new revision" をクリックします。コンソールには "Saving content creates an immutable new revision. Metadata changes do not create a revision." と表示されます:

```markdown
## Deployment Guidelines

Production deployments require two peer approvals, clean migration dry-runs, verified canary health, and automated smoke verification.
```

## 観察可能な結果

Web コンソールおよびエージェント検索を通じて、公開されたアイテムとそのリビジョンの来歴を確認します:

- コンソールバッジ: アイテムカードにステータスバッジ "Published" が表示され、現在のアクティブなリビジョンが示されます。
- リビジョン系統: "Revision history" を開くと、リビジョン 2 が現在、リビジョン 1 が過去の履歴として表示され、タイムスタンプと作成者の帰属が示されます。
- エージェント検索結果: クエリ検索ではリビジョン 2 のみが評価されます。過去のリビジョン 1 は、正確な knowledge_revision_id を指定した個別読み取りによって引き続きアクセスできます。

## エージェントがアクセスできる範囲

ナレッジベースは、エージェント統合に対して厳格なアクセスおよび可視性の境界を強制します:

- 公開アイテムのみ: エージェントは下書きアイテムにアクセスできません。クエリ検索ではアクティブなベース内の公開アイテムのみが評価されます。
- 現在リビジョンの境界: クエリ検索は自動的に current_revision_id に解決されます。置き換えられたリビジョンはクエリ検索結果に表示されません。
- プロファイルの可用性: 読み取り専用 MCP ツール search_knowledge は、cursor-plugin および ordinary-full クライアントプロファイルにおいて厳密に利用可能です (config/mcp-documentation-contract.json)。他のクライアントプロファイルでは recall_context を利用し、有効かつ承認されている場合は Knowledge が自動的に含まれます。
- リコールの動作: MCP recall_context は、アカウントで Knowledge が有効化されており、トークンに knowledge:read が含まれている場合、Knowledge を自動的に含めます。すべての recall が Knowledge を検索するわけではありません。

## 共有とストレージの境界

ナレッジベースは、厳格な空間分離と管理ロールの境界を維持します:

- 個人スペースとチームスペースの比較: 個人ベース (/me#knowledge) はアカウントに対してプライベートです。チームベース (?space=<team_id>#knowledge) はチームロールのアクセスを強制します (routes/knowledge.py:129-134)。
- ロールの機能: Owner および Admin は base:admin と item:write の権限を保持します (ベースとアイテムの作成、アーカイブ、更新、削除)。Member は item:write 権限を保持します (アイテムの作成、編集、公開)。Viewer は読み取り権限のみを保持します。
- アーカイブと完全削除の比較: アーカイブ ("Are you sure you want to archive knowledge base '<name>'? Archived bases will no longer be retrieved by agents.") は損失なしに検索を停止します。完全削除 ("Are you sure you want to permanently delete knowledge base '<name>' and all its items? This action cannot be undone.") はデータを物理的に削除します。
- プロジェクトメモリの独立性: ナレッジベースは、プロジェクトの作業メモリ/ナレッジメモリパーティションから独立して動作します。プロジェクトからメモリのリンクを解除しても、ナレッジベースのドキュメントには影響しません。

## 障害復旧

次の診断手順を使用して、ナレッジベースの一般的なアクセスおよび抽出の問題に対処します:

- ドキュメント抽出の進行中: .pdf、.docx、.pptx、または .xlsx ドキュメントをアップロードする場合、"Extraction is still in progress. Try again when it succeeds." と表示されている間はお待ちください。
- ドキュメント抽出の失敗: 処理が失敗した場合、コンソールに "Extraction failed. Retry the Document from its existing Document surface first." と表示されます。ファイルの整合性を確認するか、プレーンな Markdown テキストをアップロードしてください。
- エージェントクエリでアイテムが返されない: アイテムのステータスが "Published" ( "draft" ではない) であること、ベースがアクティブ (アーカイブされていない) であること、およびクライアントトークンに knowledge:read スコープが含まれていることを確認してください。
- 同時更新の競合: 編集を開いている間に別のユーザーまたはエージェントがアイテムを更新した場合、コンソールに "This Knowledge item changed elsewhere. Refresh it and try again." と表示されます。ページを更新して変更を再適用してください。
- 検索モードの選択: ハイブリッド検索で正確なランブックシンボルや構成キーが見落とされる場合は、正確なトークン照合を行うためにレキシカルモード (mode="lexical") に切り替えてください。

## 関連リファレンス

ナレッジベースの概念、関連ツール、およびワークスペース管理について引き続き確認してください:

- 概念: ナレッジベース (/docs/concepts/knowledge-bases) — アーキテクチャモデル、リビジョン DAG、および検索モード。
- ツール: search_knowledge (/docs/tools/search-knowledge) — 個別読み取りおよび検索パラメータのツールリファレンス。
- ツール: recall_context (/docs/tools/recall-context) — Knowledge の自動取得を含むコンテキストパッキングツール。
- ガイド: Memory Console (/docs/guides/memory-console) — Web コンソールの完全なナビゲーションガイド。
- 概念: 来歴と帰属 (/docs/concepts/provenance-attribution) — 引用エンベロープと作成者の帰属。

## 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 が起動ごとに再生成していないことを確認します。