ナレッジベースガイド

ユーザーの目標

個人またはチームのワークスペースで構造化されたナレッジベースを維持し、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." を入力します。作成を確認してアクティブなベースを初期化します。

# 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" で初期化されます:

## 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 など) の承認されたエージェントは、公開されたランブックをクエリできます。このツールは、明示的な引用参照ポインタを含むランク付けされた抜粋を返します:

# 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." と表示されます:

## 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) — 引用エンベロープと作成者の帰属。