エージェントサーバー

PocketHook Agent Serverとは？

#

エージェントサーバーはPocketHookを完全なAIアシスタントに変えます。レスポンスロジックを自分で書く代わりに、LLM（Claude、GPT、Geminiなど）を接続してメッセージを処理し、ツールを呼び出し、構造化されたPocketHookレスポンス（ショートカットトリガーを含む）を返します。

サーバーはあなた自身のマシンで動作します。データはあなたの手元にあります。

これは出発点です。 サーバーには基本的なツールセットが含まれており、あなたが拡張できるように設計されています。メール、カレンダー、ドキュメント、APIなど、独自のインテグレーションを追加して、あなたのものにしましょう。

機能

#

• マルチプロバイダーLLM — Anthropic、OpenAI、GitHub Copilot、Google、Mistral、Groq、xAI、OpenRouter、Ollama（ローカル）、LM Studio（ローカル）
• OAuth認証 — GitHub CopilotとOpenAI Codex（デバイスコード/ブラウザフロー経由）
• エージェントツール — シェルコマンド、ファイル読み書き、ディレクトリ一覧、Web検索、Webスクレイピング、開発サーバー管理
• フレームワーク/ユーザー分離 — フレームワークファイル（skills/、custom-tools/、config/）は読み取り専用のまま。あなたのカスタマイズはdata/user/配下（スキル、カスタムツール、インストラクション、型付きprefs）に配置。フレームワーク更新はあなたの作業を上書きせずにクリーンに適用
• 型付きユーザーprefs — お好みの地図アプリやトンネルドメインなどの値をdata/user/prefs.jsonに保存。スキル内で{{prefs.key}}として参照すると、サーバーが読み込み時に置換
• プログラミングタスクを1回の呼び出しで — run_code_jobメタツールが prompt タイプのバックグラウンドジョブ（あなたが構成したLLMで実行）を作成し、ユーザーへの受領通知を1ステップで送信。エラーの起きやすい「respond + create-job」パターンを置き換え
• 型付きプロトコルツール — 6つの専用 respond_* ツール（respond_text、respond_image、respond_buttons、respond_shortcut、respond_html、respond_sequence）に加え、型付きジョブツール（create_once_job、create_cron_job）と型付きワークスペースツール（create_project、list_projects、delete_project）。スキーマは不正なURL、ボタン構文、type/scheduleの組み合わせをデバイスに到達する前に拒否
• カスタマイズ用の型付きライター — create_user_skill と create_custom_tool がユーザーレイヤーのmarkdownを正しいfrontmatter付きで構築。ローダーが常にパースでき、エージェントがこれらのファイルを手書きすることはありません
• バックグラウンドジョブ — cron式またはシンプルな間隔による一回限りまたは繰り返しタスク
• ダイナミックスキル — ショートカットや動作ルールを.mdファイルで定義。コンパクトなインデックスのみがプロンプトに読み込まれ、完全な内容はload_skillツールでオンデマンドに取得
• 自己管理スキル — エージェントがスキル定義を作成、編集、削除可能（書き込みは常にユーザーレイヤーに配置）
• セマンティックメモリ — エンベディング（Ollama、LM Studio、またはOpenAI）によるベクトルベース検索。メモリはLLMによってwing/room/hall/statusの4次元に自動分類
• 知識グラフ — 自動無効化機能付きの時間的トリプルストア。複数値リレーションシップは共存し、単一値ファクトは自動置換
• PARAメソッド（プロジェクト終了時のカスケード付き） — すべてのメモリにステータス（Project、Area、Resource、Archive）がタグ付け。プロジェクト終了時は1回のcomplete_project呼び出しで、そのベクトルをアーカイブし、そのスラッグに紐づく全ての計画トリプルを無効化し、完了を記録 — 3回ではなく1回の呼び出しで完結
• ハイブリッドリコール — FTS5キーワード検索とベクトルセマンティック検索を相互ランク融合で組み合わせ
• 長期記憶 — セマンティックメモリが無効な場合のフォールバックとして、SQLite + FTS5全文検索
• トンネル契約付き開発サーバー管理 — 開発サーバーの起動、停止、一覧表示。tunnel: trueが要求された場合、サーバーは起動前と起動後の両方でそれを強制 — 到達不能なlocalhostサーバーが静かに放置されることはありません
• 自動URLサニタイズ — エージェントが応答にlocalhost URLを残した場合、respond_*ツールが対応するトンネルURLに書き換えるため、お手持ちの電話は常に到達可能なリンクを受け取ります
• カスタムツール — エージェントがCLIツールをインストールし、新しい機能として登録可能
• バージョニング — ワークスペースファイルの自動gitバージョニング。スキルとパーミッションの設定バックアップ
• Webダッシュボード — バックグラウンドジョブのライブ概要。ユーザーごとにカスタマイズ可能。/dashboard と /api/jobs は設計上認証なし — ネットワーク層でアクセスを制限してください（Tailscale ACL、ファイアウォール、basic auth付きリバースプロキシ）。不要な場合は DASHBOARD=false を設定
• HTTPSトンネリング — Tailscale、ngrok、Cloudflare Tunnelの組み込みサポート
• システムサービス — macOS、Linux、またはWindowsで永続サービスとしてインストール
• レート制限 — 設定可能なしきい値によるトークンごとのリクエスト制限

要件

#

• Bun ランタイム
• LLMプロバイダーのAPIキーまたはOAuth認証情報
• （オプション）Tailscale、ngrok、またはcloudflared（HTTPSトンネリング用）

クイックスタート

#

git clone https://github.com/pockethook-app/pockethook-agent-server.git
cd pockethook-agent-server
bun install

# インタラクティブセットアップ — プロバイダー、モデル、認証トークン、ポートを選択
bun run setup

# サーバー + HTTPSトンネルを起動
bun run dev:tunnel

セットアップウィザードが、LLMプロバイダーの選択、認証の設定、ツールパーミッションの構成をガイドします。

起動後、表示されたURLをPocketHook設定にコピーしてください：

仕組み

#

1. PocketHookでメッセージを送信
2. サーバーが選択したLLMに会話履歴、呼び出されたメモリ、利用可能なツールとともに転送
3. LLMがメッセージを処理 — シェルコマンドの実行、ファイルの読み書き、Web検索、バックグラウンドジョブのスケジュール、ファクトの記憶、開発サーバーの起動が可能
4. レスポンスがPocketHook形式（msg + shortcut + data + url）で返される
5. PocketHookがメッセージを表示し、デバイス上でショートカットを実行

サポートされるLLMプロバイダー

#

bun run switchでいつでもプロバイダーを切り替えられます。OllamaとLM Studioは完全にあなたのマシン上で動作します — APIキー不要、データがネットワーク外に出ることはありません。

メモリ

#

メモリシステムは3つのレイヤーで構成され、それぞれ異なる目的を持ちます。

セマンティックメモリの設計は、MemPalace（メモリをwing、hall、roomに整理するメモリパレスアーキテクチャ）とTiago ForteのPARAメソッド（Projects、Areas、Resources、Archive — 知識ライフサイクル管理）のアイデアを組み合わせています。

会話メモリ

#

FTS5全文検索付きSQLite。すべてのメッセージがタイムスタンプとセッションIDとともに保存されます。

• 短期 — セッションごとに最新 MAX_HISTORY 件のメッセージをメモリに保持
• 長期 — すべてのメッセージがSQLiteに永続化され、FTS5キーワードマッチングで検索可能
• ターンごとのリコール — セマンティックメモリが有効な場合、MAX_RECALL が各ターンでプロンプトに注入される関連メモリの数を制御
• セッションはSESSION_TTL_MINUTES後に期限切れになりますが、長期記憶は永久に保持

これらは bun run memory でインタラクティブに調整できます。

セマンティックメモリ

#

VECTOR_MEMORY=trueとエンベディングプロバイダー（Ollama、LM Studio、またはOpenAI）が必要です。

各メモリはベクトルとして埋め込まれ、LLMによって4つの次元に自動分類されます：

• Wing — エンティティ：user、person:john、project:blog、place:london
• Room — タイプ：facts、preferences、events、decisions、requests
• Hall — トピック：personal、tech、health、travel、food、work
• Status — PARA分類：project、area、resource、archive

質問すると、エンティティ抽出が最も関連性の高いwingにベクトル検索を集中させます。結果は相互ランク融合を使ってFTS5キーワード結果とマージされ、キーワードマッチングとセマンティックマッチングの両方の長所を得られます。

知識グラフ

#

構造化された永続的なファクトのための時間的トリプルストア：

• トリプル：(subject, predicate, object) に valid_from / valid_until タイムスタンプ付き
• 単一値述語（lives_in、partner）は更新時に古い値を自動無効化
• 複数値述語（child、friend、hobby）は無効化なしで共存
• 知識グラフのファクトは、すべての会話で呼び出されたメモリとともに注入

エージェントに*「ベルリンに引っ越した」*と伝えると、古いlives_inトリプルを無効化し、新しいものを自動的に作成します。

PARAライフサイクル

#

すべてのメモリにPARAステータスがタグ付けされます：

• Project — アクティブな期限付きの作業
• Area — 継続的な責任
• Resource — 参照資料（リスト、推薦、ハウツー）
• Archive — 完了またはキャンセルされたプロジェクト

プロジェクトが完了すると、エージェントはセマンティック類似度を使ってそのプロジェクトのメモリのみをアーカイブし、参照資料は将来の使用のために保持します。

プロジェクト終了時のカスケード

#

*「バルセロナ旅行をキャンセルする」*と言えば、たった1回のツール呼び出しですべてを処理します：

1. プロジェクトのベクトル（バルセロナに紐づくevents、decisions、requests）をアーカイブ。
2. 述語がプロジェクトのスラッグと一致するアクティブな知識グラフトリプルをすべて無効化（scheduled_visit_barcelona、planning_visit_barcelona、confirmed_visit_barcelona）。
3. 完了を新しいトリプルとして記録：(user, "cancelled_visit_barcelona", "2026-04-15")。

マッチングは境界を認識します — revisit_barcelonaのような別のプロジェクトはそのまま残ります。エージェントは3つの別々の呼び出しを正しい順序で組み立てる必要がなくなるため、小型モデルでも正しく動作します。

VECTOR_MEMORYが無効またはエンベディングプロバイダーに接続できない場合、システムはエラーなしでFTS5のみにフォールバックします。

スキル

#

スキルはskills/ディレクトリの.mdファイルで、エージェントがトリガーできるiOSショートカットや動作ルールを定義します。ダイナミックローディングを使用：コンパクトなインデックス（タイトル、説明、ショートカットリスト）のみがシステムプロンプトに注入されます。エージェントはload_skillツールでオンデマンドに完全な内容を読み込み、スキルが増えてもトークン使用量を低く保ちます。

各スキルファイルはYAMLフロントマターを使用します：

---
title: Notes
description: Create notes on the user's device with a title and body
shortcuts: [newNote]
target: mac
sync_app: Notes
---

### New Note

Shortcut name: `newNote`

Creates a new note on the user's device.

Data fields:
- title (string, required): Note title
- content (string, required): Note body

フロントマターのフィールド

#

スキルはショートカットなしの動作ルールにもできます（例：「家族旅行の計画方法」）。その場合はshortcuts: []を使用します。

エージェントはリクエストに応じてスキルを作成・管理できます — *「照明を制御するスキルを作って」*と頼めば、.mdファイルを書いてくれます。新規作成および編集されたスキルは常にあなたのユーザーレイヤー（data/user/skills/）に配置されるため、フレームワーク更新で上書きされることはありません。下記のエージェントのカスタマイズセクションをご覧ください。

Macサーバーでショートカットを実行する

#

スキルに target: mac が設定されている場合、ショートカットはiOSデバイスに送信される代わりに、shortcuts run CLIを介してMacサーバー上でサイレントに実行されます。これは、iCloudで同期されるコンテンツ（ノート、リマインダー、カレンダーイベント）を作成するアクションに最適です — PocketHookアプリが何もしなくても、結果がすべてのデバイスに自動的に同期されるためです。

仕組み：

1. エージェントがショートカットを実行すべきと判断します（例：「今日の会議メモでノートを作成」）
2. サーバーは、PocketHook iOSが使用するのと同じラッパー形式で、stdin経由でJSONとしてデータを渡しながら shortcuts run "shortcutName" を呼び出します
3. sync_app が設定されている場合、サーバーはそのアプリをバックグラウンドで一時的に開いて（open -gj -a Notes）iCloud同期を強制し、5秒後に閉じます
4. ユーザーはチャットで確認メッセージを受け取ります。ショートカット自体はデバイスに送信されません

要件：

• サーバーは macOS 上で動作している必要があります — shortcuts run はmacOS専用です。他のプラットフォームでは、サーバーが警告をログに記録し、デバイス実行にフォールバックします
• ショートカットはサーバーMacのShortcuts.appにインストールされている必要があります
• ショートカットは入力としてDictionaryを期待する必要があります（PocketHookはデータを { context, timestamp, app, data } にラップします）

target: mac を使う場面：

• iCloud同期アクション（Notes、Reminders、Calendar） — 結果はいずれにせよすべてのデバイスに届きます
• iOSデバイスから切り離したい長時間実行の処理
• iPhoneのUIと対話する必要のないショートカット

target: device（デフォルト）のままにする場面：

• iPhone専用機能（カメラ、正確な位置情報、ローカルアプリオートメーション）が必要なショートカット
• ユーザーにインタラクティブな入力を求めるショートカット
• iOS専用アプリのApp Intentsを使用するショートカット

バックグラウンドジョブ

#

エージェントにタスクのスケジュールを頼むだけで、残りは自動的に処理されます：

• 「毎朝8時に天気を確認してノートを作成して」
• 「このスクリプトを1時間ごとに実行して」
• 「30分後にメールをチェックするようリマインドして」

ジョブはcron式（0 8 * * *）やシンプルな間隔（30m、1h、2d）をサポートします。結果はPocketHookが/jobsエンドポイントをポーリングする際に配信されます。

2つの実行タイプ：

• Shell — bashコマンドを実行し、出力をキャプチャ。完了時にショートカットをトリガー可能
• Prompt — 完全なツールアクセス権を持つAIエージェントによって処理され、完全なPocketHookレスポンスを保存

開発サーバー

#

エージェントがワークスペースにWebプロジェクト（Hugo、Astro、Next.js、Flask、Goなど）を作成すると、積極的にサーブを提案します：

• プレビュー — 自動割り当てポートでローカル開発サーバーを起動してクイック表示
• パブリック — サーバーを起動し、HTTPSトンネルで公開してどこからでもアクセス可能に

エージェントがライフサイクルを管理：起動、停止、実行中のサーバー一覧表示。メインサーバーが停止すると、すべてのサーバーがクリーンアップされます。

トンネル契約

#

エージェントがトンネル公開を要求してサーバーを起動するとき、ランタイムはそれを強制します。トンネルツール（Tailscale、ngrok、cloudflared）がインストールされていない場合、サーバーは起動を拒否します。起動後にトンネル設定が失敗した場合、孤立したプロセスは停止され、エージェントには明示的に通知されます — プレビューモードへのフォールバックや、トンネルのインストールをあなたに依頼することができるようにするためです。トンネリングが有効な場合、返されるURLは常にトンネルURLで、ローカルURLはホスト限定である旨が注記されます。

セーフティネットとして、すべての respond_* ツールが自身のメッセージを後処理します：返信に紛れ込んだlocalhostや127.0.0.1 URLは、管理中のサーバーが対応するトンネルURLを持っていれば自動的に書き換えられます。書き換えができない場合、壊れたリンクがお手持ちの電話に届く代わりに、ログに警告が表示されます。

ダッシュボード

#

/dashboardの組み込みWebダッシュボードはバックグラウンドジョブのライブ概要を表示します。

設計上認証なし。 /dashboard と /api/jobs はどちらもオープンな GET エンドポイントです — ホストに到達できる人なら誰でもジョブを一覧表示できます。ネットワーク層でアクセスを制限してください（Tailscale ACL、ファイアウォール、basic auth付きリバースプロキシ）。不要な場合は DASHBOARD=false を設定。PocketHook iOSアプリはこれらのエンドポイントを使用しません。

完全にカスタマイズ可能：

• クイック編集 — シンプルなカスタマイズにはworkspace/dashboard/にdashboard.htmlを配置
• フルプロジェクト — workspace/dashboard/にフレームワークプロジェクト（Svelte、React、Vueなど）を作成し、dist/にビルド出力

エージェントにダッシュボードのカスタマイズを頼めば対応してくれます — 各ユーザーがユニークでパーソナライズされたダッシュボードを得られます。

カスタムツール

#

エージェントはCLIツールをインストールし、新しい機能として登録できます — サーバーコードを変更せずに自身を拡張します。

例えば、*「Playwrightをインストールしてスクリーンショットを撮るのに使って」*と言ってください。エージェントは：

1. 依存関係をインストール
2. ツール定義（シンプルな.mdファイル）を作成
3. 今後の会話で新しいツールを使用

カスタムツールはホットリロード — 再起動不要。.mdファイルを削除するとツールが削除されます。

バージョニング

#

すべてのユーザーデータは自動的にバージョン管理されます：

• ワークスペースファイル — workspace/内のローカルgitリポジトリで追跡。書き込みごとに自動コミット。エージェントに*「最後の変更を取り消して」*と頼むか、手動でgit revert HEADを使用
• 設定ファイル — config/agent-instructions.md、config/personality.md、skills/、permissions.jsonは変更前にバックアップ。ファイルごとに最大20バージョン

gitはオプション — インストールされていない場合、ワークスペースの変更はバージョン管理されません。設定バックアップは常に動作します。

エージェントのカスタマイズ

#

エージェントサーバーは最小限のフレームワークベースを同梱しており、その上にあなた独自のカスタマイズをレイヤー化することを想定しています。ランタイムは両者を分離しているため、フレームワーク更新があなたの作業を上書きすることはありません。

フレームワーク vs ユーザー

#

pockethook-agent-server/
├── skills/                      # フレームワーク同梱のスキル（読み取り専用）
├── custom-tools/                # フレームワーク同梱のツール用に予約（読み取り専用）
├── config/
│   ├── agent-instructions.md    # フレームワークのエージェントインストラクション（読み取り専用）
│   └── personality.md           # フレームワークのパーソナリティ（読み取り専用）
└── data/user/                   # あなたのカスタマイズはここに配置（git管理対象外）
    ├── skills/                  # あなた自身のスキル（ファイル名でベースを上書き）
    ├── custom-tools/            # あなたがインストールしたカスタムツール
    ├── instructions.md          # エージェントインストラクションへのあなたの追記
    └── prefs.json               # {{prefs.key}}として参照される型付き値

ユーザーカスタマイズは専用の型付きツール（create_user_skill、create_custom_tool）経由で書き込まれるため、生成されるファイルは常にローダーのフォーマットに一致します。write ツールも skills/、custom-tools/、config/ 配下のパスを拒否し、エージェントを data/user/* にリダイレクトします — そのため、直接的なファイル編集でもユーザーレイヤーに収まります。

ベースのcustom-tools/ディレクトリに関する注記。 現時点ではローダーが無視するテンプレート（_example.md）のみが入っており、エージェントがあなたのためにインストールするツールはすべてdata/user/custom-tools/へ格納されます。このディレクトリは、将来のフレームワークリリースがあなたのインストール済みツールを上書きせずにオプションの組み込みツールを同梱できるように予約されています。その際も、ツール名の衝突時はあなたのユーザーレイヤーのファイルが優先されるので、移行作業は不要です。

4つのカスタマイズ方法

#

これらのファイルを手書きする必要はまったくありません。やりたいことをエージェントに伝えるだけで、適切なレイヤーを自動的に選びます。

{{prefs.*}}による型付き設定

#

デフォルトの出発地点を知る必要がある経路プランナースキルを書くとします。「Madrid」をスキルにハードコーディングする代わりに、prefを参照しましょう：

- **出発地点**: {{prefs.routeOrigin}}、ユーザーが別の出発地を指定した場合を除く。

そして値はdata/user/prefs.jsonに保存します：

{
  "routeOrigin": "Madrid, Spain",
  "preferredMapsApp": "apple",
  "tunnel": { "domain": "my-host.ts.net" }
}

サーバーはスキルが読み込まれる際にプレースホルダーを置換します。ネストされたキー（{{prefs.tunnel.domain}}）も動作します。未知のキーはそのまま残されるので、タイプミスが見えるようになっています。

フレームワークベースの直接編集

#

セルフホストしていてフレームワーク自体を調整したい場合、config/agent-instructions.md、config/personality.md、skills/、custom-tools/を直接編集できます — ファイルエディタを使う限り、サーバーはあなたを止めません。ただし、エージェントは会話からはそれらのパスに書き込みません。また、フレームワーク更新があなたの編集を上書きします。残しておきたいものは、ユーザーレイヤーを優先してください。

サーバーの拡張

#

• カスタムツール — エージェントにCLIツールのインストールを頼むと、data/user/custom-tools/に自動的に配置されます
• スキル追加 — エージェントにスキルの作成を頼むと、ファイルはdata/user/skills/に配置されます
• 動作変更 — エージェントにグローバルルールの適用を頼むと、data/user/instructions.mdに追記されます
• パーミッション設定 — bun run permissionsでエージェントが使用できるツールを制御
• 組み込みツール追加 — より深いインテグレーションのためにsrc/tools.tsに新しいツール関数を実装（サーバーのフォークが必要）

設定

#

すべての設定は.env（bun run setupで作成）に保存されます。主なオプション：

完全な設定リファレンスはGitHubリポジトリをご覧ください。

サービスとして実行

#

自動起動する永続サービスとしてインストール：

bun run service install

INSTANCE_NAME のデフォルトはプロジェクトディレクトリ名から pockethook- プレフィックスを除いたものです（例：pockethook-agent-server/ のチェックアウトは agent-server になります）。同一マシン上で複数のチェックアウトを衝突なく実行するには明示的に設定してください — 各インスタンスがそれぞれ独自の data/ とログを保持します。

bun run service status、restart、stop、uninstallで管理します。

セキュリティ

#

• HTTPS必須 — PocketHookはすべてのURLにHTTPSを強制
• Bearerトークン認証 — アプリとサーバー間の共有シークレット
• レート制限 — トークンごとの制限で悪用を防止
• サンドボックスツール — シェルコマンドとファイルアクセスはパーミッションで制限
• ブロックパターン — 危険なコマンド（sudo、rm -rf /）はデフォルトでブロック
• 作業ディレクトリ境界 — エージェントは指定されたディレクトリ外に出られない
• 機密ファイル保護 — .env、.git、*.key、*.pemはエージェントアクセスからブロック
• 自動バージョニング — すべてのワークスペース変更はgit追跡され、簡単にロールバック可能