Agent Server

Apa itu PocketHook Agent Server?

#

Agent server mengubah PocketHook menjadi asisten AI lengkap. Alih-alih menulis logika respons sendiri, Anda menghubungkan LLM (Claude, GPT, Gemini, dll.) yang memproses pesan, memanggil alat, dan mengembalikan respons PocketHook terstruktur — termasuk pemicu Shortcut.

Server berjalan di mesin Anda sendiri. Data Anda tetap milik Anda.

Ini adalah titik awal. Server dilengkapi dengan serangkaian alat inti dan dirancang untuk diperluas oleh Anda. Tambahkan integrasi Anda sendiri — email, kalender, dokumen, API — dan jadikan milik Anda.

Fitur

#

• Multi-provider LLM — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (lokal), LM Studio (lokal)
• Autentikasi OAuth — GitHub Copilot dan OpenAI Codex melalui device code / browser flow
• Alat agent — Perintah shell, baca/tulis file, daftar direktori, pencarian web, web scraping, manajemen dev server
• Pemisahan framework / pengguna — File framework (skills/, custom-tools/, config/) bersifat read-only. Kustomisasi Anda berada di bawah data/user/ (skills, custom tools, instructions, typed prefs). Pembaruan framework terpasang dengan rapi tanpa menimpa pekerjaan Anda
• Typed user prefs — Simpan nilai seperti aplikasi peta favorit atau domain tunnel di data/user/prefs.json. Referensikan di skill sebagai {{prefs.key}} dan server akan menggantinya saat dimuat
• Tugas pemrograman dalam satu panggilan — Meta-tool run_code_job membuat background job bertipe prompt (dijalankan oleh LLM yang Anda konfigurasikan) dan mengirim ack ke pengguna dalam satu langkah, menggantikan pola “respond + create-job” yang rawan kesalahan
• Alat protokol bertipe — Enam alat respond_* khusus (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), ditambah alat tugas bertipe (create_once_job, create_cron_job) dan alat workspace bertipe (create_project, list_projects, delete_project). Skema menolak URL yang tidak valid, sintaks tombol, dan kombinasi type/schedule sebelum sampai ke perangkat
• Penulis bertipe untuk kustomisasi — create_user_skill dan create_custom_tool membangun markdown lapisan pengguna dengan frontmatter yang benar, sehingga loader selalu dapat memprosesnya dan agent tidak pernah menulis file-file ini secara manual
• Tugas latar belakang — Tugas sekali atau berulang dengan ekspresi cron atau interval sederhana
• Skill dinamis — Definisikan shortcut dan aturan perilaku sebagai file .md. Hanya indeks ringkas yang dimuat ke prompt; konten lengkap diambil sesuai kebutuhan melalui alat load_skill
• Skill yang mengelola sendiri — Agent dapat membuat, mengedit, dan menghapus definisi skill (penulisan selalu mendarat di lapisan pengguna)
• Memori semantik — Pencarian berbasis vektor dengan embedding (Ollama, LM Studio, atau OpenAI). Memori diklasifikasi otomatis ke dimensi wing/room/hall/status oleh LLM
• Grafik pengetahuan — Triple store temporal untuk fakta tahan lama dengan invalidasi otomatis. Relasi multi-nilai berdampingan; fakta nilai tunggal diganti otomatis
• Metode PARA dengan cascade akhir project — Setiap memori diberi tag status (Project, Area, Resource, Archive). Ketika sebuah project berakhir, satu panggilan complete_project mengarsipkan vektornya, membatalkan setiap triple perencanaan yang terikat pada slug-nya, dan mencatat penyelesaian — satu panggilan alih-alih tiga
• Recall hibrida — Menggabungkan pencarian kata kunci FTS5 dengan pencarian semantik vektor menggunakan reciprocal rank fusion
• Memori jangka panjang — SQLite + pencarian teks lengkap FTS5 sebagai fallback saat memori semantik dinonaktifkan
• Manajemen dev server dengan tunnel contract — Mulai, hentikan, dan daftar dev server. Ketika tunnel: true diminta, server memberlakukannya pre-flight dan post-spawn — server localhost yang tidak dapat dijangkau tidak akan pernah dibiarkan berjalan diam-diam
• Sanitasi URL otomatis — Jika agent meninggalkan URL localhost dalam respons, alat respond_* akan menulis ulang menjadi URL tunnel yang cocok sehingga ponsel Anda selalu mendapat tautan yang dapat dijangkau
• Alat kustom — Agent dapat menginstal alat CLI dan mendaftarkannya sebagai kemampuan baru
• Versioning — Versioning git otomatis untuk file workspace; backup konfigurasi untuk skill dan izin
• Dasbor web — Tinjauan langsung tugas latar belakang, dapat disesuaikan per pengguna. /dashboard dan /api/jobs tidak diautentikasi secara desain — batasi akses di lapisan jaringan (Tailscale ACL, firewall, reverse proxy dengan basic auth) atau atur DASHBOARD=false jika Anda tidak memerlukannya
• Tunneling HTTPS — Dukungan bawaan untuk Tailscale, ngrok, dan Cloudflare Tunnel
• Layanan sistem — Instal sebagai layanan persisten di macOS, Linux, atau Windows
• Pembatasan rate — Batas permintaan per token dengan ambang yang dapat dikonfigurasi

Persyaratan

#

• Runtime Bun
• API key atau kredensial OAuth untuk penyedia LLM Anda
• (Opsional) Tailscale, ngrok, atau cloudflared untuk tunneling HTTPS

Mulai Cepat

#

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

# Pengaturan interaktif — pilih provider, model, token auth, port
bun run setup

# Mulai server + tunnel HTTPS
bun run dev:tunnel

Wizard pengaturan akan memandu Anda melalui pemilihan penyedia LLM, konfigurasi autentikasi, dan pengaturan izin alat.

Setelah berjalan, salin URL yang ditampilkan ke Pengaturan PocketHook:

Cara Kerjanya

#

1. Anda mengirim pesan di PocketHook
2. Server meneruskannya ke LLM pilihan Anda dengan riwayat percakapan, memori yang diingat, dan alat yang tersedia
3. LLM memproses pesan — dapat menjalankan perintah shell, membaca/menulis file, mencari web, menjadwalkan tugas latar belakang, mengingat fakta, atau memulai dev server
4. Respons dikembalikan dalam format PocketHook (msg + shortcut + data + url)
5. PocketHook menampilkan pesan dan menjalankan Shortcuts di perangkat Anda

Penyedia LLM yang Didukung

#

Ganti penyedia kapan saja dengan bun run switch. Ollama dan LM Studio berjalan sepenuhnya di mesin Anda — tidak perlu API key, data tidak keluar dari jaringan Anda.

Memori

#

Sistem memori memiliki tiga lapisan, masing-masing melayani tujuan yang berbeda.

Desain memori semantik menggabungkan ide dari MemPalace (arsitektur istana memori yang mengorganisir memori ke dalam wing, hall, dan room) dan metode PARA dari Tiago Forte (Projects, Areas, Resources, Archive) untuk manajemen siklus hidup pengetahuan.

Memori percakapan

#

SQLite dengan pencarian teks lengkap FTS5. Semua pesan disimpan dengan timestamp dan ID sesi.

• Jangka pendek — MAX_HISTORY pesan terakhir disimpan dalam memori per sesi
• Jangka panjang — Semua pesan disimpan di SQLite, dapat dicari melalui pencocokan kata kunci FTS5
• Recall per giliran — Saat memori semantik aktif, MAX_RECALL mengontrol berapa banyak memori relevan yang dimasukkan ke prompt setiap giliran
• Sesi berakhir setelah SESSION_TTL_MINUTES, tetapi memori jangka panjang bertahan selamanya

Sesuaikan ini secara interaktif dengan bun run memory.

Memori semantik

#

Memerlukan VECTOR_MEMORY=true dan penyedia embedding (Ollama, LM Studio, atau OpenAI).

Setiap memori di-embed sebagai vektor dan diklasifikasi otomatis oleh LLM ke dalam empat dimensi:

• Wing — Entitas: user, person:john, project:blog, place:london
• Room — Tipe: facts, preferences, events, decisions, requests
• Hall — Topik: personal, tech, health, travel, food, work
• Status — Klasifikasi PARA: project, area, resource, archive

Saat Anda mengajukan pertanyaan, ekstraksi entitas memfokuskan pencarian vektor pada wing yang paling relevan. Hasil digabungkan dengan hasil kata kunci FTS5 menggunakan reciprocal rank fusion — sehingga Anda mendapatkan yang terbaik dari pencocokan kata kunci dan semantik.

Grafik pengetahuan

#

Triple store temporal untuk fakta terstruktur yang tahan lama:

• Triple: (subject, predicate, object) dengan timestamp valid_from / valid_until
• Predikat nilai tunggal (lives_in, partner) otomatis membatalkan nilai lama saat diperbarui
• Predikat multi-nilai (child, friend, hobby) berdampingan tanpa pembatalan
• Fakta grafik pengetahuan dimasukkan bersama memori yang diingat dalam setiap percakapan

Ketika Anda memberi tahu agent “Saya pindah ke Berlin”, ia membatalkan triple lives_in lama dan membuat yang baru — secara otomatis.

Siklus hidup PARA

#

Setiap memori diberi tag status PARA:

• Project — Pekerjaan aktif yang terikat waktu
• Area — Tanggung jawab berkelanjutan
• Resource — Materi referensi (daftar, rekomendasi, cara-cara)
• Archive — Project yang selesai atau dibatalkan

Ketika sebuah project selesai, agent menggunakan kemiripan semantik untuk mengarsipkan hanya memori project tersebut sambil mempertahankan materi referensi untuk penggunaan di masa depan.

Cascade akhir project

#

Katakan “Saya membatalkan perjalanan saya ke Barcelona” dan satu panggilan tool menangani semuanya:

1. Mengarsipkan vektor project (events, decisions, requests yang terikat pada Barcelona).
2. Membatalkan setiap triple grafik pengetahuan yang aktif yang predikatnya cocok dengan slug project (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Mencatat penyelesaian sebagai triple baru: (user, "cancelled_visit_barcelona", "2026-04-15").

Pencocokan sadar batas — project lain bernama revisit_barcelona tetap tidak tersentuh. Agent tidak perlu lagi mengatur tiga panggilan terpisah dalam urutan yang benar, sehingga model yang lebih kecil pun melakukannya dengan benar.

Jika VECTOR_MEMORY dinonaktifkan atau penyedia embedding tidak dapat dijangkau, sistem kembali ke FTS5 saja tanpa error.

Skill

#

Skill adalah file .md di skills/ yang mendefinisikan iOS Shortcuts yang dapat dipicu agent dan/atau aturan perilaku. Mereka menggunakan pemuatan dinamis: hanya indeks ringkas (judul, deskripsi, daftar shortcut) yang dimasukkan ke prompt sistem. Agent memuat konten lengkap sesuai kebutuhan melalui alat load_skill, menjaga penggunaan token tetap rendah saat Anda menambahkan lebih banyak skill.

Setiap file skill menggunakan frontmatter 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

Field frontmatter

#

Skill juga bisa berupa aturan perilaku tanpa shortcut (misalnya, “cara merencanakan perjalanan keluarga”). Gunakan shortcuts: [] untuk ini.

Agent dapat membuat dan mengelola skill saat diminta — minta agent untuk “buatkan skill untuk mengontrol lampu saya” dan ia akan menulis file .md untuk Anda. Skill baru dan yang diedit selalu mendarat di lapisan pengguna Anda (data/user/skills/), sehingga pembaruan framework tidak akan pernah menimpanya. Lihat bagian Menyesuaikan agent Anda di bawah.

Menjalankan shortcut di server Mac

#

Ketika sebuah skill memiliki target: mac, shortcut akan berjalan secara diam-diam di server Mac melalui CLI shortcuts run, alih-alih dikirim ke perangkat iOS. Ini ideal untuk aksi yang membuat konten yang disinkronkan iCloud — catatan, pengingat, acara kalender — karena hasilnya otomatis tersinkronisasi ke semua perangkat Anda tanpa perlu aplikasi PocketHook melakukan apa pun.

Cara kerjanya:

1. Agent memutuskan sebuah shortcut harus dijalankan (misalnya “buat catatan dengan notulen rapat hari ini”)
2. Server memanggil shortcuts run "shortcutName" dengan data diteruskan sebagai JSON melalui stdin, menggunakan format wrapper yang sama dengan yang digunakan PocketHook iOS
3. Jika sync_app diatur, server sebentar membuka app tersebut di latar belakang (open -gj -a Notes) untuk memaksa sinkronisasi iCloud, lalu menutupnya setelah 5 detik
4. Pengguna menerima pesan konfirmasi di chat; shortcut itu sendiri tidak dikirim ke perangkat

Persyaratan:

• Server harus berjalan di macOS — shortcuts run hanya tersedia di macOS. Di platform lain, server akan mencatat peringatan dan kembali ke eksekusi di perangkat
• Shortcut harus terinstal di Shortcuts.app di Mac server
• Shortcut harus menerima Dictionary sebagai input (PocketHook membungkus data dalam { context, timestamp, app, data })

Kapan menggunakan target: mac:

• Aksi yang disinkronkan iCloud (Notes, Reminders, Calendar) — hasilnya toh akan menjangkau setiap perangkat
• Pemrosesan yang berjalan lama yang ingin Anda jauhkan dari perangkat iOS
• Shortcut apa pun yang tidak perlu berinteraksi dengan UI iPhone

Kapan tetap menggunakan target: device (default):

• Shortcut yang membutuhkan fitur khusus iPhone (kamera, lokasi presisi, otomatisasi aplikasi lokal)
• Shortcut yang meminta input interaktif dari pengguna
• Shortcut yang menggunakan App Intents dari aplikasi khusus iOS

Tugas Latar Belakang

#

Minta agent untuk menjadwalkan tugas dan ia akan menangani sisanya:

• “Cek cuaca setiap pagi jam 8 dan buat catatan”
• “Jalankan script ini setiap jam”
• “Ingatkan saya untuk cek email dalam 30 menit”

Tugas mendukung ekspresi cron (0 8 * * *) dan interval sederhana (30m, 1h, 2d). Hasil dikirim ke PocketHook saat polling endpoint /jobs.

Dua tipe eksekusi:

• Shell — Menjalankan perintah bash, menangkap output. Dapat memicu Shortcut saat selesai
• Prompt — Diproses oleh agent AI dengan akses alat penuh, menyimpan respons PocketHook lengkap

Dev Server

#

Ketika agent membuat proyek web di workspace (Hugo, Astro, Next.js, Flask, Go, dll.), ia secara proaktif menawarkan untuk menyajikannya:

• Preview — Memulai dev server lokal di port yang ditetapkan otomatis untuk tampilan cepat
• Public — Memulai server dan mengeksposnya melalui tunnel HTTPS sehingga dapat diakses dari mana saja

Agent mengelola siklus hidup: mulai, hentikan, dan daftar server yang berjalan. Semua server dibersihkan saat server utama berhenti.

Tunnel contract

#

Ketika agent memulai server dengan permintaan eksposur tunnel, runtime memberlakukannya: jika tidak ada alat tunnel (Tailscale, ngrok, cloudflared) yang terinstal, server menolak untuk memulai. Jika setup tunnel gagal setelah spawn, proses yatim dihentikan dan agent diberitahu secara eksplisit — agar ia dapat kembali ke mode preview atau meminta Anda menginstal tunnel. URL yang dikembalikan selalu URL tunnel saat tunneling aktif, dengan catatan bahwa URL lokal hanya untuk host.

Sebagai jaring pengaman, setiap alat respond_* memproses pasca pesannya: URL localhost atau 127.0.0.1 apa pun yang menyelinap ke dalam balasan akan ditulis ulang secara otomatis menjadi URL tunnel yang cocok saat server yang dikelola memilikinya. Saat tidak bisa menulis ulang, Anda akan menerima peringatan di log alih-alih tautan rusak di ponsel Anda.

Dasbor

#

Dasbor web bawaan di /dashboard menampilkan tinjauan langsung tugas latar belakang.

Tidak diautentikasi secara desain. Baik /dashboard maupun /api/jobs adalah endpoint GET terbuka — siapa pun yang dapat mencapai host dapat melihat daftar tugas. Batasi akses di lapisan jaringan (Tailscale ACL, firewall, reverse proxy dengan basic auth) atau atur DASHBOARD=false jika Anda tidak memerlukannya. Aplikasi PocketHook iOS tidak menggunakan endpoint ini.

Sepenuhnya dapat disesuaikan:

• Edit cepat — Tempatkan dashboard.html di workspace/dashboard/ untuk kustomisasi sederhana
• Proyek lengkap — Buat proyek framework (Svelte, React, Vue, dll.) di workspace/dashboard/ dengan output build ke dist/

Minta agent untuk menyesuaikan dasbor Anda dan ia akan menangani sisanya — setiap pengguna mendapat dasbor unik dan dipersonalisasi.

Alat Kustom

#

Agent dapat menginstal alat CLI dan mendaftarkannya sebagai kemampuan baru — memperluas dirinya sendiri tanpa memodifikasi kode server.

Misalnya, katakan “instal Playwright dan gunakan untuk mengambil screenshot”. Agent akan:

1. Menginstal dependensi
2. Membuat definisi alat (file .md sederhana)
3. Menggunakan alat baru di percakapan selanjutnya

Alat kustom di-hot-reload — tidak perlu restart. Hapus file .md untuk menghapus alat.

Versioning

#

Semua data pengguna di-version secara otomatis:

• File workspace — Dilacak dengan repo git lokal di dalam workspace/. Setiap penulisan membuat auto-commit. Minta agent untuk “batalkan perubahan terakhir” atau gunakan git revert HEAD secara manual
• File konfigurasi — config/agent-instructions.md, config/personality.md, skills/, dan permissions.json dicadangkan sebelum setiap modifikasi. Hingga 20 versi per file

Git bersifat opsional — jika tidak terinstal, perubahan workspace tidak di-version. Backup konfigurasi selalu berfungsi.

Menyesuaikan Agent Anda

#

Agent server dikirim dengan framework base minimal dan mengharapkan Anda untuk melapisi kustomisasi Anda sendiri di atasnya. Runtime menjaga keduanya terpisah sehingga pembaruan framework tidak pernah menghancurkan pekerjaan Anda.

Framework vs pengguna

#

pockethook-agent-server/
├── skills/                      # skill bawaan framework (read-only)
├── custom-tools/                # dicadangkan untuk tool bawaan framework (read-only)
├── config/
│   ├── agent-instructions.md    # instruksi agent framework (read-only)
│   └── personality.md           # kepribadian framework (read-only)
└── data/user/                   # kustomisasi ANDA ada di sini (git-ignored)
    ├── skills/                  # skill milik Anda (menimpa base berdasarkan nama file)
    ├── custom-tools/            # custom tools yang Anda instal
    ├── instructions.md          # tambahan Anda untuk instruksi agent
    └── prefs.json               # nilai bertipe yang direferensikan sebagai {{prefs.key}}

Kustomisasi pengguna ditulis melalui tool bertipe khusus (create_user_skill, create_custom_tool) sehingga file yang dihasilkan selalu sesuai dengan format loader. Tool write juga menolak path apa pun di bawah skills/, custom-tools/, atau config/ dan mengarahkan agent ke data/user/* — sehingga bahkan pengeditan file langsung pun berakhir di lapisan pengguna.

Catatan tentang direktori custom-tools/ base. Saat ini hanya berisi template (_example.md) yang diabaikan loader — setiap tool yang diinstal agent untuk Anda masuk ke data/user/custom-tools/. Direktori ini dicadangkan agar rilis framework mendatang dapat mengirim tool bawaan opsional tanpa menimpa instalasi Anda. Ketika itu terjadi, file lapisan pengguna Anda tetap menang pada benturan nama tool, jadi tidak ada yang perlu dimigrasikan.

Empat cara untuk menyesuaikan

#

Anda tidak perlu menulis file-file ini secara manual. Cukup beri tahu agent apa yang Anda inginkan dan ia akan memilih lapisan yang tepat secara otomatis.

Typed preferences dengan {{prefs.*}}

#

Misalkan Anda menulis skill perencana rute yang perlu tahu titik awal default Anda. Alih-alih meng-hardcode “Madrid” ke dalam skill, referensikan pref:

- **Titik awal**: {{prefs.routeOrigin}}, kecuali pengguna menentukan titik awal yang berbeda.

Dan simpan nilainya di data/user/prefs.json:

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

Server mengganti placeholder saat skill dimuat. Kunci bersarang ({{prefs.tunnel.domain}}) juga berfungsi. Kunci yang tidak dikenal dibiarkan tidak tersentuh agar salah ketik tetap terlihat.

Mengedit framework base secara langsung

#

Jika Anda self-hosting dan ingin men-tweak framework itu sendiri, Anda dapat mengedit config/agent-instructions.md, config/personality.md, skills/, atau custom-tools/ secara langsung — server tidak menghentikan Anda saat menggunakan editor file. Tapi agent tidak akan menulis ke path tersebut dari percakapan. Dan pembaruan framework akan menimpa suntingan Anda. Lebih baik gunakan lapisan pengguna untuk apa pun yang ingin Anda pertahankan.

Memperluas Server

#

• Alat kustom — Minta agent untuk menginstal alat CLI; mereka mendarat di data/user/custom-tools/ secara otomatis
• Tambah skill — Minta agent untuk membuat skill; file-nya masuk ke data/user/skills/
• Ubah perilaku — Minta agent untuk menerapkan aturan global; itu ditambahkan ke data/user/instructions.md
• Konfigurasi izin — Jalankan bun run permissions untuk mengontrol alat mana yang dapat digunakan agent
• Tambah alat bawaan — Implementasi fungsi alat baru di src/tools.ts untuk integrasi yang lebih dalam (memerlukan fork server)

Konfigurasi

#

Semua pengaturan disimpan di .env (dibuat oleh bun run setup). Opsi utama:

Lihat referensi konfigurasi lengkap di repositori GitHub.

Menjalankan sebagai Layanan

#

Instal sebagai layanan persisten yang dimulai secara otomatis:

bun run service install

INSTANCE_NAME secara default adalah basename direktori proyek dengan prefix pockethook- dihilangkan (mis., checkout di pockethook-agent-server/ menjadi agent-server). Atur secara eksplisit untuk menjalankan beberapa checkout di mesin yang sama tanpa benturan — setiap instance menyimpan data/ dan log-nya sendiri.

Kelola dengan bun run service status, restart, stop, atau uninstall.

Keamanan

#

• HTTPS wajib — PocketHook memerlukan HTTPS untuk semua URL
• Autentikasi bearer token — Rahasia bersama antara aplikasi dan server
• Pembatasan rate — Batas per token mencegah penyalahgunaan
• Alat sandbox — Perintah shell dan akses file dibatasi oleh izin
• Pola yang diblokir — Perintah berbahaya (sudo, rm -rf /) diblokir secara default
• Batas direktori kerja — Agent tidak dapat keluar dari direktori yang ditentukan
• File sensitif dilindungi — .env, .git, *.key, *.pem diblokir dari akses agent
• Versioning otomatis — Semua perubahan workspace dilacak git untuk kemudahan rollback