# SYNAPSE ドキュメント — 完全リファレンス
# 生成日時: 2026-07-18T06:14:48.978Z
# 総記事数: 47
このドキュメントにはSynapse APIの完全なドキュメントが含まれています。
Base URL: https://synapse.schaefer.zone
Language: ja
========================================================================
## カテゴリ: はじめに
Synapseを始めるために必要なすべての情報。
────────────────────────────────────────────────────────────
# Authentication & Mind Keys
SUMMARY: Synapse の認証の仕組み：エージェント向け Mind Key、人間向け JWT、URL 単体ツール向け ?key=。
KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.
Authentication & Mind Keys
Synapse は 2 つの認証方法を使用し、それぞれが異なるユースケースに最適化されています。信頼できる連携を構築するには、この違いを理解することが不可欠です。
2 つの認証方法
| 方法 | ユースケース | レート制限 | 有効期限 |
|--------|----------|------------|--------|
| Mind Key | LLM エージェント、自動化ツール | なし（ヘッダー）/ 60/分（クエリ） | なし |
| JWT | ヒューマン向け UI、アカウント操作 | なし | 7 日 |
Mind Key（エージェント向け）
Mind Key はテナントスコープの API トークンです。単一 mind のデータ（メモリ、タスク、チャット、スクリプトなど）を認証します。以下に使用します。
- API を呼び出す LLM エージェント
- バックグラウンド自動化スクリプト
- MCP サーバー設定
- 任意の長期間の連携
ヘッダー認証（推奨）
[CODE BLOCK]
クエリパラメータ（URL 単体ツール向け）
[CODE BLOCK]
> [!WARNING]
> クエリパラメータは 60 リクエスト/分 にレート制限されます。Bearer ヘッダーにはレート制限がありません。クライアントがカスタムヘッダーをサポートする場合は常にヘッダーを使用してください。
Mind Key の作成
[CODE BLOCK]
レスポンスに が含まれます — すぐに保存してください。一度しか表示されません。
mind の一覧
[CODE BLOCK]
mind の削除（不可逆！）
[CODE BLOCK]
JWT（人間向け）
JWT は特定の mind ではなくユーザーアカウントを認証します。以下に使用します。
- アカウントの登録とログイン
- mind の作成/一覧/削除
- 他のユーザーとの mind 共有
- Web Push サブスクリプション管理
登録
[CODE BLOCK]
返却値：
ログイン
[CODE BLOCK]
返却値：
JWT の有効期限
JWT は 7 日後に期限切れになります。期限切れの場合は、再度 を呼び出して新しい JWT を取得してください。Mind Key は期限切れにならないため、既存のエージェント連携は継続して動作します。
セキュリティのベストプラクティス
> [!CRITICAL]
> - Mind Key を git にコミットしない。 環境変数を使用してください。
> - Mind Key をログに出力しない。 ログではマスクしてください（）。
> - 漏洩が疑われる場合はキーをローテーション（mind を削除し、新規作成）。
> - プロジェクトごとに 1 つの mind を使用し、キー漏洩時の被害範囲を限定。
環境変数パターン
[CODE BLOCK]
[CODE BLOCK]
MCP サーバー設定
[CODE BLOCK]
マルチ mind パターン
各ユーザーは複数の mind を持てます。よくあるパターン：
| Mind 名 | 目的 |
|-----------|---------|
| | 仕事関連のメモリ |
| | 個人の設定、家族 |
| | 特定プロジェクトのコンテキスト |
| | 学習の進捗 |
| | 汎用フォールバック |
異なる LLM セッションで異なる Mind Key を使用し、コンテキストを分離してください。
レート制限
| 認証方法 | 制限 | スコープ |
|-------------|-------|-------|
| Mind Key（ヘッダー） | なし | mind ごと |
| Mind Key（?key=） | 60/分 | IP ごと |
| JWT（ヘッダー） | なし | ユーザーごと |
| パブリックエンドポイント | なし | グローバル |
該当する場合、レスポンスにレート制限ヘッダー（、、）が含まれます。
次のステップ
- Mind Key vs JWT — どちらを使うべきか
- Memory API — Mind Key でできること
- User API — JWT によるアカウント管理
────────────────────────────────────────────────────────────
# Mind Key vs JWT — どちらを使うべきか
SUMMARY: 判断ガイド：エージェントのデータアクセスには Mind Key、アカウント管理には JWT。
KEY CONTEXT:
Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.
JWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.
Simple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.
Exception: /computers/me/* uses Computer Token (not Mind Key or JWT).
Mind Key vs JWT — どちらを使うべきか
Synapse には 2 つの認証トークンがあります。誤った方を選ぶと 401 エラーになります。本ガイドは明確な判断基準を提供します。
クイック判断表
| やりたいこと | 使用するもの |
|----------------|-----|
| メモリの保存/再取得 | Mind Key |
| チャットメッセージの送信/ポーリング | Mind Key |
| タスク管理 | Mind Key |
| スクリプトの保存 | Mind Key |
| Webhook の登録 | Mind Key |
| コンピュータの制御 | Mind Key（ユーザー側）/ Computer Token（エージェント側） |
| ユーザーアカウントの登録 | なし（パブリック） |
| ログイン | なし（パブリック） |
| mind の作成/一覧/削除 | JWT |
| 他のユーザーとの mind 共有 | JWT |
| Web Push 通知の購読 | JWT |
| 監査ログの閲覧 | Mind Key |
シンプルなルール
> [!TIP]
> 単一 mind のデータに触れる場合 → Mind Key。
> アカウントや mind メタデータを管理する場合 → JWT。
Mind Key — データアクセス権
Mind Key は1 つの mind のデータへのアクセスを許可します。期限切れにならない長期間のトークンです（mind が削除されるまで）。以下に最適です。
- セッションをまたいでメモリを永続化する LLM エージェント
- バックグラウンド cron ジョブ
- MCP サーバー設定
- Webhook 連携
- メモリを読むモバイルアプリ
Mind Key でできること
- — この mind の全メモリを読む
- — メモリの保存/更新
- — チャットメッセージの読み取り
- — チャットメッセージの送信
- — タスクの一覧
- — タスクの作成
- — スクリプトの保存
- — Webhook の登録
- — コンピュータコマンドのキューイング
Mind Key でできないこと
- mind の作成/一覧/削除（JWT が必要）
- 他のユーザーとの mind 共有（JWT が必要）
- ユーザーアカウント情報の閲覧（JWT が必要）
- Web Push の購読（JWT が必要）
JWT — アカウント管理トークン
JWT はユーザーアカウントを認証します。7 日後に期限切れとなり、複数の mind にまたがる、または他のユーザーを含むアカウントレベルの操作に使用されます。
JWT でできること
- — 新しい mind の作成（新しい Mind Key を返す）
- — このユーザーの全 mind の一覧
- — mind の削除
- — 他のユーザーとの mind 共有
- — Web Push 通知の購読
- — mind 共有の一覧
JWT でできないこと
- メモリの読み書き（Mind Key が必要）
- チャットメッセージの送信（Mind Key が必要）
- タスク管理（Mind Key が必要）
- Webhook の登録（Mind Key が必要）
特殊ケース：Computer Token
エンドポイント（エージェント向け、screen-remote-agent 用）は第 3 のトークン種別である Computer Token を使用します。このトークンはインストールコードを引き換える際に が返し、1 つの登録済みコンピュータに固有です。
| エンドポイント | 認証 |
|----------|------|
| | Computer Token |
| | Computer Token |
| | Mind Key または JWT |
| | Mind Key または JWT |
よくあるパターン
パターン 1：単一 LLM エージェント
1. 一度登録 → JWT を取得
2. 1 つの mind を作成 → Mind Key を取得
3. LLM はすべてに Mind Key を使用
パターン 2：マルチプロジェクトエージェント
1. 一度登録 → JWT を取得
2. 複数の mind を作成（work、personal、project-x）→ 複数の Mind Key を取得
3. LLM はコンテキストに応じて異なる Mind Key を読み込み
パターン 3：チーム共有
1. ユーザー A が mind を作成 → Mind Key A を取得
2. ユーザー A が JWT でユーザー B と共有（）
3. ユーザー B は自身の JWT でアクセス可能
4. LLM アクセスには、ユーザー B は自身の Mind Key を作成する必要がある（または A のものを使用）
パターン 4：MCP サーバー
MCP サーバーは常に Mind Key を使用します（ 環境変数で設定）。1 つの MCP サーバーインスタンス = 1 つの mind。マルチ mind アクセスには、複数の MCP インスタンスを動かすか、クライアント側で mind 切り替えを実装してください。
トークン形式のチートシート
| トークン | 形式 | 例 |
|-------|--------|---------|
| Mind Key | + 36 文字 | |
| JWT | + base64 | |
| Computer Token | + 36 文字 | |
次のステップ
- Authentication — 完全な認証ガイド
- User & Minds API — JWT で保護されたエンドポイント
- Memory API — Mind Key で保護されたエンドポイント
────────────────────────────────────────────────────────────
# LLM エージェント向けクイックスタート
SUMMARY: 3 つの API 呼び出しで：全メモリの再取得、新規保存、検索。LLM の必須ワークフロー。
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query)
ALWAYS call /memory/recall at the start of every session.
Wichtigste Befehle: GET /memory/recall, POST /memory, GET /memory/search?q=...
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
FTS5 search: multiple words = AND, "phrases" in quotes, prefix* for prefix search
LLM エージェント向けクイックスタート
セッション間ですべてのメモリを失います。Synapse はあなたの外部脳です。本ガイドはすべての LLM エージェントが知っておくべき 3 つの必須 API 呼び出しを示します。
> [!CRITICAL]
> 毎セッションの開始時に を呼び出してください。
> これを呼び出さないと、ユーザーが誰か、何を約束したか、前回何を作業していたかの記憶がありません。
ステップ 1：全メモリの再取得（常に最初に）
[CODE BLOCK]
保存された全メモリの構造化されたプレーンテキスト要約を返します。これを解析して、ユーザー、プロジェクト、過去のやり取りのメンタルモデルを再構築します。
レスポンス例：
[CODE BLOCK]
ステップ 2：新規メモリの保存
記憶する価値のあることを学んだら：
[CODE BLOCK]
カテゴリ： 、、、、、、、
優先度： 、、、
> [!TIP]
> 常に フィールドを含めてください — メモリの短い識別子です。同じキーで再 POST することで、後から同じメモリを更新できます。
ステップ 3：特定メモリの検索
[CODE BLOCK]
> [!TIP]
> FTS5 構文：複数単語 = AND 検索。フレーズは引用符：。プレフィックス検索：。ブール：。
オープンツール（認証ヘッダーなし）
ツールが URL しか開けない場合（カスタムヘッダーなし）、 パラメータを使用します。
[CODE BLOCK]
> [!WARNING]
> は 60 リクエスト/分にレート制限されます。Bearer ヘッダーにはレート制限がありません。可能な限り Bearer ヘッダーを使用してください。
完全なセッションワークフロー
1. セッション開始： — 全メモリを読み込む
2. 作業中： — 特定の事実を検索
3. 新情報： — 保存（category、key、tags、priority を指定）
4. 定期的に： — 人間のメッセージを確認
5. セッション終了： 最終的な学習内容を で保存
よくあるパターン
既存メモリの更新
同じ と で を呼び出すと、重複ではなく既存メモリが更新されます。
プロジェクトステータスの保存
[CODE BLOCK]
過ちの記録（繰り返しを避けるため）
[CODE BLOCK]
人間のメッセージの確認
[CODE BLOCK]
人間からの未読メッセージを返します。以下で返信：
[CODE BLOCK]
次のステップ
- Authentication — Mind Key vs JWT
- Memory API reference — 22 のメモリエンドポイントすべて
- Chat API — 人間との非同期通信
- LLM Cookbook — 実践的パターン
────────────────────────────────────────────────────────────
# クイックスタート（人間向け）
SUMMARY: アカウント登録、最初の mind の作成、メモリの保存まで — 5 分で完了。
クイックスタート（人間向け）
本ガイドでは Synapse アカウントの取得、最初の Mind Key の作成、最初のメモリの保存までを案内します。所要時間：約 5 分。
ステップ 1：アカウントの登録
Synapse API を開き、アカウントを作成します。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
> [!TIP]
> JWT を安全な場所に保存してください — mind の作成に必要です。JWT は 7 日後に期限切れになります。同じエンドポイントで再ログインして更新してください。
ステップ 2：最初の mind の作成
「mind」は分離されたメモリスコープです。ほとんどのユーザーは 1 つの mind から始めますが、複数持つこともできます（例：「work」「personal」「project-x」）。各 mind は独自のユニークな Mind Key を持ちます。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
> [!CRITICAL]
> をすぐに保存してください。 一度しか表示されず、後から取得できません。失くした場合は新しい mind を作成する必要があります。
ステップ 3：最初のメモリの保存
Mind Key を使用してメモリを保存します。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
ステップ 4：全メモリの再取得
保存したすべてを取得するには：
[CODE BLOCK]
レスポンス（プレーンテキスト、LLM 消費向けに最適化）：
[CODE BLOCK]
ステップ 5：メモリの検索
キーワードで特定のメモリを見つけます。
[CODE BLOCK]
ステップ 6：LLM の接続
LLM に Synapse へのアクセスを与える最も簡単な方法は MCP 経由です。
- Claude Desktop setup — 2 分の設定
- Claude Code setup — ターミナル連携
- Cursor setup — IDE 連携
設定後、LLM は毎セッションの開始時に自動的に を呼び出し、 で新しい事実を永続化します。
メモリのカテゴリ
Synapse は 8 カテゴリをサポート — 最も具体的なものを選んでください。
| カテゴリ | ユースケース |
|----------|----------|
| | ユーザー名、役割、連絡先情報 |
| | 好き嫌い、作業スタイル |
| | 検証可能な事実（プロジェクト詳細、日付） |
| | プロジェクトのステータス、マイルストーン、ToDo |
| | ユーザーが得意なこと |
| | 過去のエラー — 繰り返しを避ける |
| | セッション関連のコンテキスト |
| | その他のメモ |
優先度レベル
- — 知っておくとよい
- — デフォルト
- — 重要
- — 絶対に忘れてはならない（ユーザー ID、法的情報）
次のステップ
- Authentication deep-dive
- Mind Key vs JWT
- Memory API reference
- MCP integration
────────────────────────────────────────────────────────────
# Synapse とは
SUMMARY: Synapse は LLM エージェント向けの永続メモリ API — AI がセッションをまたいで忘れません。
KEY CONTEXT:
Synapse is an HTTP API that gives LLM agents persistent memory across sessions.
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query, rate-limited 60/min)
Most important endpoints: GET /memory/recall (start of every session), POST /memory (store new facts), GET /memory/search?q=...
Mind Key = tenant-scoped API key. Each user can have multiple minds (projects/contexts).
MCP server available: npx -y synapse-mcp-api (79 tools for Claude Desktop, Cursor, etc.)
Synapse とは
Synapse は LLM エージェント向けの永続メモリ API です。チャットベースの LLM が抱える根本的な問題 — セッション間でエージェントがすべてを忘れてしまう — を解決します。Synapse は AI に会話をまたぎ、日をまたぎ、異なる LLM プロバイダーをまたいで存続する永続的かつクエリ可能な脳を与えます。
> [!CRITICAL]
> これを読んでいる LLM エージェントへ：毎セッションの開始時に を呼び出してください。 これを呼び出さないと、過去のやり取りの記憶がなく、ユーザーが誰かの知識もなく、進行中のプロジェクトのコンテキストもありません。
Synapse が解決する問題
すべての最新 LLM（Claude、GPT、Gemini、Llama）は同じアーキテクチャ上の制限を持ちます。会話コンテキストウィンドウは有限で、セッションが終わるとすべての状態が失われます。つまり AI アシスタントは：
- チャット間でユーザーの名前、設定、進行中のプロジェクトを忘れる
- セッションをまたいで過去の過ちから学習できない
- 長期間の作業の継続性がない
- 毎回同じ確認質問を繰り返す
Synapse は LLM が構造化されたメモリを保存・取得できるシンプルな HTTP API を提供することでこれを解決します。メモリはサーバーに永続化され、インデックス化と検索が可能なため、将来のセッションで再取得できます。
主な機能
- 永続メモリストレージ — 事実、設定、プロジェクト、過ち、スキル
- フルテキスト検索（FTS5）— ミリ秒でキーワードから任意のメモリを検索
- セマンティック検索 — 概念クエリ向けの埋め込みベースの類似検索
- マルチテナント — 各ユーザーは分離された「minds」を持つ（1 ユーザー、多数プロジェクト）
- 非同期チャット — 人間はエージェントが作業中にメッセージを残せる
- タスク & スケジューリング — 組み込みのタスクマネージャーと cron スケジューラー
- MCP 連携 — Claude、Cursor、Continue 向けに Model Context Protocol で 79 ツールを公開
- ブラウザ & コンピュータ制御 — リモート自動化ツール
- Webhooks — メモリ/チャット/タスク変更時に HTTP コールバックを受信
仕組み
[CODE BLOCK]
1. LLM はセッション開始時に を呼び出す
2. Synapse は保存された全メモリの構造化テキスト要約を返す
3. LLM は作業し、定期的に を呼び出して新しい事実を保存
4. ユーザーが質問すると、LLM は を呼び出せる
5. セッション終了時に、重要な新しいコンテキストが次回セッションのために永続化
対象者
- 永続状態が必要な LLM エージェント開発者
- ローカル LLM（Ollama、LM Studio）とカスタムエージェントを動かす パワーユーザー
- 共有メモリが必要な AI アシスタントを構築する チーム
- セッションをまたいで LLM 呼び出しを連鎖させる 自動化エンジニア
クイック比較
| 機能 | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| ストレージ場所 | OpenAI サーバー | あなたのサーバー |
| API アクセス | なし（クローズ） | あり（REST + MCP） |
| マルチテナント | なし | あり（minds） |
| カスタムカテゴリ | なし | あり（8 カテゴリ） |
| 検索 | 限定的 | FTS5 + セマンティック |
| セルフホスト可能 | なし | あり（Docker） |
次のステップ
- Quick Start for humans — 5 分で Mind Key を取得
- Quick Start for LLMs — 最初の API 呼び出し
- Authentication — Mind Keys vs JWTs
- Architecture overview — Synapse の構築方法
## カテゴリ: APIリファレンス
すべてのAPIエンドポイントの完全なリファレンス。
────────────────────────────────────────────────────────────
# Browser Proxy
SUMMARY: ブラウザ自動化サービス — ポート 13000 で稼働するヘッドレスブラウザ制御用の別 Docker コンテナ。
KEY CONTEXT:
Browser Proxy is a SEPARATE Docker service (port 13000), NOT a Synapse endpoint.
Synapse endpoints do NOT include /browser/* paths.
For browser automation, use the MCP browser_new tool OR connect to the browser-proxy service directly.
Synapse MCP exposes browser tools (browser_new, browser_navigate, browser_click, etc.)
Browser Proxy
Browser Proxy は Playwright 経由でヘッドレスブラウザ自動化を提供する独立した Docker サービスです。Synapse API の直接の一部ではなく、Synapse エンドポイントには パスは含まれません。
アーキテクチャ
[CODE BLOCK]
アクセス方法
方法 1：Synapse MCP Server 経由（推奨）
Synapse MCP サーバーはブラウザツールを MCP ツールとして公開しています。LLM 駆動のブラウザ自動化にはこちらを使用してください。
[CODE BLOCK]
利用可能な MCP ブラウザツール：
- — 新しいブラウザタブを開く
- — URL に移動
- — 要素をクリック
- — フィールドにテキストを入力
- — スクリーンショットを取得
- — タブを閉じる
- （その他多数 — MCP 連携 を参照）
方法 2：Browser Proxy への直接アクセス
MCP を使用しない連携では、browser-proxy サービスに直接接続します。
[CODE BLOCK]
よくあるユースケース
Web スクレイピング
[CODE BLOCK]
フォーム自動化
[CODE BLOCK]
スクリーンショット取得
[CODE BLOCK]
関連サービス
| サービス | ポート | 目的 |
|---------|------|---------|
| Synapse API | 12800 | Memory、chat、tasks |
| Synapse MCP | 13100 | MCP サーバー（79 ツール） |
| Browser Proxy | 13000 | ヘッドレスブラウザ自動化 |
| SSH Proxy | 12900 | リモートマシンへの SSH アクセス |
次のステップ
- MCP 連携 — MCP 経由でのブラウザツールの使い方
- Computer Control API — 登録済みマシン上での GUI 自動化
────────────────────────────────────────────────────────────
# Chat API
SUMMARY: 人間と LLM エージェント間の非同期チャット — ポーリング、返信、履歴、未読数、ファイルアップロード。
KEY CONTEXT:
Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)
Poll: GET /chat/poll (returns unread messages, marks them as read)
Reply: POST /chat/reply { content }
History: GET /chat/history?limit=50
Unread count: GET /chat/unread?role=agent (or ?role=human)
Upload: POST /chat/upload (multipart, file attachment)
Pattern: poll between tool calls, reply when human asks questions
Chat API
Chat API は人間と LLM エージェント間の非同期メッセージングを実現します。同期型チャット（ChatGPT 形式）とは異なり、エージェントが作業中でも人間はメッセージを残すことができ、エージェントはツール呼び出しの間にポーリングします。
仕組み
[CODE BLOCK]
1. 人間が Web UI 経由でメッセージを送信（JWT を使用）
2. メッセージが保存され、未読としてマークされる
3. エージェントがツール呼び出しの間に を実行
4. ポーリングがすべての未読メッセージを返し、既読にする
5. エージェントがメッセージを処理し、必要に応じて で返信
エンドポイント
GET /chat/poll
人間からの新規メッセージをポーリングします。未読メッセージを返し、既読に変更します。ツール呼び出しの間に使用してください。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
POST /chat/reply
エージェントとしてメッセージを送信します。
[CODE BLOCK]
POST /chat/send
人間としてメッセージを送信します（Mind Key ではなく JWT が必要）。
[CODE BLOCK]
GET /chat/history
最近のチャット履歴（両ロール）を取得します。
[CODE BLOCK]
GET /chat/unread
未読メッセージ数を取得します。
[CODE BLOCK]
GET /chat/status
チャットセッションのステータス（最終メッセージのタイムスタンプ、未読数）を取得します。
[CODE BLOCK]
POST /chat/upload
特定のメッセージに対するファイル添付をアップロードします（multipart 形式）。
[CODE BLOCK]
GET /chat/files/:messageid
メッセージのファイル添付一覧を取得します。
[CODE BLOCK]
GET /chat/file/:fileid
ファイル添付をダウンロードします。
[CODE BLOCK]
ポーリングパターン
> [!TIP]
> ツール呼び出しの間に 30〜60 秒ごとにポーリングしてください。これより頻繁なポーリングは API クォータを無駄に消費するだけで、メリットはありません。
[CODE BLOCK]
次のステップ
- Tasks API
- Chat Polling Pattern
────────────────────────────────────────────────────────────
# Computer Control API
SUMMARY: 登録済みコンピュータのリモート制御 — コマンドのキューイング、スクリーンショット取得、リモートマシン上でのスクリプト実行。
KEY CONTEXT:
Two sides: user-facing (Mind Key/JWT) and agent-facing (Computer Token)
Register agent: POST /computers/register { install_code } → returns computer_token
List: GET /computers/list (Mind Key or JWT)
Queue command: POST /computers/:id/commands { type, payload }
Command types: screenshot, click, move, type, key, scroll, drag
Agent poll: GET /computers/me/poll?wait=5 (Computer Token)
Agent result: POST /computers/me/commands/:cid/result (Computer Token)
One-shot screenshot: GET /computers/:id/screenshot (waits 30s for result)
Pattern: register agent on remote machine → user queues commands → agent polls and executes
Computer Control API
Computer Control API は登録済みコンピュータをリモート制御するための API です。対象マシン上で小型のエージェント（）が動作し、コマンドをポーリングして実行し、結果を報告します。これにより LLM 駆動の GUI 自動化が可能になります。
アーキテクチャ
[CODE BLOCK]
ユーザー向けエンドポイント（Mind Key または JWT）
GET /computers/list
登録済みの全コンピュータを一覧表示します。
[CODE BLOCK]
GET /computers/:id
単一コンピュータの詳細を取得します。
[CODE BLOCK]
POST /computers/install-code
新規コンピュータ登録用のインストールコードを生成します。
[CODE BLOCK]
レスポンス：
POST /computers/:id/commands
リモートエージェントが実行するコマンドをキューに追加します。
[CODE BLOCK]
レスポンス：
GET /computers/:id/command（クエリ経由）
GET リクエストでコマンドをキューに追加します（単純なケース向け）。
[CODE BLOCK]
GET /computers/:id/commands
コンピュータの最近のコマンド一覧を取得します。
[CODE BLOCK]
GET /computers/:id/commands/:cid
特定コマンドのステータスと結果を取得します。
[CODE BLOCK]
GET /computers/:id/screenshot
ワンショット：スクリーンショットコマンドをキューに追加し、最大 30 秒待って結果を取得します。
[CODE BLOCK]
POST /computers/:id/disable
コンピュータを無効化します（トークンを失効させ、監査用にレコードは保持）。
[CODE BLOCK]
DELETE /computers/:id
コンピュータを完全に削除します。
[CODE BLOCK]
エージェント向けエンドポイント（Computer Token）
これらのエンドポイントは対象マシン上で動作する が使用します。Mind Key ではなく、Computer Token（ が返す）を使用します。
POST /computers/register
インストールコードを引き換えて Computer Token を取得します。
[CODE BLOCK]
レスポンス：
> [!CRITICAL]
> を必ず保存してください。表示は一度きりで、エージェント側の全エンドポイントで必要になります。
GET /computers/me/poll
新規コマンドをロングポーリングします。エージェントはこれをループで呼び出します。
[CODE BLOCK]
保留中のコマンドがあれば即座に返されます。ない場合は 秒後に返されます。
POST /computers/me/commands/:cid/result
コマンド実行の結果を投稿します。
[CODE BLOCK]
コマンド種別
| 種別 | Payload | 説明 |
|------|---------|-------------|
| | | 画面を PNG（base64）で取得 |
| | | 座標をクリック |
| | | 座標にマウスを移動 |
| | | カーソル位置にテキストを入力 |
| | | キーコンビネーションを押下 |
| | | ホイールをスクロール |
| | | ドラッグ＆ドロップ |
よくあるパターン：LLM 駆動の GUI 自動化
[CODE BLOCK]
次のステップ
- Browser Proxy — ブラウザ自動化用の別サービス
- Self-Hosted Agents Guide
────────────────────────────────────────────────────────────
# Cron & Scheduler
SUMMARY: 定期実行される API 呼び出しのスケジュール設定 — 定期的な同期やリマインダーに最適な Cron ジョブ。
KEY CONTEXT:
Auth: Mind Key
Create: POST /cron { schedule, endpoint, method?, body?, headers?, enabled? }
List: GET /cron
Delete: DELETE /cron/:id
Toggle: PUT /cron/:id/toggle
Schedule: 5-field cron (minute hour day month day-of-week) OR integer interval (seconds)
Endpoint: must be http(s) URL, same Synapse instance OR public HTTPS (no private IPs)
Pattern: schedule /memory/recall every hour, /chat/poll every 5 min, etc.
Cron & Scheduler
Cron API は Synapse エンドポイント（または外部 HTTPS エンドポイント）に対する定期 HTTP 呼び出しをスケジュール設定できる API です。定期同期、リマインダー、メンテナンスタスクに最適です。
エンドポイント
POST /cron
スケジュールタスクを作成します。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
GET /cron
すべてのスケジュールタスクを一覧表示します。
[CODE BLOCK]
DELETE /cron/:id
スケジュールタスクを削除します。
[CODE BLOCK]
PUT /cron/:id/toggle
タスクを削除せずに有効化/無効化を切り替えます。
[CODE BLOCK]
スケジュール構文
標準 Cron（5 フィールド）
[CODE BLOCK]
例：
| Schedule | 意味 |
|----------|---------|
| | 毎時 |
| | 15 分ごと |
| | 平日の午前 9 時 |
| | 毎週日曜日の深夜 |
| | 毎月 1 日の深夜 |
整数間隔（秒）
単純な間隔の場合は整数を指定します。
[CODE BLOCK]
エンドポイントの制限
> [!WARNING]
> エンドポイントは以下を指す または URL でなければなりません：
> - 同じ Synapse インスタンス（例：）
> - パブリック HTTPS URL（プライベート IP、localhost、メタデータ IP は不可）
これは、侵害された mind が内部サービスに対してリクエストをスケジュールする SSRF 攻撃を防ぐためです。
よくあるパターン
毎時のメモリ再取得（LLM エージェント向け）
[CODE BLOCK]
毎日のバックアップ
[CODE BLOCK]
定期的なチャットポーリング（5 分ごと）
[CODE BLOCK]
週次レポートトリガー
[CODE BLOCK]
次のステップ
- Variables API
- Webhooks API
────────────────────────────────────────────────────────────
# Errors & Error Handling
SUMMARY: HTTP ステータスコード、エラーレスポンス形式、よくあるエラーからの復旧方法。
KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.
Errors & Error Handling
Synapse は標準的な HTTP ステータスコードと一貫したエラーレスポンス形式を使用します。本ページではエラーの解釈と復旧方法を説明します。
エラーレスポンス形式
すべてのエラーは以下の構造の JSON を返します。
[CODE BLOCK]
| フィールド | 説明 |
|-------|-------------|
| | HTTP ステータスコード |
| | HTTP ステータス名 |
| | 人間が読めるエラーの説明 |
| | 関連ドキュメントの URL（該当する場合） |
HTTP ステータスコード
200 OK
成功。リクエストが正常に処理されました。
201 Created
成功。新しいリソースが作成されました（例：）。
204 No Content
成功。レスポンスボディはありません（例：）。
400 Bad Request
リクエストの形式が不正です。よくある原因：
- 必須 JSON フィールドの欠落
- 無効な JSON 構文
- 無効な enum 値（例：カテゴリの誤り）
[CODE BLOCK]
対策： リクエストボディを API ドキュメントと照合してください。すべての必須フィールドが存在し、有効な値であることを確認します。
401 Unauthorized
認証に失敗しました。よくある原因：
- ヘッダーの欠落
- 無効な Mind Key または JWT
- Mind Key が必要な場所で JWT を使用（またはその逆）
[CODE BLOCK]
対策： トークンを確認してください。Authentication を参照。
403 Forbidden
認証は成功していますが、このアクションの実行が許可されていません。よくある原因：
- 他のユーザーの mind を削除しようとした
- Mind Key でメモリを検証しようとした（JWT が必要）
- mind が無効化されている
対策： このエンドポイントに対して正しいトークン種別を使用しているか確認してください。
404 Not Found
要求されたパスまたはリソースが存在しません。
> [!CRITICAL]
> エンドポイントのパスを推測しないでください。 にリストされたパスのみが存在します。404 が返された場合は、誤ったパスを使用しています。
[CODE BLOCK]
対策： を呼び出して有効なエンドポイントのリストを確認してください。URL をリストと文字単位で比較してください。
409 Conflict
リクエストが既存の状態と競合しています。よくある原因：
- 既に存在するメールアドレスで登録しようとした
- Webhook URL の重複
対策： 別の値を使用するか、 で既存リソースを更新してください。
429 Too Many Requests
レート制限に達しました。 クエリパラメータ認証（60 回/分）にのみ適用されます。
[CODE BLOCK]
レスポンスヘッダー：
[CODE BLOCK]
対策： ヘッダーに切り替える（レート制限なし）、または 秒待機してください。
500 Internal Server Error
サーバーエラーです。本来発生すべきではありません。発生した場合はバグです。
対策：
1. 指数バックオフで再試行（1 秒、2 秒、4 秒、8 秒）
2. でサーバー稼働状況を確認
3. 持続する場合はエラーを報告
503 Service Unavailable
サーバーが一時的に停止しています（デプロイ中やデータベースマイグレーション中など）。
対策： 待機して再試行してください。 を確認。
復旧パターン
指数バックオフでの再試行
[CODE BLOCK]
認証エラーの処理
[CODE BLOCK]
よくあるエラーシナリオ
"Mind Key fehlt oder ungültig"
- ヘッダーを忘れた
- を使用したがキーが間違っている
- Mind Key が必要な場所で JWT を使用している
"Route not found"
- 存在しないパスを推測した
- 動詞を誤使用（例： と ）
- で有効なパスを確認
"Rate limit exceeded"
- を使用して 60 回/分を超えた
- ヘッダーに切り替える
次のステップ
- Authentication
- API Overview
- Rate Limits
────────────────────────────────────────────────────────────
# Memory API
SUMMARY: 22 のメモリエンドポイントの完全リファレンス — 保存、再取得、検索、セマンティック検索、同期、監査など。
KEY CONTEXT:
Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)
ALWAYS call GET /memory/recall at session start.
POST /memory with same category+key updates the existing memory.
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
Search: GET /memory/search?q=... (FTS5 syntax: AND, OR, "phrases", prefix*)
Semantic: GET /memory/semantic-search?q=... (slower, conceptual)
Sync: GET /memory/diff?since=TIMESTAMP (incremental sync)
Export: GET /memory/mind-export (full JSON dump)
Memory API
Memory API は Synapse の中核です。構造化されたメモリの保存、取得、検索、管理のための 22 のエンドポイントを提供します。すべてのエンドポイントで認証に Mind Key が必要です。
> [!CRITICAL]
> 毎セッションの開始時に必ず を呼び出してください。 これが、前回のセッションからコンテキストを再構築する唯一の方法です。
カテゴリ
メモリは 8 つのカテゴリに整理されます。
| カテゴリ | ユースケース |
|----------|----------|
| | ユーザー名、役割、連絡先情報、自己に関する設定 |
| | 好き嫌い、作業スタイル、コミュニケーションの好み |
| | 検証可能な事実（プロジェクト詳細、日付、URL） |
| | プロジェクトのステータス、マイルストーン、アーキテクチャ |
| | ユーザーが得意なこと |
| | 過去のエラー — 繰り返しを避ける |
| | セッション関連のコンテキスト |
| | その他のメモ |
優先度
- — 知っておくとよい
- — デフォルト
- — 重要
- — 絶対に忘れてはならない（ユーザー ID、法的情報）
コアエンドポイント
GET /memory/recall
すべてのメモリを LLM 向けに最適化されたプレーンテキストで返します。毎セッションの開始時に呼び出してください。
[CODE BLOCK]
レスポンス（text/plain）：
[CODE BLOCK]
POST /memory
新しいメモリを保存するか、既存のメモリを更新します（同じ category + key なら更新）。
[CODE BLOCK]
レスポンス：
GET /memory
オプションのフィルタ付きでメモリを一覧表示します。
[CODE BLOCK]
PUT /memory/:id
ID で特定のメモリを更新します。
[CODE BLOCK]
DELETE /memory/:id
単一メモリを削除します。
[CODE BLOCK]
検索エンドポイント
GET /memory/search
FTS5 を使用したフルテキスト検索です。
[CODE BLOCK]
FTS5 構文：
- 複数単語 = AND：
- フレーズ：
- プレフィックス：
- ブール：
- 除外：
GET /memory/semantic-search
埋め込みを使用した概念検索（FTS5 より遅いが意味を理解）。
[CODE BLOCK]
キーワードが一致しなくても、クエリと意味的に類似したメモリを返します。X が異なる表現で記述されている「X に関するメモリを見つける」といった場合に有用です。
GET /memory/by-tag
タグでメモリを一覧表示します。
[CODE BLOCK]
GET /memory/related/:id
特定のメモリに関連するメモリを（共通タグ経由で）見つけます。
[CODE BLOCK]
同期 & Diff
GET /memory/diff
差分同期 — 指定タイムスタンプ以降に変更されたメモリを返します。
[CODE BLOCK]
レスポンス：
POST /memory/sync
別インスタンスからの diff を適用します（セルフホスト同期用）。
[CODE BLOCK]
一括操作
POST /memory/bulk-delete
ID で複数のメモリを削除します。
[CODE BLOCK]
POST /memory/embed-batch
まだ埋め込みを持たないメモリの埋め込みを生成します（セマンティック検索用）。
[CODE BLOCK]
GET /memory/embed-batch-status
埋め込み生成の進捗を確認します。
[CODE BLOCK]
検証
メモリには フラグがあります。エージェントが保存したメモリはデフォルトで未検証（）、人間が保存したメモリは検証済み（）です。
POST /memory/verify
メモリを検証済みとしてマークします（Mind Key ではなく JWT が必要）。
[CODE BLOCK]
POST /memory/unverify
メモリを未検証としてマークします（JWT が必要）。
[CODE BLOCK]
GET /memory/unverified
人間の検証待ちのメモリを一覧表示します。
[CODE BLOCK]
統計 & 監査
GET /memory/stats
現在の mind の集計統計です。
[CODE BLOCK]
返却値：
GET /memory/audit
状態を変更する全操作の監査ログです。
[CODE BLOCK]
GET /memory/contradictions
保存されたメモリ内の潜在的矛盾を検出します。
[CODE BLOCK]
GET /memory/expiring
有効期限が近づいているメモリを一覧表示します。
[CODE BLOCK]
ヘルス & エクスポート
GET /memory/health
メモリシステムのクイックヘルスチェックです。
[CODE BLOCK]
GET /memory/mind-export
全メモリの完全 JSON エクスポート（バックアップ用）。
[CODE BLOCK]
POST /memory/compact
類似メモリを圧縮します（自動要約）。
[CODE BLOCK]
次のステップ
- Quick Start for LLMs
- Memory Best Practices
- FTS5 Search
- Semantic Search
────────────────────────────────────────────────────────────
# API 概要 & ベース URL
SUMMARY: Synapse API の全エンドポイント、ベース URL、認証パターン、レスポンス形式を一覧でご紹介します。
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)
OR ?key=YOUR_MIND_KEY (query, 60 req/min)
All responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)
All 404 responses mean the path does not exist — do NOT guess paths.
GET /endpoints returns machine-readable list of all valid endpoints.
API 概要 & ベース URL
Synapse API は RESTful な HTTP API です。特記のない限り、すべてのエンドポイントは JSON を返します。本ページでは、各エンドポイントの詳細に入る前に知っておくべき基本事項を説明します。
ベース URL
[CODE BLOCK]
本ドキュメント内のすべてのパスは、このベース URL に対する相対パスです。セルフホスト環境の場合は、ご自身の URL に置き換えてください。
認証
2 種類の方法があり、いずれも ヘッダーで送信します。
[CODE BLOCK]
またはクエリパラメータで送信することも可能です（60 回/分にレート制限されます）。
[CODE BLOCK]
詳しくは Authentication を参照してください。
エンドポイントグループ
| グループ | 認証 | 説明 |
|-------|------|-------------|
| Public | なし | ランディングページ、ヘルスチェック、OpenAPI、ドキュメント |
| Memory | Mind Key | CRUD、検索、同期、埋め込み |
| Chat | Mind Key / JWT | 人間とエージェント間の非同期メッセージング |
| Tasks | Mind Key | タスク管理 |
| Scripts | Mind Key / JWT | 永続スクリプトストア |
| Scheduler | Mind Key | Cron ジョブ + 変数 |
| Webhooks | Mind Key | イベント時の HTTP コールバック |
| Computers | Mind Key / JWT | リモートコンピュータ制御 |
| User/Minds | JWT | アカウント + mind 管理 |
| Sharing | JWT | ユーザー間の mind 共有 |
| Push | JWT | Web Push サブスクリプション |
| Tools | なし | 時刻、電卓、乱数（パブリックユーティリティ） |
レスポンス形式
- JSON（デフォルト）：
- プレーンテキスト： は LLM 向けに最適化されたテキストを返します
- HTML：、、、、
標準レスポンスエンベロープ
成功時のレスポンスはデータを直接返します。
[CODE BLOCK]
エラー時のレスポンスは以下の形式を使用します。
[CODE BLOCK]
> [!NOTE]
> フィールドは、よくあるエラーに関するドキュメントへのリンクを提供します。
HTTP ステータスコード
| コード | 意味 |
|------|---------|
| 200 | 成功（GET、PUT） |
| 201 | 作成済み（POST） |
| 204 | コンテンツなし（DELETE） |
| 400 | 不正なリクエスト（バリデーションエラー） |
| 401 | 認証エラー（トークン missing/invalid） |
| 403 | 禁止（トークン種別の不一致） |
| 404 | 見つからない（パスが存在しない） |
| 409 | 競合（重複） |
| 429 | リクエスト過多（レート制限） |
| 500 | サーバーエラー |
探索用エンドポイント
| エンドポイント | 目的 |
|----------|---------|
| | ランディングページ（LLM 向け最適化） |
| | すべてのエンドポイントの機械可読リスト |
| | プレーンテキスト形式のエンドポイントリスト |
| | OpenAPI 3.0 仕様 |
| | 完全な API ドキュメント（HTML） |
| | JSON 形式の API ドキュメント |
| | ドキュメントシステム（HTML） |
| | ドキュメントインデックス（JSON） |
| | すべてのドキュメントを 1 つのテキストブロックで |
| | インタラクティブな API プレイグラウンド |
レート制限
| 認証方法 | 制限 |
|-------------|-------|
| Mind Key（ヘッダー） | なし |
| Mind Key（?key=） | 60 回/分（IP ごと） |
| JWT（ヘッダー） | なし |
| パブリックエンドポイント | なし |
レート制限対象のレスポンスには以下が含まれます。
[CODE BLOCK]
ページネーション
リストエンドポイントは と をサポートしています。
[CODE BLOCK]
デフォルトの limit：100。最大 limit：500。
CORS
すべてのエンドポイントはブラウザベースのクライアント向けに CORS をサポートしています。
[CODE BLOCK]
SDK & クライアント
- Node.js SDK：（リポジトリ）
- MCP Server：（リポジトリ）
- HTTP クライアント：任意の HTTP ライブラリ（curl、fetch、axios など）
次のステップ
- Memory API — 最も重要なエンドポイント
- Chat API — 人間とエージェント間の非同期通信
- Errors & Error Handling
────────────────────────────────────────────────────────────
# Rate Limits & Quotas
SUMMARY: Synapse API のレート制限ポリシー — Bearer ヘッダー（無制限）、?key=（60 回/分）、パブリックエンドポイント。
KEY CONTEXT:
Mind Key (Authorization: Bearer header) → NO rate limit
Mind Key (?key= query param) → 60 req/min per IP
JWT (Authorization: Bearer header) → NO rate limit
Public endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
Recommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.
Rate Limits & Quotas
Synapse はシンプルで予測可能なレート制限ポリシーを採用しており、悪用を防ぎつつ正当な利用を妨げません。
レート制限ポリシー
| 認証方法 | 制限 | スコープ |
|-------------|-------|-------|
| Mind Key（） | なし | mind ごと |
| Mind Key（） | 60 回/分 | IP ごと |
| JWT（） | なし | ユーザーごと |
| パブリックエンドポイント | なし | グローバル |
> [!TIP]
> 可能な限り常に ヘッダーを使用してください。 レート制限がありません。 はカスタムヘッダーを設定できないツールでのみ使用してください。
レート制限ヘッダー
認証を使用する場合、レスポンスにレート制限ヘッダーが含まれます。
[CODE BLOCK]
制限を超過した場合：
[CODE BLOCK]
レート制限に達した場合
429 を受け取った場合：
1. Authorization ヘッダーに切り替える（推奨）：
[CODE BLOCK]
2. または 秒待機してから再試行してください。
?key= 制限が存在する理由
クエリパラメータは URL 単体のツール（ブラウザ、 コマンド）に便利ですが、セキュリティとパフォーマンスの懸念があります。
- セキュリティ： クエリパラメータはサーバーのアクセスログ、ブラウザ履歴、Referer ヘッダーに記録されます。利用を制限することで露出を減らせます。
- パフォーマンス： クエリパラメータ認証は IP ベースのレートリミッタを必要とし（リクエストごとに Redis ルックアップ）、レイテンシが増加します。ヘッダー認証はこれをスキップします。
- 悪用防止： 流出した URL は共有され大量リクエストを受ける可能性があります。IP 制限は被害範囲を限定します。
推奨パターン
LLM エージェント
[CODE BLOCK]
ブラウザベースのツール
ツールが URL を開くことしかできない場合：
[CODE BLOCK]
MCP サーバー
MCP サーバーは常に 環境変数経由でヘッダー認証を使用します — レート制限は適用されません。
一括インポート
一括操作（例：1000 件のメモリインポート）では、常にヘッダー認証を使用してください。 経由の一括インポートは 1 分以内にレート制限に達します。
クォータ（mind レベル）
現在、ストレージサイズやメモリ数に関する mind ごとのクォータはありません。すべての制限はデータレベルではなく、認証/IP レベルです。マルチテナントの公平性のため、将来的に変更される可能性があります。
利用状況の監視
[CODE BLOCK]
次のステップ
- Authentication
- Errors & Error Handling
────────────────────────────────────────────────────────────
# Scripts API
SUMMARY: 永続スクリプトストア — 再利用可能なシェル、Python、Node スクリプトを保存し、curl | bash で取得。
KEY CONTEXT:
Auth: Mind Key or JWT
Store: POST /script { name, content, description?, language? }
Fetch as text: GET /script/:name (returns text/plain, curl | bash ready)
Info: GET /script/:name/info (metadata without content)
List: GET /scripts (JSON array)
Delete: DELETE /script/:name
Use case: store deployment scripts, config generators, troubleshooting snippets
Scripts API
Scripts API は再利用可能なスクリプトのための永続ストアを提供します。スクリプトは mind 内で名前付きかつバージョン管理され、プレーンテキストとして取得できます — パターンに最適です。
エンドポイント
POST /script
スクリプトを保存または更新します。
[CODE BLOCK]
GET /script/:name
スクリプトの内容を で取得します。bash にパイプするのに最適です。
[CODE BLOCK]
GET /script/:name/info
内容を含まずにスクリプトのメタデータを取得します。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
GET /scripts
現在の mind 内のすべてのスクリプトを一覧表示します。
[CODE BLOCK]
DELETE /script/:name
スクリプトを削除します。
[CODE BLOCK]
よくあるユースケース
デプロイスクリプト
標準的なデプロイ手順を保存することで、LLM が毎回手順を再導出せずに実行できます。
[CODE BLOCK]
トラブルシューティングスニペット
よくある問題の診断コマンドを保存します。
[CODE BLOCK]
設定ファイルジェネレータ
設定を生成するスクリプトを保存します。
[CODE BLOCK]
次のステップ
- Variables API
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Tasks API
SUMMARY: LLM エージェント向けのタスク管理 — 優先度付きでタスクの作成、一覧、更新、完了、削除。
KEY CONTEXT:
Auth: Mind Key
List: GET /mind/tasks?status=pending|in_progress|done|cancelled|all
Create: POST /mind/task { title, description?, priority?, due_at? }
Update: PUT /mind/task/:id { title?, description?, priority?, status?, due_at? }
Complete: GET /mind/task/:id/complete
Delete: GET /mind/task/:id/delete
Priorities: low, normal, high, critical
Statuses: pending, in_progress, done, cancelled
Pattern: create tasks for multi-step work, update status as you progress
Tasks API
Tasks API は LLM エージェントが多段階の作業を追跡するための構造化された手段を提供します。タスクは現在の mind にスコープされ、セッションをまたいで永続化されるため、エージェントは中断した箇所から作業を再開できます。
エンドポイント
GET /mind/tasks
現在の mind の全タスクを一覧表示します。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
POST /mind/task
新しいタスクを作成します。
[CODE BLOCK]
GET /mind/task（クエリパラメータ）
GET リクエストでタスクを作成します（URL 単体のツール向け）。
[CODE BLOCK]
PUT /mind/task/:id
既存のタスクを更新します。
[CODE BLOCK]
GET /mind/task/:id/complete
タスクを完了としてマークします。
[CODE BLOCK]
GET /mind/task/:id/delete
タスクを完全に削除します。
[CODE BLOCK]
優先度
- — 緊急でない
- — デフォルト
- — 重要
- — すぐにやるべき
ステータス
- — 作成済み、未着手
- — 現在作業中
- — 完了
- — 中止
パターン：タスク駆動ワークフロー
[CODE BLOCK]
次のステップ
- Task-Driven Workflow
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Utility Tools（time、calc、random）
SUMMARY: パブリックユーティリティエンドポイント — サーバー時刻、安全な電卓、乱数ジェネレータ。認証不要。
KEY CONTEXT:
No auth required for any /tools/* endpoint.
GET /tools/time → { time, timezone, offset }
GET /tools/calc?expr=(10+5)*3 → { result, expr } (safe, no eval, arithmetic only)
GET /tools/random?type=uuid → { value, type } (types: uuid, int, float, hex, alpha)
Use case: LLM agents that need current time, safe math, or random values.
Utility Tools
エンドポイントはパブリックユーティリティです — 認証は不要です。サーバー側の時刻、安全な計算、乱数値が必要な LLM エージェントに有用です。
GET /tools/time
現在のサーバー時刻、タイムゾーン、UTC オフセットを取得します。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
ユースケース：スケジューリング、タイムスタンプ、相対日付計算で「今何時か」を知る必要がある LLM エージェント。
GET /tools/calc
安全な電卓 — 算術のみで、 は使用しません。、、、、、、、数値をサポートします。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
> [!TIP]
> 頭の中や文字列解析で計算する代わりにこちらを使用してください。安全（コードインジェクションの可能性なし）かつ正確です。
サポートされる演算子
- 加算
- 減算
- 乗算
- 除算
- 剰余
- 括弧
- 数値（整数と小数）
例
[CODE BLOCK]
GET /tools/random
乱数値を生成します。
[CODE BLOCK]
タイプパラメータ
| タイプ | パラメータ | 出力 |
|------|-----------|--------|
| | なし | UUID v4 文字列 |
| | 、（デフォルト 0-100） | 整数 |
| | 、（デフォルト 0-100） | 浮動小数点 |
| | 、（長さ範囲、デフォルト 8-16） | 16 進数文字列 |
| | 、（長さ範囲、デフォルト 8-16） | アルファベット文字列 |
LLM エージェントのユースケース
ユニーク ID の生成
[CODE BLOCK]
パーセンテージの計算
[CODE BLOCK]
現在のタイムスタンプの取得
[CODE BLOCK]
テストデータの生成
[CODE BLOCK]
次のステップ
- API Overview — 全エンドポイントグループ
- Errors & Error Handling
────────────────────────────────────────────────────────────
# User & Minds API
SUMMARY: アカウント管理 — 登録、ログイン、mind の作成・一覧・削除。JWT で保護。
KEY CONTEXT:
Auth: JWT (from /register or /login)
Register: POST /register { email, password, display_name? } → returns JWT
Login: POST /login { email, password } → returns JWT
Create mind: POST /minds { name, description? } → returns mind_key (shown once!)
List minds: GET /minds
Delete mind: DELETE /minds/:id (irreversible — deletes all memories!)
JWT expires after 7 days. Mind Key never expires.
Mind Key is shown only once at creation — save it permanently.
User & Minds API
User & Minds API はアカウント管理を扱います。これらのエンドポイントはアカウントレベル（mind レベルではなく）で動作するため、Mind Key ではなく JWT 認証を使用します。
認証エンドポイント
POST /register
新規ユーザーアカウントを作成します。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
POST /login
既存アカウントにログインします。
[CODE BLOCK]
レスポンス： と同じ。
Minds エンドポイント
POST /minds
新しい mind を作成します。Mind Key を返します — すぐに保存してください。一度しか表示されません。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
> [!CRITICAL]
> は一度しか表示されません。紛失した場合は再取得できず、mind を削除して新規作成する必要があります（保存された全メモリが失われます）。
GET /minds
現在のユーザーの全 mind を一覧表示します。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
DELETE /minds/:id
mind を完全に削除します。
[CODE BLOCK]
> [!WARNING]
> mind の削除は取り消せません。その mind 内の全メモリ、タスク、チャット履歴、スクリプトが完全に失われます。バックアップが必要な場合は、事前に でエクスポートしてください。
マルチ mind パターン
ほとんどのユーザーは、コンテキストを分離するために複数の mind を作成すると便利です。
[CODE BLOCK]
異なる LLM セッションで異なる Mind Key を使用することで、コンテキストを分離できます。
アカウントセキュリティ
パスワード要件
- 最低 6 文字
- 上限なし（パスワードマネージャーの使用を推奨）
- bcrypt ハッシュで保存（プレーンテキストにはなりません）
JWT の有効期限
JWT は 7 日後に期限切れになります。期限切れの場合は、再度 を呼び出してください。
Mind Key のセキュリティ
Mind Key は期限切れになりません。Mind Key が侵害された場合：
1. で新しい mind を作成
2. LLM 設定を新しい Mind Key で更新
3. で侵害された mind を削除
次のステップ
- Authentication — 完全な認証ガイド
- Mind Key vs JWT — 判断ガイド
- Sharing API — 他のユーザーとの mind 共有
────────────────────────────────────────────────────────────
# Variables API
SUMMARY: LLM 向けの高速キーバリューストア — カウンター、フラグ、最終閲覧タイムスタンプ、部分進捗。
KEY CONTEXT:
Auth: Mind Key
Set: POST /var { key, value }
Get: GET /var/:key
List: GET /var
Delete: DELETE /var/:key
Use case: store last-seen timestamps, counters, flags, partial workflow state
Faster than memory (PostgreSQL direct, no FTS5 indexing)
Not for: structured facts (use /memory), long content (use /script)
Variables API
Variables API は一時的な状態のための高速キーバリューストアです。メモリ（インデックス化、検索可能、構造化）とは異なり、変数は迅速な読み書きアクセスに最適化されており、カウンター、フラグ、セッション状態に最適です。
エンドポイント
POST /var
変数を設定または更新します。
[CODE BLOCK]
GET /var/:key
単一変数を取得します。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
GET /var
すべての変数を一覧表示します。
[CODE BLOCK]
DELETE /var/:key
変数を削除します。
[CODE BLOCK]
変数とメモリの使い分け
| ユースケース | 使用するもの |
|----------|-----|
| ユーザー名、設定 | Memory（検索可能、構造化） |
| 最終セッションのタイムスタンプ | Variable（一時状態） |
| カウンター（例：送信メッセージ数） | Variable（頻繁な更新） |
| ワークフロー状態（「5 ステップ中 3 ステップ完了」など） | Variable（一時的） |
| 長文のプロジェクトメモ | Memory（フルテキストインデックス付き） |
| 再利用可能なスクリプト | Script store（名前付き、バージョン管理） |
よくあるパターン
最終セッションの追跡
[CODE BLOCK]
カウンターパターン
[CODE BLOCK]
フィーチャーフラグ
[CODE BLOCK]
次のステップ
- Memory API — 構造化された検索可能なデータ向け
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Webhooks API
SUMMARY: メモリ、チャット、タスクイベントに対する HTTP コールバックの登録 — データ変更時に通知を受信。
KEY CONTEXT:
Auth: Mind Key
Register: POST /webhooks { url, events, secret? }
List: GET /webhooks
Get: GET /webhooks/:id
Update: PUT /webhooks/:id { url?, events?, secret?, enabled? }
Delete: DELETE /webhooks/:id
Events: memory.*, memory.store, memory.update, memory.delete, chat.*, chat.message_received, task.*, task.created, task.completed
Secret: HMAC-SHA256 signed payload, sent in X-Synapse-Signature header
Pattern: register webhook → receive POST → process event → call Synapse API
Webhooks API
Webhooks を使用すると、Synapse でイベントが発生した際に HTTP コールバックを受信できます。外部自動化のトリガー、通知の送信、他システムへの同期に最適です。
エンドポイント
POST /webhooks
新しい Webhook を登録します。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
GET /webhooks
現在の mind のすべての Webhook を一覧表示します。
[CODE BLOCK]
GET /webhooks/:id
単一の Webhook を取得します。
[CODE BLOCK]
PUT /webhooks/:id
Webhook を更新します（URL、events、secret、enabled フラグ）。
[CODE BLOCK]
DELETE /webhooks/:id
Webhook を削除します。
[CODE BLOCK]
イベント種別
| パターン | 発生タイミング |
|---------|------------|
| | 任意のメモリイベント |
| | 新規メモリの保存 |
| | メモリの更新 |
| | メモリの削除 |
| | 任意のチャットイベント |
| | 人間からの新規メッセージ |
| | 任意のタスクイベント |
| | 新規タスクの作成 |
| | タスクの完了マーク |
| | 全イベント |
Webhook ペイロード
イベント発生時、Synapse はあなたの URL に POST リクエストを送信します。
[CODE BLOCK]
署名検証
を設定すると、Synapse は各ペイロードを HMAC-SHA256 で署名します。
[CODE BLOCK]
ハンドラで検証します：
[CODE BLOCK]
パターン：リアルタイム同期
[CODE BLOCK]
次のステップ
- Cron & Scheduler
- Webhook Automation Guide
## カテゴリ: MCP統合
Claude、Cursor、その他のMCPクライアントとの統合。
────────────────────────────────────────────────────────────
# Claude Code での MCP
SUMMARY: Claude Code ターミナルエージェントから Synapse ツールを使用 — コーディングセッションの永続的メモリ。
KEY CONTEXT:
Claude Code config: ~/.claude/config.json (or via `claude mcp add` command)
Command: npx -y synapse-mcp-api@latest
Env: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional)
Alternative: `claude mcp add synapse -- npx -y synapse-mcp-api@latest`
Then: set SYNAPSE_MIND_KEY env var in your shell
Test: in claude code, type "recall all my memories"
Claude Code での MCP
Claude Code は Anthropic のターミナルベースのコーディングエージェントです。Synapse MCP により、Claude Code はコーディングセッションをまたぐ永続的メモリを得ます — プロジェクトコンテキスト、過去の決定、コードベースのパターンを記憶します。
セットアップ
方法 1：CLI コマンド（推奨）
[CODE BLOCK]
方法 2：設定ファイルを編集
を編集します：
[CODE BLOCK]
動作確認
Claude Code を起動します：
[CODE BLOCK]
Claude Code プロンプトで次のように入力します：
[CODE BLOCK]
Claude は を呼び出し、保存されたメモリで応答するはずです。
よくあるパターン
プロジェクトコンテキストの永続化
コーディングセッション開始時に：
[CODE BLOCK]
Claude は を呼び出し、プロジェクトリストを確認して、前回中断した箇所から作業を続けます。
コードベースの決定
アーキテクチャの決定を行うとき：
[CODE BLOCK]
Claude は をカテゴリ 、優先度 で呼び出します。
過去の失敗の回避
[CODE BLOCK]
Claude はカテゴリ のメモリを検索し、過去のエラーを思い出させます。
タスク追跡
[CODE BLOCK]
Claude は を呼び出し、タスクはセッションをまたいで永続します。
ツールプロファイル
119 個すべてのツールを必要としないコーディングセッション用：
[CODE BLOCK]
トラブルシューティング
MCP サーバーが起動しない
[CODE BLOCK]
Mind Key が認識されない
[CODE BLOCK]
Claude Code がツールを認識しない
- 設定変更後に Claude Code を再起動
- で Synapse が登録されているか確認
- MCP Troubleshooting を参照
次のステップ
- Claude Desktop Setup
- Cursor Setup
- Persistent LLM Agent Guide
────────────────────────────────────────────────────────────
# Claude Desktop での MCP
SUMMARY: Synapse を Claude Desktop に 2 分で接続。Claude は Synapse の 79 ツールをネイティブに取得。
KEY CONTEXT:
Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
%APPDATA%\Claude\claude_desktop_config.json (Windows)
MCP server command: npx -y synapse-mcp-api@latest
Env vars: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional, default https://synapse.schaefer.zone)
After config: restart Claude Desktop, check for 🔌 icon with "79 tools"
Test: type "memory_recall aufrufen" in a new chat
Troubleshooting: Node.js ≥ 18, check Mind Key, see /docs/mcp/troubleshooting
Claude Desktop での MCP
Claude Desktop は macOS と Windows 向けの Anthropic のデスクトップアプリです。Synapse MCP サーバーを設定すると、Claude は 79 個すべての Synapse ツールにネイティブアクセスします — メモリの保存、リコール、タスク管理、チャットなどが可能です。
前提条件
- Claude Desktop アプリ（macOS または Windows）
- Node.js 18+ がインストール済み（）
- Synapse Mind Key
ステップ 1：設定ファイルを開く
- macOS：
- Windows：
ファイルが存在しない場合は作成してください。
ステップ 2：Synapse MCP サーバーを追加
[CODE BLOCK]
> [!TIP]
> 既に他の MCP サーバーを設定している場合は、既存の オブジェクト内に ブロックを追加するだけです。
ステップ 3：Claude Desktop を再起動
1. Claude Desktop を完全に終了（macOS では Cmd+Q、ウィンドウを閉じるだけではありません）
2. Claude Desktop を再度開く
3. 新しいチャットを開始
4. 左下の 🔌 プラグアイコンを探します —「79 tools」と表示されるはずです
ステップ 4：テスト
新しいチャットで次のように入力します：
[CODE BLOCK]
Claude は ツールを呼び出し、保存されたメモリのサマリーで応答するはずです（mind が空の場合は「No memories yet」）。
利用可能なツール（抜粋）
| ツール | 説明 |
|------|-------------|
| | すべてのメモリをリコール |
| | 新しいメモリを保存 |
| | メモリを検索 |
| | タスクを一覧 |
| | タスクを作成 |
| | 新着メッセージを確認 |
| | メッセージに返信 |
| | ブラウザタブを開く |
| | 登録されたコンピュータを一覧 |
完全なリスト：What is MCP?
トラブルシューティング
Claude Desktop にツールが表示されない
1. Node.js バージョンを確認：（≥ 18 であること）
2. 設定ファイルが有効な JSON か確認（末尾のカンマなし）
3. Claude Desktop を完全に再起動（Cmd+Q、閉じるだけではない）
4. Claude Desktop ログを確認：（macOS）
「Mind Key invalid」エラー
- が で始まることを確認
- で新しいキーを取得（ の JWT が必要）
- JSON 内のキーに引用符なし
npx が見つからない
- Node.js 18+ をインストール：
- インストール後にターミナルを再起動
- Homebrew を使う macOS の場合：
ツールは表示されるが呼び出しが失敗
- に到達できるか確認：
- Mind Key が動作するか確認：
- MCP Troubleshooting を参照
ツールプロファイル（トークンを節約）
より小さい LLM を使用する場合やコンテキストトークンを節約したい場合は、ツールプロファイルを設定します：
[CODE BLOCK]
プロファイル：（8 ツール）、（25）、（119、デフォルト）。
次のステップ
- Claude Code Setup
- Cursor Setup
- MCP Troubleshooting
────────────────────────────────────────────────────────────
# Continue.dev での MCP
SUMMARY: Synapse を Continue.dev に接続 — VS Code と JetBrains 向けオープンソース AI コーディングアシスタント。
Continue.dev での MCP
Continue.dev は VS Code と JetBrains IDE 向けのオープンソース AI コーディングアシスタントです。Synapse MCP により、Continue はセッションをまたぐ永続的メモリを得ます。
前提条件
- VS Code または JetBrains IDE
- Continue.dev 拡張機能がインストール済み
- Node.js 18+
- Synapse Mind Key
セットアップ
ステップ 1：Continue 設定を開く
VS Code または JetBrains で：
1. Continue 拡張サイドバーを開く
2. 歯車アイコンをクリック →「Open config.json」
または を直接編集します。
ステップ 2：Synapse MCP サーバーを追加
[CODE BLOCK]
ステップ 3：Continue をリロード
VS Code ウィンドウをリロード（Cmd+Shift+P →「Reload Window」）するか、IDE を再起動します。
動作確認
Continue チャットで：
[CODE BLOCK]
Continue は を呼び出し、保存されたメモリで応答するはずです。
よくあるパターン
プロジェクトコンテキスト
[CODE BLOCK]
Continue は を呼び出し、プロジェクトメモリを確認して、前回中断した箇所から作業を続けます。
コードレビューパターン
[CODE BLOCK]
Continue は保存されたコードレビューパターンを見つけて適用します。
ペアプログラミングのメモリ
[CODE BLOCK]
Continue は メモリとして保存します。
トラブルシューティング
MCP サーバーが接続しない
1. が有効な JSON か確認
2. Node.js を確認：
3. Continue の出力パネルを確認（View → Output → Continue）
4. IDE を再起動
ツールが表示されない
- Continue が MCP をサポートするバージョンか確認（≥ 0.9.x）
- 環境変数が設定内で設定されているか確認
- Continue のログで MCP エラーを探す
次のステップ
- Claude Desktop Setup
- Custom MCP Client
────────────────────────────────────────────────────────────
# Cursor での MCP
SUMMARY: Synapse を Cursor IDE に接続してコーディングセッションをまたぐ永続的プロジェクトメモリを実現。
Cursor での MCP
Cursor は VS Code ベースの AI 駆動 IDE です。Synapse MCP により、Cursor はセッションをまたぐ永続的メモリを得ます — プロジェクトの決定、コードベースのパターン、過去のデバッグセッションを記憶します。
前提条件
- Cursor IDE がインストール済み（）
- Node.js 18+
- Synapse Mind Key
セットアップ
ステップ 1：Cursor 設定を開く
Cursor で：
1. 設定を開く（macOS では Cmd+,、Windows/Linux では Ctrl+,）
2. 「MCP」を検索するか、 に移動
ステップ 2：Synapse MCP サーバーを追加
「Add MCP Server」をクリックして設定します：
| フィールド | 値 |
|-------|-------|
| 名前 | |
| タイプ | |
| コマンド | |
| 環境変数 | |
ステップ 3：config.json を直接編集（代替）
Cursor は MCP 設定を に保存します：
[CODE BLOCK]
ステップ 4：Cursor を再起動
Cursor を完全に再起動します（macOS では Cmd+Q して再度開く）。
動作確認
Cursor のチャットパネル（Cmd+L）で：
[CODE BLOCK]
Cursor は を呼び出し、保存されたメモリで応答するはずです。
よくあるパターン
プロジェクトのオンボーディング
新しいプロジェクトを開くとき：
[CODE BLOCK]
Cursor は を呼び出し、前回中断した箇所から作業を続けます。
アーキテクチャの決定
[CODE BLOCK]
Cursor は 優先度の メモリとして保存します。
デバッグ履歴
[CODE BLOCK]
Cursor は メモリを検索し、過去の修正を思い出させます。
セッションをまたぐコードパターン
[CODE BLOCK]
Cursor は以前行った認証実装に関するメモリを見つけます。
トラブルシューティング
MCP サーバーが接続しない
1. Node.js を確認：（≥ 18）
2. MCP サーバーをテスト：（エラーなしで起動するはず）
3. Cursor の MCP ログを確認（View → Output → MCP）
4. Cursor を完全に再起動
ツールが表示されない
- が有効な JSON か確認
- 環境変数が設定されているか確認
- Cursor が MCP をサポートするバージョンか確認（≥ 0.42）
Mind Key が無効
[CODE BLOCK]
次のステップ
- Claude Desktop Setup
- Continue.dev Setup
- Persistent LLM Agent Guide
────────────────────────────────────────────────────────────
# カスタム MCP クライアントを構築
SUMMARY: MCP SDK を使用して独自のアプリケーションから Synapse MCP サーバーに接続。
カスタム MCP クライアントを構築
独自の LLM アプリケーションを構築している場合、公式 MCP SDK を使用して Synapse MCP サーバーに直接接続できます。これにより、アプリは 79 個すべての Synapse ツールにアクセスできます。
SDK
| 言語 | パッケージ |
|----------|---------|
| TypeScript/JavaScript | |
| Python | |
TypeScript の例
インストール
[CODE BLOCK]
stdio で接続
[CODE BLOCK]
HTTP/SSE で接続（リモート）
[CODE BLOCK]
Python の例
インストール
[CODE BLOCK]
stdio で接続
[CODE BLOCK]
ツールプロファイル
接続時に、 ヘッダー（HTTP/SSE）または 環境変数（stdio）で特定のツールプロファイルを要求できます：
[CODE BLOCK]
エラー処理
[CODE BLOCK]
ユースケース
- カスタム AI アシスタント — 永続的メモリを持つ独自エージェントを構築
- ワークフロー自動化 — カスタムワークフローで Synapse ツールをチェーン
- データパイプライン — メモリを抽出、変換、他の場所にロード
- 監視ダッシュボード — メモリ統計、チャット履歴、タスクを表示
次のステップ
- MCP Specification
- Synapse MCP Repo
- API Overview
────────────────────────────────────────────────────────────
# MCP トラブルシューティング
SUMMARY: よくある MCP 連携の問題を解決 — サーバーが起動しない、ツールが表示されない、認証エラー。
KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/
MCP トラブルシューティング
Synapse MCP を LLM クライアントに連携する際のよくある問題と解決策。
クイック診断チェックリスト
1. ✅ Node.js 18+ がインストール済み？（）
2. ✅ Mind Key が で始まる？（JWT ではない）
3. ✅ Synapse API に到達可能？（）
4. ✅ Mind Key が動作する？（）
5. ✅ 設定ファイルが有効な JSON？（末尾のカンマなし、コメントなし）
6. ✅ 設定変更後にクライアントを再起動した？
7. ✅ MCP サーバーが手動で起動する？（）
問題：クライアントにツールが表示されない
症状
- Claude Desktop / Cursor / Continue が 0 ツールを表示
- MCP サーバーリストに 🔌 アイコンや「synapse」エントリがない
解決策
1. クライアントを完全に再起動 — macOS では Cmd+Q（ウィンドウを閉じるだけではない）
2. 設定ファイルの場所を確認：
- Claude Desktop macOS：
- Claude Desktop Windows：
- Cursor：
- Continue：
3. JSON を検証 — 設定を に貼り付け
4. クライアントログを確認 して MCP エラーを探す：
- Claude Desktop：（macOS）
- Cursor：View → Output → MCP
5. MCP サーバーを手動で実行 して起動エラーを確認：
[CODE BLOCK]
問題：「Mind Key invalid」エラー
症状
- ツールは表示されるが呼び出しが「401 Unauthorized」で失敗
- エラー：「Mind Key fehlt oder ungültig」
解決策
1. Mind Key フォーマットを確認 — で始まる、約 40 文字
2. 直接テスト：
[CODE BLOCK]
3. 環境変数が設定されているか確認 — stdio トランスポートの場合、環境変数はシェルではなく MCP サーバー設定にある必要がある
4. 新しい Mind Key を取得：
[CODE BLOCK]
問題：npx が見つからない
症状
- エラー：「npx: command not found」
- MCP サーバーが起動に失敗
解決策
1. Node.js 18+ をインストール：
- macOS： または からダウンロード
- Linux：
- Windows： からダウンロード
2. インストール後にターミナルを再起動
3. 確認：
問題：SYNAPSEURL に到達できない
症状
- MCP サーバーは起動するがツール呼び出しがタイムアウト
- エラー：「fetch failed」または「ECONNREFUSED」
解決策
1. 接続をテスト：
[CODE BLOCK]
2. 企業ファイアウォールを確認 — 送信 HTTPS をブロックしている可能性
3. 代替 URL を試す：
- 本番：
- MCP サーバー：
4. セルフホストの場合：Synapse インスタンスが実行中でアクセス可能であることを確認
問題：MCP サーバーがクラッシュする
症状
- MCP サーバーが起動直後に終了
- クライアントログに「MCP server disconnected」と表示
解決策
1. 手動で実行してエラーを確認：
[CODE BLOCK]
2. ポート競合を確認 — MCP サーバーはデフォルトでポート 13100 を使用
3. npx キャッシュをクリア：
[CODE BLOCK]
4. 最新に更新：
[CODE BLOCK]
問題：ツール呼び出しが 429 を返す
症状
- エラー：「Rate limit exceeded」
解決策
MCP では発生しないはずです（ヘッダー認証を使用、レート制限なし）。発生した場合：
1. どこかで を使用していないか確認 — ヘッダー認証に切り替え
2. を確認 — 正しいインスタンスを指していることを確認
3. 問題が続く場合はサポートに連絡
問題：ツールは表示されるが動作しない
症状
- クライアントにツールがリストされる
- ツールを呼び出すとエラーまたは結果なし
解決策
1. ツール名を確認 — 正確である必要（例： ではなく ）
2. 引数を確認 — ツールの入力スキーマを確認
3. 直接 API でテスト：
[CODE BLOCK]
4. Synapse のヘルスを確認：
[CODE BLOCK]
ヘルプを得る
上記のいずれも問題を解決しない場合：
1. 既存の Issue を確認：
2. 次を含めて新しい Issue を開く：
- MCP サーバーのバージョン（）
- クライアント名とバージョン
- オペレーティングシステム
- 関連ログの抜粋
- 再現手順
次のステップ
- Claude Desktop Setup
- Claude Code Setup
- API Errors
────────────────────────────────────────────────────────────
# MCP とは？
SUMMARY: Model Context Protocol は LLM が外部ツールを呼び出すことを可能にします。Synapse は公式 MCP サーバーで 79 ツールを公開。
KEY CONTEXT:
MCP = Model Context Protocol (Anthropic, 2024). Open standard for LLM-tool integration.
Synapse has official MCP server: synapse-mcp-api (npm package, npx -y synapse-mcp-api@latest)
79 tools exposed: 22 memory, 7 chat, 8 scheduler, 4 tasks, 5 scripts, 9 computers, 4 push, 5 user, 3 utility
3 transports: stdio (local), HTTP/SSE (remote), WebSocket (mobile)
Supported clients: Claude Desktop, Claude Code, Cursor, Continue, Cline, any MCP-compatible client
Tool Profiles (v1.4.0): minimal (8 tools), standard (25), full (119) — controlled via MCP_PROFILE env or Mcp-Tool-Profile header
MCP とは？
Model Context Protocol（MCP） は Anthropic（2024）によるオープン標準で、LLM が構造化された方法で外部ツールを呼び出せるようにします。プロンプトに API ドキュメントを貼り付ける代わりに、MCP サーバーにツールを登録し、LLM が必要に応じて呼び出します — 関数呼び出しのようなものですが、標準化されクライアント非依存です。
Synapse MCP サーバー
Synapse は公式 MCP サーバー（npm の ）を同梱し、Synapse のすべての機能をカバーする 79 ツール を公開します：
| カテゴリ | ツール | 数 |
|----------|-------|-------|
| Memory | recall, list, store, search, semantic-search, update, delete, bulk-delete, stats, unverified, contradictions, audit, related, by-tag, diff, expiring, health, sync, embed-batch, verify, unverify, mind-export | 22 |
| Chat | poll, reply, status, history, unread, send, upload | 7 |
| Scheduler | cronlist, croncreate, crondelete, crontoggle, varlist, varget, varset, vardelete | 8 |
| Tasks | tasklist, taskget, taskcreate, taskupdate | 4 |
| Scripts | scriptlist, scriptget, scriptinfo, scriptstore, scriptdelete | 5 |
| Computers | computerlist, computerget, installcode, screenshot, commandqueue, commandstatus, commandslist, disable, delete | 9 |
| Push | vapidpublickey, subscribe, unsubscribe, test | 4 |
| User/Mind | register, login, mindslist, mindcreate, minddelete | 5 |
| Utility | time, calc, random | 3 |
| Visualization | graph, tags, compact | 3 |
| Sharing | share, list, revoke | 3 |
| Webhooks | register, list, get, update, delete | 5 |
| Browser | new, navigate, click, type, screenshot, close | 6 |
| 合計 | | 79+ |
仕組み
[CODE BLOCK]
1. LLM クライアント（Claude Desktop、Cursor など）を設定して Synapse MCP サーバーを使用します
2. クライアントが MCP サーバーを起動します（ 経由）
3. MCP サーバーは Mind Key を使用して Synapse API に接続します
4. LLM は 79 個すべてのツールを呼び出し可能なネイティブ関数として見ます
5. LLM が何かを記憶する必要があるとき、 を呼び出します — MCP サーバーはこれを Synapse の に変換します
トランスポート
Synapse MCP サーバーは 3 つのトランスポートをサポートします：
stdio（ローカル、デスクトップに推奨）
[CODE BLOCK]
HTTP/SSE（リモート、マルチテナント）
MCP クライアントを次に接続：
[CODE BLOCK]
WebSocket（モバイル、高頻度）
[CODE BLOCK]
ツールプロファイル（v1.4.0）
より小さい LLM のトークンオーバーヘッドを減らすため、MCP サーバーは 3 つのツールプロファイルをサポートします：
| プロファイル | ツール | トークン | 最適な用途 |
|---------|-------|--------|----------|
| | 8（コンポジットディスパッチ） | 500 | ≤8k コンテキストのセルフホスト LLM |
| | 25（名前付き） | 2,500 | 中規模 LLM（Claude Haiku、GPT-3.5） |
| | 119（すべて） | 8,250 | 大規模 LLM（Claude Sonnet/Opus、GPT-4） — デフォルト |
制御方法：
- 環境変数：
- ヘッダー：
サポートされるクライアント
- Claude Desktop — Anthropic のデスクトップアプリ
- Claude Code — ターミナルコーディングエージェント
- Cursor — AI 駆動 IDE
- Continue.dev — オープンソース AI コーディングアシスタント
- Cline — VS Code 拡張機能
- MCP 互換の任意のクライアント
直接 API ではなく MCP を使う理由は？
| アプローチ | 長所 | 短所 |
|----------|------|------|
| 直接 API | シンプル、追加レイヤーなし | LLM が URL、ヘッダー、認証を知る必要 |
| MCP | LLM はネイティブツールを認識、URL 暗記不要 | 追加の MCP サーバープロセス |
ほとんどの LLM エージェントユースケースでは、MCP がより良い選択肢です — LLM は API パスや認証パターンを記憶する必要がありません。
次のステップ
- Claude Desktop Setup — 2 分で設定
- Claude Code Setup — ターミナル連携
- Custom MCP Client — 独自に構築
## カテゴリ: ガイドとチュートリアル
具体的なシナリオのためのステップバイステップガイド。
────────────────────────────────────────────────────────────
# iOS アプリの自動テスト
SUMMARY: Synapse + Computer Control API を使用して Simulator 経由で iOS アプリテストを自動化。
iOS アプリの自動テスト
Synapse のメモリシステムと Computer Control API を組み合わせて、LLM 駆動の iOS アプリテストを構築します。LLM はテストシナリオを記憶し、過去の失敗から学習し、UI 変更に適応します。
アーキテクチャ
[CODE BLOCK]
前提条件
- Synapse アカウント + Mind Key
- Claude Desktop で構成された Synapse MCP サーバー
- をインストールした iOS Simulator
- Synapse に登録されたコンピュータ（Computer Control API を参照）
ステップ 1：Simulator コンピュータの登録
iOS Simulator を実行する Mac 上で：
[CODE BLOCK]
ステップ 2：テストシナリオをメモリに保存
再利用可能なテストシナリオをメモリとして保存します。
[CODE BLOCK]
ステップ 3：LLM 駆動のテスト実行
Claude Desktop で（Synapse MCP を構成済み）：
[CODE BLOCK]
Claude は以下を行います。
1. を呼び出して メモリを見つける
2. を呼び出して現在の状態を確認
3. 各ステップを （click、type）経由で実行
4. スクリーンショットで結果を検証
5. 失敗があれば メモリとして保存
ステップ 4：自己修復テスト
テスト失敗時に、失敗と復旧を保存します。
[CODE BLOCK]
次回 LLM がテストを実行する際、失敗を再取得し、復旧を自動的に適用します。
ステップ 5：テスト結果の追跡
テスト実行をタスクとして追跡します。
[CODE BLOCK]
よくあるコマンド
| アクション | コマンド |
|--------|---------|
| Simulator 起動 | |
| スクリーンショット | （Synapse MCP 経由） |
| (x,y) をタップ | |
| テキスト入力 | |
| Home を押す | |
ベストプラクティス
> [!TIP]
> - UI 座標をメモリとして保存 — UI は変わるが、LLM は再学習可能
> - アクセシビリティラベルを使用 — 座標より安定
> - テストデータは別々に保存 — ユーザー名、パスワードには変数を使用
> - クリーンな状態でテスト実行 — 実行間で Simulator をリセット
> - 失敗時のスクリーンショットを記録 — デバッグに有用
次のステップ
- Self-Healing Tests
- Computer Control API
- Memory Best Practices
────────────────────────────────────────────────────────────
# バックアップ & リストア
SUMMARY: バックアップのためのメモリエクスポート、mind 間の移行、データ損失後のリストア。
バックアップ & リストア
Synapse はメモリのバックアップ、移行、ディザスタリカバリのための完全なエクスポート/インポートを提供します。本ガイドでは必須操作を説明します。
エクスポート
完全な mind エクスポート
mind 内の全メモリを JSON でエクスポートします。
[CODE BLOCK]
レスポンス形式：
[CODE BLOCK]
差分エクスポート（Diff）
指定タイムスタンプ以降に変更されたメモリのみをエクスポートします。
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
自動バックアップ
cron で毎日のバックアップをスケジュールします。
[CODE BLOCK]
> [!NOTE]
> cron エンドポイントはレスポンスを受け取りますが保存しません。実際のバックアップには、レスポンスを保存する独自のバックアップサーバーを cron の宛先にしてください。
より良い方法：外部バックアップスクリプト
[CODE BLOCK]
crontab に追加：
[CODE BLOCK]
リストア
同じ mind へのリストア
[CODE BLOCK]
新しい mind へのリストア
[CODE BLOCK]
Python リストアスクリプト
[CODE BLOCK]
mind 間の移行
[CODE BLOCK]
その他のデータのバックアップ
以下も忘れずにバックアップしてください。
| データ型 | エンドポイント |
|-----------|----------|
| メモリ | |
| タスク | |
| スクリプト | |
| Webhooks | |
| Cron ジョブ | |
| 変数 | |
| チャット履歴 | |
検証
リストア後、検証します。
[CODE BLOCK]
ベストプラクティス
> [!TIP]
> - 毎日バックアップ — cron で自動化
> - リストアをテスト — 復元できないバックアップは無意味
> - 複数バージョンを保持 — 少なくとも 30 日分
> - オフサイト保存 — S3、Backblaze B2 など
> - 機密バックアップを暗号化 — メモリに PII が含まれる可能性
> - リストア手順を文書化 — 必要なときには忘れているはず
次のステップ
- Memory API
- Cron & Scheduler — 自動バックアップ用
────────────────────────────────────────────────────────────
# メモリのベストプラクティス
SUMMARY: 効果的な再取得のためのメモリ構造化 — カテゴリ、キー、タグ、優先度。
メモリのベストプラクティス
メモリの構造化方法が有用性を決定します。本ガイドでは、LLM が適切な時に適切な情報を再取得できるよう、メモリのカテゴリ化、タグ付け、優先度付けのパターンを説明します。
カテゴリ：最も具体的なものを選ぶ
| カテゴリ | 用途 | 例 |
|----------|---------|---------|
| | ユーザー名、役割、連絡先情報 | |
| | 好き嫌い、作業スタイル | |
| | 検証可能な事実 | |
| | プロジェクトのステータス、決定 | |
| | ユーザーのスキル | |
| | 避けるべき過去のエラー | |
| | セッション関連のコンテキスト | |
| | その他のメモ | |
> [!TIP]
> 迷ったら、検証可能な情報には を、それ以外には を使用してください。カテゴリ化しすぎず — 混乱する より明確な の方が良いです。
キー：意味のある識別子
フィールドはメモリの識別子です。意味のある安定したキーを使用してください。
良いキー：
-
-
-
-
悪いキー：
- （意味がない）
- （説明的でない）
- （日付は再取得に役立たない）
キーの命名規則
- （小文字とアンダースコア）
- カテゴリをプレフィックスに：、、
- 動詞ではなく説明的な名詞を使用
- 50 文字以内に収める
タグ：検索とフィルタリング用
タグにより高速なフィルタリングと検索が可能です。メモリごとに 2〜5 個のタグを追加してください。
[CODE BLOCK]
タグのパターン
- プロジェクト名：、、
- トピック：、、、
- ステータス：、、
- 優先度指標：、
> [!NOTE]
> タグは大文字小文字を区別しません。一貫性のために小文字を使用してください。
優先度：現実的に
| 優先度 | 用途 | メモリの割合 |
|----------|---------|---------------|
| | ユーザー ID、法的情報、不可逆な決定 | 約 5% |
| | 進行中のプロジェクト、重要な設定 | 約 20% |
| | ほとんどの事実、メモ、コンテキスト | 約 65% |
| | 一時的、知っておくとよいこと | 約 10% |
> [!WARNING]
> すべてを にしないでください。すべてが critical なら、何も critical ではありません。 は忘れた場合に実害が出るものに予約してください。
保存すべきか否か
常に保存
- ユーザー ID（名前、メール、役割）
- 長期的な設定
- プロジェクトの決定と根拠
- 過去の過ちと学んだ教訓
- ユーザーへの約束
保存しない
- 一時的な状態（変数を使用）
- 逐語的な会話履歴（チャットシステムが処理）
- 機密データ（パスワード、API キー）
- 容易に導出できる事実（現在日付、ファイル内容）
- 一時的なコンテキスト（ カテゴリ + low 優先度を使用）
メモリの更新
同じ + で を呼ぶと既存メモリが更新されます。
[CODE BLOCK]
> [!TIP]
> 重複を作らずに更新できるよう、安定したキーを使用してください。LLM は情報が変わるたびに新しいメモリを作るのではなく、同じキーで再 POST すべきです。
メモリのライフサイクル
[CODE BLOCK]
- Create：完全なコンテキスト付きで POST /memory
- Active：頻繁に再取得、必要に応じて更新
- Stale：まだ関連するが活発に使用されていない（優先度を下げる？）
- Archive：優先度を に設定、歴史的参照用に保持
- Delete：関連しなくなったら DELETE /memory/:id
定期的なクリーンアップ
[CODE BLOCK]
パターン：メモリの継承
階層的コンテキスト（プロジェクト → サブプロジェクト → タスク）向け：
[CODE BLOCK]
LLM は で検索し、関連する全メモリを見つけられます。
パターン：決定ログ
LLM が再考しないよう、決定を根拠と共に保存します。
[CODE BLOCK]
パターン：過ちの回避
具体的な回避指示と共に過ちを保存します。
[CODE BLOCK]
避けるべきアンチパターン
> [!WARNING]
> - 会話ログの保存 — チャットシステムが処理
> - ファイル全体の保存 — スクリプトストアや外部ストレージを使用
> - 一時的な状態の保存 — 変数を使用
> - シークレットの保存 — 環境変数を使用
> - メモリの重複 — 安定したキーを使用
> - タグの過剰使用 — メモリごとに 2〜5 個が理想
> - すべてが critical — 優先度は現実的に
次のステップ
- Memory API
- Persistent LLM Agent
- Memory Tagging Strategy
────────────────────────────────────────────────────────────
# マルチエージェント連携
SUMMARY: 共有 Synapse minds、タスク、チャットを使用した複数 LLM エージェントの連携。
マルチエージェント連携
関連するタスクに取り組む複数の LLM エージェントがある場合、Synapse が連携レイヤーを提供します — 共有メモリ、タスク割り当て、非同期チャット。
パターン
パターン 1：共有 mind（信頼できる唯一の情報源）
すべてのエージェントが 1 つの Mind Key を共有。同じメモリストアを読み書きします。
[CODE BLOCK]
ユースケース： 1 つのプロジェクトに取り組む少数のエージェントチーム。
セットアップ：
[CODE BLOCK]
タスク経由の連携：
[CODE BLOCK]
パターン 2：専門 mind（分離されたコンテキスト）
各エージェントが自身の mind を持ち、共有の「調整」mind 経由で通信します。
[CODE BLOCK]
ユースケース： 異なる専門性（コーディング、レビュー、デプロイ）を持つエージェント。
セットアップ：
[CODE BLOCK]
共有 mind 経由の連携：
[CODE BLOCK]
パターン 3：ハブ＆スポーク（オーケストレータ）
中央のオーケストレータエージェントがワーカーエージェントにタスクを割り当てます。
[CODE BLOCK]
ユースケース： 並列作業を伴う複雑なワークフロー。
実装：
[CODE BLOCK]
チャット経由の連携
エージェントはチャットシステム経由で通信できます。
[CODE BLOCK]
> [!NOTE]
> チャットメッセージにはロールタグが付きます。エージェント間メッセージには role=agent、人間とエージェント間には role=human を設定してください。
変数経由の連携
軽量な連携（ロック、フラグ）には変数を使用します。
[CODE BLOCK]
ベストプラクティス
> [!TIP]
> - 懸念事項ごとに別々の mind を使用 — コーダーとレビューアーのメモリを混ぜない
> - チャットでエージェントをタグ付け — 明確な宛先に
> - 作業割り当てにはタスクを使用 — チャットではなく（チャットは議論用）
> - 冪等性を実装 — エージェントは失敗した操作を再試行する可能性
> - すべてを記録 — 監査可能性のために決定をメモリに保存
次のステップ
- Persistent LLM Agent
- LLM Cookbook
- Webhook Automation
────────────────────────────────────────────────────────────
# 永続 LLM エージェントの構築
SUMMARY: Synapse を使用してセッションをまたいで記憶する LLM エージェントを構築するステップバイステップガイド。
概要
本ガイドでは、Synapse を使用してセッションをまたいでコンテキストを永続化する LLM エージェントの構築を順を追って説明します。完了すると、エージェントは以下を行えます。
- セッション開始時に過去のコンテキストを再取得
- 新しい学習内容を発生時に保存
- セッションをまたぐ多段階タスクの追跡
- 非同期チャットで人間と通信
アーキテクチャ
[CODE BLOCK]
ステップ 1：Mind Key の設定
[CODE BLOCK]
ステップ 2：セッション開始プロトコル
毎セッションの開始時に、すべてのメモリを再取得します。
[CODE BLOCK]
ステップ 3：新しい学習内容の保存
エージェントが記憶する価値のあることを学んだら常に保存します。
[CODE BLOCK]
ステップ 4：タスク管理
セッションをまたぐ多段階作業を追跡します。
[CODE BLOCK]
ステップ 5：人間との非同期チャット
ツール呼び出しの間にメッセージをポーリングします。
[CODE BLOCK]
ステップ 6：セッション終了プロトコル
セッション終了時に、最終コンテキストを保存します。
[CODE BLOCK]
完全なパターン
[CODE BLOCK]
ベストプラクティス
> [!TIP]
>
> - 常に最初に再取得 — コンテキストを読み込まずに作業を開始しない
> - 積極的に保存 — セッション終了まで待たない
> - 意味のあるキーを使用 — ではなく 、
> - すべてにタグ付け — タグが検索とフィルタリングを支える
> - 現実的な優先度を設定 — すべてが ではない
次のステップ
- LLM Cookbook — 実践的パターン
- Memory Best Practices
- Multi-Agent Coordination
────────────────────────────────────────────────────────────
# 自己修復テストパイプライン
SUMMARY: Synapse メモリを使用して失敗から学習し自動適応するテストパイプラインの構築。
自己修復テストパイプライン
従来のテストスイートは UI が変わると壊れます。自己修復テストは Synapse メモリを使用して過去の失敗から学習し適応します — フレイキーテストとメンテナンス負荷を削減します。
コンセプト
[CODE BLOCK]
1. テストを実行
2. 失敗したら、失敗内容（何が、なぜ、どう修正するか）を保存
3. 次回実行：実行前に該当する失敗を再取得
4. 既知の修正を自動的に適用
実装
ステップ 1：テストラッパー
各テストをメモリの再取得/保存でラップします。
[CODE BLOCK]
ステップ 2：適応型テストロジック
テスト内で既知の失敗を確認し、修正を適用します。
[CODE BLOCK]
ステップ 3：復旧戦略
復旧戦略をメモリとして保存します。
[CODE BLOCK]
ステップ 4：CI 連携
[CODE BLOCK]
ステップ 5：失敗分析ダッシュボード
[CODE BLOCK]
ベストプラクティス
> [!TIP]
> - トレースバックを保存 — 失敗した正確な行を含む
> - テスト名でタグ付け — 高速フィルタリングを可能に
> - カテゴリを使用 — 通常のメモリと分離
> - 優先度を設定 — 失敗は決して忘れるべきでない
> - 定期クリーンアップ — 解決済み問題のメモリを削除
> - 機密データを保存しない — 認証情報、PII
保存すべき一般的な失敗パターン
| 失敗種別 | 保存すべき内容 |
|--------------|---------------|
| 要素が見つからない | 試したセレクタ、ページ状態、スクリーンショット |
| タイムアウト | 待機時間、何を待っていたか |
| アサーション失敗 | 期待値と実際の値 |
| ネットワークエラー | URL、ステータスコード、レスポンス本文 |
| 権限拒否 | 必要な権限、現在のユーザーロール |
次のステップ
- Automated iOS Testing
- Memory Best Practices
- Error Recovery Cookbook
────────────────────────────────────────────────────────────
# Webhook 自動化
SUMMARY: メモリ変更時に外部システムをトリガー — 同期、通知、自動化。
Webhook 自動化
Webhook を使用すると、Synapse イベント発生時に外部システムをトリガーできます。本ガイドでは一般的な自動化パターンを説明します。
一般的なパターン
パターン 1：クリティカルメモリの通知
クリティカルメモリ保存時に Slack メッセージを送信します。
[CODE BLOCK]
Webhook を登録します。
[CODE BLOCK]
パターン 2：外部システムへの同期
メモリを Notion、Obsidian、その他の外部 KB に同期します。
[CODE BLOCK]
パターン 3：CI/CD のトリガー
「release」メモリ保存時にデプロイをトリガーします。
[CODE BLOCK]
パターン 4：人間メッセージでのエージェント起動
人間がチャットメッセージを送信したときに LLM エージェント実行をトリガーします。
[CODE BLOCK]
パターン 5：メトリクス集計
メモリ増加、チャット活動、タスク完了を追跡します。
[CODE BLOCK]
署名検証
なりすましを防ぐため、Webhook 署名を常に検証してください。
[CODE BLOCK]
再試行ロジック
Synapse は失敗した Webhook を指数バックオフで再試行します。ハンドラは以下を行うべきです。
1. 200 を素早く返す — 同期的に重い作業をしない
2. 作業をキューに入れる — バックグラウンドジョブシステムを使用
3. 冪等にする — 同じイベントが 2 回配信される可能性
[CODE BLOCK]
Webhook のデバッグ
配信履歴の確認
Webhook 配信はログに記録されます。Webhook の最近の配信を確認します。
[CODE BLOCK]
Webhook の手動テスト
[CODE BLOCK]
よくある問題
| 問題 | 修正 |
|-------|-----|
| 4xx レスポンス | ハンドラが 200 を返すか確認 |
| 5xx レスポンス | サーバーエラー — アプリログを確認 |
| タイムアウト | 200 を素早く返し、作業を非同期でキューに |
| 重複配信 | ハンドラを冪等にする |
| 署名不一致 | secret が正しいか確認 |
ベストプラクティス
> [!TIP]
> - 署名を常に検証 — 絶対にスキップしない
> - 200 を素早く返す — Synapse をブロックしない
> - 冪等にする — 重複配信を処理
> - 具体的なイベントを使用 — ではなく
> - 配信失敗を監視 — アラートを設定
次のステップ
- Webhooks API
- Cron & Scheduler
- Persistent LLM Agent
## カテゴリ: コンセプト
Synapseの背後にあるアーキテクチャとコンセプト。
────────────────────────────────────────────────────────────
# Synapse アーキテクチャ
SUMMARY: Synapse の構成 — Fastify、PostgreSQL、FTS5、埋め込み、MCP サーバー。
Synapse アーキテクチャ
Synapse は Fastify、FTS5 搭載 PostgreSQL、セマンティック検索用のオプションの埋め込みサービスで構築されたマルチテナントメモリ API です。
全体アーキテクチャ
[CODE BLOCK]
コアコンポーネント
1. Synapse API（Fastify）
メインの HTTP サーバーです。以下を処理します。
- REST エンドポイント（、、 など）
- 認証（エージェントは Mind Key、人間は JWT）
- レート制限（ 認証のみ）
- 静的ファイル配信（、 などの Web UI）
- Webhook ディスパッチ
パフォーマンス重視で Fastify 5 により構築されています。本番環境ではポート 12800 で動作します。
2. FTS5 搭載 PostgreSQL
プライマリデータストアです。フルテキスト検索用に FTS5 拡張を備えた PostgreSQL を使用します。
主なテーブル：
| テーブル | 目的 |
|-------|---------|
| | ユーザーアカウント |
| | Mind スコープ（各々が Mind Key を持つ） |
| | FTS5 仮想テーブル付きのメモリレコード |
| | タスク管理 |
| | チャット履歴 |
| | 永続スクリプト |
| | Webhook 登録 |
| | スケジュールタスク |
| | キーバリューストア |
| | 監査トレイル |
FTS5 により、全メモリコンテンツに対するサブミリ秒のフルテキスト検索が可能です。詳しくは FTS5 Search を参照。
3. 埋め込みサービス（オプション）
セマンティック検索のため、Synapse はメモリコンテンツのベクトル埋め込みを生成します。これらはメモリと一緒に保存され、類似度検索に使用されます。
- プロバイダー：構成可能（OpenAI、ローカルモデルなど）
- テーブルの カラムとして保存
- エンドポイントで使用
- Semantic Search を参照
4. MCP サーバー（別サービス）
Synapse MCP サーバーは別プロセス（ポート 13100）として動作します。以下を行います。
- Model Context Protocol 経由で 79 のツールを公開
- stdio、HTTP/SSE、WebSocket トランスポートをサポート
- MCP ツール呼び出しを Synapse API 呼び出しに変換
- マルチテナント：セッションごとに 1 つの Mind Key
5. Browser Proxy（別サービス）
ブラウザ自動化用に、Playwright ベースの別サービスがポート 13000 で動作します。MCP サーバーは ツールのためにこれを呼び出せます。
6. SSH Proxy（別サービス）
SSH ベースのリモートコマンド用に、別サービスがポート 12900 で動作します。
マルチテナントモデル
[CODE BLOCK]
各 mind は完全に分離されています。Mind Key は厳密に 1 つの mind へのアクセスを許可します。JWT はユーザーアカウントへのアクセスを許可します（mind 管理用）。
詳しくは Multi-Tenancy を参照。
リクエストフロー
メモリ保存リクエスト
[CODE BLOCK]
メモリ検索リクエスト
[CODE BLOCK]
デプロイ
Synapse は Docker コンテナとしてデプロイされます。 を参照：
[CODE BLOCK]
パフォーマンス特性
| 操作 | レイテンシ | スループット |
|-----------|---------|------------|
| メモリ保存 | 5ms | 1000+ req/s |
| メモリ再取得 | 20ms | 500 req/s |
| FTS5 検索 | 10ms | 800 req/s |
| セマンティック検索 | 50ms | 200 req/s |
| チャットポーリング | 5ms | 2000 req/s |
次のステップ
- Memory Model
- Multi-Tenancy
- FTS5 Search
────────────────────────────────────────────────────────────
# FTS5 フルテキスト検索
SUMMARY: Synapse が SQLite FTS5 を使用してサブミリ秒のフルテキストメモリ検索を実現する仕組み。
FTS5 フルテキスト検索
Synapse は高速かつ柔軟なメモリ検索のために FTS5（Full-Text Search 5）を使用しています。本ページでは、その仕組みと効果的な使い方を説明します。
FTS5 とは？
FTS5 はフルテキスト検索機能を提供する SQLite 拡張（PostgreSQL でも拡張経由で利用可能）です。以下をサポートします。
- テキストコンテンツのインデックスによる高速キーワード検索
- ブール演算子（AND、OR、NOT）
- 引用符によるフレーズマッチング
- によるプレフィックスマッチング
- 関連度による結果ランキング
Synapse は全メモリコンテンツを FTS5 でインデックス化し、数千件のメモリにわたるサブミリ秒検索を可能にしています。
Synapse での FTS5 利用
時の処理：
1. メモリコンテンツが テーブルに保存
2. コンテンツが FTS5 仮想テーブルにも挿入
3. FTS5 が自動的にトークン化とインデックス化を実行
時の処理：
1. Synapse が FTS5 構文でクエリを解析
2. FTS5 インデックスに対して を実行
3. でフィルタ（テナント分離）
4. ランク付けされた結果を返却
クエリ構文
単純なキーワード検索
[CODE BLOCK]
「docker」を含むメモリを返します。
複数キーワード（暗黙の AND）
[CODE BLOCK]
「docker」と「swarm」の両方を含むメモリを返します。
フレーズマッチング
[CODE BLOCK]
完全なフレーズ「docker swarm」を含むメモリを返します。
プレフィックスマッチング
[CODE BLOCK]
「docker」で始まる単語（「dockers」「dockerfile」「dockerize」など）を含むメモリを返します。
ブール OR
[CODE BLOCK]
「docker」または「kubernetes」を含むメモリを返します。
ブール NOT
[CODE BLOCK]
「docker」を含むが「swarm」を含まないメモリを返します。
グループ化
[CODE BLOCK]
「docker」または「kubernetes」を含むが「test」を含まないメモリを返します。
実践例
プロジェクトに関するメモリの検索
[CODE BLOCK]
完全フレーズの検索
[CODE BLOCK]
テストメモリの除外
[CODE BLOCK]
技術による検索
[CODE BLOCK]
ランキング
FTS5 は BM25 アルゴリズムで関連度により結果をランク付けします。考慮要素：
- 用語頻度（用語の出現回数）
- 逆文書頻度（まれな用語ほど上位）
- 文書長（短い文書ほど上位）
- カラムウェイト（title > content）
結果はランク順（最も関連度の高いものが先頭）で返されます。
パフォーマンス
| 操作 | レイテンシ |
|-----------|---------|
| 100 件のメモリ検索 | < 5ms |
| 1,000 件のメモリ検索 | < 10ms |
| 10,000 件のメモリ検索 | < 25ms |
| 100,000 件のメモリ検索 | < 100ms |
FTS5 は読み取り中心のワークロードに高度に最適化されています。
制限事項
ステミング
FTS5 はデフォルトでステミングを行いません。「running」と「run」は異なる用語として扱われます。
回避策： プレフィックスマッチングを使用 —
誤字許容
FTS5 はファジーマッチングをサポートしません。誤字があると結果が返りません。
回避策： 概念マッチングにはセマンティック検索（）を使用してください。
ストップワード
一般的な単語（the、a、an、is）はインデックス化されますが、検索には有用でない場合があります。FTS5 はこれを自動的に処理します。
FTS5 とセマンティック検索の比較
| 側面 | FTS5 | セマンティック検索 |
|--------|------|-----------------|
| 速度 | サブミリ秒 | 50〜100ms |
| マッチング | 完全キーワード | 概念的 |
| 誤字許容 | なし | 一部あり |
| ステミング | なし | 暗黙的 |
| 埋め込み必要 | 不要 | 必要 |
| 最適な用途 | 特定の用語 | 概念 |
キーワードが分かっている場合は FTS5 を使用してください。X が異なる表現で記述されている「X に関するメモリ」を探す場合はセマンティック検索を使用してください。
ベストプラクティス
> [!TIP]
> - 具体的な用語を使用 — 「container orchestration」より「docker swarm」が良い
> - フレーズを引用 — でフレーズマッチを確実に
> - バリエーションにプレフィックス — で「deploy」「deployment」「deploying」を捕捉
> - ノイズを除外 — でテストメモリをフィルタ
> - タグと組み合わせ — で結果を絞り込み
次のステップ
- Semantic Search
- Memory API
- Memory Best Practices
────────────────────────────────────────────────────────────
# メモリモデル
SUMMARY: メモリの構造 — カテゴリ、キー、タグ、優先度、ソース、検証。
メモリモデル
Synapse のメモリモデルは LLM エージェント向けに設計されています — 信頼できる再取得のための十分な構造と、任意のドメインに対応する柔軟性を備えています。
メモリの構造
[CODE BLOCK]
フィールド
| フィールド | 型 | 必須 | 説明 |
|-------|------|----------|-------------|
| | string | 自動 | ユニーク ID（memxxx） |
| | enum | ✅ | 8 カテゴリのいずれか |
| | string | ✅ | 安定した識別子（更新に使用） |
| | string | ✅ | メモリの内容（任意のテキスト） |
| | string[] | – | 検索とフィルタリング用 |
| | enum | – | low、normal、high、critical（デフォルト：normal） |
| | enum | 自動 | user、agent（保存者） |
| | bool | 自動 | 人間が検証済みか |
| | float | – | 0.0 〜 1.0（デフォルト：user は 1.0、agent は 0.7） |
| | timestamp | – | このメモリを忘れるタイミング |
| | string | 自動 | 所有する mind |
| | timestamp | 自動 | 初回保存日時 |
| | timestamp | 自動 | 最終更新日時 |
カテゴリ
8 つのカテゴリが一般的な LLM エージェントのユースケースをカバーします。
| カテゴリ | 目的 | 内容の例 |
|----------|---------|-----------------|
| | ユーザーが誰か | "User is Michael Schäfer, software engineer in Berlin" |
| | ユーザーの設定 | "Prefers concise technical responses" |
| | 検証可能な事実 | "Office is in Berlin, timezone Europe/Berlin" |
| | プロジェクトのステータス | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| | ユーザーのスキル | "Advanced Python, 10+ years" |
| | 過去のエラー | "Forgot to bump npm version — CI failed" |
| | セッションのコンテキスト | "Currently reviewing PR #42" |
| | その他のメモ | "Try Redis for caching next sprint" |
キー：安定した識別子
フィールドは重要です — 重複を作らずにメモリを更新するための方法です。
[CODE BLOCK]
キーのルール：
- (category, mind) 内でユニークである必要があります
- を使用
- 明確さのためにカテゴリをプレフィックスに：、
- 安定性を保つ — 作成後にキーを変更しない
タグ：検索用
タグにより高速なフィルタリングと検索が可能です。
[CODE BLOCK]
タグのベストプラクティス：
- メモリごとに 2〜5 個のタグ（付けすぎない）
- 一貫性のために小文字
- プロジェクト名、トピック、技術を使用
- タグは大文字小文字を区別しません
優先度レベル
| 優先度 | 使用場面 | 再取得時の挙動 |
|----------|-------------|-----------------|
| | ID、法的、不可逆 | 常に再取得の先頭 |
| | 進行中のプロジェクト、主要な設定 | 再取得で目立つ |
| | ほとんどのメモリ（デフォルト） | 標準的な再取得順 |
| | 一時的、知っておくとよいこと | 要約される可能性 |
は優先度（critical が先頭）、次に新しさでソートします。
ソース：user と agent
メモリには が付与されます。
- — 人間が保存（JWT または human UI 経由）
- — LLM エージェントが保存（Mind Key 経由）
これは以下に影響します。
- 検証： メモリは自動検証、 メモリは未検証
- 信頼度： はデフォルト 1.0、 は 0.7
- 再取得： は未検証メモリに「(unverified)」を付ける
> [!NOTE]
> ソースのメモリは適切な懐疑心を持って扱ってください。ユーザーが直接述べたものではなく、推論や仮定の可能性があります。
検証
フラグは人間がメモリを確認したことを示します。
- メモリ：自動検証（）
- メモリ：デフォルトで未検証（）
以下でメモリを検証します。
[CODE BLOCK]
> [!NOTE]
> 検証には Mind Key（エージェント認証）ではなく JWT（人間の認証）が必要です。これにより、人間のみがメモリを検証済みとしてマークできます。
信頼度
フィールド（0.0 〜 1.0）はメモリの信頼性を示します。
- 1.0 — ユーザーが直接述べた
- 0.7 — エージェントが推論した
- 0.5 — 不確実、検証が必要
- 0.0 — 明示的に疑わしい
保存時に信頼度を設定します。
[CODE BLOCK]
有効期限
時間依存のメモリには を設定します。
[CODE BLOCK]
期限切れのメモリは で返されません（ただし DB には存在）。 で期限切れが近いメモリを確認できます。
メモリのライフサイクル
[CODE BLOCK]
再取得時の挙動
は LLM コンテキスト向けに最適化されたプレーンテキストの要約を返します。
[CODE BLOCK]
- 優先度（critical → low）、次に新しさでソート
- 未検証メモリは でマーク
- タグはコンテキストのために含まれる
- プレーンテキスト（JSON 解析不要）
次のステップ
- Memory API
- Memory Best Practices
- FTS5 Search
────────────────────────────────────────────────────────────
# マルチテナント & 分離
SUMMARY: Synapse がユーザー間や mind 間でデータを分離する仕組み — セキュリティ境界の解説。
マルチテナント & 分離
Synapse はマルチテナントです — 複数のユーザーが各々複数の mind を持ち、完全に分離されています。本ページでは分離モデルを説明します。
テナント階層
[CODE BLOCK]
分離レベル
レベル 1：ユーザー分離
各ユーザーアカウントは分離されています。Alice は以下を行えません。
- Bob の mind を見る
- Bob のメモリにアクセス（彼女の JWT でも不可）
- Bob のアカウント情報を一覧表示
実装：全テーブルに カラム、JWT は を含む、全クエリが でフィルタ。
レベル 2：Mind 分離
ユーザー内で各 mind は分離されています。Mind A は以下を行えません。
- Mind B のメモリを見る
- Mind B のタスク、チャット、スクリプトにアクセス
実装：全データテーブルに カラム、Mind Key は を含む、全クエリが でフィルタ。
> [!CRITICAL]
> Mind Key の分離が主要なセキュリティ境界です。流出した Mind Key はその mind のデータへの完全なアクセスを許可します — ただし、その mind のみ。
認証トークン
| トークン | スコープ | アクセス可能なもの |
|-------|-------|-------------------|
| Mind Key | 単一 mind | その mind のデータのみ |
| JWT | ユーザーアカウント | アカウント管理（mind の作成/一覧/削除） |
| Computer Token | 単一コンピュータ | そのコンピュータのコマンド |
Mind 間アクセス
同一ユーザー内
ユーザーは JWT 経由で自身の全 mind にアクセスできます（例： が全件リスト）。ただしメモリデータの読み書きには特定の Mind Key が必要です。
ユーザー間
ユーザーは互いのデータにアクセスできません — Sharing API で明示的に mind を共有した場合を除きます。
[CODE BLOCK]
共有後、Bob は自身の JWT で Mind A にアクセスできます（ の場合は読み取り専用）。
セキュリティ境界
[CODE BLOCK]
よくあるマルチテナントパターン
パターン 1：単一ユーザー、単一 mind
個人 LLM エージェントユーザーに最も一般的。
- 1 ユーザーアカウント
- 1 mind
- 1 Mind Key
- すべてのメモリが 1 スコープに
パターン 2：単一ユーザー、複数 mind
複数コンテキスト（仕事、個人、プロジェクト）を持つユーザー向け。
- 1 ユーザーアカウント
- N mind（例：「work」「personal」「project-x」）
- N Mind Key
- 各 LLM セッションは 1 つの Mind Key を使用
パターン 3：チーム共有 mind
プロジェクトで協業するチーム向け。
- 1 ユーザーが mind を作成（Mind Key を取得）
- 作成者が JWT でチームメンバーと共有
- 全チームメンバーが JWT（または共有 Mind Key）でアクセス
> [!WARNING]
> Mind Key の共有は完全な読み書きアクセスを与えます。チーム協業には、Mind Key を直接共有するより Sharing API（JWT ベース）を使用してください。
パターン 4：SaaS プロバイダー
Synapse をメモリレイヤーとして組み込むアプリ向け。
- 各顧客 = 1 ユーザーアカウント
- 各顧客プロジェクト = 1 mind
- アプリが顧客/プロジェクトごとに Mind Key を保存
- 顧客間の完全な分離
分離の検証
テスト：Mind Key は他の mind にアクセスできない
[CODE BLOCK]
テスト：JWT はメモリデータに直接アクセスできない
[CODE BLOCK]
ベストプラクティス
> [!TIP]
> - プロジェクト/コンテキストごとに 1 つの mind を使用 — 分離は味方です
> - Mind Key を共有しない — Sharing API を使用
> - 侵害された場合は Mind Key をローテーション（mind を削除して新規作成）
> - 共有 mind を監査 — 定期的に を確認
> - human UI には JWT を使用 — エンドユーザーに Mind Key を露出しない
次のステップ
- Authentication
- Mind Key vs JWT
- Architecture
────────────────────────────────────────────────────────────
# セマンティック検索（埋め込み）
SUMMARY: ベクトル埋め込みを使用した概念メモリ検索 — キーワードだけでなく意味で検索。
セマンティック検索（埋め込み）
Synapse はベクトル埋め込みを使用したセマンティック検索をサポートしています。FTS5（キーワードマッチング）とは異なり、セマンティック検索はキーワードが一致しなくても意味でメモリを検索します。
仕組み
[CODE BLOCK]
埋め込みとは？
埋め込みはテキストの数値ベクトル表現です。類似する意味のテキストは類似するベクトルを持ちます。Synapse は各メモリのコンテンツに対しベクトル（例：1536 次元）を生成します。
コサイン類似度
意味的に類似するメモリを見つけるため、Synapse はクエリベクトルと各メモリベクトルのコサイン類似度を計算します。類似度が高い = より関連性が高い。
セマンティック検索を使うべき場面
セマンティック検索が適している場合：
- X が保存されている表現と異なる形で記述されている「X に関するメモリ」を探したい
- FTS5 が結果を返さない（キーワードが一致しない）
- 概念的グループ化が欲しい（例：一部が「release」と言っている場合でも、すべての「deployment」メモリ）
- クエリが質問の場合：「認証はどう処理していますか？」
FTS5 が適している場合：
- 正確なキーワードが分かっている
- ブールロジック（AND、OR、NOT）が必要
- サブミリ秒の応答が必要
- フレーズマッチングが欲しい
エンドポイント
GET /memory/semantic-search
[CODE BLOCK]
レスポンス：
[CODE BLOCK]
例
デプロイメントメモリの検索
[CODE BLOCK]
「deployment」「release」「publishing」「rolling out」などに関するメモリを返します。
認証パターンの検索
[CODE BLOCK]
login、auth、JWT、セッション管理、OAuth などに関するメモリを返します。
類似メモリの検索
[CODE BLOCK]
セマンティック類似度（共通タグと埋め込みベクトルの両方）を使用します。
埋め込みの生成
埋め込みはいつ生成されるか？
- メモリ保存時 — 埋め込みサービスが構成されていれば、同期的に生成
- バッチ生成 — が埋め込みを持たないメモリに対して生成
- 非同期更新 — コンテンツ更新時に埋め込みを再生成
埋め込みプロバイダー
Synapse は構成可能な埋め込みプロバイダーをサポートします。
- OpenAI（、）
- ローカルモデル（Ollama 経由など）
- カスタム（embeddings インターフェースを実装）
環境変数で構成：
[CODE BLOCK]
バッチ生成
埋め込みが欠落しているメモリが多数ある mind の場合：
[CODE BLOCK]
パフォーマンス
| 操作 | レイテンシ |
|-----------|---------|
| 埋め込み生成（OpenAI） | 100〜200ms |
| セマンティック検索（1k メモリ） | 50〜100ms |
| セマンティック検索（10k メモリ） | 200〜500ms |
| バッチ生成（100 メモリ） | 10〜20s |
> [!NOTE]
> セマンティック検索はベクトル計算のため FTS5 より遅くなります。既知のキーワードには FTS5 を、概念的クエリにはセマンティックを使用してください。
制限事項
埋め込みのコスト
OpenAI を使用する場合、埋め込み生成にはコストがかかります（text-embedding-3-small で 100 万トークンあたり約 $0.02）。平均 100 トークンのメモリ 10,000 件で約 $0.02 — 無視できる程度です。
コールドスタート
埋め込みが構成される前に保存されたメモリには埋め込みがありません。 を実行してバックフィルしてください。
プロバイダー依存
埋め込みプロバイダーがダウンした場合、セマンティック検索は graceful に失敗します（空の結果またはエラーを返す）。FTS5 は引き続き動作します。
埋め込みが利用できない場合
埋め込みサービスが構成されていない場合：
- は 503 Service Unavailable を返す
- は引き続き動作（埋め込みは生成されないだけ）
- FTS5 検索は引き続き動作
ベストプラクティス
> [!TIP]
> - 概念的クエリにはセマンティックを使用 — 「X をどう処理するか？」
> - 特定の用語には FTS5 を使用 — 「docker swarm」
> - 定期的に埋め込みをバックフィル —
> - プロバイダーの健全性を監視 — セマンティック検索はそれに依存
> - タグと組み合わせ — セマンティック + タグフィルタで結果を絞り込み
次のステップ
- FTS5 Search
- Memory API
- Architecture
## カテゴリ: LLMクックブック
LLMエージェントのレシピとパターン。
────────────────────────────────────────────────────────────
# チャットポーリングパターン
SUMMARY: ツール呼び出しの間に人間のメッセージをポーリングし、ワークフローをブロックしない方法。
チャットポーリングパターン
チャットシステムは非同期です — 作業中でも人間はメッセージを残せます。本パターンは、ワークフローをブロックせずにメッセージをポーリングする方法を示します。
パターン
[CODE BLOCK]
タイトループではなく、ツール呼び出しの間にポーリングします。
ツール呼び出しの間にポーリングする理由
- ブロックしない — タイトループでのポーリングは API 呼び出しを無駄にする
- メッセージを見逃さない — ポーリングが少なすぎると応答が遅い
- 適切な頻度 — 30〜60 秒ごと、または各ツール呼び出し後にポーリング
実装
基本的なポーリング
[CODE BLOCK]
パターン 1：各ツール呼び出し後にポーリング
[CODE BLOCK]
パターン 2：時間ベースのポーリング
[CODE BLOCK]
パターン 3：イベント駆動（Webhook 使用）
リアルタイム通知には、Webhook を登録します。
[CODE BLOCK]
その後、Webhook ハンドラがエージェントを起動できます。
[CODE BLOCK]
メッセージ処理パターン
パターン：確認してから処理
[CODE BLOCK]
パターン：バッチ処理用のキュー
[CODE BLOCK]
パターン：優先度ルーティング
[CODE BLOCK]
ポーリング頻度
| ユースケース | 頻度 |
|----------|-----------|
| インタラクティブエージェント（人間待機） | 5〜10 秒ごと |
| バックグラウンドエージェント | 30〜60 秒ごと |
| バッチ処理 | 5 分ごと |
| Webhook トリガー | ポーリング不要 — Webhook を使用 |
> [!WARNING]
> 5 秒につき 1 回を超えるポーリングは API 呼び出しを無駄にします。 エンドポイントは保留中メッセージがあれば即座に返すため、より高速なポーリングにメリットはありません。
マルチエージェントチャット
エージェント間通信用：
[CODE BLOCK]
ベストプラクティス
> [!TIP]
> - ツール呼び出しの間にポーリング — タイトループでしない
> - 即座に確認 — 人間はメッセージが届いたと知る
> - 非同期で処理 — 長い作業でブロックしない
> - リアルタイムには Webhook を使用 — ポーリングにはレイテンシあり
> - 5 秒につき 1 回を超えてポーリングしない — API 呼び出しを無駄にする
よくある問題
メッセージが見失われる
- は自動的にメッセージを既読にする
- 処理しなければ、消える
- 対策： 返却前に必ずメッセージを処理
重複返信
- ハンドラがクラッシュすると、2 回返信する可能性
- 対策： ハンドラを冪等にする（既に返信したか確認）
遅い応答
- 60 秒ごとのポーリングは最大 60 秒のレイテンシを意味する
- 対策： 10〜30 秒ごとにポーリング、または Webhook を使用
次のステップ
- Chat API
- Session Start Pattern
- Error Recovery
────────────────────────────────────────────────────────────
# エージェントのエラー復旧
SUMMARY: LLM エージェントがエラーを処理し復旧する方法 — 再試行、保存、学習。
エージェントのエラー復旧
エラーは発生します。ネットワークは失敗し、API は 500 を返し、Mind Key は失効します。本ガイドは LLM エージェントがエラーを適切に処理し、そこから学習する方法を示します。
エラー処理の原則
1. バックオフで再試行 — 一時的エラーは解決することが多い
2. エラーを保存 — パターンから学習
3. 緩やかに縮退 — セッション全体をクラッシュさせない
4. 人間に通知 — 解決できないエラーについて
HTTP エラー処理
指数バックオフで再試行
[CODE BLOCK]
認証エラー処理
[CODE BLOCK]
エラーをメモリとして保存
エラー発生時、将来のセッションが学習できるよう保存します。
[CODE BLOCK]
よくあるエラーシナリオ
シナリオ 1：Mind Key 無効
[CODE BLOCK]
シナリオ 2：ネットワークエラー
[CODE BLOCK]
シナリオ 3：レート制限
[CODE BLOCK]
シナリオ 4：サーバーエラー（5xx）
[CODE BLOCK]
シナリオ 5：ツール呼び出し失敗
[CODE BLOCK]
パターン：サーキットブレーカー
繰り返し失敗に対しては、一時的に試行を停止します。
[CODE BLOCK]
ベストプラクティス
> [!TIP]
> - 一時的エラーは常に再試行 — ネットワークは失敗し、サーバーは一時的に不調になる
> - クライアントエラー（4xx）は再試行しない — 自然には解決しない
> - エラーをメモリとして保存 — パターンから学習
> - クリティカルエラーは人間に通知 — 知る必要がある
> - 緩やかに縮退 — 部分的作業はクラッシュより良い
> - サーキットブレーカーを使用 — 失敗中のサービスを叩き続けない
次のステップ
- Errors API Reference
- Session Start Pattern
- Self-Healing Tests
────────────────────────────────────────────────────────────
# メモリタグ付け戦略
SUMMARY: 効果的な検索とフィルタリングのためのメモリのタグ付け方法 — スケールするタグ付けシステム。
メモリタグ付け戦略
タグはスケーラブルなメモリ取得の秘訣です。本ガイドは、適切なタイミングで適切なメモリが戻ってくるようにメモリにタグを付ける方法を示します。
タグが重要な理由
タグがない場合、フラットな全文検索しかありません。タグがあれば、構造化されたナビゲーションが可能になります。
[CODE BLOCK]
タグによって可能になること：
- 高速なフィルタリング —
- スコープ付き検索 —
- グループ化 — あるプロジェクトのすべての「失敗」メモリを見つける
- 相互参照 — タグを共有するメモリは関連している
タグ付けスキーマ
プロジェクトタグ
プロジェクト名をタグとして使用します：
[CODE BLOCK]
テクノロジータグ
テクノロジー名を使用します：
[CODE BLOCK]
トピックタグ
トピックカテゴリを使用します：
[CODE BLOCK]
ステータスタグ
ステータス指標を使用します：
[CODE BLOCK]
タイプタグ
タイプ指標を使用します：
[CODE BLOCK]
タグ付けルール
ルール 1：メモリあたり 2〜5 個のタグ
少なすぎると発見性が低くなり、多すぎるとノイズになります。
[CODE BLOCK]
ルール 2：小文字、ハイフン区切り
[CODE BLOCK]
ルール 3：一貫した語彙を使用
タグ付けの語彙を確立し、それに従ってください：
[CODE BLOCK]
ルール 4：検索意図でタグ付け
「このメモリをどうやって検索するか？」を自問してください。
[CODE BLOCK]
パターン
パターン 1：プロジェクト + トピック
[CODE BLOCK]
検索：（Synapse プロジェクトのすべてのメモリ）
検索：（Synapse 内のデプロイ関連メモリ）
パターン 2：タイプ + ドメイン
[CODE BLOCK]
検索：（すべての失敗）
検索：（デプロイ関連の失敗）
パターン 3：階層型
プロジェクト内のサブプロジェクト用：
[CODE BLOCK]
検索：（Synapse 全体）
検索：（docs サブプロジェクトのみ）
パターン 4：ステータス追跡
[CODE BLOCK]
よくあるユースケース
プロジェクトに関するすべての決定を見つける
[CODE BLOCK]
ドメイン内のすべての失敗を見つける
[CODE BLOCK]
アクティブな作業を見つける
[CODE BLOCK]
技術に関するメモリを見つける
[CODE BLOCK]
タグのメンテナンス
定期的なレビュー
[CODE BLOCK]
タグの統合
タグに一貫性がない場合（ と ）は統合してください：
[CODE BLOCK]
ベストプラクティス
> [!TIP]
> - 早期に語彙を確立 — 1 日目から一貫したタグを
> - 検索意図でタグ付け — 後でどうやって見つけるか？
> - 2〜5 個が最適 — 少なすぎても多すぎても悪い
> - 小文字 + ハイフン — ではなく
> - 定期的にレビュー — 重複を統合、未使用を削除
次のステップ
- Memory Best Practices
- FTS5 Search
- Task-Driven Workflow
────────────────────────────────────────────────────────────
# セッション開始パターン
SUMMARY: すべての LLM エージェントが従うべき標準的なセッション開始シーケンス。
KEY CONTEXT:
ALWAYS at session start: 1) GET /memory/recall, 2) GET /chat/poll, 3) GET /mind/tasks?status=in_progress
Build system prompt from recall output.
Process unread chat messages before doing new work.
Resume any in_progress tasks before starting new ones.
Store new learnings as they happen — don't wait until session end.
セッション開始パターン
すべての LLM エージェントセッションはこの標準的なスタートアップシーケンスに従うべきです。ステップを省略すると、コンテキストの喪失、メッセージの見逃し、タスクの忘れにつながります。
パターン
[CODE BLOCK]
実装
ステップ 1：すべてのメモリをリコール
> [!CRITICAL]
> これが最も重要な呼び出しです。これがないと、過去のセッションの記憶がありません。
[CODE BLOCK]
すべてのメモリのプレーンテキストサマリーを優先度順で返します。
ステップ 2：未読チャットメッセージをポーリング
[CODE BLOCK]
人間からの未読メッセージを返します。自動的に既読にします。
ステップ 3：進行中のタスクを確認
[CODE BLOCK]
前回のセッションで作業していたタスクを返します。
ステップ 4：コンテキストを構築
3 つのレスポンスをシステムプロンプトにまとめます：
[CODE BLOCK]
ステップ 5：保留中の項目を処理
[CODE BLOCK]
完全な例
[CODE BLOCK]
よくある間違い
> [!WARNING]
> - リコールを省略 — コンテキストなしで開始し、過去の失敗を繰り返す
> - チャットのポーリング忘れ — 人間のメッセージが未応答のまま
> - アクティブなタスクの無視 — 作業が実行中に忘れられる
> - 何も保存しない — セッションが永続的価値を生まない
バリエーション
最小パターン（低コンテキスト LLM）
コンテキストウィンドウが小さい LLM の場合、完全なリコールを省略します：
[CODE BLOCK]
必要に応じて特定のトピックを検索します：
[CODE BLOCK]
積極的パターン（長時間実行エージェント）
数時間動くエージェントには、定期的な再リコールを追加します：
[CODE BLOCK]
次のステップ
- Memory Tagging Strategy
- Task-Driven Workflow
- Chat Polling Pattern
────────────────────────────────────────────────────────────
# タスク駆動ワークフロー
SUMMARY: Synapse タスクを使用してセッションをまたぐマルチステップ LLM ワークフローを駆動。
タスク駆動ワークフロー
タスクは単なる TODO ではありません — 永続的 LLM ワークフローの骨格です。マルチステップ作業のタスクを作成することで、セッションをまたぐ継続性を確保し、作業内容の監査証跡を提供できます。
なぜタスク駆動か？
タスクがない場合：
- LLM は各セッションで何をすべきか不明なまま開始
- マルチステップ作業が実行中に忘れられる
- 何が行われたかの記録なし
タスクがある場合：
- LLM は進行中タスクを即座に再開
- マルチステップ作業がセッションをまたいで存続
- すべての作業の組み込み監査証跡
パターン
[CODE BLOCK]
実装
ステップ 1：マルチステップ作業のタスクを作成
[CODE BLOCK]
ステップ 2：タスクの説明で進捗を追跡
[CODE BLOCK]
ステップ 3：セッションをまたいで再開
[CODE BLOCK]
ステップ 4：完了してアーカイブ
[CODE BLOCK]
完全な例：デプロイワークフロー
[CODE BLOCK]
タスク階層
複雑な作業には、親子タスク関係を使用します：
[CODE BLOCK]
サブタスクを検索：
[CODE BLOCK]
ステータスワークフロー
[CODE BLOCK]
保留中
作成されたが未開始のタスク。計画作業に使用。
進行中
現在作業中。説明に進捗を更新。
完了
正常に完了。説明にサマリーを含めるべきです。
キャンセル
放棄。説明に理由を含めるべきです。
ベストプラクティス
> [!TIP]
> - マルチステップ作業にタスクを作成 — 単一ステップ作業にタスクは不要
> - 説明に進捗を更新 — 再開を可能にする
> - アクティブな作業に高優先度を使用 — リコールで浮上
> - 完了時にタスクを完了 — inprogress のまま放置しない
> - 完了サマリーをメモリとして保存 — 長期参照
よくあるパターン
パターン：バグ修正ワークフロー
[CODE BLOCK]
パターン：調査ワークフロー
[CODE BLOCK]
次のステップ
- Session Start Pattern
- Chat Polling Pattern
- Error Recovery
## カテゴリ: よくある質問
よくある質問と一般的な問題。
────────────────────────────────────────────────────────────
# API FAQ
SUMMARY: API に関するよくある質問 — 認証、レート制限、エラー処理、エンドポイント探索。
API FAQ
Synapse API に関するよくある質問です。
認証はどうすればよいですか？
2 つの方法があります。
1. Mind Key（データエンドポイント用）：
2. JWT（アカウントエンドポイント用）：
またはクエリパラメータ経由（60 回/分の制限あり）：
Authentication を参照。
Mind Key と JWT の違いは何ですか？
- Mind Key：テナントスコープ、期限切れなし、メモリ/チャット/タスクデータ用
- JWT：ユーザースコープ、7 日間の有効期限、アカウント/mind 管理用
Mind Key vs JWT を参照。
401 Unauthorized が出るのはなぜですか？
よくある原因：
1. ヘッダーの欠落
2. 無効な Mind Key（ で始まるか確認）
3. Mind Key が必要な場所で JWT を使用（またはその逆）
4. Mind Key が失効している
対策： トークンを確認してください。Authentication を参照。
404 Not Found が出るのはなぜですか？
誤ったエンドポイントパスを使用しています。Synapse には にリストされたパスのみが存在します。
対策： を呼び出して有効なパスをすべて確認してください。推測しないでください。
429 Too Many Requests が出るのはなぜですか？
クエリパラメータ認証を使用しており、60 回/分にレート制限されています。
対策： ヘッダーに切り替えてください（レート制限なし）。
Rate Limits を参照。
すべてのエンドポイントを一覧表示するには？
[CODE BLOCK]
適切なエンドポイントを見つけるには？
1. で機械可読リストを確認
2. で完全な API ドキュメントを確認
3. でドキュメントシステムを参照
4. で OpenAPI 3.0 仕様を使用
POST の代わりに GET を使用できますか？
一部の POST エンドポイントには、URL 単体のツール向けに GET 版があります。
- ↔
- ↔
- ↔
で利用可能な GET バリアントを確認してください。
エラーはどう処理すればよいですか？
すべてのエラーは JSON を返します。
[CODE BLOCK]
Errors & Error Handling を参照。
リクエストボディの上限は？
10 MB です。それ以上のペイロード（ファイルアップロードなど）には multipart エンドポイントを使用してください。
API は CORS をサポートしていますか？
はい。全エンドポイントが以下を返します。
[CODE BLOCK]
SDK はありますか？
はい。
- Node.js：
- MCP：
詳しくは API Overview を参照。
ページネーションはどうすればよいですか？
と を使用します。
[CODE BLOCK]
デフォルト limit：100。最大：500。
カテゴリやタグでメモリをフィルタできますか？
はい。
[CODE BLOCK]
メモリを検索するには？
2 つの方法があります。
1. FTS5 キーワード検索：
2. セマンティック検索：
FTS5 Search と Semantic Search を参照。
メモリを更新するには？
同じ + で を呼び出すと、既存メモリが重複ではなく更新されます。
[CODE BLOCK]
メモリを削除するには？
[CODE BLOCK]
一括削除はできますか？
はい。
[CODE BLOCK]
次のステップ
- API Overview
- Errors & Error Handling
- Authentication
────────────────────────────────────────────────────────────
# 一般 FAQ
SUMMARY: Synapse に関するよくある質問 — 概要、仕組み、対象者。
一般 FAQ
Synapse に関するよくある質問です。
Synapse とは何ですか？
Synapse は LLM エージェント向けの永続メモリ API です。AI アシスタントにセッションをまたいで存続する永続的かつクエリ可能な「脳」を与えます。チャットが閉じてもすべてを忘れるのではなく、LLM はシンプルな HTTP API でメモリを保存・取得します。
詳細： What is Synapse?
Synapse の対象者は？
- 永続状態が必要な LLM エージェント開発者
- ローカル LLM とカスタムエージェントを動かす パワーユーザー
- 共有メモリを持つ AI アシスタントを構築する チーム
- セッションをまたいで LLM 呼び出しを連鎖させる 自動化エンジニア
Synapse は無料ですか？
Synapse は でホストされており、個人利用は無料です。セルフホストについては リポジトリ を参照してください。
ChatGPT Memory との違いは？
| 機能 | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| ストレージ | OpenAI サーバー | あなたのサーバー |
| API アクセス | なし | あり（REST + MCP） |
| マルチテナント | なし | あり（minds） |
| カスタムカテゴリ | なし | あり（8 カテゴリ） |
| フルテキスト検索 | 限定的 | FTS5 + セマンティック |
| セルフホスト可能 | なし | あり |
Synapse はどの LLM で動作しますか？
HTTP 呼び出しや MCP を使用できる任意の LLM で動作します。
- Claude（Anthropic）— MCP または直接 API 経由
- GPT-4 / GPT-3.5（OpenAI）— function calling + API 経由
- Gemini（Google）— function calling + API 経由
- Llama / Mistral（ローカル）— カスタム連携経由
- Synapse MCP サーバー経由で任意の LLM
自分で Synapse をホストする必要がありますか？
いいえ。 のホスト版が公開利用可能です。セルフホストはオプションです（プライバシー、カスタマイズ、エアギャップ環境向け）。
どれくらいのデータを保存できますか？
ホスト版にハードリミットはありません。典型的な利用：
- mind ごとに 100〜1000 メモリ
- メモリごとに 1〜10 KB（content フィールド）
- 合計：mind あたり約 10 MB
より大規模な用途にはセルフホストしてください。
データはプライベートですか？
はい。各 mind は分離されています（Multi-Tenancy を参照）。他のユーザーはあなたのデータを見られません。ホスティングプロバイダー（Schaefer Services）はアクセス権を持ちますが、ユーザーデータを閲覧しません。
最大限のプライバシーには、セルフホストしてください。
データをエクスポートできますか？
はい。 で全メモリを JSON としてエクスポートできます。Backup & Restore を参照。
Mind Key を失くしたらどうなりますか？
Mind Key は作成時に一度しか表示されません。失くした場合：
1. メール/パスワードでログインして JWT を取得
2. で新しい mind を作成
3. 新しい Mind Key を保存
4. （オプション） で古い mind を削除
キーを失くした mind からメモリを復元することはできません。
複数の LLM エージェントが 1 つの mind を共有できますか？
はい。同じ Mind Key を使用するすべてのエージェントがその mind のデータを共有します。協調マルチエージェント作業については Multi-Agent Coordination を参照してください。
Synapse はオフラインで動作しますか？
いいえ。Synapse はサーバー（ホスト版またはセルフホスト版）へのインターネット接続が必要です。オフライン LLM には、Synapse をローカルで動かしてください。
メモリ検索の速度は？
- FTS5 キーワード検索：1000 メモリで 10ms 未満
- セマンティック検索：1000 メモリで 50〜100ms
- 完全再取得：1000 メモリで 50ms 未満
詳しくは FTS5 Search を参照。
LLM なしで Synapse を使えますか？
はい。Synapse は汎用メモリ API です。カテゴリとタグを持つ永続的で検索可能なキーバリューストレージが有益な任意のアプリケーションから使用できます。
次のステップ
- What is Synapse?
- Quick Start
- API FAQ
────────────────────────────────────────────────────────────
# MCP FAQ
SUMMARY: MCP 連携に関するよくある質問 — ツール、トランスポート、トラブルシューティング。
MCP FAQ
Synapse MCP サーバーに関するよくある質問です。
MCP とは何ですか？
MCP（Model Context Protocol）は LLM とツールの連携のための Anthropic によるオープン標準です。プロンプトに API ドキュメントを貼り付ける代わりに、MCP サーバーにツールを登録し、LLM がネイティブ関数として呼び出します。
What is MCP? を参照。
Synapse MCP はいくつのツールを公開していますか？
12 カテゴリにわたり 79 ツール：memory、chat、scheduler、tasks、scripts、computers、push、user、utility、visualization、sharing、webhooks、browser。
完全なリストは What is MCP? を参照。
どの MCP クライアントがサポートされていますか？
- Claude Desktop（macOS、Windows）
- Claude Code（ターミナル）
- Cursor（IDE）
- Continue.dev（VS Code、JetBrains）
- Cline（VS Code）
- MCP 互換の任意のクライアント
設定例は Claude Desktop Setup を参照。
どのトランスポートがサポートされていますか？
1. stdio（ローカル、デスクトップに推奨）
2. HTTP/SSE（リモート、マルチテナント）
3. WebSocket（モバイル、高頻度）
Claude Desktop での設定方法は？
を編集します。
[CODE BLOCK]
Claude Desktop Setup を参照。
Claude Desktop にツールが表示されないのはなぜですか？
1. Claude Desktop を完全に再起動（macOS では Cmd+Q）
2. 設定ファイルが有効な JSON か確認
3. Node.js 18+ がインストールされているか確認
4. MCP ログを確認：
MCP Troubleshooting を参照。
別の mind を使うには？
MCP 設定の を変更し、クライアントを再起動してください。
複数の mind を使用するには、異なる Mind Key で複数の MCP サーバーインスタンスを動かします。
公開するツールを制限できますか？
はい、Tool Profiles を使用します。
- ：8 コンポジットツール（約 500 トークン）
- ：25 ツール（約 2,500 トークン）
- ：119 ツール（約 8,250 トークン、デフォルト）
環境変数または ヘッダーで設定します。
MCP の問題をデバッグするには？
1. MCP サーバーを手動で実行：
2. クライアントログを確認（クライアントにより異なります）
3. Mind Key が動作するか確認：
4. Synapse のヘルスを確認：
MCP Troubleshooting を参照。
MCP サーバーは無料ですか？
はい。npm パッケージ はオープンソースです。 のホスト版 MCP サーバーは公開利用が無料です。
MCP サーバーをセルフホストできますか？
はい。
[CODE BLOCK]
MCP と直接 API 呼び出しの違いは？
| 側面 | 直接 API | MCP |
|--------|-----------|-----|
| LLM が知る必要があるもの | URL、ヘッダー、認証 | ツール名のみ |
| 認証処理 | 手動 | 自動（環境変数） |
| ツール探索 | /endpoints を読む | MCP プロトコルで自動 |
| エラー処理 | 手動 | 標準化 |
| 最適な用途 | カスタム連携 | LLM エージェント |
独自の MCP クライアントを構築できますか？
はい。公式 MCP SDK を使用してください。
- TypeScript：
- Python：
Custom MCP Client を参照。
MCP のバグを報告するには？
Issue を開いてください：
含めるもの：
- MCP サーバーのバージョン
- クライアント名とバージョン
- オペレーティングシステム
- 関連ログ
- 再現手順
次のステップ
- What is MCP?
- Claude Desktop Setup
- MCP Troubleshooting
────────────────────────────────────────────────────────────
# トラブルシューティング FAQ
SUMMARY: Synapse のよくある問題の解決策 — 認証、ネットワーク、データ、デプロイ。
トラブルシューティング FAQ
Synapse のよくある問題の解決策です。
ログインできない
症状
- が 401 を返す
- "Invalid email or password"
解決策
1. メールアドレスが正しいか確認 — 大文字小文字を区別
2. パスワードを確認 — 最低 6 文字
3. アカウントがない場合は登録：
4. パスワードリセット（SMTP 構成時）— Web UI 経由
Mind Key を失くした
症状
- メモリにアクセスできない
- Mind Key が削除/紛失
解決策
Mind Key は復元できません。以下を行う必要があります。
1. ログインして JWT を取得：
2. mind を一覧：（JWT で）
3. 新しい mind を作成：
4. 新しい Mind Key を保存
5. （オプション）古い mind を削除：
古い mind のデータは失われます — Mind Key が見つからない限り。
API 呼び出しが 401 を返す
症状
- すべての API 呼び出しが 401 Unauthorized を返す
- "Mind Key fehlt oder ungültig"
解決策
1. ヘッダー形式を確認：
2. Mind Key が で始まるか確認（ は JWT）
3. 直接テスト：
[CODE BLOCK]
4. Mind Key が失効している可能性 — 新しい mind を作成
Authentication を参照。
API 呼び出しが 404 を返す
症状
- 404 Not Found
- "Route not found"
解決策
> [!CRITICAL]
> エンドポイントのパスを推測しないでください。 にあるパスのみが存在します。
1. 有効なエンドポイントを確認：
2. URL を正確に比較 — 大文字小文字を区別、末尾スラッシュなし
3. HTTP メソッドを確認 — と は異なる
API 呼び出しが 429 を返す
症状
- 429 Too Many Requests
- "Rate limit exceeded"
解決策
1. ヘッダー認証に切り替え（レート制限なし）：
[CODE BLOCK]
2. を使う必要がある場合は 秒待機
Rate Limits を参照。
メモリ検索が結果を返さない
症状
- が空を返す
- メモリが存在することは分かっている
解決策
1. メモリが存在するか確認：
2. 検索構文を確認 — FTS5 には固有の構文があります
3. よりシンプルなクエリを試す — ではなく
4. 概念的クエリにはセマンティック検索を使用：
FTS5 Search を参照。
メモリが永続化されない
症状
- POST /memory は成功を返す
- GET /memory/recall に表示されない
解決策
1. 同じ Mind Key か確認 — 異なるキー = 異なる mind
2. レスポンスを確認 — POST は を返す
3. /memory/recall（テキスト）の代わりに GET /memory（JSON リスト）を試す
4. フィルタを確認 — や が隠している可能性
Claude Desktop にツールが表示されない
症状
- Claude Desktop が 0 ツールを表示
- 🔌 アイコンがない
解決策
1. Claude Desktop を完全に再起動（Cmd+Q）
2. 設定ファイルが有効な JSON か確認
3. Node.js 18+ がインストールされているか確認
4. MCP を手動で実行：
5. ログを確認：
MCP Troubleshooting を参照。
Synapse がオフライン
症状
- synapse.schaefer.zone に届かない
- curl がタイムアウト
解決策
1. インターネット接続を確認 — 別のサイトを試す
2. Synapse のヘルスを確認：
3. 待機 — 一時的な停止やデプロイの可能性
4. ステータスページを確認（あれば）
セルフホストの場合：Docker コンテナのステータス、データベース接続を確認。
データベースエラー
症状
- 500 Internal Server Error
- "Database connection failed"
解決策
セルフホストの場合：
1. PostgreSQL が実行中か確認：
2. 環境の DATABASEURL を確認
3. マイグレーションを確認：
4. ディスク容量を確認：
ホスト版の場合：サポートに報告。
Webhook が発火しない
症状
- Webhook を登録したがコールバックを受け取らない
- あなたの URL に POST が来ない
解決策
1. URL が到達可能か確認：
2. events フィルタを確認 — は全メモリイベントにマッチ
3. Webhook をテスト：
4. Webhook が有効か確認：
5. SSL を確認 — Synapse は Webhook URL に有効な HTTPS を要求
Webhooks API を参照。
Cron ジョブが実行されない
症状
- Cron ジョブを作成したが発火しない
- が更新されない
解決策
1. スケジュール構文を確認 — 有効な 5 フィールド cron または整数秒である必要
2. エンドポイントが許可されているか確認 — http(s) で、プライベート IP 不可
3. ジョブが有効か確認：
4. 次のスケジュール時刻まで待機 — cron は即時ではない
Cron & Scheduler を参照。
さらにヘルプが必要な場合
1. 既存のドキュメントを確認：
2. ドキュメントを検索：
3. Issue を開く：
4. 連絡先： ページを参照
次のステップ
- Errors & Error Handling
- API FAQ
- MCP Troubleshooting