Agentový server

Čo je PocketHook Agent Server?

#

Agentový server premení PocketHook na plnohodnotného AI asistenta. Namiesto toho, aby ste sami písali logiku odpovedí, pripojíte LLM (Claude, GPT, Gemini atď.), ktorý spracúva správy, volá nástroje a vracia štruktúrované odpovede PocketHook — vrátane spúšťačov Skratiek.

Server beží na vašom vlastnom počítači. Vaše dáta zostávajú u vás.

Toto je východiskový bod. Server sa dodáva so základnou sadou nástrojov a je navrhnutý tak, aby ste ho rozširovali. Pridajte vlastné integrácie — e-mail, kalendáre, dokumenty, API — a prispôsobte si ho.

Funkcie

#

• Viacero poskytovateľov LLM — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (lokálne), LM Studio (lokálne)
• OAuth autentifikácia — GitHub Copilot a OpenAI Codex cez device code / browser flow
• Agentové nástroje — Príkazy shellu, čítanie/zápis súborov, výpis adresárov, webové vyhľadávanie, web scraping, správa vývojových serverov
• Rozdelenie framework / používateľ — Súbory frameworku (skills/, custom-tools/, config/) zostávajú iba na čítanie. Vaše prispôsobenia žijú v data/user/ (zručnosti, vlastné nástroje, inštrukcie, typované preferencie). Aktualizácie frameworku sa inštalujú čisto, bez prepisovania vašej práce
• Typované používateľské preferencie — Ukladajte hodnoty ako preferovanú mapovú aplikáciu alebo doménu tunela do data/user/prefs.json. Odkazujte na ne v zručnostiach ako {{prefs.key}} a server ich pri načítaní nahradí
• Programovacie úlohy jedným volaním — Meta-nástroj run_code_job vytvorí úlohu na pozadí typu prompt (spúšťanú vaším nakonfigurovaným LLM) a jedným krokom pošle používateľovi potvrdenie, čím nahrádza chybový vzor „respond + create-job"
• Typované protokolové nástroje — Šesť dedikovaných nástrojov respond_* (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), plus typované nástroje úloh (create_once_job, create_cron_job) a typované nástroje pracovného priestoru (create_project, list_projects, delete_project). Schémy odmietajú zle formátované URL, syntax tlačidiel a kombinácie type/schedule skôr, než sa dostanú na zariadenie
• Typované zapisovače pre prispôsobenie — create_user_skill a create_custom_tool zostavujú markdown používateľskej vrstvy so správnym frontmatterom, takže loader ich vždy parsuje a agent tieto súbory nikdy nepíše ručne
• Úlohy na pozadí — Jednorazové alebo opakované úlohy s cron výrazmi alebo jednoduchými intervalmi
• Dynamické zručnosti — Definujte skratky a pravidlá správania ako .md súbory. Do promptu sa načíta iba kompaktný index; plný obsah sa načítava na vyžiadanie cez nástroj load_skill
• Samospravované zručnosti — Agent môže vytvárať, upravovať a mazať definície zručností (zápisy vždy smerujú do používateľskej vrstvy)
• Sémantická pamäť — Vektorové vyhľadávanie s embeddingami (Ollama, LM Studio alebo OpenAI). Spomienky sú automaticky klasifikované LLM do dimenzií wing/room/hall/status
• Znalostný graf — Temporálne úložisko trojíc pre trvalé fakty s automatickou invalidáciou. Viachodnotové vzťahy koexistujú; jednohodnotové fakty sa automaticky nahrádzajú
• Metóda PARA s kaskádou ukončenia projektu — Každá spomienka je označená statusom (Projekt, Oblasť, Zdroj, Archív). Keď projekt skončí, jediné volanie complete_project archivuje jeho vektory, invaliduje všetky plánovacie trojice spojené s jeho slugom a zaznamená dokončenie — jedno volanie namiesto troch
• Hybridné vybavovanie — Kombinuje kľúčové slovo vyhľadávanie FTS5 s vektorovým sémantickým vyhľadávaním pomocou reciprocal rank fusion
• Dlhodobá pamäť — SQLite + fulltextové vyhľadávanie FTS5 ako záložné riešenie, keď je sémantická pamäť vypnutá
• Správa vývojových serverov s kontraktom tunela — Spúšťanie, zastavovanie a výpis vývojových serverov. Keď je požadované tunnel: true, server to vynucuje pred štartom aj po spawne — nedostupný localhost server nikdy nebeží potichu
• Automatická sanitizácia URL — Ak agent nechá v odpovedi URL localhost, nástroje respond_* ju prepíšu na zodpovedajúcu URL tunela, aby váš telefón vždy dostal dostupný odkaz
• Vlastné nástroje — Agent môže inštalovať CLI nástroje a registrovať ich ako nové schopnosti
• Verzovanie — Automatické git verzovanie pre súbory workspace; zálohy konfigurácie pre zručnosti a oprávnenia
• Webový dashboard — Živý prehľad úloh na pozadí, prispôsobiteľný na používateľa. /dashboard a /api/jobs sú zámerne neautentifikované — obmedzte prístup na úrovni siete (Tailscale ACL, firewall, reverse proxy s basic auth) alebo nastavte DASHBOARD=false, ak ich nepotrebujete
• HTTPS tunelovanie — Vstavaná podpora pre Tailscale, ngrok a Cloudflare Tunnel
• Systémová služba — Inštalácia ako trvalá služba na macOS, Linux alebo Windows
• Obmedzovanie požiadaviek — Limity na token s konfigurovateľnými prahmi

Požiadavky

#

• Runtime Bun
• API kľúč alebo OAuth prihlasovacie údaje pre vášho poskytovateľa LLM
• (Voliteľne) Tailscale, ngrok alebo cloudflared pre HTTPS tunelovanie

Rýchly štart

#

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

# Interaktívne nastavenie — výber poskytovateľa, modelu, autentifikačného tokenu, portu
bun run setup

# Spustenie servera + HTTPS tunela
bun run dev:tunnel

Sprievodca nastavením vás prevedie výberom poskytovateľa LLM, konfiguráciou autentifikácie a nastavením oprávnení nástrojov.

Po spustení skopírujte zobrazené URL do Nastavení PocketHook:

Ako to funguje

#

1. Odošlete správu v PocketHook
2. Server ju prepošle vášmu zvolenému LLM s históriou konverzácie, vybavenými spomienkami a dostupnými nástrojmi
3. LLM správu spracuje — môže spúšťať príkazy shellu, čítať/zapisovať súbory, prehľadávať web, plánovať úlohy na pozadí, pamätať si fakty alebo spúšťať vývojové servery
4. Odpoveď je vrátená vo formáte PocketHook (msg + shortcut + data + url)
5. PocketHook zobrazí správu a vykoná prípadné Skratky na vašom zariadení

Podporovaní poskytovatelia LLM

#

Prepnite poskytovateľa kedykoľvek pomocou bun run switch. Ollama a LM Studio bežia úplne na vašom počítači — nepotrebujete API kľúč, žiadne dáta neopustia vašu sieť.

Pamäť

#

Systém pamäte má tri vrstvy, z ktorých každá slúži inému účelu.

Dizajn sémantickej pamäte kombinuje myšlienky z MemPalace (architektúra pamäťového paláca, ktorá organizuje spomienky do krídel, chodieb a izieb) a metódy PARA od Tiaga Forte (Projekty, Oblasti, Zdroje, Archív) pre správu životného cyklu znalostí.

Konverzačná pamäť

#

SQLite s fulltextovým vyhľadávaním FTS5. Všetky správy sú ukladané s časovými pečiatkami a identifikátormi relácií.

• Krátkodobá — Posledných MAX_HISTORY správ uchovávaných v pamäti na reláciu
• Dlhodobá — Všetky správy uložené v SQLite, prehľadávateľné cez FTS5 párovanie kľúčových slov
• Vybavovanie za ťah — Keď je sémantická pamäť zapnutá, MAX_RECALL určuje, koľko relevantných spomienok sa vkladá do promptu pri každom ťahu
• Relácie vypršia po SESSION_TTL_MINUTES, ale dlhodobá pamäť pretrváva navždy

Tieto hodnoty laďte interaktívne príkazom bun run memory.

Sémantická pamäť

#

Vyžaduje VECTOR_MEMORY=true a poskytovateľa embeddingov (Ollama, LM Studio alebo OpenAI).

Každá spomienka je vložená ako vektor a automaticky klasifikovaná LLM do štyroch dimenzií:

• Wing — Entita: user, person:john, project:blog, place:london
• Room — Typ: facts, preferences, events, decisions, requests
• Hall — Téma: personal, tech, health, travel, food, work
• Status — PARA klasifikácia: project, area, resource, archive

Keď položíte otázku, extrakcia entít zameria vektorové vyhľadávanie na najrelevantnejšie krídla. Výsledky sú zlúčené s FTS5 výsledkami kľúčových slov pomocou reciprocal rank fusion — takže dostanete to najlepšie z oboch prístupov.

Znalostný graf

#

Temporálne úložisko trojíc pre štruktúrované, trvalé fakty:

• Trojice: (subjekt, predikát, objekt) s časovými pečiatkami valid_from / valid_until
• Jednohodnotové predikáty (lives_in, partner) automaticky invalidujú starú hodnotu pri aktualizácii
• Viachodnotové predikáty (child, friend, hobby) koexistujú bez invalidácie
• Fakty zo znalostného grafu sú vkladané spolu s vybavenými spomienkami do každej konverzácie

Keď agentovi poviete „Presťahoval som sa do Berlína", invaliduje starú trojicu lives_in a vytvorí novú — automaticky.

PARA životný cyklus

#

Každá spomienka je označená PARA statusom:

• Projekt — Aktívna, časovo obmedzená práca
• Oblasť — Prebiehajúce zodpovednosti
• Zdroj — Referenčný materiál (zoznamy, odporúčania, návody)
• Archív — Dokončené alebo zrušené projekty

Keď je projekt dokončený, agent použije sémantickú podobnosť na archiváciu iba spomienok daného projektu, pričom zachová referenčný materiál pre budúce použitie.

Kaskáda ukončenia projektu

#

Povedzte „Ruším cestu do Barcelony" a jediné volanie nástroja zariadi všetko:

1. Archivuje vektory projektu (udalosti, rozhodnutia, požiadavky spojené s Barcelonou).
2. Invaliduje každú aktívnu trojicu znalostného grafu, ktorej predikát zodpovedá slugu projektu (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Zaznamená dokončenie ako novú trojicu: (user, "cancelled_visit_barcelona", "2026-04-15").

Porovnávanie rešpektuje hranice slov — iný projekt s názvom revisit_barcelona zostane nedotknutý. Agent už nemusí orchestrovať tri oddelené volania v správnom poradí, takže to zvládnu aj menšie modely.

Ak je VECTOR_MEMORY vypnuté alebo je poskytovateľ embeddingov nedostupný, systém sa prepne na FTS5 bez chýb.

Zručnosti

#

Zručnosti sú .md súbory v adresári skills/, ktoré definujú iOS Skratky, ktoré agent môže spúšťať, a/alebo pravidlá správania. Používajú dynamické načítavanie: do systémového promptu sa vkladá iba kompaktný index (názov, popis, zoznam skratiek). Agent načítava plný obsah na vyžiadanie cez nástroj load_skill, čím udržiava nízku spotrebu tokenov pri pridávaní ďalších zručností.

Každý súbor zručnosti používa YAML frontmatter:

---
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

Polia frontmatteru

#

Zručnosti môžu byť aj pravidlá správania bez skratiek (napr. „ako naplánovať rodinný výlet"). Pre tieto použite shortcuts: [].

Agent môže vytvárať a spravovať zručnosti na vyžiadanie — požiadajte ho o „vytvor zručnosť na ovládanie mojich svetiel" a napíše .md súbor za vás. Nové a upravené zručnosti vždy smerujú do vašej používateľskej vrstvy (data/user/skills/), takže aktualizácie frameworku ich nikdy neprepíšu. Pozrite sekciu Customizing your agent nižšie.

Spúšťanie skratiek na Mac serveri

#

Keď má zručnosť target: mac, skratky bežia ticho na Mac serveri cez CLI shortcuts run, namiesto toho, aby boli odoslané na zariadenie iOS. Je to ideálne pre akcie, ktoré vytvárajú obsah synchronizovaný s iCloud — poznámky, pripomienky, udalosti kalendára — pretože výsledok sa automaticky synchronizuje na všetky vaše zariadenia bez toho, aby aplikácia PocketHook musela čokoľvek robiť.

Ako to funguje:

1. Agent rozhodne, že sa má skratka spustiť (napr. „vytvor poznámku s dnešnými poznámkami zo stretnutia")
2. Server volá shortcuts run "názovSkratky" s údajmi odovzdanými ako JSON na stdin, v rovnakom obalovom formáte, aký používa PocketHook iOS
3. Ak je sync_app nastavené, server na chvíľu otvorí túto aplikáciu na pozadí (open -gj -a Notes), aby si vynútil synchronizáciu iCloud, a po 5 sekundách ju zatvorí
4. Používateľ dostane potvrdzujúcu správu v chate; samotná skratka sa na zariadenie neposiela

Požiadavky:

• Server musí bežať na macOS — shortcuts run je iba pre macOS. Na iných platformách server zaloguje varovanie a vráti sa k vykonaniu na zariadení
• Skratka musí byť nainštalovaná v Shortcuts.app na Mac serveri
• Skratka by mala očakávať Dictionary ako vstup (PocketHook zabalí údaje do { context, timestamp, app, data })

Kedy použiť target: mac:

• Akcie synchronizované s iCloud (Notes, Reminders, Calendar) — výsledok sa aj tak dostane na každé zariadenie
• Dlhotrvajúce spracovanie, ktoré chcete držať mimo iOS zariadenia
• Akákoľvek skratka, ktorá nepotrebuje interagovať s používateľským rozhraním iPhonu

Kedy ponechať target: device (predvolené):

• Skratky, ktoré potrebujú funkcie dostupné iba na iPhone (kamera, presná poloha, lokálne automatizácie aplikácií)
• Skratky, ktoré žiadajú používateľa o interaktívny vstup
• Skratky používajúce App Intents z aplikácií dostupných iba na iOS

Úlohy na pozadí

#

Požiadajte agenta o naplánovanie úloh a zvyšok zvládne sám:

• „Kontroluj počasie každé ráno o 8 a vytvor poznámku"
• „Spúšťaj tento skript každú hodinu"
• „Pripomeň mi skontrolovať e-mail za 30 minút"

Úlohy podporujú cron výrazy (0 8 * * *) a jednoduché intervaly (30m, 1h, 2d). Výsledky sú doručované do PocketHook, keď dopytuje koncový bod /jobs.

Dva typy vykonávania:

• Shell — Spustí bash príkaz, zachytí výstup. Môže spustiť Skratku po dokončení
• Prompt — Spracovaný AI agentom s plným prístupom k nástrojom, uloží kompletnú odpoveď PocketHook

Vývojové servery

#

Keď agent vytvorí webový projekt v workspace (Hugo, Astro, Next.js, Flask, Go atď.), proaktívne ponúkne jeho servírovanie:

• Náhľad — Spustí lokálny vývojový server na automaticky pridelenom porte pre rýchle zobrazenie
• Verejný — Spustí server a vystaví ho cez HTTPS tunel, aby bol prístupný odkiaľkoľvek

Agent spravuje životný cyklus: spúšťanie, zastavovanie a zobrazovanie zoznamu bežiacich serverov. Všetky servery sa upracú pri zastavení hlavného servera.

Kontrakt tunela

#

Keď agent spúšťa server s požiadavkou na expozíciu cez tunel, runtime to vynucuje: ak nie je nainštalovaný žiadny tunelovací nástroj (Tailscale, ngrok, cloudflared), server odmietne štart. Ak nastavenie tunela zlyhá po spawne, osirelý proces je zastavený a agent dostane explicitnú informáciu — tak, aby sa mohol vrátiť do režimu náhľadu alebo vás požiadať o inštaláciu tunela. Vrátená URL je vždy URL tunela, keď je tunelovanie zapnuté, s poznámkou, že lokálna URL je dostupná iba hostiteľovi.

Ako poistka každý nástroj respond_* post-spracováva svoju správu: akákoľvek URL localhost alebo 127.0.0.1, ktorá sa do odpovede vkradne, sa automaticky prepíše na zodpovedajúcu URL tunela, keď spravovaný server nejakú má. Keď prepísať nejde, dostanete varovanie v logoch namiesto pokazeného odkazu na telefóne.

Dashboard

#

Vstavaný webový dashboard na /dashboard zobrazuje živý prehľad úloh na pozadí.

Zámerne neautentifikovaný. /dashboard aj /api/jobs sú otvorené GET endpointy — ktokoľvek, kto sa dostane na hostiteľa, môže vypísať úlohy. Obmedzte prístup na úrovni siete (Tailscale ACL, firewall, reverse proxy s basic auth) alebo nastavte DASHBOARD=false, ak ich nepotrebujete. iOS aplikácia PocketHook tieto endpointy nepoužíva.

Je plne prispôsobiteľný:

• Rýchla úprava — Umiestnite súbor dashboard.html do workspace/dashboard/ pre jednoduché úpravy
• Plný projekt — Vytvorte projekt s frameworkom (Svelte, React, Vue atď.) vo workspace/dashboard/ s výstupom zostavenia do dist/

Požiadajte agenta o prispôsobenie vášho dashboardu a zvyšok zvládne sám — každý používateľ dostane unikátny, personalizovaný dashboard.

Vlastné nástroje

#

Agent môže inštalovať CLI nástroje a registrovať ich ako nové schopnosti — rozširuje sa sám bez úpravy kódu servera.

Napríklad povedzte „nainštaluj Playwright a použi ho na robenie snímok obrazovky". Agent:

1. Nainštaluje závislosť
2. Vytvorí definíciu nástroja (jednoduchý .md súbor)
3. Použije nový nástroj v budúcich konverzáciách

Vlastné nástroje sa načítavajú za behu — reštart nie je potrebný. Zmažte .md súbor na odstránenie nástroja.

Verzovanie

#

Všetky používateľské dáta sú automaticky verzované:

• Súbory workspace — Sledované lokálnym git repozitárom vnútri workspace/. Každý zápis vytvorí auto-commit. Požiadajte agenta o „vráť späť poslednú zmenu" alebo použite git revert HEAD ručne
• Konfiguračné súbory — config/agent-instructions.md, config/personality.md, skills/ a permissions.json sú zálohované pred každou úpravou. Až 20 verzií na súbor

Git je voliteľný — ak nie je nainštalovaný, zmeny workspace nie sú verzované. Zálohy konfigurácie fungujú vždy.

Customizing your agent

#

Agentový server sa dodáva s minimálnou základňou frameworku a očakáva, že si na ňu navrstvíte vlastné prispôsobenia. Runtime udržiava obe vrstvy oddelené, aby aktualizácie frameworku nikdy neprepísali vašu prácu.

Framework vs používateľ

#

pockethook-agent-server/
├── skills/                      # zručnosti dodávané frameworkom (iba na čítanie)
├── custom-tools/                # rezervované pre nástroje dodávané frameworkom (iba na čítanie)
├── config/
│   ├── agent-instructions.md    # inštrukcie agenta z frameworku (iba na čítanie)
│   └── personality.md           # osobnosť z frameworku (iba na čítanie)
└── data/user/                   # VAŠE prispôsobenia žijú tu (ignorované gitom)
    ├── skills/                  # vaše vlastné zručnosti (prepíšu základ podľa názvu súboru)
    ├── custom-tools/            # vaše nainštalované vlastné nástroje
    ├── instructions.md          # vaše doplnky k inštrukciám agenta
    └── prefs.json               # typované hodnoty referencované ako {{prefs.key}}

Používateľské prispôsobenia sa zapisujú cez dedikované typované nástroje (create_user_skill, create_custom_tool), takže výsledné súbory vždy zodpovedajú formátu loadera. Nástroj write tiež odmieta akúkoľvek cestu pod skills/, custom-tools/ alebo config/ a presmerováva agenta do data/user/* — takže aj priame úpravy súborov končia v používateľskej vrstve.

Poznámka k základnému adresáru custom-tools/. Dnes obsahuje iba šablónu (_example.md), ktorú loader ignoruje — každý nástroj, ktorý agent nainštaluje, smeruje do data/user/custom-tools/. Adresár je rezervovaný, aby budúce verzie frameworku mohli dodávať voliteľné vstavané nástroje bez prepísania vašich inštalácií. Keď k tomu dôjde, vaše súbory v používateľskej vrstve stále vyhrávajú pri kolízii názvov, takže nie je čo migrovať.

Štyri spôsoby prispôsobenia

#

Tieto súbory nikdy nemusíte písať ručne. Stačí povedať agentovi, čo chcete, a on sám vyberie správnu vrstvu.

Typované preferencie s {{prefs.*}}

#

Povedzme, že píšete zručnosť plánovača trasy, ktorá potrebuje poznať váš predvolený východiskový bod. Namiesto toho, aby ste do zručnosti natvrdo napísali „Madrid", odkážte sa na preferenciu:

- **Východiskový bod**: {{prefs.routeOrigin}}, pokiaľ používateľ neurčí iný počiatok.

A uložte hodnotu do data/user/prefs.json:

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

Server nahrádza placeholdery pri načítaní zručnosti. Vnorené kľúče ({{prefs.tunnel.domain}}) fungujú tiež. Neznáme kľúče zostanú nedotknuté, aby preklepy zostali viditeľné.

Úprava základne frameworku priamo

#

Ak si server hostujete sami a chcete upraviť samotný framework, môžete editovať config/agent-instructions.md, config/personality.md, skills/ alebo custom-tools/ priamo — server vás nezastaví, keď použijete editor súborov. Ale agent do týchto ciest z konverzácie nezapíše. A aktualizácie frameworku vaše úpravy prepíšu. Pre čokoľvek, čo chcete zachovať, preferujte používateľskú vrstvu.

Rozšírenie servera

#

• Vlastné nástroje — Požiadajte agenta o inštaláciu CLI nástrojov; automaticky smerujú do data/user/custom-tools/
• Pridajte zručnosti — Požiadajte agenta o vytvorenie zručnosti; súbor smeruje do data/user/skills/
• Zmeňte správanie — Požiadajte agenta o aplikáciu globálneho pravidla; pripojí ho do data/user/instructions.md
• Konfigurujte oprávnenia — Spustite bun run permissions na kontrolu, ktoré nástroje agent môže používať
• Pridajte vstavané nástroje — Implementujte nové funkcie nástrojov v src/tools.ts pre hlbšie integrácie (vyžaduje fork servera)

Konfigurácia

#

Všetky nastavenia sú uložené v .env (vytvorenom pomocou bun run setup). Kľúčové možnosti:

Kompletnú referenciu konfigurácie nájdete v GitHub repozitári.

Spustenie ako služba

#

Nainštalujte ako trvalú službu, ktorá sa spúšťa automaticky:

bun run service install

INSTANCE_NAME sa štandardne odvodzuje z názvu adresára projektu s odstráneným prefixom pockethook- (napr. kópia v pockethook-agent-server/ sa stane agent-server). Nastavte ho explicitne pre spustenie viacerých kópií na rovnakom počítači bez kolízií — každá inštancia si zachováva vlastné data/ a logy.

Spravujte pomocou bun run service status, restart, stop alebo uninstall.

Bezpečnosť

#

• Vyžadované HTTPS — PocketHook vyžaduje HTTPS pre všetky URL
• Bearer token autentifikácia — Zdieľaný tajný kľúč medzi aplikáciou a serverom
• Obmedzovanie požiadaviek — Limity na token bránia zneužitiu
• Izolované nástroje — Príkazy shellu a prístup k súborom obmedzený oprávneniami
• Blokované vzory — Nebezpečné príkazy (sudo, rm -rf /) blokované v predvolenom nastavení
• Hranica pracovného adresára — Agent nemôže opustiť svoj určený adresár
• Chránené citlivé súbory — .env, .git, *.key, *.pem blokované pred prístupom agenta
• Automatické verzovanie — Všetky zmeny workspace sú sledované gitom pre ľahký návrat