> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shannon.run/llms.txt
> Use this file to discover all available pages before exploring further.

# ベクトルメモリ

> Qdrantによるセマンティックメモリでインテリジェントなコンテキスト検索を実現

## 概要

Shannonのメモリシステムは、ユーザーセッション間でインテリジェントなコンテキスト保持と検索を提供し、Agentが会話の継続性を維持し、履歴インタラクションを活用して応答を改善できるようにします。

## アーキテクチャ

<img src="https://mintcdn.com/ptmind-3aa3d4e1/2Bzddmlzr-QTR0Yc/ja/architecture/assets/vector-memory-architecture.svg?fit=max&auto=format&n=2Bzddmlzr-QTR0Yc&q=85&s=2d10d84a7e3ef130a5bcfe1b26ddf95e" alt="ベクトルメモリアーキテクチャ - ストレージレイヤー（PostgreSQL、Redis、Qdrant）とメモリタイプ（Session、Semantic、Agent、Supervisor）の相互作用を示す図 / Vector Memory Architecture - Diagram showing interaction between storage layers (PostgreSQL, Redis, Qdrant) and memory types (Session, Semantic, Agent, Supervisor)" width="800" height="600" data-path="ja/architecture/assets/vector-memory-architecture.svg" />

## ストレージレイヤー

### PostgreSQL

* **セッションコンテキスト**: セッションレベルの状態とメタデータ
* **実行永続化**: AgentとTool実行履歴
* **タスク追跡**: 高レベルのタスクとWorkflowメタデータ

### Redis

* **セッションキャッシュ**: アクティブセッションデータへの高速アクセス（TTL: 3600秒）
* **トークン予算**: リアルタイムトークン使用量追跡
* **圧縮状態**: コンテキスト圧縮状態の追跡

### Qdrant（ベクトルストア）

* **セマンティックメモリ**: 高性能ベクトル類似性検索
* **コレクション構成**: task\_embeddings、summaries、tool\_results、document\_chunks
* **ハイブリッド検索**: 新しさとセマンティック関連性を組み合わせ

## メモリタイプ

### 階層メモリ（デフォルト）

複数の検索戦略を組み合わせ:

* **最近のメモリ**: 現在のセッションの最後のN回のインタラクション
* **セマンティックメモリ**: クエリ類似性に基づくコンテキスト関連コンテンツ
* **圧縮サマリー**: 古い会話の圧縮表現

### セッションメモリ

セッション内の最近のインタラクションの時系列検索。

### Agentメモリ

個別のAgent実行記録:

* 入力クエリと生成された応答
* トークン使用量とモデル情報
* Tool実行と結果

### Supervisorメモリ

インテリジェントなタスク分解のための戦略的メモリ:

* **分解パターン**: 再利用可能な成功したタスク分解
* **戦略パフォーマンス**: 戦略タイプごとの集計メトリクス
* **失敗パターン**: 既知の失敗と緩和戦略

## 設定

### 環境変数

| 変数                  | デフォルト    | 説明             |
| ------------------- | -------- | -------------- |
| `QDRANT_HOST`       | `qdrant` | Qdrantサーバーホスト名 |
| `QDRANT_PORT`       | `6333`   | Qdrantサーバーポート  |
| `REDIS_TTL_SECONDS` | `3600`   | セッションキャッシュTTL  |

### 埋め込み要件

<Warning>
  メモリ機能にはテキスト埋め込み用のOpenAI APIアクセスが必要です。
</Warning>

* **デフォルトモデル**: `text-embedding-3-small`（1536次元）
* **フォールバック動作**: OpenAIキーが設定されていない場合、メモリ操作は静かに劣化 - Workflowは履歴コンテキストなしで継続

## 主要機能

### インテリジェントチャンキング

* 長い回答（>2000トークン）を管理可能なチャンクに分割
* コンテキスト保持のための200トークンオーバーラップ
* 効率化のためのバッチ埋め込み

### MMR（最大限界関連性）

* 多様性を考慮したリランキングで関連性と情報の多様性をバランス
* デフォルトlambda=0.7で関連性が高く多様なコンテキスト選択を最適化
* 3倍のアイテムを取得し、多様性のためにリランク

### コンテキスト圧縮

* メッセージ数とトークン推定に基づく自動トリガー
* 過度な圧縮を防ぐレート制限
* 異なるティアのモデル対応閾値

## メモリ検索フロー

<Steps>
  <Step title="クエリ分析">
    受信クエリのセマンティックコンテンツを分析
  </Step>

  <Step title="最近の取得">
    Redis経由で現在のセッションから最後のNメッセージを取得
  </Step>

  <Step title="セマンティック検索">
    Qdrantでベクトル類似性検索を実行
  </Step>

  <Step title="マージ＆重複排除">
    結果を組み合わせて重複を削除
  </Step>

  <Step title="コンテキスト注入">
    関連メモリをAgentコンテキストに注入
  </Step>
</Steps>

## プライバシーとデータガバナンス

### PII保護

* データ最小化: 必要なフィールドのみ保存
* 匿名化: 実際のIDの代わりにUUIDを使用
* 自動PII検出とマスキング

### データ保持

* **会話履歴**: デフォルト30日保持
* **分解パターン**: 90日保持
* **ユーザー設定**: セッションベース、24時間有効期限

## パフォーマンス最適化

* **バッチ処理**: 複数チャンクに対する単一API呼び出し（5倍高速）
* **スマートキャッシング**: LRU（2048エントリ）+ Redis
* **ペイロードインデックス**: session\_id、tenant\_id、user\_idでのフィルタリングが50-90%高速
* **最適化されたHNSW**: m=16、ef\_construct=100で高速類似性検索

## 制限事項

* メモリ検索はレイテンシを追加（キャッシングで緩和）
* ベクトル類似性は完全なキーワードマッチを見逃す可能性
* 圧縮は非可逆（重要なポイントのみ保持）
* クロスセッションメモリには明示的なセッションリンクが必要

## セマンティックメモリの有効化

以下の手順に従って、Qdrantを基盤としたShannonのセマンティックメモリシステムを有効化します。

### 前提条件

<Note>
  開始前に、以下の条件を確認してください：

  * **Qdrant** が稼働中であること（Shannonの `docker-compose.yaml` にデフォルトで含まれています）
  * 環境に **`OPENAI_API_KEY`** が設定されていること（`text-embedding-3-small` embeddingモデルに必要）
</Note>

### セットアップ手順

<Steps>
  <Step title="shannon.yaml でベクトルメモリを有効化">
    `shannon.yaml` 設定ファイルに `vector` ブロックを追加または更新します：

    ```yaml shannon.yaml theme={null}
    vector:
      enabled: true                    # true に設定必須（デフォルト: false）
      host: "qdrant"
      port: 6333
      top_k: 10
      threshold: 0.5
      default_model: "text-embedding-3-small"
      cache_ttl: "1h"
      use_redis_cache: true
      expected_embedding_dim: 1536
    ```

    <Warning>
      `vector.enabled` のデフォルトは `false` です。セマンティックメモリを機能させるには、明示的に `true` に設定する必要があります。
    </Warning>
  </Step>

  <Step title="Qdrant コレクションの確認">
    Shannonは5つのコレクションを自動作成します（すべて `text-embedding-3-small` の1536次元ベクトルを使用）：

    | コレクション            | 用途                        |
    | ----------------- | ------------------------- |
    | `task_embeddings` | セマンティック検索用のタスク結果embedding |
    | `tool_results`    | Tool実行結果のembedding        |
    | `cases`           | パターンマッチング用のケースライブラリ       |
    | `document_chunks` | RAG用のドキュメントチャンクembedding  |
    | `summaries`       | サマリーembedding             |

    Qdrant REST APIにクエリしてコレクションが作成されたことを確認できます：

    ```bash theme={null}
    curl http://localhost:6333/collections
    ```
  </Step>

  <Step title="MMR 多様性リランキングの設定">
    MMR（Maximal Marginal Relevance、最大限界関連性）は検索結果における関連性と多様性のバランスを取ります。有効化すると、Shannonはより大きな候補プールを取得し、関連性を維持しながら冗長性を削減するためにリランキングを行います。

    ```yaml shannon.yaml theme={null}
    mmr_enabled: true
    mmr_lambda: 0.7           # 0 = 純粋な多様性、1 = 純粋な関連性
    mmr_pool_multiplier: 3    # リランキング用に3倍の候補を取得
    ```

    <Note>
      `mmr_lambda` を `0.7` に設定するのが推奨デフォルトです。関連性を強く重視しつつ、ほぼ重複した結果をフィルタリングします。
    </Note>
  </Step>

  <Step title="embeddings エンドポイントの設定">
    LLM Serviceがデフォルト以外のアドレスで稼働している場合、またはキャッシュ動作を調整したい場合は、`embeddings` ブロックを更新します：

    ```yaml shannon.yaml theme={null}
    embeddings:
      base_url: "http://llm-service:8000"
      default_model: "text-embedding-3-small"
      timeout: "10s"
      cache_ttl: "1h"
      max_lru: 4096
    ```

    * `cache_ttl` はembeddingベクトルのRedisでのキャッシュ期間を制御します。
    * `max_lru` はインメモリLRUキャッシュの最大エントリ数を設定します。
  </Step>
</Steps>

## 次のステップ

<CardGroup cols={2}>
  <Card title="アーキテクチャ概要" icon="sitemap" href="/ja/architecture/overview">
    システムアーキテクチャ
  </Card>

  <Card title="セッションAPI" icon="messages" href="/ja/api/rest/sessions">
    セッション管理
  </Card>
</CardGroup>