memory-lancedb-pro

memory-lancedb-pro プラグインのメンテナンスガイド

概要

memory-lancedb-pro は、OpenClaw 用の強化版長期記憶プラグインです。組み込みの memory-lancedb プラグインを置き換え、高度な検索機能、複数スコープのメモリ分離、管理用 CLI を提供します。

リポジトリ: https://github.com/win4r/memory-lancedb-pro ライセンス: MIT | 言語: TypeScript（ESM） | ランタイム: OpenClaw Gateway 経由の Node.js

アーキテクチャ

┌─────────────────────────────────────────────────────────┐
│                   index.ts (Entry Point)                │
│  Plugin Registration · Config Parsing · Lifecycle Hooks │
└────────┬──────────┬──────────┬──────────┬───────────────┘
         │          │          │          │
    ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
    │ store  │ │embedder│ │retriever│ │   scopes    │
    │ .ts    │ │ .ts    │ │ .ts    │ │    .ts      │
    └────────┘ └────────┘ └────────┘ └─────────────┘
         │                     │
    ┌────▼───┐           ┌─────▼──────────┐
    │migrate │           │noise-filter.ts │
    │ .ts    │           │adaptive-       │
    └────────┘           │retrieval.ts    │
                         └────────────────┘
    ┌─────────────┐   ┌──────────┐
    │  tools.ts   │   │  cli.ts  │
    │ (Agent API) │   │ (CLI)    │
    └─────────────┘   └──────────┘

ファイルリファレンス（クイックナビゲーション）

ファイル	用途	主なエクスポート
index.ts	プラグインのエントリーポイント。OpenClaw Plugin API に登録し、設定を解析して、ライフサイクルフックをマウントします	memoryLanceDBProPlugin（デフォルト）、shouldCapture、detectCategory
openclaw.plugin.json	プラグインのメタデータと、uiHints を含む完全な JSON Schema 設定	—
package.json	NPM パッケージ。依存関係：@lancedb/lancedb、openai、@sinclair/typebox	—
cli.ts	CLI：memory-pro list/search/stats/delete/delete-bulk/export/import/reembed/migrate	createMemoryCLI、registerMemoryCLI
src/store.ts	LanceDB ストレージ層。テーブル作成、FTS インデックス作成、CRUD、ベクトル/BM25 検索	MemoryStore、MemoryEntry、loadLanceDB
src/embedder.ts	埋め込み処理の抽象化。OpenAI 互換 API、タスク対応、LRU キャッシュ	Embedder、createEmbedder、getVectorDimensions
src/retriever.ts	ハイブリッド検索エンジン。スコアリングパイプライン全体	MemoryRetriever、createRetriever、DEFAULT_RETRIEVAL_CONFIG
src/scopes.ts	複数スコープのアクセス制御	MemoryScopeManager、createScopeManager
src/tools.ts	エージェントツール定義：memory_recall/store/forget/update/stats/list	registerAllMemoryTools
src/noise-filter.ts	低品質なコンテンツのノイズフィルター	isNoise、filterNoise
src/adaptive-retrieval.ts	あいさつ、コマンド、絵文字の場合に検索をスキップします	shouldSkipRetrieval
src/migrate.ts	レガシー版 memory-lancedb からの移行	MemoryMigrator、createMigrator
scripts/jsonl_distill.py	JSONL セッションの抽出スクリプト（Python）	—

コアサブシステムリファレンス

各サブシステムの詳細については、該当するリファレンスファイルをお読みください。

• 検索パイプライン（スコアリング計算、RRF 融合、リランキング、すべてのスコアリング段階）：references/retrieval_pipeline.md を参照
• ストレージとデータモデル（LanceDB スキーマ、FTS インデックス作成、CRUD、ベクトル次元）：references/storage_and_schema.md を参照
• 埋め込みシステム（プロバイダー、タスク対応 API、キャッシュ、次元）：references/embedding_system.md を参照
• プラグインのライフサイクルと設定（フック、登録、設定解析）：references/plugin_lifecycle.md を参照
• スコープシステム（複数スコープの分離、エージェントのアクセス、パターン）：references/scope_system.md を参照
• ツールと CLI（エージェントツール、CLI コマンド、パラメーター）：references/tools_and_cli.md を参照
• よくある注意点とトラブルシューティング：references/troubleshooting.md を参照

開発ワークフロー

新しい埋め込みプロバイダーの追加

1. OpenAI 互換かどうかを確認します（ほとんどが互換です）。互換であれば、コード変更は不要で、設定だけで対応できます
2. モデルが src/embedder.ts の EMBEDDING_DIMENSIONS マップにない場合は、追加します
3. プロバイダーが task と normalized 以外の特別なリクエストフィールドを必要とする場合は、src/embedder.ts の buildPayload() を拡張します
4. embedder.test() メソッドでテストします
5. README.md の表にプロバイダーを記載します

新しいリランキングプロバイダーの追加

1. src/retriever.ts の RerankProvider 型にプロバイダー名を追加します
2. リクエスト形式（ヘッダーと本文）に対応するケースを buildRerankRequest() に追加します
3. レスポンス解析に対応するケースを parseRerankResponse() に追加します
4. openclaw.plugin.json の rerankProvider enum に追加します
5. 実際の API 呼び出しでテストします。リランカーには 5 秒のタイムアウト保護があります

新しいスコアリングステージの追加

1. MemoryRetriever に private apply<StageName>(results: RetrievalResult[]): RetrievalResult[] メソッドを作成します
2. RetrievalConfig インターフェースに対応する設定フィールドを追加します
3. hybridRetrieval() と vectorOnlyRetrieval() の両方で、パイプラインの実行順序にステージを挿入します
4. DEFAULT_RETRIEVAL_CONFIG にデフォルト値を追加します
5. openclaw.plugin.json に JSON Schema のフィールドを追加します
6. パイプラインの順序：Fusion → Rerank → Recency → Importance → LengthNorm → TimeDecay → HardMin → Noise → MMR

新しいエージェントツールの追加

1. src/tools.ts に registerMemory<ToolName>Tool() を作成します
2. @sinclair/typebox の Type.Object() でパラメーターを定義します
3. 列挙型のパラメーターには openclaw/plugin-sdk の stringEnum() を使用します
4. 必ず context.scopeManager でスコープへのアクセスを検証します
5. registerAllMemoryTools() に登録します。コア（常時）にするか管理用（任意）にするかを決めます
6. { content: [{ type: "text", text }], details: {...} } を返します

新しい CLI コマンドの追加

1. cli.ts の registerMemoryCLI() にコマンドを追加します
2. パターン：memory.command("name <args>").description("...").option("--flag", "...").action(async (args, opts) => { ... })
3. 機械可読な出力に対応する --json フラグをサポートします
4. エラー時には process.exit(1) を使用します
5. CLI は index.ts の api.registerCli() を介して登録されます

自動キャプチャロジックの変更

1. index.ts の shouldCapture(text) が、自動キャプチャの対象を制御します
2. MEMORY_TRIGGERS 正規表現配列がトリガーパターンを定義します（英語／CJK に対応）
3. detectCategory(text) が、キャプチャを preference/fact/decision/entity/other に分類します
4. 自動キャプチャは agent_end フックで実行され、1 ターンあたり最大 3 件に制限されます
5. 重複判定のしきい値：コサイン類似度 > 0.95

自動想起ロジックの変更

1. 自動想起には before_agent_start フックを使用します（デフォルトでは OFF）
2. src/adaptive-retrieval.ts の shouldSkipRetrieval() が検索を制御します
3. UNTRUSTED DATA の警告を含む <relevant-memories> XML ブロックとして挿入されます
4. sanitizeForContext() が HTML と改行を除去し、メモリごとに 300 文字に制限します
5. 1 ターンあたり最大 3 件のメモリが挿入されます

主な設計上の決定事項

• autoRecall はデフォルトで OFF — モデルが挿入されたメモリコンテキストをそのまま繰り返すのを防ぎます
• autoCapture はデフォルトで ON — 透過的にメモリを蓄積します
• sessionMemory はデフォルトで OFF — セッションの生の要約は検索品質を低下させます。代わりに JSONL による抽出を使用してください
• LanceDB の動的インポート — ブロックを避けるために非同期で読み込み、シングルトンの Promise にキャッシュします
• 起動時チェックは fire-and-forget 方式 — ゲートウェイは HTTP ポートをすぐにバインドし、埋め込み／検索テストは 8 秒のタイムアウト付きでバックグラウンド実行されます
• 日次 JSONL バックアップ — 24 時間間隔で実行し、直近 7 ファイルを保持します。起動 1 分後に開始します
• BM25 スコアの正規化 — BM25 の生スコアには上限がないため、シグモイド関数で正規化します：1 / (1 + exp(-score/5))
• 更新 = 削除 + 再追加 — LanceDB はインプレース更新をサポートしていません
• ID のプレフィックス照合 — 8 文字以上の 16 進数プレフィックスから完全な UUID を特定できるため、ユーザーが簡単に指定できます
• CJK 対応のしきい値 — 中国語／日本語／韓国語のテキストでは、最小文字数を短く設定します（英語の 10～15 文字に対し、4～6 文字）
• 環境変数の解決 — ${VAR} 構文は設定の解析時に解決されます。ゲートウェイサービスにはシェルの環境変数が継承されない場合があります

テスト

• スモークテスト：node test/cli-smoke.mjs
• 手動検証：openclaw plugins doctor、openclaw memory-pro stats
• 埋め込みテスト：embedder.test() は { success, dimensions, error? } を返します
• 検索テスト：retriever.test() は { success, mode, hasFtsSupport, error? } を返します