openviking-context-database

OpenViking Context Database — OpenClaw Plugin Operator Skill

@openviking/openclaw-plugin をインストールして設定した後に、このスキルを使用してください。これは、スタンドアロンの OpenViking Python SDK ではなく、現在の OpenClaw プラグインの実装について説明しています。

対象範囲と安全ルール

• このプラグインはリモート専用です。HTTP 経由で既存の OpenViking サーバーと通信し、openviking-server の起動や管理は行いません。
• OpenViking の REST エンドポイントを創作しないでください。以下で説明する、登録済みの OpenClaw ツールとコマンドを使用してください。
• エージェントに公開される add_resource ツールはデフォルトで無効です（enableAddResourceTool=false）。検索、取得、URI の読み取り、検索結果の最適化では add_resource を使用しないでください。これらの操作では ov_search と ov_read を使用してください。
• 手動の /add-resource を使用してください。または、リソースのインポート、追加、アップロード、保存、インデックス登録をユーザーが明示的に依頼した場合に限り、add_resource を使用してください。
• ユーザーが OpenViking への Agent Skill のインポート、追加、インストール、登録を明示的に依頼した場合に限り、add_skill を使用してください。
• ローカルのファイルやディレクトリでは、プラグインのツールにローカルパスを渡してください。プラグインは /api/v1/resources/temp_upload 経由でアップロードします。ローカルのファイルシステムパスを自分でリモートサーバーに送信しないでください。
• API キーをログに記録したり、そのまま表示したりしないでください。プラグインは API キーを X-API-Key／セットアップ確認用ヘッダーとして送信し、セットアップ出力ではマスクします。

現在のアーキテクチャ

OpenClaw はエージェントの実行、プロンプト、ツール呼び出しを担います。OpenViking は長期的なコンテキストを管理します。

レイヤー	現在の動作
assemble	OpenViking から圧縮されたセッション履歴を再構築し、関連するリコール情報を最新のユーザーメッセージに挿入します。
afterTurn	新しいターンのみを OpenViking のセッションに追加します。pending_tokens >= tokenBudget * commitTokenThresholdRatio の場合、非同期コミットが開始されることがあります。
compact	commit(wait=true) を実行し、アーカイブ／抽出の完了を待ってから、最新のアーカイブ概要を読み戻します。
ツール	メモリーの呼び出し／保存／削除、アーカイブの検索／展開、リソース／スキルのインポート／検索、リコールのトレース照会、ツール結果の一覧表示／検索／読み取り。

長期メモリーは通常、/compact の実行時、またはしきい値によってコミットが開始されたときに抽出されます。新しい会話で言及された事実は、長期メモリーになる前でも、最近のセッションコンテキストとして残っている場合があります。

設定クイックリファレンス

まずステータスを確認します。

openclaw openviking status --json
openclaw config get plugins.entries.openviking.config
openclaw config get plugins.slots.contextEngine

コア設定は plugins.entries.openviking.config にあります。

フィールド	デフォルト	用途
baseUrl	http://127.0.0.1:1933	OpenViking の HTTP エンドポイントです。OPENVIKING_BASE_URL / OPENVIKING_URL からも設定できます。
apiKey	empty	任意の API キーです。OPENVIKING_API_KEY からも設定できます。
peer_role	none	メモリのスコープです。none（共有 viking://user/<user_id>/memories）、assistant（.../peers/<assistant_id>/memories に保存するアシスタントに関連付けられたメモリ）、または sender（.../peers/<sender_id>/memories に保存する送信者に関連付けられたメモリ）を指定します。レガシー値の person は sender として受け付けられます。
peer_prefix	empty	peer_role=assistant の場合に、アシスタントの peer_id / アクターの peer 値に付ける任意のプレフィックスです。
accountId / userId	empty	ルートキーまたは信頼済みのデプロイで使用する、高度なテナント ID ヘッダーです。
targetUri	viking://~/memories	レガシーの対象指定メモリ検索で使用するデフォルトの検索スコープです。
autoCapture	true	サニタイズされたターンのテキストを OpenViking セッションに追加します。
captureMode	semantic	semantic または keyword を指定します。サーバー側の抽出フィルタリングに影響します。
captureMaxLength	24000	キャプチャするターンごとのサニタイズ済みテキストの最大長です。
autoRecall	true	返信前にリコールを実行し、関連するコンテキストを挿入します。
recallTargetTypes	user,agent	targetUri が省略された場合のデフォルトの対象タイプです。指定可能な値は resource、user、agent です。
recallResources	false	recallTargetTypes が未設定の場合に、デフォルトのリコール対象へ resource を追加する互換用のショートカットです。
recallLimit	6	選択するリコール項目の最大数です。
recallScoreThreshold	0.15	後処理後の最小スコアです。
recallMaxInjectedChars	4000	挿入する文字数の合計上限です。上限に収まらないメモリは、完全な状態で挿入できないためスキップされます。
commitTokenThresholdRatio	0.5	モデルのコンテキストウィンドウに対する割合（0～1）で表す非同期コミットのしきい値です（例：0.5 = 50%）。0 の場合は毎ターンコミットします。
commitKeepRecentCount	10	afterTurn コミット後もライブ状態に保つ最近のメッセージ数です。Compact では常に 0 が使用されます。
bypassSessionPatterns	empty	OpenViking を完全にバイパスする、グロブ形式のセッションキーです（* はセグメント単位、** は複数セグメントに一致）。
emitStandardDiagnostics	false	構造化された openviking: diag {...} 行を出力します。
logFindRequests	false	find とセッション書き込みのルーティングをログに記録します。OPENVIKING_LOG_ROUTING=1 または OPENVIKING_DEBUG=1 でも有効にできます。
traceRecall	false	メモリにリコールトレースを記録します。
traceRecallPersist	false	リコールトレースをローカルの JSONL ファイルとして保存します。
traceRecallDir	~/.openclaw/openviking/recall-traces	永続化が有効な場合のリコールトレースディレクトリです。

通常のセットアップコマンド：

openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json

便利なバリエーション：

openclaw openviking setup --base-url <URL> --api-key <KEY> --peer-role assistant --peer-prefix openclaw-prod --json
openclaw openviking setup --base-url <URL> --api-key <ROOT_KEY> --account-id <ACCOUNT_ID> --user-id <USER_ID> --json
openclaw openviking setup --base-url <URL> --api-key <KEY> --recall-target-types resource --json
openclaw openviking setup --base-url <URL> --api-key <KEY> --allow-offline --json
openclaw openviking setup --base-url <URL> --api-key <KEY> --force-slot --json

ツール選択ガイド

ユーザーの意図	使用するツール
「以前、何を言いましたか？」、好み、判断、既知の事実	memory_recall
「これを今、記憶して」	memory_store
「X を忘れて」	memory_forget
要約に、過去のチャットにあった正確なコマンド／パス／スニペットが含まれていない	ov_archive_search を使用し、必要に応じて ov_archive_expand を使用します
ドキュメント、PDF、ローカルディレクトリ、URL、Git リポジトリ、メディア添付ファイルをインポートする	手動で /add-resource を使用します。add_resource は enableAddResourceTool=true の場合に限り使用できます
Agent Skill をインポート／登録する	add_skill
インポート済みのリソースまたはスキルを検索する	ov_search
ov_search またはリコールトレースで見つかった正確な viking://... を読み取る	ov_read
リコール／検索で特定の結果が返された理由を説明する	ov_recall_trace
以前のツール結果にプレビュー／参照のみが表示されている	openviking_tool_result_list、openviking_tool_result_search、openviking_tool_result_read

ツールインターフェースリファレンス

memory_recall

メモリ／リソースをセマンティック検索します。セッション履歴にはアーカイブツールを使用してください。

パラメーター	必須	説明
query	はい	検索クエリ。
limit	いいえ	選択する結果の最大数。デフォルトは recallLimit です。
scoreThreshold	いいえ	スコアのしきい値 0..1。デフォルトは recallScoreThreshold です。
targetUri	いいえ	検索対象の URI を指定します。設定した場合、この URI のみを検索します。
resourceTypes	いいえ	resource、user、agent の配列です。targetUri を省略した場合にのみ使用されます。

注：targetUri を省略した場合、プラグインは resourceTypes または設定済みの recallTargetTypes から検索プランを決定し、要求数より多くの候補を取得して重複を排除し、リーフメモリをフィルタリングして再ランク付けし、recallMaxInjectedChars を遵守します。

memory_store

セッションを書き込み、wait=true を指定してコミットすることで、テキストをすぐに永続化します。

パラメーター	必須	説明
text	はい	情報源のテキスト。
role	いいえ	セッションのロール。デフォルトは user です。
sessionId	いいえ	既存の OpenViking/OpenClaw セッションへの参照。省略した場合、一時的な memory-store-* セッションが作成されます。

memory_forget

メモリを削除します。

パラメーター	必須	説明
uri	いいえ	正確な viking://user/.../memories/... メモリ URI。メモリ以外の URI は拒否されます。
query	いいえ	uri が不明な場合の検索クエリ。
targetUri	いいえ	検索範囲の URI。デフォルトは targetUri です。
limit	いいえ	検索上限。デフォルトは 5 です。
scoreThreshold	いいえ	検索のしきい値。デフォルトは recallScoreThreshold です。

クエリモードで複数の候補が見つかった場合は、候補を提示して正確な URI をユーザーに選んでもらってください。曖昧なメモリは削除しないでください。

ov_archive_search

現在のセッションのアーカイブ済み会話メッセージ全体を対象に、キーワードで grep 検索します。

パラメーター	必須	説明
query	はい	単一のキーワードまたは短いフレーズ。名前、日付、ファイルパス、コマンド、特徴的な名詞を優先してください。
archiveId	いいえ	1 つのアーカイブに限定します。例：archive_002。

アーカイブ内の詳細が取得できないと結論づける前に、具体的なキーワードのバリエーションを少なくとも 2 つ試してください。

ov_archive_expand

パラメーター	必須	説明
archiveId	はい	[Archive Index] にあるアーカイブ ID。例：archive_002。

アーカイブ検索の後、または [Archive Index] から正確な詳細が含まれていそうなアーカイブを特定できる場合に使用してください。

add_resource

リソースを viking://resources/... にインポートします。

このエージェントツールはデフォルトで無効です。リソースの取り込みには、手動の /add-resource を優先してください。enableAddResourceTool=true によってツールが利用可能になっている場合は、明示的なインポート／インデックス作成のリクエストに限って使用し、検索／取得の最適化には使用しないでください。

パラメーター	必須	説明
source	はい	ローカルパス、OpenClaw のメディア添付ファイルのパス、ディレクトリパス、公開 URL、または Git URL。
to	いいえ	正確なターゲット URI。例：viking://resources/project-docs。parent との併用はできません。
parent	いいえ	viking://resources 配下の親 URI。to との併用はできません。
reason	いいえ	インポートの理由／メモ。
instruction	いいえ	セマンティック抽出の処理指示。
wait	いいえ	処理の完了を待つかどうか。

現在の OpenClaw ツールが公開するパラメーターは上記のとおりです。基盤となるクライアントは、strict、ignore_dirs、include、exclude、preserve_structure など、サーバー向けのリソースオプションもコマンド／内部パス用にサポートしています。登録済みのスキーマで公開されていない限り、これらをツールに渡さないでください。

add_skill

Agent Skills を viking://~/skills/... にインポートします。

パラメーター	必須	説明
source	いいえ	ローカルの SKILL.md のパス、またはスキルディレクトリです。source と data のどちらか一方が必須です。
data	いいえ	生の SKILL.md コンテンツ、または MCP ツールの辞書です。source と data のどちらか一方が必須です。
wait	いいえ	処理が完了するまで待機します。

Agent Skill のベストプラクティス：スキルには、正確なフロントマター（name、トリガーを意識した description、有用な tags）、明確な適用範囲、必要に応じて「使用しない場合」の明示的な指針、具体的なパラメーターを含む実行可能な手順を設定してください。スキルのコンテンツにシークレットを含めないでください。

ov_search

パラメーター	必須	説明
query	はい	検索クエリです。
uri	いいえ	検索 URI です。デフォルトはリソースとエージェントスキルです。
limit	いいえ	スコープごとの最大結果数です。デフォルトは 10 です。

リソース／スキルのインポート後、またはユーザーが OpenViking 管理下のナレッジの検索を依頼した場合に使用します。

重要：ov_search は viking://resources/project-docs/api.md#chunk-3 のような OpenViking の仮想 URI を返します。これらはローカルファイルパスではありません。ファイルシステムの読み取りツールは使用せず、完全なコンテンツが必要な場合は正確な URI を指定して ov_read を呼び出してください。

ov_read

/api/v1/content/read を通じて、正確な OpenViking 仮想 URI 1 件の完全なコンテンツを読み取ります。

パラメーター	必須	説明
uri	はい	ov_search またはリコールトレースの結果で返された正確な viking://... URI です。openviking://... のエイリアスとローカルファイルパスは拒否されます。

ov_recall_trace

パラメーター	必須	説明
turn	いいえ	latest または all です。デフォルトは latest です。
traceId	いいえ	正確なトレース ID です。
sessionId / sessionKey / ovSessionId	いいえ	OpenClaw/OpenViking セッションで絞り込みます。
source	いいえ	auto_recall、memory_recall、ov_search、または ov_archive_search です。
resourceTypes	いいえ	resource、user、agent を含む配列または文字列です。
since / until	いいえ	ミリ秒単位の Unix タイムスタンプ範囲です。
includeContent	いいえ	選択／表示された URI のコンテンツプレビューを必要に応じて読み取ります。
limit	いいえ	返すトレースの最大数です。デフォルトは 20 です。

トレースレコードが存在するのは traceRecall=true の場合のみです。永続化された検索には traceRecallPersist=true と、アクセス可能なトレースファイルが必要です。

外部化されたツール結果用ツール

プレビューに viking://user/{user_id}/sessions/<session_id>/tool-results/<tool_result_id> が含まれる場合に使用します。

ツール	パラメーター
openviking_tool_result_list	tool_name?、limit?（デフォルトは 50）
openviking_tool_result_search	tool_output_ref、query、limit?（デフォルトは 20）、context_chars?（デフォルトは 300）
openviking_tool_result_read	tool_output_ref、offset?（デフォルトは 0）、limit?（デフォルトは 20000。サーバーパスでは残りすべてのコンテンツを取得するために -1 を指定できます）

プラグインは、別のセッションに属するツール結果の参照の読み取り／検索を拒否します。

スラッシュコマンド

/add-resource ./README.md --to viking://resources/openviking-readme --wait
/add-skill ./skills/install-openviking-memory --wait
/ov-search "OpenViking install" --uri viking://resources/openviking-readme --limit=5
/ov-recall-trace --turn latest --source auto_recall --include-content

コマンドパーサーは、引用符で囲まれた引数とフラグに対応しています。リソース専用のフラグは、スキルのインポートでは拒否されます。

トラブルシューティング

症状	考えられる原因	最初の対応
configured=false	セットアップの設定が保存されていません	openclaw openviking setup ... --json を再実行し、JSON の error に応じて処理してください。
slotActive=false	別のコンテキストエンジンがスロットを使用しているか、ゲートウェイの状態が古くなっています	plugins.slots.contextEngine を確認してください。ユーザーの確認を得てから --force-slot を使用してください。
health.ok=false	サーバーに接続できないか、baseUrl またはキーが正しくありません	baseUrl、ネットワーク、/health、認証を確認してください。
新しい事実を追加しても長期記憶に残らない	/compact またはコミット／抽出が実行されていないか、サーバーでの抽出に失敗しています	明示的に記憶／保存／格納する意図がある場合は memory_store を使用してください。それ以外の場合は /compact を実行するか、しきい値に達してコミットされるまで待ってから、OpenViking サーバーのログを確認してください。
共有ドキュメントを検索しても見つからない	resource の対象が有効になっていません	resourceTypes:["resource"] を指定して memory_recall を使用するか、recallTargetTypes: ["resource"] を設定してください。
要約に正確な詳細がない	アーカイブの要約が大まかすぎます	具体的なキーワードで ov_archive_search を使用し、その後 ov_archive_expand を実行してください。
大きなツール出力のプレビューでは不十分	ツールの結果が外部化されています	ref を指定して openviking_tool_result_search/read を使用してください。
検索動作を説明する必要がある	トレースが無効になっているか、そのターンのトレースがありません	traceRecall を有効にしてください。必要に応じて traceRecallPersist も有効にし、ov_recall_trace を照会してください。

このリポジトリのリファレンスドキュメント

• README.md / README_CN.md：機能の概要とクイックスタート。
• INSTALL.md / INSTALL-ZH.md：インストール、アップグレード、アンインストール、JSON セットアップの処理。
• INSTALL-AGENT.md：エージェント向けのインストールワークフロー。
• docs/openviking-openclaw-plugin-guide.md：中国語の包括的な運用者／開発者向けガイド。