ナレッジベースのしくみ

ナレッジベースには、AI があなたの事業について知っておくべきで、メールそのものからは学べないことを入れます。価格、ポリシー、営業時間、製品情報、そしてチームの答え方などです。メモ、ファイル、ウェブページを追加すると、AI はあなたの代わりに書くたびに、関係のある部分を読みます。

ストアはワークスペースごとに 1 つで、レベルは 3 つです。1 つのブランドや 1 つのチームにだけ当てはまる答えは、そこにとどまります。アプリの「ワークスペース → ナレッジベース」、REST API、SDK と CLI、そしてアシスタントと MCP クライアントから読み書きできます。

各項目は 1 つのレベル、つまり scope にあります。アドレスのために書く AI は、そのアドレス、次にそのドメイン、次にワークスペース全体を読み、2 つの項目が食い違うときはより具体的なほうが優先されます。

• —プラスアドレスは元のアドレスも読みます。たとえば [email protected] は、[email protected] 用に保持された内容を使います。
• —GET /knowledge/levels は、見えるすべてのレベルと、それぞれの項目数、そこで項目を変更できるかどうかを一覧にします。
• —ドメインを別のワークスペースに移すと、そのドメインとそのアドレス用の項目も一緒に移ります。

• —メモはその場で書くテキストで、最大 20,000 文字です。Markdown も使えます。たいてい 1、2 秒で AI が使えるようになります。
• —ファイルはバックグラウンドでテキストとして読み取られます。PDF、Word 文書、スプレッドシート（Excel、OpenDocument、Numbers、CSV）、OpenDocument テキスト、HTML、XML、Markdown、プレーンテキスト、JSON、画像（JPEG、PNG、WebP、SVG）に対応します。文書は最大 20 MB、画像は最大 10 MB です。
• —ウェブページは公開の http または https アドレスから取得され、最大 5 MB までバックグラウンドで読み取られます。1 つのレベルに同じページは 1 回だけ入り、更新すると変更後のページを取得し直します。
• —1 つの項目から保持するテキストは最大 1,000,000 文字で、検索のために見出しごとの箇所に分けられます。

項目は読み取り中は queued、続いて processing、AI が使えるようになると ready、読み取れなかったときは理由を示す failure 付きの failed になります。変更した項目は queued に戻り、新しいテキストの準備ができるまで AI は前のテキストを使い続けます。更新すると項目を読み直し、失敗も消えます。

• —スレッドの最新メッセージの下にある返信の提案は、メッセージが届いたアドレスのレベルを読みます。
• —説明から書く下書きは、エディタでも POST /emails/compose でも、送信元アドレスのレベルを読みます。応答の sources には、参考にした項目が並びます。
• —アシスタントは開いているスレッドのレベルを、何も開いていなければ見えるすべてのレベルを読みます。また、searchKnowledge ツールでナレッジベースを自分で検索できます。
• —GET /threads/{id}/reply-suggestions の応答は、提案の根拠になった項目を sources に挙げます。

ピン留めしたメモは、書いている内容と合うかどうかにかかわらず、そのレベルのすべてのプロンプトに入ります（各レベル最大 2,000 文字）。残りの枠、全体でおよそ 6,000 文字は、意味と語句の両方で探した、依頼にいちばん合う箇所に使われます。インデックスがすぐに応答しないときは、待たせずにそれなしで書きます。

項目はアプリの「ワークスペース → ナレッジベース」で、またはコードから API、SDK、CLI で追加します。アシスタントと MCP クライアントは、何かを覚えておくよう頼むとメモを保存したりリンクを追加したりでき、項目の変更、更新、削除もできます。アプリのチャットでは、項目の追加、変更、更新は依頼していない場合に先に確認し、削除は必ず先に確認します。

各項目は、どこから来たかを origin（app、api、assistant、mcp）に、誰が追加したかを createdBy に記録します。

ナレッジベースはひとりでにも育ちます。AI はチームが送った返信からメモを提案し、まだ何も答えていない質問を書き留めます。コネクタはサイト全体、サイトマップ、フィード、ヘルプセンターを最新に保ち、リンクは決まった間隔で読み直せます。以下の各節でそれぞれを説明します。

ワークスペースの誰かが会話で返信すると、AI はその返信と、返信先のメッセージを読み、ほかの人にも当てはまる事実を最大 3 つ提案します。たとえば価格、ポリシー、配送日数などです。各提案はレビュー待ちのメモで、返信を送ったドメインのレベルに置かれます。そのドメインがワークスペースのものでない場合は、ワークスペース全体のレベルです。ナレッジベースにすでにある事実は除かれ、1 日に読む返信は最大 100 件です。

アプリか GET /knowledge/suggestions で確認します。提案を受け入れるとメモとして保存され、その際にタイトル、テキスト、レベル、ピン留めを変更できます。不要なら却下します。同じ事実が再び提案されると、2 つ目の提案は作られず occurrences が増えます。却下した提案は二度と出てきません。

受信したメッセージへの返信を AI が提案するとき、送信者が事業について尋ね、会話にもナレッジベースにも答えがないことを最大 3 つ書き留めます。たとえば、その国へ発送しているかどうかなどです。それぞれが、メッセージが届いたドメインのレベルの質問になります。そのドメインがワークスペースのものでない場合は、ワークスペース全体のレベルです。同じ質問が再び来ると occurrences が増えるので、よく出る質問がわかります。

質問に答えると、それがメモになります。答えをテキストにして受け入れると、変更しない限りタイトルは質問のままです。以後、その質問が出るたびに AI はその答えを使います。答えが要らない質問は却下すれば、二度と書き留められません。

各項目は、インデックス作成時にすべてのレベルのいちばん近い項目と比べられ、変更されるたびに比べ直されます。ほとんど同じことを述べる 2 つの項目には duplicate のフラグが付きます。価格や期限など、ある事実について食い違う密接な 2 つの項目には conflict のフラグが付き、何が食い違うかを 1 文で示します。AI は矛盾を 1 日に最大 200 回チェックします。

• —各項目は、自分を名指しする未解決のフラグの数を flags に持ちます。GET /knowledge/flags はそれらを新しい順に挙げます。
• —フラグを解決するには、2 つの項目のどちらかを変更するか削除します。変更した項目は、インデックスが済むと比べ直されます。
• —2 つの項目がそのままで問題なければフラグを却下します。同じ組み合わせが同じ理由でフラグを付けられることはもうありません。
• —フラグは、両方の項目を見られる人にだけ表示されます。

コネクタは、1 つのソースの多数のページをナレッジベースに置きます。各ページはコネクタのレベルのリンク項目になり、ソースが変わると最新に保たれます。

• —最初の同期は 1 分以内に始まります。その後は 7 日ごと、または 1 日か 30 日ごとに同期し直します。依頼したときだけ同期することもでき、その同期も 1 分以内に始まります。
• —保持するページは最大 25 件、または指定した数 (最大 200 件) で、その項目はプランの上限に数えられます。上限に達すると、同期はページの追加をやめます。
• —同期のたびに新しいページが追加され、変わったページは読み直され、ソースからなくなったページの項目は削除されます。
• —同じレベルに自分でリンクとして追加したページはその項目のまま残り、コネクタを削除しても、そのコネクタが追加した項目だけが消えます。
• —コネクタを別のレベルへ移すと、その項目も一緒に移ります。

リンクは 1 日、7 日、30 日ごとに自動で読み直せます。追加するときか後で refreshDays を設定します。ページが変わっていれば、読み取った時点で新しいテキストが古いものに置き換わり、それまでは AI が古いテキストを使い続けます。次に読む日時は nextRefreshAt でわかり、取得できなかったページは翌日にもう一度試されます。

AI は会話を読み、チームがまた必要とする事実を 1 つのメモに下書きできます。個人情報や、その会話だけに関わることは除かれます。保存するまでは何も残りません。下書きを読み、好きなように直してメモとして保存すると、元の会話が threadId に記録されます。

下書きはレベルを提案します。会話が届いたドメインに項目を追加できるならそのドメイン、そうでなければワークスペース全体かそのアドレスです。下書き 1 回ごとに AI アクションを 1 回分使います。コードからは、knowledge:write に加えて threads:read が必要な POST /knowledge/drafts で下書きし、同じ threadId を付けて POST /knowledge/notes で保存します。

検索は意味と語句の両方で箇所を探します。POST /knowledge/search に rerank: true を付けて送ると、AI が上位 25 件の箇所も読み、質問にいちばんよく答える順に並べ、役に立たないものは外します。1、2 秒長くかかり、AI アクションを 1 回分使うため、依頼したときだけ行われます。行われたかどうかは応答の reranked でわかり、時間内に終わらなかった場合、箇所はいつもの順のままです。

GET /knowledge/stats は、過去 30 日間 (指定すれば最大 90 日間) に AI がナレッジベースをどう使ったかを示します。

• —返信の提案、下書き、アシスタント、検索が何かを見つけた回数、探して何も見つからなかった回数、何かが見つかった割合を日ごとに示します。
• —利用があった場所: compose、reply、chat、tool、search。
• —よく使われた項目と、準備ができているのに一度も使われていない項目の数。各項目は自分の回数を uses に、最後に使われた日時を lastUsedAt に持ちます。
• —レビュー待ちの提案と質問の数、未解決のフラグの数。

ワークスペースの設定 knowledgeLearning は既定でオンです。PATCH /settings と { "knowledgeLearning": false } でオフにすると、AI は提案する事実を探して送信済みの返信を読むこと、受信メールから質問を書き留めること、項目の矛盾をチェックすることをやめます。重複には引き続きフラグが付き、すでに出ている提案は受け入れか却下のために残ります。

• —読み取りには knowledge:read、変更には読み取りを含む knowledge:write が必要です。組み込みのロールでは Admin、Member、Developer が項目を変更でき、Viewer は読むことができ、Billing は届きません。
• —項目を変更するには、そのレベルが対象とするすべてのアドレスに届く必要があります。ワークスペース全体にはすべてのアドレスが、ドメインにはドメイン全体が、アドレスにはそのアドレスが必要です。特定のアドレスに限定されたキーやアプリは、それらのアドレス、または丸ごと持つドメインでしか項目を変更できません。
• —特定のアドレスに限定された人は、ワークスペース全体の項目と、自分のアドレスとそのドメインの項目を読みます。その人のために動くアシスタントと MCP ツールが項目を追加・変更できるのは、その人が送信できるアドレスだけです。

• —各項目のテキストは保存時に暗号化されます。メモの本文、ファイルやページから読み取ったテキスト、そしてすべての箇所です。語句による検索で照合する語句は、語句そのものではなく鍵付きハッシュとして保存されます。
• —ファイルはテキストに変換され、ウェブページは OpenEmail が読み込みます。お客様のデータを処理するすべてのサービスは、プライバシーポリシーに記載しています。
• —意味で検索するため、各パッセージと各質問は、内容を表す数値のリストであるベクトルに変換されます。ベクトルは、メールの意味検索と同じく、暗号化されたテキストの横に暗号化せずに保存されます。
• —プロンプトが使う箇所は、プロンプトのほかの部分と同じく、返信、下書き、回答を書く AI モデルに送られます。
• —項目を削除すると、そのファイル、テキスト、箇所がまとめて消えます。ナレッジベースはワークスペースのエクスポートに含まれ、ワークスペースを削除するとナレッジベースも削除されます。
• —学習がオンのあいだ、AI モデルはメモを提案するために、会話で送られた各返信を返信先のメッセージと一緒に読みます。また、密接な 2 つの項目を読んで矛盾がないかをチェックします。設定 knowledgeLearning で両方をオフにできます。

ここまでの内容はすべて、REST API の /knowledge、SDK の openemail.knowledge（TypeScript）と client.knowledge（Python、Ruby、PHP）、CLI の openemail knowledge、そして MCP ツールで使えます。キーには、読むために knowledge:read、項目を変更するために knowledge:write が必要です。