ナレッジベース

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 を指定することで正確な過去のリビジョンを検査でき、再現可能な引用が保持されます。

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 は、バックエンドサービスおよびカスタムツール向けに知識検索への直接のプログラムアクセスを提供します。

{
  "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 ルートはありません。