# Memory API

Memory API は Synapse の中核です。構造化されたメモリの保存、取得、検索、管理のための 22 のエンドポイントを提供します。すべてのエンドポイントで認証に Mind Key が必要です。

> [!CRITICAL]
> **毎セッションの開始時に必ず `GET /memory/recall` を呼び出してください。** これが、前回のセッションからコンテキストを再構築する唯一の方法です。

## カテゴリ

メモリは 8 つのカテゴリに整理されます。

| カテゴリ | ユースケース |
|----------|----------|
| `identity` | ユーザー名、役割、連絡先情報、自己に関する設定 |
| `preference` | 好き嫌い、作業スタイル、コミュニケーションの好み |
| `fact` | 検証可能な事実（プロジェクト詳細、日付、URL） |
| `project` | プロジェクトのステータス、マイルストーン、アーキテクチャ |
| `skill` | ユーザーが得意なこと |
| `mistake` | 過去のエラー — 繰り返しを避ける |
| `context` | セッション関連のコンテキスト |
| `note` | その他のメモ |

## 優先度

- `low` — 知っておくとよい
- `normal` — デフォルト
- `high` — 重要
- `critical` — 絶対に忘れてはならない（ユーザー ID、法的情報）

## コアエンドポイント

### GET /memory/recall

すべてのメモリを LLM 向けに最適化されたプレーンテキストで返します。毎セッションの開始時に呼び出してください。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/recall
```

レスポンス（text/plain）：

```
Mind: Michael's Mind
Memories: 12 total (10 verified)

[001] identity (CRITICAL)
  user_name
  Michael Schäfer
  Tags: person, identity

...
```

### POST /memory

新しいメモリを保存するか、既存のメモリを更新します（同じ category + key なら更新）。

```bash
curl -X POST https://synapse.schaefer.zone/memory \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "fact",
    "key": "user_name",
    "content": "The user's name is Michael Schäfer",
    "tags": ["person", "identity"],
    "priority": "critical"
  }'
```

レスポンス：`{ "id": "mem_001", "status": "stored" }`

### GET /memory

オプションのフィルタ付きでメモリを一覧表示します。

```bash
# All memories (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# Filter by category
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# Filter by tag
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"
```

### PUT /memory/:id

ID で特定のメモリを更新します。

```bash
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content", "priority": "high"}'
```

### DELETE /memory/:id

単一メモリを削除します。

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mem_001
```

## 検索エンドポイント

### GET /memory/search

FTS5 を使用したフルテキスト検索です。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=docker+swarm"
```

FTS5 構文：

- 複数単語 = AND：`docker swarm`
- フレーズ：`"docker swarm"`
- プレフィックス：`docker*`
- ブール：`docker OR kubernetes`
- 除外：`docker -swarm`

### GET /memory/semantic-search

埋め込みを使用した概念検索（FTS5 より遅いが意味を理解）。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"
```

キーワードが一致しなくても、クエリと意味的に類似したメモリを返します。X が異なる表現で記述されている「X に関するメモリを見つける」といった場合に有用です。

### GET /memory/by-tag

タグでメモリを一覧表示します。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"
```

### GET /memory/related/:id

特定のメモリに関連するメモリを（共通タグ経由で）見つけます。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/related/mem_001
```

## 同期 & Diff

### GET /memory/diff

差分同期 — 指定タイムスタンプ以降に変更されたメモリを返します。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/diff?since=1700000000"
```

レスポンス：`{ "added": [...], "updated": [...], "deleted": [...] }`

### POST /memory/sync

別インスタンスからの diff を適用します（セルフホスト同期用）。

```bash
curl -X POST https://synapse.schaefer.zone/memory/sync \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"added": [...], "updated": [...], "deleted": [...]}'
```

## 一括操作

### POST /memory/bulk-delete

ID で複数のメモリを削除します。

```bash
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'
```

### POST /memory/embed-batch

まだ埋め込みを持たないメモリの埋め込みを生成します（セマンティック検索用）。

```bash
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'
```

### GET /memory/embed-batch-status

埋め込み生成の進捗を確認します。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## 検証

メモリには `verified` フラグがあります。エージェントが保存したメモリはデフォルトで未検証（`source=agent`）、人間が保存したメモリは検証済み（`source=user`）です。

### POST /memory/verify

メモリを検証済みとしてマークします（Mind Key ではなく JWT が必要）。

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \
  -H "Authorization: Bearer YOUR_JWT"
```

### POST /memory/unverify

メモリを未検証としてマークします（JWT が必要）。

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \
  -H "Authorization: Bearer YOUR_JWT"
```

### GET /memory/unverified

人間の検証待ちのメモリを一覧表示します。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/unverified?limit=100"
```

## 統計 & 監査

### GET /memory/stats

現在の mind の集計統計です。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/stats
```

返却値：`{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

状態を変更する全操作の監査ログです。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"
```

### GET /memory/contradictions

保存されたメモリ内の潜在的矛盾を検出します。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/contradictions
```

### GET /memory/expiring

有効期限が近づいているメモリを一覧表示します。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/expiring?within=7d"
```

## ヘルス & エクスポート

### GET /memory/health

メモリシステムのクイックヘルスチェックです。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/health
```

### GET /memory/mind-export

全メモリの完全 JSON エクスポート（バックアップ用）。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mind-export > backup.json
```

### POST /memory/compact

類似メモリを圧縮します（自動要約）。

```bash
curl -X POST https://synapse.schaefer.zone/memory/compact \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```

## 次のステップ

- [Quick Start for LLMs](/docs/getting-started/quick-start-llm)
- [Memory Best Practices](/docs/guides/memory-best-practices)
- [FTS5 Search](/docs/concepts/fts5-search)
- [Semantic Search](/docs/concepts/semantic-search)