helix-memory-system

Helix メモリーシステム

グラフリレーションシップ、ベクトル類似検索、BM25 全文検索を 1 つのデータベースに統合した、テナントごとの永続的なエージェントメモリープラットフォームを Helix 上に構築します。このスキルでは、メモリーのライフサイクル全体を扱います。生のコンテキストの取り込み、抽出、メモリー生成、重複排除、更新とバージョン管理、削除と忘却、分類、プロフィールの維持、ハイブリッド検索が含まれます。

Helix はストレージおよび検索エンジンです。完全なメモリー製品には、抽出、チャンク化、埋め込み、リレーションシップ分類、再ランキング、コネクター同期、プロフィール要約を行うアプリケーションワーカーも必要です。

使用する場面

次のようなタスクでは、このスキルを使用してください。

• エージェントメモリー、長期記憶、ユーザープロフィール、ドキュメント／チャンク RAG、または「ユーザーが話した内容を覚えておく」機能のデータモデルを設計する
• メモリーの作成、重複排除、強化、統合、バージョン管理、修正、有効期限設定、忘却、分類、検索を行うクエリを記述する
• 特定のメモリー操作で、どの Helix 機能（プロパティインデックス、グラフエッジ、ベクトルインデックス、BM25 テキストインデックス）を使うべきか判断する
• セマンティック検索＋キーワード検索＋グラフ＋プロフィールコンテキストを統合するハイブリッド検索を構築する
• ソースドキュメント、チャンク、コネクター、抽出済みファクト、進化するプロフィール、リレーションシップを考慮した検索、忘却などの高度なメモリーコンポーネントを実装する

一般的なクエリ構文に関する質問には、このスキルを使用しないでください。ビルダーやメソッドの詳細については、helix-query-typescript（デフォルトの DSL）、helix-query-rust、または helix-query-json-dynamic を参照してください。このスキルでは、それらを前提とし、Helix 上に構築するメモリーアーキテクチャに焦点を当てます。

最初の手順

1. 対象リポジトリを調べ、既存のラベル、エッジ、プロパティ、インデックス、ルートのスタイルを確認します。既存のものがあれば、大文字と小文字の使い方も含めてそのまま再利用します。
2. デフォルトでは TypeScript v3 DSL（@helix-db/[email protected]）を使用し、アプリケーションのクエリ生成をサービスコードの近くに保ちます。実行環境が Rust の場合、またはチームが Rust クエリを明示的に採用している場合に限り、EXAMPLES.rust.md を使用します。
3. モデリングを始める前に、テナント境界を決めます。標準のテナントプロパティは tenant_id です。現在、テナント単位でパーティション化された Helix テキストインデックスでは、この名前が必須です。テナント所有のすべてのノードとエッジに tenant_id を付与します。
4. テナント境界とは別に、メモリーの可視性境界を決めます。多くのアプリでは、tenant_id がインデックスをパーティション化し、どのメモリーを検索できるかは userId、containerId、projectId、またはアプリケーションの ACL によって決まります。デフォルトの例では、2 段階目のスコープとして userId を使用します。
5. 独自のラベルを考案する前に、以下の標準モデルを再利用します。名前は調整しても、モデルの形は変えません。
6. 埋め込みの生成方法を確認します。本番環境およびベンチマーク可能なメモリーシステムでは、デフォルトで OpenAI の text-embedding-3-small を使用します。次元数は 1536 で、F32 配列として保存します。アプリケーション側でクライアントサイドの埋め込みを計算し、数値配列（param.array(param.f32())）を渡します。Helix は動的クエリの経路ではテキストを埋め込みません。現在の DSL に Embed()／SearchV はありません。各ベクトルインデックスでは、埋め込みモデルと次元数を固定します。決定論的ハッシュ埋め込みを使用できるのは、ローカル UI のデモまたはスモークテストに限ります。品質ベンチマークには使用しないでください。
7. Helix の外部で実行するアプリケーションワーカーを特定します。抽出器、チャンク化処理、埋め込み生成器、メモリー書き込み処理、リレーションシップ分類器、減衰／有効期限の確認処理、プロフィール要約処理、任意のクエリ書き換え処理、任意の再ランキング処理、コネクター同期ジョブが含まれます。

メモリモデルの概要

中核となるラベル：Tenant、User、UserProfile、SourceDocument、Chunk、Memory、Category、Entity、Session、オプションの Connector と IngestionJob。

中核となるエッジ：OWNS（Tenant/User→Memory）、HAS_PROFILE（User→UserProfile）、HAS_CHUNK（SourceDocument→Chunk）、EXTRACTED_FROM（Memory→Chunk または SourceDocument）、IN_CATEGORY（Memory→Category）、MENTIONS（Memory→Entity）、UPDATES（新しい Memory→古い Memory）、EXTENDS（Memory→Memory の拡張）、DERIVES（推論された Memory→根拠となる Memory）、RELATES_TO（Memory→Memory の関連付け）、DERIVED_FROM（Memory→Session）、オプションの PARENT_OF（Category→Category）。

高速かつ安全に使うためのフィールド：

• テナントが所有するすべてのノードとエッジに tenant_id を設定し、アンカーとして使う場合は等価インデックスを設定します
• ユーザーまたはコンテナー固有のメモリ、ソースドキュメント、チャンクには userId または同等のスコープキーを設定します。意図的に共有するレコードのみ、テナント全体で共有します
• memoryId、documentId、chunkId、categoryKey、entityKey、sessionId、profileId などの安定した ID
• レコードのライフサイクルをフィルタリングするための Memory.isLatest、validFrom、validTo、expiresAt、deletedAt
• 日付のあるイベントや事実に関するメモリには、observedAt、eventStartAt、eventEndAt、temporalText、timezone などの実世界の時間に関するフィールドを任意で設定します
• tenant_id でパーティション化した Memory.embedding／Memory.content のベクトル／テキストインデックスと、任意で Chunk.embedding／Chunk.content のインデックス

完全な仕様、型、インデックスの初期設定については REFERENCE.md を参照してください。

モダリティの選択ルール

回答する質問に応じて仕組みを選び、意図的に組み合わせてください：

必要なもの	使用するもの	理由
テナントの分離（tenant_id）、厳密な識別、ライフサイクルフラグ（deletedAt、expiresAt、validTo、isLatest）、並べ替え／フィルタリング（createdAt、salience）	プロパティ＋等価／範囲インデックス	範囲を絞ったアンカーと安全なフィルターを実現できます。テナントスコープは必須です。
カテゴリ分類、エンティティ、出典情報、プロフィールの所有関係、更新／拡張／導出、関連クラスター、タクソノミー	グラフエッジ	これらは関係性です。トラバースして集約します。
重複排除、言い換えの検索、このようなメモリ、このようなチャンク	ベクトル検索	意味的類似性に基づき、言い換えにも対応できます。
正確な名前、ID、まれなトークン、コマンド、ファイルパス、製品用語	BM25 テキスト検索	埋め込みでは正確なトークンが曖昧になりますが、BM25 なら保持できます。
モデルが常に把握しておくべきユーザーの広範なコンテキスト	UserProfile ノード＋要約ワーカー	安定した ID／好み／最近の関心について、複数回検索するのを避けられます。
生のドキュメントと引用	SourceDocument＋Chunk ノード	メモリ内の事実は、ソースに基づく RAG の代わりにはなりません。

経験則：メモリシステムをベクトル検索だけにしてはいけません。 ベクトル検索では正確な名前を見落とし、所有関係、新しさ、矛盾、出典情報、プロフィールの状態、カテゴリも把握できません。

ベクトル検索／BM25 検索では、常に tenantValue = tenant_id でスコープを指定してください。テナントスコープは必要ですが、常にそれだけで十分とは限りません。デフォルトのユーザーメモリ検索では、レコードがテナント全体に明示的に共有されていない限り、userId またはアプリ内の同等のコンテナー／ACL でもフィルタリングする必要があります。すべての検索経路で、忘却済み／古いレコードを除外してください：deletedAt IsNull、isLatest = true、validTo IsNull、expiresAt が存在しないか未来であること。ベクトル検索または BM25 検索をトラバーサルのスコープ内で行う前に、これらの候補を絞り込みます。これにより、意味検索とキーワード検索の両方で、可視性の条件を厳密に適用できます。ある経路で可視性の条件をすべて表現できない場合は、残りの条件をアプリケーションコードで適用してください。

プロダクトレイヤー

Helix はグラフと検索のプリミティブを提供します。完全なインテリジェントメモリシステムには、次の要素も必要です。

レイヤー	責務
取り込み API	テキスト、チャット、ファイル、URL、コネクターイベント、メモリへの直接書き込みを受け付けます。
抽出器	PDF、ドキュメント、HTML、画像／OCR、音声／動画の文字起こし、コード、構造化データをテキストに変換します。
チャンカー	セマンティックなセクション、メッセージのターン、ドキュメントの見出し、コードの AST 境界、文字起こしのセグメントに基づいて、生のコンテキストを分割します。
埋め込みワーカー	アプリが別のモデルを明示的に標準化していない限り、Helix に書き込む前に、メモリとチャンク用の text-embedding-3-small による 1536 次元の F32 埋め込みを生成します。
メモリ生成器	現在のターンに、最近のコンテキスト、アクティブなエンティティ、想起したメモリ、現在の日付を加えて使用し、会話／ドキュメントからエンティティ中心の原子的な候補事実を抽出します。
関係分類器	各候補を UPDATES、EXTENDS、DERIVES、重複、または単独で成立するもののいずれとするかを判断します。
プロファイル要約器	最新のメモリをもとに、UserProfile.staticSummary と dynamicSummary を維持します。
忘却ジョブ	有効期限、減衰、古くなったプロファイル、コネクター削除のスイープを実行します。
検索サービス	クエリを書き換え、メモリ／チャンクに対してベクトル検索と BM25 を実行し、結果を統合、再ランキング、グラフ拡張して、引用付きのコンテキストをパッキングします。
評価	再現率の品質、古いメモリの抑制、テナント分離、レイテンシー、トークン効率を測定します。

Helix が抽出、チャンク化、埋め込み、関係分類、プロファイル生成、コネクター同期、再ランキング、TTL を自動で行うかのように示さないでください。これらは、ユーザーがそれらを提供するマネージドサービスを利用していない限り、アプリケーション側の責任です。

メモリのライフサイクル

各ステップには、EXAMPLES.md（TypeScript）と EXAMPLES.rust.md（Rust）の完全な例へのリンクがあります。

1. 取り込みと生成

1. 生のコンテキストを SourceDocument、会話／セッション、メモリへの直接書き込み、またはコネクターの更新として受け付けます。
2. 入力がすでに原子的なメモリでない場合は、アプリ側で抽出とチャンク化を行います。
3. 各メモリ候補／チャンクを、デフォルトではアプリ側で OpenAI text-embedding-3-small を使って埋め込みます。長さ 1536 の F32 ベクトルを保存／渡します。
4. 原子的で自己完結したメモリ候補を抽出します。エンティティ中心の事実を優先します。たとえば「朝のミーティングを好む」ではなく「Alex は朝のミーティングを好む」とします。
5. 候補の種類を fact、preference、episode、procedure、またはアプリ固有の同等の種類に分類します。
6. 書き込み前に重複を排除します。類似度のしきい値はバッチ条件にできないため、意味的な重複排除には読み取り後に書き込み、完全一致の繰り返しには冪等な upsert を使用します。
7. tenant_id、memoryId、content、embedding、kind、salience、isLatest: true、ライフサイクルのタイムスタンプを指定して Memory を書き込み、所有権と出典のエッジをリンクします。
8. 直ちに分類し、エンティティをリンクします。

文脈に基づく抽出ルール

最新のユーザーメッセージだけを切り離して抽出してはいけません。抽出ワーカーには、次の情報を渡してください。

• 現在のユーザーメッセージ
• 短い回答の意味を定めていることが多いため、直前のアシスタントメッセージ
• 直近の会話のうち、範囲を限定したウィンドウ
• 想起された有効なメモリーと有効なエンティティ
• 相対的な時間表現を解釈するための現在日時
• メモリーのスコープ（tenant_id と userId、containerId、projectId、または ACL コンテキスト）

メモリーを保存するかどうかを判断する前に、代名詞、省略、短い追加回答を解決してください。アシスタントがメモリーに関する追加質問をし、ユーザーが簡潔に回答した場合は、その回答を単独で意味が通じるメモリーに変換してください。

抽出結果は、決定論的な書き込みができるだけの構造化された形式にしてください。shouldStore、単独で意味が通じるcontent、kind、confidence、salience、entities、sourceポインター、scope、任意の時間フィールド、および関係の判定（new、duplicate、EXTENDS、UPDATES、DERIVES）を含めます。単一のベクトル距離しきい値だけで更新を決定してはいけません。ベクトル検索と BM25 で候補を取得し、完全な重複か、更新か、拡張かをアプリケーションコードで判定してください。

例：

Existing memory: User is planning a trip to Japan with Maya.
Assistant: When are you going?
User: next April
Extract: User is planning a trip to Japan with Maya next April.
Relationship: EXTENDS the existing Japan trip memory; MENTIONS Maya and Japan.

Assistant: What do you want to do there?
User: mostly food, temples, and trains
Extract: User wants their Japan trip with Maya to focus on food, temples, and trains.
Relationship: EXTENDS the existing Japan trip memory; categorise as travel/preferences.

User later: actually we're going in May instead
Extract: User is planning a trip to Japan with Maya in May.
Relationship: UPDATES the previous next-April timing memory and invalidates the older version.

2. 更新とバージョン管理

• アクセス時の強化： accessCount、lastAccessedAt、および上限付きのsalienceを増加させます。
• 更新／訂正： 新しいメモリーを作成し、new -UPDATES-> oldとしてリンクします。古いメモリーのisLatest = falseとvalidToを設定し、通常の想起から除外する必要がある場合は、任意でdeletedAtも設定します。
• 拡張： 新しい事実が古い事実を置き換えずに補足する場合は、new -EXTENDS-> existingとしてリンクします。
• 導出： 推論した事実を、根拠となるメモリーにDERIVESエッジでリンクし、信頼度メタデータを付けて推論結果として記録します。
• contentが変更された場合は、同じ書き込みの中で再埋め込みを行い、embeddingを更新します。コンテンツとベクトルに不整合が生じてはいけません。
• ライフサイクル上の有効性（validFrom、validTo、deletedAt）は、現実世界のイベント時刻（eventStartAt、eventEndAt、temporalText）とは別に管理します。事実の変更を理由にメモリーを更新する場合、どちらの事実も未来または過去の日付を指していたとしても、古いレコードを無効にする必要があります。
• 書き込みの永続性を待機します。 更新／バージョン管理は読み取り後に書き込みを行い、セッション間で並行して実行されることも多いため、HTTP 409 の書き込み競合が発生する可能性が高まります。競合を減らすため、書き込みの永続性を待機してください（TypeScript では.shouldAwaitDurability(true)、Rust では.should_await_durability(true)、Go ではhelix.AwaitDurability(true)）。実際の競合は、診断メッセージを解析するのではなく、安定したtransaction_conflictコード（リモート呼び出しでは HTTP 409）で判定してください。ミューテーションを再構築する前に、信頼できるメモリーの状態を再読み込みし、べき等である場合、またはそれ以外の方法で安全な場合に限り、上限付きバックオフで再実行してください。言語別スキルと../../docs/error-handling.mdを参照してください。

3. 削除／忘却

Helix に標準の TTL や減衰機能はありません。忘却は、アプリが実行する明示的な書き込みクエリで行います。

• 論理削除（推奨）：deletedAt = Expr.datetime()を設定し、読み取り時に除外します。取り消し可能で、監査にも適しています。
• バージョンの無効化： メモリーが新しい内容に置き換えられたとき、isLatest = falseとvalidTo = Expr.datetime()を設定します。
• 有効期限の一括処理： expiresAt < nowのメモリーを非表示にするか、物理削除します。
• 減衰の一括処理： 重要度が低く、古く、アクセス頻度の低いエピソードメモリーを非表示にします。
• 物理削除： ポリシー上必要な場合に限り、drop()を使用します。drop()はノードと、それに接続するエッジを削除します。マルチグラフに影響する経路でエッジだけを削除する場合は、dropEdgeByIdを使用します。

4. カテゴリ分類とエンティティのリンク付け

• 表示カテゴリは、tenant_id のスコープ内で Category ノードとして保存し、${tenant_id}:${normalisedName} などの一意な categoryKey を使用します。
• エンティティは、tenant_id のスコープ内で Entity ノードとして保存し、${tenant_id}:${normalisedName} などの一意な entityKey を使用します。
• タグ／エンティティで走査、集計、検索を行う場合は、配列よりもエッジを優先してください。
• グラフの展開が不要な表示／監査フィールドには、ネストしたオブジェクトのメタデータを使用してください。頻繁にフィルタリングするフィールドはトップレベルに置き、タグ／エンティティで走査、集計、検索を行う場合はエッジを優先してください。

5. プロファイルのメンテナンス

• ユーザー／コンテナごとに UserProfile を 1 つ維持し、profileId、tenant_id、userId、staticSummary、dynamicSummary、updatedAt を含めます。
• 静的プロファイル：本人確認情報、安定した嗜好、長期的な背景情報。
• 動的プロファイル：現在のプロジェクト、最近のコンテキスト、一時的な目標、未解決のタスク。
• メモリの書き込みと削除の後に、プロファイルを非同期で更新してください。プロファイル生成は、テスト可能な程度に決定的なものにしてください。

検索

複数の検索経路を実行し、アプリ側で統合します。

1. 常時使用するコンテキストとして UserProfile を取得します。
2. 現在の Memory ノードに対してベクトル検索と BM25 を実行します。テナント、ユーザー／コンテナのスコープを適用し、鮮度でフィルタリングします。
3. ソースに基づく RAG と引用のため、必要に応じて Chunk ノードに対してベクトル検索と BM25 を実行します。ドキュメントを意図的に共有する場合を除き、同じ所有者／スコープのポリシーを適用します。
4. アプリ側で RRF により統合し、その後、顕著性、最近性、関係タイプ、任意のクロスエンコーダースコアで再ランキングします。
5. 深さとテナントフィルターに上限を設けて、上位のメモリを MENTIONS、IN_CATEGORY、EXTENDS、UPDATES、RELATES_TO を通じて展開します。
6. 埋め込みなしでコンテキストをパッキングし、利用可能な場合はソース／引用のメタデータを含めます。

アンチパターン

次のことは避けてください。

• 新しい動的／TS／Rust DSL の作業で、非推奨の .hx 方言（Embed()、SearchV、SearchBM25、AddV）を使用する
• テキストインデックスのテナントプロパティに userId を使用する。テナント分割されたテキスト／ベクトルインデックスには tenant_id を使用してください
• tenant_id だけで、組織／チームのテナントに対する安全な検索境界になると想定する。userId、containerId、プロジェクト ACL、または明示的な共有メモリフラグでフィルタリングしてください
• Memory のみに tenant_id を付与する。テナント所有のすべてのノードとエッジに必要です
• tenant_id も確認せずに、memoryId によってメモリを変更、削除、カテゴリ分類、または強化する
• 検索で deletedAt だけを確認し、置き換え済み／忘却済み／期限切れのメモリを返す
• ライフサイクルのタイムスタンプ（validTo、deletedAt）と実世界のイベント日を混同する。旅行、締め切り、予定、過去の事実に関するメモリには、別個の時間フィールドを使用してください
• ベクトルのみのストアを構築して、それをメモリと呼ぶ
• 本番環境の検索やベンチマークの主張に、おもちゃのハッシュ埋め込みを使用する。アプリにより優れた標準モデルがない限り、デフォルトで text-embedding-3-small を使用してください
• ベクトルのしきい値だけで重複排除／更新／拡張を判断する。完全一致チェック、BM25 の候補、ベクトルの候補、およびアプリ／LLM による判定を使用してください
• 最新のユーザーメッセージだけからメモリを抽出し、「来年の 4 月」や「主に食べ物、お寺、電車」といったコンテキストを踏まえた続きの発言を見落とす
• コンテキストを解決する前に自己完結していないという理由で、短い続きの回答を破棄する
• 所有者またはスコープのフィールドなしでユーザー固有のチャンク／ドキュメントを書き込み、その後、テナント全体から検索する
• Helix がファイルの抽出、ドキュメントのチャンク化、埋め込みの生成、更新の分類、プロファイルの構築、再ランキング、コネクターの同期、TTL ジョブの実行を自動で行うと期待する
• out／in／both ステップの後に $distance または $score を読み取る。検索直後にランクメタデータをプロジェクションしてください
• 類似度しきい値による重複排除を BatchCondition で表現しようとする。判定できるのは変数の空／サイズだけです
• 再埋め込みせずに content を更新する
• 明示的に必要とされていない限り、API レスポンスで embedding 配列を返す
• マルチテナントのメモリアプリで、表示名によって Category または Entity をグローバルにする

検証チェックリスト

完了する前に、以下を確認してください。

• readBatch() と writeBatch() の使い分けが正しい
• テナントが所有するすべてのノードとエッジに tenant_id がある
• ベクトルインデックスとテキストインデックスで tenant_property = "tenant_id" を使い、検索では tenantValue = tenant_id を渡す
• ベクトル検索と BM25 検索の再現率を高める処理では、トラバーサルのスコープ内で検索する前に、ユーザー／ACL とライフサイクルに基づく候補を作成する
• すべてのメモリ読み取りで、tenant_id、ユーザー／コンテナーの可視性、deletedAt IsNull、現在／最新の状態、有効期限の有効性をフィルタリングする
• すべての書き込みルートで tenant_id を受け取り、それに基づいてフィルタリングする
• アップサートに使用する ID は、グローバルに一意か、テナントで修飾されている（categoryKey、entityKey など）
• ユーザー／コンテナー固有のドキュメントとチャンクに、再現処理で使うものと同じ所有者／スコープのフィールドを設定するか、アプリのポリシーに基づいて明示的に共有としてマークする
• ライフサイクルの有効性フィールドをイベント時刻フィールドとして流用しない。日付付きの事実には observedAt、eventStartAt、eventEndAt、temporalText、またはアプリ側の同等フィールドを使う
• 埋め込みモデルは openai:text-embedding-3-small とし、アプリで別の固定モデル／次元数を標準化している場合を除き、すべてのベクトルを 1536 次元の F32 にする
• コンテンツの編集時に、同じ書き込み処理で再度埋め込みを生成する
• 生成時に意味的な重複を排除し、完全一致する繰り返しは冪等に処理する
• 何を保存するかを決定する前に、抽出処理で、直前のアシスタントのターン、直近の会話ウィンドウ、再現された有効なメモリ／エンティティ、現在の日付を確認する
• 抽出処理で、決定論的にテストできる、構造化された関係／スコープ／ソース／時間に関する判定を出力する
• 引用や未加工のコンテキストに対する RAG を機能として提供する場合、ソースドキュメント／チャンクを用意する
• 常時有効なパーソナライズを機能として提供する場合、ユーザープロファイル更新ジョブを用意する
• テナント分離、ユーザー／コンテナー分離、古いメモリの抑制、文脈に応じたフォローアップの抽出、完全一致トークンの再現、時間に関する修正、削除、プロファイルの再構築、レイテンシ、トークン予算を評価対象に含める
• タイムスタンプの規約を統一する。このスキルでは、Expr.datetime() と param.dateTime() による型付き DateTime を使用する
• 明示的に必要な場合を除き、射影結果に embedding を含めない
• 最大 1 件のレスポンスフィールドでは null を許容する。コレクション／fold／ミューテーションの空の値は [] のままとし、スカラーの 0 または false はスカラーのままにする
• ラベル／エッジ／プロパティが既存のリポジトリの大文字・小文字の規則と一致する

リファレンスファイル

• REFERENCE.md — データモデルの完全な仕様、テナントの規則、インデックス、モダリティの早見表、埋め込みのガイダンス、統合／再ランキングの計算式、TypeScript ↔ Rust API の対応表。
• EXAMPLES.md — @helix-db/[email protected] の TypeScript スニペットによるライフサイクルのシナリオ。既定。
• EXAMPLES.rust.md — Rust DSL による同じシナリオ。
• 関連スキル：helix-query-typescript、helix-query-rust、helix-query-json-dynamic、helix-query-optimize。