# メモリガイド

SDK の Memory モジュールが提供する **セマンティックメモリ** を使って、エージェントに長期記憶を実装する方法を解説します。

> **プロジェクトの記憶とは別のものです**
>
> このページのメモリは、エージェントが自分で読み書きするものです。SaaS 版のプロジェクトにある「プロジェクトの記憶」（実行や確認の内容を、プラットフォームが次の実行へ引き継ぐ仕組み）は、マーケットプレイス版にはありません。プロジェクトの工程の間で情報を受け渡すときは、ファイルを使います（[Project ＞ 案件ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/case-guide.md)）。

## 概要

セマンティックメモリは Mem0 + Qdrant をバックエンドとした、ベクトル検索ベースのメモリシステムです。ユーザーの知識・好み・事実を記憶し、類似度検索で関連する記憶を想起します。

```text
ユーザーとの対話
       │
       ▼
セマンティックメモリ（Mem0 + Qdrant）
  「ユーザーは Python が得意」
  「プロジェクトXの締切は3月」
  「前回はCSV出力を希望した」
       │
       ▼
LLM コンテキストに注入 → より適切な回答
```

SemanticMemoryClient のメソッド（add / search / get\_all / delete / delete\_all）はすべて **同期メソッド** です。`await` は不要です。cleanup() のみ非同期です。

## 設定

config.toml の `[memory]` セクションで LLM・Embedder・ベクトルストアを設定します。

```toml
[memory.llm]
model = "azure_openai/gpt-4.1"
api_key = "${AZURE_OPENAI_API_KEY}"
base_url = "https://your-endpoint.openai.azure.com/"
api_version = "2024-12-01-preview"

[memory.embedder]
model = "azure_openai/text-embedding-3-large"
api_key = "${AZURE_OPENAI_API_KEY}"
base_url = "https://your-endpoint.openai.azure.com/"
api_version = "2024-12-01-preview"

# OpenAI 互換エンドポイント（Azure AI inference の embed-v-4-0 等）を使う場合（v0.5.24+）:
# [memory.embedder]
# model = "openai/embed-v-4-0"
# api_key = "${AZURE_AI_API_KEY}"
# base_url = "https://your-resource.services.ai.azure.com/models"  # /models まで含める。
#     # base_url 未設定だと公式 api.openai.com に接続され 401 になる

[memory.vector_store]
provider = "qdrant"

[memory.vector_store.config]
url = "http://qdrant.internal:6333"
collection_name = "semantic_memory"
```

## 基本操作

```python
from agenticstar_platform.memory import SemanticMemoryClient, SemanticMemoryConfig

# 初期化
config = SemanticMemoryConfig.from_toml("config.toml")
memory = SemanticMemoryClient(config)

# メモリの追加（messages は OpenAI 形式の dict リスト）
result = memory.add(
    messages=[
        {"role": "user", "content": "私は Python と TypeScript が得意です"},
        {"role": "assistant", "content": "承知しました。スキルセットを記録します。"},
    ],
    user_id="user-001",
    metadata={"source": "self_introduction"},
)

# メモリの検索（類似度ベース）
result = memory.search(
    query="このユーザーのスキルセットは？",
    user_id="user-001",
    limit=5,
)
for r in result.get("results", []):
    print(f"{r['memory']}")

# 全メモリの取得
result = memory.get_all(user_id="user-001")

# メモリの削除
result = memory.delete(memory_id="mem-xxx")

# ユーザーの全メモリを削除
result = memory.delete_all(user_id="user-001")

# 非同期クリーンアップ（終了時に呼び出し）
await memory.cleanup()
```

## LLM プロバイダーの選択

`LLMProviderConfig` の `model` フィールドに `プロバイダー/モデル名` 形式で指定します。

**Azure OpenAI**

```toml
[memory.llm]
model = "azure_openai/gpt-4.1"
api_key = "${AZURE_OPENAI_API_KEY}"
base_url = "https://your-endpoint.openai.azure.com/"
api_version = "2024-12-01-preview"
```

**Anthropic**

```toml
[memory.llm]
model = "anthropic/claude-sonnet-4-6"
api_key = "${ANTHROPIC_API_KEY}"
```

**AWS Bedrock**

```toml
[memory.llm]
model = "aws_bedrock/anthropic.claude-sonnet-4-6-20250514-v1:0"
aws_region_name = "us-east-1"
aws_access_key_id = "${AWS_ACCESS_KEY_ID}"
aws_secret_access_key = "${AWS_SECRET_ACCESS_KEY}"
```

## エージェントでの活用パターン

### パターン 1: コンテキスト強化

エージェントの LLM 呼び出し前に、メモリからコンテキストを取得して追加します。

```python
def build_context(user_id: str, query: str) -> str:
    """メモリからコンテキストを構築"""
    result = memory.search(query=query, user_id=user_id, limit=5)

    context = "## このユーザーについて\n"
    for r in result.get("results", []):
        context += f"- {r['memory']}\n"

    return context

# LLM 呼び出し時にコンテキストを注入
context = build_context("user-001", user_message)
messages = [
    {"role": "system", "content": f"以下のユーザー情報を参考にしてください:\n{context}"},
    {"role": "user", "content": user_message},
]
```

### パターン 2: 対話後の自動記憶

対話終了後に重要な情報をメモリに保存します。

```python
def save_conversation_memory(user_id: str, conversation: list[dict]):
    """対話をメモリに保存"""
    memory.add(
        messages=conversation,  # [{"role": "user", ...}, {"role": "assistant", ...}]
        user_id=user_id,
        metadata={"source": "conversation"},
    )
```

### パターン 3: ユーザー別のパーソナライゼーション

```python
def personalize_response(user_id: str, base_response: str) -> str:
    """ユーザーの好みに基づいてレスポンスを調整"""
    result = memory.search(
        query="ユーザーの好みや要望",
        user_id=user_id,
        limit=3,
    )
    memories = result.get("results", [])

    if not memories:
        return base_response

    adjustment_prompt = "以下のユーザーの好みを考慮して回答を調整してください:\n"
    for m in memories:
        adjustment_prompt += f"- {m['memory']}\n"

    return adjust_with_llm(base_response, adjustment_prompt)
```

## ユーティリティ関数

SDK はメモリの設定変換に使えるユーティリティ関数を提供しています。

```python
from agenticstar_platform.memory import (
    normalize_provider,
    parse_model_string,
    convert_llm_to_mem0,
    convert_embedder_to_mem0,
)

# プロバイダー名の正規化
provider = normalize_provider("Azure_OpenAI")  # → "azure"

# モデル文字列の解析
provider, model = parse_model_string("azure_openai/gpt-4.1")
# → ("azure", "gpt-4.1")

# LLMProviderConfig から Mem0 形式の設定に変換
llm_config = convert_llm_to_mem0(llm_provider_config)
embedder_config = convert_embedder_to_mem0(embedder_config)
```

## 次のステップ

SDK API リファレンス — メモリモジュール

SemanticMemoryClient の完全仕様

[ガイドを見る](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/reference/sdk-ref.md#-メモリモジュール)

セキュリティガイド

メモリに保存する前のコンテンツ検証

[ガイドを見る](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/security-guide.md)
