# メモリのベストプラクティス

メモリの構造化方法が有用性を決定します。本ガイドでは、LLM が適切な時に適切な情報を再取得できるよう、メモリのカテゴリ化、タグ付け、優先度付けのパターンを説明します。

## カテゴリ：最も具体的なものを選ぶ

| カテゴリ | 用途 | 例 |
|----------|---------|---------|
| `identity` | ユーザー名、役割、連絡先情報 | `"user_name": "Michael Schäfer"` |
| `preference` | 好き嫌い、作業スタイル | `"communication": "Prefers concise responses"` |
| `fact` | 検証可能な事実 | `"office_location": "Berlin, Germany"` |
| `project` | プロジェクトのステータス、決定 | `"project_synapse": "v1.5.0 deployed"` |
| `skill` | ユーザーのスキル | `"skill_python": "Advanced, 10+ years"` |
| `mistake` | 避けるべき過去のエラー | `"mistake_npm_version": "Always bump version"` |
| `context` | セッション関連のコンテキスト | `"current_focus": "Working on docs system"` |
| `note` | その他のメモ | `"note_idea": "Try Redis for caching"` |

> [!TIP]
> 迷ったら、検証可能な情報には `fact` を、それ以外には `note` を使用してください。カテゴリ化しすぎず — 混乱する `context` より明確な `fact` の方が良いです。

## キー：意味のある識別子

`key` フィールドはメモリの識別子です。意味のある安定したキーを使用してください。

**良いキー：**
- `user_name`
- `project_synapse_status`
- `preference_communication_style`
- `mistake_npm_version_bump`

**悪いキー：**
- `mem_001`（意味がない）
- `temp`（説明的でない）
- `2026-06-27-note`（日付は再取得に役立たない）

### キーの命名規則

- `snake_case`（小文字とアンダースコア）
- カテゴリをプレフィックスに：`preference_*`、`project_*`、`mistake_*`
- 動詞ではなく説明的な名詞を使用
- 50 文字以内に収める

## タグ：検索とフィルタリング用

タグにより高速なフィルタリングと検索が可能です。メモリごとに 2〜5 個のタグを追加してください。

```json
{
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system.",
  "tags": ["synapse", "deployment", "status", "v1.5.0"]
}
```

### タグのパターン

- **プロジェクト名**：`synapse`、`synapse-mcp`、`synapse-chat`
- **トピック**：`deployment`、`ci`、`database`、`auth`
- **ステータス**：`active`、`completed`、`blocked`
- **優先度指標**：`urgent`、`long-term`

> [!NOTE]
> タグは大文字小文字を区別しません。一貫性のために小文字を使用してください。

## 優先度：現実的に

| 優先度 | 用途 | メモリの割合 |
|----------|---------|---------------|
| `critical` | ユーザー ID、法的情報、不可逆な決定 | 約 5% |
| `high` | 進行中のプロジェクト、重要な設定 | 約 20% |
| `normal` | ほとんどの事実、メモ、コンテキスト | 約 65% |
| `low` | 一時的、知っておくとよいこと | 約 10% |

> [!WARNING]
> すべてを `critical` にしないでください。すべてが critical なら、何も critical ではありません。`critical` は忘れた場合に実害が出るものに予約してください。

## 保存すべきか否か

### 常に保存

- ユーザー ID（名前、メール、役割）
- 長期的な設定
- プロジェクトの決定と根拠
- 過去の過ちと学んだ教訓
- ユーザーへの約束

### 保存しない

- 一時的な状態（変数を使用）
- 逐語的な会話履歴（チャットシステムが処理）
- 機密データ（パスワード、API キー）
- 容易に導出できる事実（現在日付、ファイル内容）
- 一時的なコンテキスト（`context` カテゴリ + low 優先度を使用）

## メモリの更新

同じ `category` + `key` で `POST /memory` を呼ぶと既存メモリが更新されます。

```python
# Initial store
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# Later: update with same key
store("project", "project_synapse_status", "v1.5.0 deployed. CI green.", priority="high")
```

> [!TIP]
> 重複を作らずに更新できるよう、安定したキーを使用してください。LLM は情報が変わるたびに新しいメモリを作るのではなく、同じキーで再 POST すべきです。

## メモリのライフサイクル

```
Create → Active → Stale → Archive → Delete
```

- **Create**：完全なコンテキスト付きで POST /memory
- **Active**：頻繁に再取得、必要に応じて更新
- **Stale**：まだ関連するが活発に使用されていない（優先度を下げる？）
- **Archive**：優先度を `low` に設定、歴史的参照用に保持
- **Delete**：関連しなくなったら DELETE /memory/:id

### 定期的なクリーンアップ

```python
# Find memories not updated in 90 days
old_memories = requests.get(
    f"{URL}/memory/search?q=*",
    headers={"Authorization": f"Bearer {KEY}"}
)

for mem in old_memories["results"]:
    if is_stale(mem, days=90):
        # Either delete or lower priority
        if is_obsolete(mem):
            delete_memory(mem["id"])
        else:
            update_memory(mem["id"], priority="low")
```

## パターン：メモリの継承

階層的コンテキスト（プロジェクト → サブプロジェクト → タスク）向け：

```python
# Parent project
store("project", "project_synapse", "Main Synapse project", 
      tags=["synapse", "parent"], priority="high")

# Sub-project (tags link to parent)
store("project", "project_synapse_docs", "Docs system for Synapse",
      tags=["synapse", "docs", "synapse-parent"], priority="high")

# Specific task (tags link to sub-project)
store("project", "task_docs_loader", "Implement docs-loader.ts",
      tags=["synapse", "docs", "task"], priority="normal")
```

LLM は `q=synapse+docs` で検索し、関連する全メモリを見つけられます。

## パターン：決定ログ

LLM が再考しないよう、決定を根拠と共に保存します。

```python
store("fact", "decision_postgres_over_sqlite",
      "Chose PostgreSQL over SQLite for production. Reason: concurrent writes, "
      "FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.",
      tags=["decision", "database", "postgres", "sqlite"],
      priority="high")
```

## パターン：過ちの回避

具体的な回避指示と共に過ちを保存します。

```python
store("mistake", "mistake_forget_version_bump",
      "Forgot to bump package.json version after changes. npm publish failed. "
      "FIX: Always run `npm version patch` before pushing. "
      "CI fails with 'version already exists' if you forget.",
      tags=["npm", "ci", "publish", "version"],
      priority="high")
```

## 避けるべきアンチパターン

> [!WARNING]
> - **会話ログの保存** — チャットシステムが処理
> - **ファイル全体の保存** — スクリプトストアや外部ストレージを使用
> - **一時的な状態の保存** — 変数を使用
> - **シークレットの保存** — 環境変数を使用
> - **メモリの重複** — 安定したキーを使用
> - **タグの過剰使用** — メモリごとに 2〜5 個が理想
> - **すべてが critical** — 優先度は現実的に

## 次のステップ

- [Memory API](/docs/api/memory)
- [Persistent LLM Agent](/docs/guides/persistent-llm-agent)
- [Memory Tagging Strategy](/docs/llm-cookbook/memory-tagging-strategy)