ナレッジベース

概要

ナレッジベースはデータを構造化されたナレッジグラフに変換するドメイン非依存のシステムです。AIエージェントは会話中にこのグラフを検索して、ハルシネーション（幻覚）ではなく正確で根拠のある応答を提供します。

そしてマルチプレイヤーです。エージェントは会話中に学んだことをプロジェクトKBに自律的に書き戻すことができ、他のすべてのエージェントが次のセッションでそれを読み取ります — 人間の組織記憶と同じように複利で蓄積される、閉じたループの会社のブレインです。さらに、チームを担当する単一のエージェントはユーザー間で属性付きメモリを保持できるため、ユーザーBと話して得たコンテキストでユーザーAに応答できます。詳細は ウィズダム（Wisdom）と共有メモリ（Shared Memory） を参照してください。

プロジェクト（あなたのテナント）
                            |
 +--------------------------+--------------------------+
 |                          |                          |
 v                          v                          v
エージェント A             エージェント B             エージェント C
 |                          |                          |
 |--- 検証済み事実を ------+                          |
 |    書き込む              |                          |
 |                          |                          |
 |                  読み取り + 応答を裏付け            |
 |                          |                          |
 |                          +--- 事実を更新 ----------->|
 |                                                     |
 |                                          強化された事実を読み取り
 v                          v                          v
ユーザー X                 ユーザー Y                 ユーザー Z

 エージェント間：閉じたループ。1 つのエージェントが学んだ
 ことが他のすべてのエージェントに即座に利用可能。

 エージェント内：単一のエージェントもサーブするユーザー間
 でメモリを共有できる — 属性付き（sharedMemory）または
 非属性（wisdom）。同じエージェント、複数のユーザー、共有
 コンテキスト。

ドキュメントをアップロード / APIプッシュ
     |
     v
エンティティと関係を抽出
     |
     v
ナレッジグラフを構築（重複排除されたノードとエッジ）
     |
     v
アナリティクスルールを実行（レコメンデーション、トレンド）
     |
     v
エージェントが会話中にグラフをクエリ

ナレッジベースへのデータ取り込み

ナレッジベースを構成する2つの方法と、そのいずれかの上に重ねて切り替えられる1つのオプション機能があります：

1. 手動アップロード。 SDKまたはダッシュボードからPDF・DOCX・Markdown・プレーンテキストファイルをアップロードします。プラットフォームはエンティティと関係を自動的に抽出し、グラフに書き込みます。あなたが管理する静的なドキュメント — ハンドブック、ポリシー、製品マニュアル、ローレ — に使用。1回のみ、またはソースが変更されるたびに再アップロード。→ ドキュメントアップロード

2. 差分変更時にAPIへプッシュするETLジョブ。 エンティティスキーマを一度定義し、ジョブが insertFacts または bulkUpdate をスケジュール、キュー、または変更データキャプチャストリームで呼び出します。データベース、価格フィード、CMS、スクレイパーなどのライブな信頼できるソースに使用 — ソースが変更されるとKBが同期して保たれます。アップサートはイデムポテントで、同じラベルを2回プッシュするとプロパティがマージされバージョンがインクリメントされるため、同じジョブを任意のスケジュールで安全に再実行できます。→ SDK：挿入と検索

+ エージェントの自律編集 (オプションのトグル — エージェント単位またはプロジェクト全体で有効化／無効化)。knowledgeBaseWrite 機能をオンにすると、エージェントは knowledge_create / knowledge_update / knowledge_delete ツールを取得します。会話中にエージェント自身が検証済みの事実を記録し、すべての書き込みは source = "agent:<agent-id>" でスタンプされ、コンペア・アンド・スワップの更新セマンティクスにより管理者の同時編集が黙って上書きされることはありません。会話そのものが信頼できるソースである場合に使用 — サポートエージェントが検証済みインシデント詳細を記録、カスタマーサクセスが更新コンテキストを取得、書記係エージェントが議事録を書く、など。

2つの取り込みパスは独立しています — どちらか、両方、またはどちらも使えます。自律編集はエージェント単位のトグル（または default_agent_kb_write によるプロジェクト全体のデフォルト）で、すでに実行している取り込みパスの上に重なります。あなたは常に制御を保持します：すべてのエージェント書き込みはサーバー側でスキーマに対して検証され、クォータで制限され、エージェント自身のプロジェクトにスコープされ、可逆です — ソフト削除のみ、ハード削除は管理者のみです。

手動アップロード        差分変更時のETL            会話中のエージェント
 (PDF / DOCX / MD)       (insertFacts / bulkUpdate) (knowledge_create / update / delete)
      |                          |                          |
      |                          |                          | knowledgeBaseWrite: true
      |                          |                          | が必要
      v                          v                          v
 +----------------------------------------------------------------+
 |                プロジェクトナレッジグラフ                        |
 |    エンティティ + 関係 + バージョン履歴 + 監査証跡             |
 +----------------------------------------------------------------+
                            |
                            v
            すべての会話中にエージェントが
            knowledge_search でクエリ

データ取り込みの2つの方法

1. ドキュメントアップロード

PDF・DOCX・Markdown・プレーンテキストファイルをアップロードします。プラットフォームはドキュメントを自動処理し、エンティティと関係を抽出してナレッジグラフに追加します。

import fs from "fs";

const doc = await client.knowledge.uploadDocument(projectId, {
file: fs.createReadStream("product_catalog.pdf"),
fileName: "product_catalog.pdf",
});

console.log(doc.documentId, doc.status); // "processing"

2. APIプッシュ（構造化データ）

プログラム的に構造化データをプッシュします——スクレイパー・在庫フィード・価格トラッカー・その他の外部データソースに最適です。

await client.knowledge.insertFacts(projectId, {
source: "inventory_sync",
facts: [
  {
    entityType: "product",
    label: "Widget Pro X",
    properties: {
      price:    29.99,
      category: "electronics",
      inStock:  true,
      tags:     ["wireless", "bluetooth"],
    },
  },
],
relationships: [
  { fromLabel: "Widget Pro X", toLabel: "Electronics", edgeType: "belongs_to" },
],
});

SDK：挿入と検索

SDKを使用してサーバーからデータをプッシュし、検索します。

import { Sonzai } from "@sonzai-labs/agents";

const client = new Sonzai({ apiKey: "sk-..." });

// エンティティを挿入
await client.knowledge.insertFacts(projectId, {
source: "price_sync",
facts: [
  {
    entityType: "item",
    label: "Charizard Base Set",
    properties: { price: 450, trend: "+12%", condition: "PSA 10" },
  },
],
relationships: [
  { fromLabel: "Charizard Base Set", toLabel: "Fire Pokemon", edgeType: "is_type" },
],
});

// 検索
const results = await client.knowledge.search(projectId, {
query: "fire pokemon under 500",
type: "item",
limit: 10,
});
for (const r of results.results) {
console.log(r.label, r.properties);
}

SDK：一括更新

bulkUpdate で外部データ（価格・在庫・統計）を一括同期します。変更されたフィールドのみ更新されます——頻繁な同期に効率的です。

await client.knowledge.bulkUpdate(projectId, {
source: "price_sync",
updates: [
  { label: "Charizard Base Set", entityType: "item", properties: { price: 460 } },
  { label: "Blastoise Base Set", entityType: "item", properties: { price: 390 } },
],
});

エンティティスキーマ

型付きフィールドでカスタムエンティティタイプを定義します。スキーマによって抽出が guided され、プラットフォームが探すべきフィールドを正確に把握できます。サポートされる型：string・number・boolean・date・enum・array。

await client.knowledge.createSchema(projectId, {
entityType: "pokemon_card",
description: "Collectible trading cards",
fields: [
  { name: "price",     type: "number", required: true },
  { name: "condition", type: "enum",   enumValues: ["PSA 10", "PSA 9", "Raw"] },
  { name: "set",       type: "string", required: true },
  { name: "rarity",    type: "enum",   enumValues: ["Common", "Uncommon", "Rare", "Ultra Rare"] },
  { name: "tags",      type: "array" },
],
similarityConfig: {
  enabled: true,
  threshold: 0.7,
  fieldWeights: { price: 0.3, set: 0.4, rarity: 0.3 },
},
});

ナレッジグラフ

エンティティは型付きの関係を通じて接続されます。グラフは任意のエンティティタイプと関係タイプをサポートします——完全にドメイン非依存です。

検索

すべてのエンティティラベルとプロパティにわたるフルテキスト検索。タイプフィルタリング・プロパティフィルタ・関連エンティティを含むグラフトラバーサルをサポートします。

const results = await client.knowledge.search(projectId, {
query:   "bluetooth speaker",
type:    "product",
limit:   10,
filters: { in_stock: true },
});

for (const r of results.results) {
console.log(r.label, r.score, r.properties);
// r.related[] には1ホップトラバーサルから接続されたノードが含まれます
}

レコメンデーションエンジン

フィールドマッチングに基づいてソースエンティティをターゲットエンティティにマッチさせるルールを定義します。エンジンはフィードバックループを防ぎ、コンバージョンフィードバックを通じて時間とともにレコメンデーションを改善します。

// レコメンデーションルールを作成
const rule = await client.knowledge.createAnalyticsRule(projectId, {
ruleType: "recommendation",
name: "Similar cards",
config: { matchFields: ["set", "rarity"], limit: 5 },
enabled: true,
});

// レコメンデーションを取得
const recs = await client.knowledge.getRecommendations(
projectId, rule.ruleId, sourceNodeId, 5
);
for (const rec of recs.results) {
console.log(rec.label, rec.score);
}

// フィードバックを記録（将来のレコメンデーションを改善）
await client.knowledge.recordFeedback(projectId, {
ruleId:       rule.ruleId,
sourceNodeId: sourceNodeId,
targetNodeId: rec.nodeId,
action:       "converted",  // "shown" | "converted"
});

トレンドアナリティクス

時間ウィンドウ（7日・30日・90日）にわたるエンティティプロパティの変化を追跡します。トップゲイナー・ルーザー・最も変動の激しいもの・最高平均のランキングを取得します。

// トレンドランキングを取得
const trends = await client.knowledge.getTrendRankings(projectId, {
ruleId: ruleId,
type:   "top_gainers",   // "top_gainers" | "top_losers" | "most_volatile" | "highest_avg"
window: "30d",           // "7d" | "30d" | "90d"
limit:  10,
});

for (const item of trends.rankings) {
console.log(item.label, item.currentValue, item.changePercent);
}

エージェントがナレッジを使用する方法

会話中、AIエージェントはナレッジベースをクエリする knowledge_search ツールにアクセスできます。事実をハルシネーションする代わりに、エージェントはグラフから正確なデータを引き出します——エンティティのプロパティ・関係・レコメンデーションを含みます。

ユーザー：「500ドル以下で最高のカードは何ですか？」
     |
     v
エージェントが knowledge_search("cards under 500") を呼び出す
     |
     v
KBが返す：Charizard（450ドル、+12%）、Blastoise（380ドル、+8%）
     |
     v
エージェント：「Charizard Base Setは450ドルで、今月12%上昇中です。
            500ドル以下の素晴らしい投資選択肢です。」

ウィズダム（Wisdom）と共有メモリ（Shared Memory）

静的なドキュメントの先には、多数のユーザーと対話するエージェントが蓄積するパターンがあります——繰り返される行動、共通の目標、安定した嗜好。Sonzai はこの「ユーザー横断の汎化」を、補完関係にある2つの層で公開します：ウィズダム（wisdom）（脱帰属化、デフォルトON）と共有メモリ（shared memory）（帰属付き、明示的にON）。

Wisdom（脱帰属化、デフォルトON）

wisdom ケイパビリティが ON のとき（新規エージェントは全員デフォルトON）、プラットフォームは毎日プロモーション・ジョブを実行します：ユーザー単位の事実履歴からパターンを抽出し、k-匿名化を施し、その結果を LLM で書き直して脱帰属化された知識に変換します。個別ユーザーは特定できません。エージェントは「だいたい何が効く / だいたい何が出てくるか」の恩恵を、誰が何を言ったかを漏らすことなく受けられます。

これは無料で得られる汎化レイヤーです。エージェントが何かを呼び出す必要はありません——ケイパビリティが ON のとき、wisdom は事実と並んでエージェントの文脈に自動で現れます。

// 新規エージェントは wisdom がデフォルト ON。特定のエージェントで無効化したい
// 場合（たとえばユーザー横断の汎化が不適切なシングルユーザーのコンパニオン製品）、
// 作成時、もしくは updateCapabilities で false を渡してください：
await client.agents.updateCapabilities("agent_abc", { wisdom: false });

Shared Memory（帰属付き、明示的にON）

ある種のビジネスは、脱帰属化のちょうど反対を求めます——同じエージェントを使う複数のユーザーが、誰が何をしているかを見えるようにしたい、というニーズです。チームコラボレーション用エージェントは「Alice はマイグレーション担当、Bob はインシデント対応」と表示するかもしれません。パーティーコーディネーターのエージェントは「Carol はデザート担当、Dave はセットアップ担当」と記録するかもしれません。これを制御するのが sharedMemory ケイパビリティです。

このケイパビリティが ON になると、エージェントは人/エンティティ帰属の事実（役割・専門性・ビジネス文脈・関係エッジ）を記録し、同じエージェントを共有する他のユーザーに公開します。3 つの挙動が変わります：

1. ツール。 エージェントに wisdom_create・wisdom_update・wisdom_delete・関係エッジ系ツール、加えて管理画面側の CSV インポートが追加されます。
2. コンテキスト。 他ユーザーの帰属付き事実が、帰属情報を保ったままエージェントの毎ターンのコンテキストに現れます。
3. プライバシーフロア。 永続化前に、専用のセマンティック・バリデーターでプライバシー禁止リスト（報酬・健康・政治）に対して全書き込みが検証されます——ユーザーに頼まれても、本来ユーザー境界を越えてはいけない情報をエージェントが共有することはありません。

Shared memory はデフォルトOFF です。エージェントがグループ・チーム・パーティーのような、ユーザー横断の可視性が本当に価値を生むユースケースに使われるときだけ、明示的に有効化してください。

// Wisdom が前提条件です（新規エージェントはデフォルトON——上書きするときだけ
// 明示的に渡してください）。
await client.agents.updateCapabilities("agent_abc", {
wisdom:       true,
sharedMemory: true,
});

エージェント作成時にも有効化できます：

const agent = await client.agents.create({
name:       "Team Coordinator",
project_id: "proj_abc",
tool_capabilities: {
  wisdom:        true,
  shared_memory: true,
},
});

ユースケース

APIリファレンス

すべてのエンドポイントは Authorization: Bearer {api_key} ヘッダーを使用します。

実践ガイド

すべてのオーディエンスがナレッジベースを使用しますが、何をアップロードするか、どうクエリするかは異なります。

await client.knowledge.insertFacts("project-id", {
  entities: [
    { label: "Aunt Miriam", type: "person", properties: { relation: "mentor", alive: false } },
    { label: "The old observatory", type: "place", properties: { significance: "first-love" } },
  ],
});