# ナレッジベース

構造化された知識をimmutable revisionで保持し、公開されたcurrent contentまたは引用付きの正確な過去のバージョンを取得します。

- Canonical: https://docs.xmemo.dev/ja/docs/concepts/knowledge-bases
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: 6abd27813899cf8de3d349ccd4016d92fe96f6b1cca4e84f29dab16a78c512a4
- Edition-Digest: 80c947a9b3331009f72f4f7bcf729ca3b4b8a1101259023fb68945da919d5f80
- Source-Revision: sha256:fd48f8faf2e2fd5083059df93e298741fed8b459995a58140a2b3724b315e545

## Base、Item、および Revision のアーキテクチャ

Knowledge Base は、owner-scoped または team-scoped の参照ドキュメント、仕様、およびランブックのコレクションです。技術的知識を 3 つの明確な階層エンティティに整理します。

- Knowledge Base: 最上位コンテナ（「Engineering Runbooks」など）。Base には名前、説明、ステータス（active または archived）、およびスペース所有権（Personal または Team）があります。
- Knowledge Item: Base 内の個別のドキュメントまたはガイドライン（「Deployment Guidelines」など）。Item にはタイトル、ロケーター、ステータス（draft、published、または archived）、ソース種別（user_created または file）、および current_revision_id ポインターがあります。
- Knowledge Revision: カノニカルコンテンツ、リビジョン番号、コンテンツフォーマット（markdown など）、コンテンツハッシュ、ソースメタデータ、および provenance を含む immutable スナップショット。
- 公開ライフサイクル: Item は draft ステータスから始まります。公開（publish）されると、その current revision が agent から検出可能になります。その後の編集では、過去のリビジョンを変更することなく、immutable な新しいリビジョンが作成され、current ポインターが進められます。

## 公開境界と Agent の可視性

Knowledge Base は、人間の執筆と自律型 agent による取得の間に厳格な公開境界を適用します。呼び出し元は query search と addressed read のいずれかを選択します。Query search は、現在の active なリビジョンにある公開済み item のみを評価することで鮮度を保護します。

- Active な Base のみ: アーカイブ（archived）された Base は agent の検出対象から除外されます。アーカイブすると、コンテンツを破棄することなく、含まれるすべての item の取得が中断されます。
- 公開済み Item のみ: 下書き（draft）の item は、明示的に公開されるまで作成者およびチーム編集者に対して非公開のままとなります。Agent は query search で draft item を検出したり引用したりすることはできません。
- デフォルトで Current リビジョン: Query search は current_revision_id によって参照されるリビジョンのみを評価します。置き換えられた過去のリビジョンが query search 結果として表示されることはありません。
- Addressed read: Addressed read では、knowledge_item_id とともに knowledge_revision_id を指定することで正確な過去のリビジョンを検査でき、再現可能な引用が保持されます。

```text
query search       -> active base + published item + current_revision_id
addressed (no pin) -> published item's current revision
addressed (pinned) -> exact immutable revision (e.g. knowledge:<item-id>@<revision-id>)
```

## 取得モード: Hybrid、RRF、Semantic、および Lexical

検索ランタイムは、語彙の精度と意味的理解のバランスを取るために 4 つの取得モードをサポートしています。

- hybrid（デフォルト）: パラメーター alpha（デフォルト 0.5）を使用した正規化された語彙スコアと意味スコアの線形結合。alpha が 1 に近いほど完全な語彙の一致が優先され、0 に近いほど概念的な意味の類似性が優先されます。ベクトルスコアが利用できない場合は lexical にフォールバックします。
- rrf（Reciprocal Rank Fusion、逆順位融合）: ランク定数 k（デフォルト 60）を使用して独立した語彙および意味のランク付けリストを融合し、スコアのキャリブレーションを必要とせずにバランスの取れた順序を保証します。
- semantic: 埋め込み表現に基づくベクトル類似度ランキング。埋め込みが構成されていない場合は語彙マッチングにフォールバックします。
- lexical: 正確なシンボル、関数名、エラーコード、および構成キーに最適化された正規化トークンおよびフレーズマッチング。

## サポートされているファイルタイプとアップロードパイプライン

Knowledge item は、Markdown で直接作成することも、2 つの異なる取り込みメカニズムを介してローカルファイルからインポートすることもできます。

- ブラウザで読み取るテキストおよびコードファイル: プレーンテキストおよびコードファイル（.md、.markdown、.txt、.json、.csv、.py、.js、.ts、.tsx、.html、.yaml、.yml、.toml）はブラウザで直接読み取られ、カノニカルな Markdown コンテンツとして保存されます。
- ドキュメント抽出パイプライン: フォーマットされたドキュメント（.pdf、.docx、.pptx、.xlsx）は Documents API を介してアップロードされ、テキスト抽出ワーカーによって処理され、抽出が成功すると Knowledge item としてスナップショット化されます。
- ファイルの境界: 取り込みの境界は、クライアント環境とサーバー環境全体に適用されます。信頼性の高い処理を行うには、知識をモノリシックなファイルダンプではなく、焦点を絞ったモジュール化されたドキュメントに整理してください。

## Agent アクセスインターフェースとクライアントプロファイル

認可された agent は、専用の MCP ツールとスタンドアロンの Skill コマンドを介して Knowledge にアクセスします。

- MCP search_knowledge: knowledge:read トークンスコープを必要とする専用の読み取り専用検索ツール。特に cursor-plugin および ordinary-full クライアントプロファイル（config/mcp-documentation-contract.json）で公開され、chatgpt-public または generic-public プロファイルでは公開されません。
- MCP recall_context: アカウントで Knowledge が有効になっており、トークンに knowledge:read が含まれている場合、エピソード記憶とともに適切な Knowledge item を自動的に含めます。
- スタンドアロン XMemo Skill: 明示的な知識の包含を伴って recall-context を実行します: node scripts/xmemo-skill.mjs recall-context --query "api authentication" --include_knowledge true。
- スコープの強制: すべての recall が自動的に Knowledge を照会するわけではありません。取得は、構成され、トークンスコープで許可され、アクティブなクライアントプロファイルによってサポートされている場合にのみ発生します。
- REST コンパニオン: 認証されたコンパニオンエンドポイント POST /api/v1/knowledge/search は、バックエンドサービスおよびカスタムツール向けに知識検索への直接のプログラムアクセスを提供します。

```json
{
  "type": "knowledge_search",
  "results": [
    {
      "knowledge_item_id": "item_runbook_deploy",
      "knowledge_revision_id": "rev_v2_deploy_runbook",
      "title": "Production Deployment Runbook",
      "content": "Production deployments require two peer approvals, clean migration dry-runs, and verified canary health.",
      "reference": "knowledge:item_runbook_deploy@rev_v2_deploy_runbook",
      "score": 3.84
    }
  ]
}
```

## チームロール、スペース、およびライフサイクル操作

Knowledge Base は、ロールベースのアクセス制御を備えた個人用およびコラボレーション用ワークスペースをサポートします。

- ロールの機能: Owner と Admin は base:admin および item:write 権限を保持します（Base と Item の作成、アーカイブ、更新、削除）。Member は item:write 権限を保持します（Item の作成、編集、公開は可能ですが、Base の削除やアーカイブは不可）。Viewer は読み取り専用権限を保持します。
- スペースの境界: Personal スペース（/me#knowledge）は所有者専用です。Team スペース（?space=<team_id>#knowledge）は、認証されたチームメンバー間で公開ドキュメントを共有します。
- アーカイブと完全削除: Base をアーカイブするとステータスが archived に設定され、完全な復元を可能にしながら、agent のクエリからすべての item が即座に除外されます。完全削除は、Base と関連するすべてのリビジョンを不可逆的かつ物理的に破棄します。

## プロジェクト記憶との違い

Knowledge Base は精選された参照ドキュメントを提供し、対話型のプロジェクト記憶とは異なる保証の下で動作します。

- Knowledge Base item: 複数リビジョンの履歴と正確な引用参照（knowledge:<item-id>@<revision-id>）を備えた、精選されたバージョン管理付き参照ドキュメント（ランブック、設計ドキュメント、コーディング標準など）。
- プロジェクトの Knowledge/Working 記憶: プロジェクトワークスペース内で、永続的なコンテキスト（knowledge）と一時的なタスク状態（working 記憶）として分類される対話型の記憶レコード。
- 独立性: プロジェクトから記憶レコードを削除したりドキュメントのリンクを解除したりしても、基盤となる Knowledge Base item が変更、アーカイブ、または削除されることはありません。

## 可用性とランタイムの有効化

Knowledge Base は Preview ではなく、コア機能として記載されています。アカウントで Knowledge が有効になっている場合、可用性はアクティブです。バックエンドの知識ランタイムが構成されていないか無効になっている場合、リクエストはコード knowledge_runtime_disabled とともに HTTP 503 を返します。カタログプランの指定（Plus ティアの割り当てなど）は、ランタイムの強制メカニズムではなくプランの許容量を表します。プランティアを強制する API ルートはありません。

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