Agentserver

Vad är PocketHook Agent Server?

#

Agentservern gör PocketHook till en fullständig AI-assistent. Istället för att skriva responslogik själv ansluter du en LLM (Claude, GPT, Gemini osv.) som bearbetar meddelanden, anropar verktyg och returnerar strukturerade PocketHook-svar — inklusive Shortcut-triggers.

Servern körs på din egen maskin. Dina data stannar hos dig.

Detta är en startpunkt. Servern levereras med en grunduppsättning verktyg och är designad för att utvidgas av dig. Lägg till dina egna integrationer — e-post, kalendrar, dokument, APIs — och gör den till din.

Funktioner

#

• Multi-provider LLM — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (lokal), LM Studio (lokal)
• Snabb modell — Kör en lättviktig sekundär modell för interna hjälpare (minnesklassificering, entitetsextraktion) tillsammans med din huvudsakliga chattmodell — full kontroll över kostnad och latens
• Safari-tillägg — Parkoppla ett notariserat macOS Safari-tillägg så att agenten kan öppna flikar, inspektera sidor, klicka, fylla i formulär och ta skärmdumpar i din riktiga webbläsarsession, på den behörighetsnivå du väljer
• OAuth-autentisering — GitHub Copilot och OpenAI Codex via device-code-/webbläsarflow
• Agentverktyg — Shell-kommandon, filläsning/skrivning, kataloglistning, webbsökning, web scraping, dev-serverhantering
• Ramverks-/användaruppdelning — Ramverksfiler (skills/, custom-tools/, config/) förblir skrivskyddade. Dina anpassningar bor under data/user/ (skills, anpassade verktyg, instruktioner, typade preferenser). Ramverksuppdateringar landar rent utan att skriva över ditt arbete
• Typade användarpreferenser — Lagra värden som din föredragna kartapp eller tunneldomän i data/user/prefs.json. Referera till dem i skills som {{prefs.key}}, och servern sätter in dem vid laddning
• Programmeringsuppgifter i ett anrop — Meta-verktyget run_code_job skapar ett bakgrundsjobb av prompt-typ (kört av din konfigurerade LLM) och skickar användaren bekräftelsen i ett steg, och ersätter det felbenägna mönstret “respond + create-job”
• Typade protokollverktyg — Sex dedikerade respond_*-verktyg (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), plus typade jobbverktyg (create_once_job, create_cron_job) och typade workspace-verktyg (create_project, list_projects, delete_project). Scheman avvisar felaktiga URL:er, knappsyntax och type/schedule-kombinationer innan de når enheten
• Typade skribenter för anpassning — create_user_skill och create_custom_tool bygger användarlagrets markdown med korrekt frontmatter, så laddaren alltid parsar dem och agenten aldrig skriver dessa filer för hand
• Bakgrundsjobb — Engångs- eller återkommande uppgifter med cron-uttryck eller enkla intervall
• Dynamiska skills — Definiera Shortcuts och beteenderegler som .md-filer. Bara ett kompakt index laddas i prompten; fullständigt innehåll hämtas vid behov via load_skill-verktyget
• Självhanterande skills — Agenten kan skapa, redigera och ta bort skilldefinitioner (skrivningar landar alltid i användarlagret)
• Semantiskt minne — Vektorbaserad sökning med embeddings (Ollama, LM Studio eller OpenAI). Minnen klassificeras automatiskt av LLM:et i wing/room/hall/status-dimensioner
• Kunskapsgraf — Temporalt triple-store för varaktiga fakta med automatisk invalidering. Multivärdesrelationer samexisterar; enkelvärdesfakta ersätts automatiskt
• PARA-metoden med projektavslutnings-kaskad — Varje minne taggas med en status (Projekt, Område, Resurs, Arkiv). När ett projekt avslutas arkiverar ett enda complete_project-anrop dess vektorer, invaliderar varje planeringstripel knuten till projektets slug och registrerar slutförandet — ett anrop i stället för tre
• Hybrid recall — Kombinerar FTS5-sökordssökning med vektor-semantisk sökning via reciprocal rank fusion
• Långtidsminne — SQLite + FTS5-fulltextsökning som fallback när semantiskt minne är inaktiverat
• Dev-serverhantering med tunnelkontrakt — Starta, stoppa och lista dev-servrar. När tunnel: true begärs, genomdriver servern det både före flight och efter spawn — en onåbar localhost-server lämnas aldrig tyst i gång
• Automatisk URL-sanering — Om agenten lämnar en localhost-URL i ett svar skriver respond_*-verktygen om den till den matchande tunnel-URL:en, så din telefon alltid får en nåbar länk
• Anpassade verktyg — Agenten kan installera CLI-verktyg och registrera dem som nya förmågar
• Versionshantering — Automatisk git-versionshantering för workspace-filer; konfigurationssäkerhetskopiering för skills och behorigheter
• Webbdashboard — Live-översikt över bakgrundsjobb, anpassningsbart per användare. /dashboard och /api/jobs är avsiktligt oautentiserade — begränsa åtkomst på nätverkslagret (Tailscale-ACL, brandvägg, reverse proxy med basic auth) eller sätt DASHBOARD=false om du inte behöver den
• HTTPS-tunnling — Inbyggt stöd för Tailscale, ngrok och Cloudflare Tunnel
• Systemtjänst — Installera som persistent tjänst på macOS, Linux eller Windows
• Rate limiting — Per-token begränsningar med konfigurerbara trösklar

Krav

#

• Bun runtime
• En API-nyckel eller OAuth-uppgifter för din LLM-leverantör
• (Valfritt) Tailscale, ngrok eller cloudflared för HTTPS-tunnling

Snabbstart

#

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

# Interaktiv installation — vaelj leverantoer, modell, auth-token, port
bun run setup

# Starta server + HTTPS-tunnel
bun run dev:tunnel

Installationsguiden vägleder dig genom valet av LLM-leverantör, konfiguration av autentisering och inställning av verktygsbehörigheter — inklusive om Safari-tillägget ska installeras (valfritt, kan hoppas över, endast macOS).

Kör bun run help när som helst för en fullständig lista över kommandon, eller bun run config för att se din aktuella konfiguration i ett ögonkast (hemligheter maskerade).

När servern körs, kopiera de visade URL:erna till PocketHook-inställningar:

Hur det fungerar

#

1. Du skickar ett meddelande i PocketHook
2. Servern vidarebefordrar det till din valda LLM med konversationshistorik, hämtade minnen och tillgängliga verktyg
3. LLM:et bearbetar meddelandet — det kan köra shell-kommandon, läsa/skriva filer, söka på webben, schemalägga bakgrundsjobb, minnas fakta eller starta dev-servrar
4. Svaret returneras i PocketHook-format (msg + shortcut + data + url)
5. PocketHook visar meddelandet och kör alla Shortcuts på din enhet

Stödda LLM-leverantörer

#

Byt leverantör när som helst med bun run switch. Ollama och LM Studio körs helt på din maskin — ingen API-nyckel behövs, inga data lämnar ditt nätverk.

Minne

#

Minnessystemet har tre lager, vart och ett med ett olika syfte.

Designen av det semantiska minnet kombinerar ideer från MemPalace (en minnespalats-arkitektur som organiserar minnen i wings, halls och rooms) och Tiago Fortes PARA-metod (Projekt, Områden, Resurser, Arkiv) för kunskapslivscykelhantering.

Konversationsminne

#

SQLite med FTS5-fulltextsökning. Alla meddelanden lagras med tidsstämplar och sessions-ID:n.

• Kortsiktigt — Senaste MAX_HISTORY meddelanden hålls i minnet per session
• Långsiktigt — Alla meddelanden sparade i SQLite, sökbara via FTS5-sökordsmatchning
• Recall per tur — När semantiskt minne är på styr MAX_RECALL hur många relevanta minnen som injiceras i prompten varje tur
• Sessioner går ut efter SESSION_TTL_MINUTES, men långtidsminnet består för alltid

Justera dessa interaktivt med bun run memory.

Semantiskt minne

#

Kräver VECTOR_MEMORY=true och en embedding-leverantör (Ollama, LM Studio eller OpenAI).

Varje minne bäddas in som en vektor och klassificeras automatiskt av LLM:et i fyra dimensioner:

• Wing — Entiteten: user, person:john, project:blog, place:london
• Room — Typen: facts, preferences, events, decisions, requests
• Hall — Ämnet: personal, tech, health, travel, food, work
• Status — PARA-klassificering: project, area, resource, archive

När du ställer en fråga fokuserar entitetsextraktion vektorsökningen på de mest relevanta wings. Resultat sammanfogas med FTS5-sökordresultat via reciprocal rank fusion — så du får det bästa av både sökords- och semantisk sökning.

Kunskapsgraf

#

Ett temporalt triple-store för strukturerade, varaktiga fakta:

• Tripplar: (subjekt, predikat, objekt) med valid_from / valid_until tidsstämplar
• Enkelvärde-predikat (lives_in, partner) invaliderar automatiskt det gamla värdet vid uppdatering
• Multivärde-predikat (child, friend, hobby) samexisterar utan invalidering
• Kunskapsgraffakta injiceras tillsammans med hämtade minnen i varje konversation

När du berättar för agenten “Jag har flyttat till Berlin”, invaliderar den den gamla lives_in-trippeln och skapar en ny — automatiskt.

PARA-livscykel

#

Varje minne taggas med en PARA-status:

• Projekt — Aktivt, tidsbundet arbete
• Område — Pågående ansvarsområden
• Resurs — Referensmaterial (listor, rekommendationer, guider)
• Arkiv — Avslutade eller avbrutna projekt

När ett projekt avslutas använder agenten semantisk likhet för att bara arkivera det projektets minnen medan referensmaterial bevaras för framtida bruk.

Projektavslutnings-kaskad

#

Säg “Jag ställer in min resa till Barcelona”, och ett enda verktygsanrop sköter allt:

1. Arkiverar projektets vektorer (events, decisions, requests knutna till Barcelona).
2. Invaliderar varje aktivt kunskapsgraf-tripel vars predikat matchar projektets slug (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Registrerar slutförandet som ett nytt tripel: (user, "cancelled_visit_barcelona", "2026-04-15").

Matchningen är gränsmedveten — ett annat projekt som heter revisit_barcelona förblir orört. Agenten behöver inte längre orkestrera tre separata anrop i rätt ordning, så mindre modeller klarar det också.

Om VECTOR_MEMORY är inaktiverat eller embedding-leverantören är onåbar, faller systemet tillbaka till FTS5-only utan fel.

Skills

#

Skills är .md-filer i skills/ som definierar iOS-Shortcuts agenten kan utlösa och/eller beteenderegler. De använder dynamisk laddning: bara ett kompakt index (titel, beskrivning, shortcutlista) injiceras i systemprompten. Agenten laddar fullständigt innehåll vid behov via load_skill-verktyget, så tokenanvändningen hålls låg när du lägger till fler skills.

Varje skillfil använder 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

Frontmatter-fält

#

Skills kan också vara beteenderegler utan shortcuts (t.ex. “hur man planerar en familjeresa”). Använd shortcuts: [] för dessa.

Agenten kan skapa och hantera skills när du ber om det — be den att “skapa en skill för att styra mina lampor” och den skriver .md-filen åt dig. Nya och redigerade skills landar alltid i ditt användarlager (data/user/skills/), så ramverksuppdateringar skriver aldrig över dem. Se avsnittet Customizing your agent nedan.

Köra shortcuts på Mac-servern

#

När en skill har target: mac körs shortcuts tyst på Mac-servern via CLI-verktyget shortcuts run i stället för att skickas till iOS-enheten. Det är idealiskt för åtgärder som skapar iCloud-synkat innehåll — anteckningar, påminnelser, kalenderhändelser — eftersom resultatet synkas till alla dina enheter automatiskt utan att PocketHook-appen behöver göra något.

Så här fungerar det:

1. Agenten bestämmer att en shortcut ska köra (t.ex. “skapa en anteckning med dagens mötesanteckningar”)
2. Servern anropar shortcuts run "shortcutNamn" med datan skickad som JSON på stdin, i samma wrapper-format som PocketHook iOS använder
3. Om sync_app är satt öppnar servern kortfattat den appen i bakgrunden (open -gj -a Notes) för att tvinga iCloud-synkronisering, och stänger den sedan efter 5 sekunder
4. Användaren får ett bekräftelsemeddelande i chatten; själva shortcut’en skickas inte till enheten

Krav:

• Servern måste köra på macOS — shortcuts run finns bara på macOS. På andra plattformar loggar servern en varning och faller tillbaka till enhetskörning
• Shortcut’en måste vara installerad i Shortcuts.app på Mac-servern
• Shortcut’en ska förvänta ett Dictionary som indata (PocketHook packar in datan i { context, timestamp, app, data })

När du ska använda target: mac:

• iCloud-synkade åtgärder (Notes, Reminders, Calendar) — resultatet når ändå alla enheter
• Långvarig bearbetning du vill hålla borta från iOS-enheten
• Alla shortcuts som inte behöver interagera med iPhone’ns användargränssnitt

När du ska behålla target: device (standard):

• Shortcuts som behöver iPhone-specifika funktioner (kamera, exakt plats, lokala app-automatiseringar)
• Shortcuts som ber användaren om interaktiv inmatning
• Shortcuts som använder App Intents från iOS-enbart-appar

Bakgrundsjobb

#

Be agenten att schemalägga uppgifter och den sköter resten:

• “Kontrollera vädret varje morgon kl. 8 och skapa en anteckning”
• “Kör det här skriptet varje timme”
• “Påminn mig att kolla min e-post om 30 minuter”

Jobb stöder cron-uttryck (0 8 * * *) och enkla intervall (30m, 1h, 2d). Resultat levereras till PocketHook när den pollar /jobs-slutpunkten.

Två körningstyper:

• Shell — Kör ett bash-kommando, fångar utdata. Kan utlösa en Shortcut vid slutförande
• Prompt — Bearbetas av AI-agenten med full verktygstillgång, lagrar det kompletta PocketHook-svaret

Dev-servrar

#

När agenten skapar ett webbprojekt i workspace:t (Hugo, Astro, Next.js, Flask, Go osv.) erbjuder den proaktivt att servera det:

• Förhandsgranskning — Startar en lokal dev-server på en automatiskt tilldelad port för snabb visning
• Offentlig — Startar servern och exponerar den via HTTPS-tunnel så den är tillgänglig överallt

Agenten hanterar livscykeln: starta, stoppa och lista körande servrar. Alla servrar städas upp när huvudservern stoppas.

Tunnelkontrakt

#

När agenten startar en server med tunnelexponering begärd genomdriver körtiden det: om inget tunnelverktyg (Tailscale, ngrok, cloudflared) är installerat vägrar servern att starta. Om tunnelupplägget misslyckas efter spawn stoppas den föräldralösa processen och agenten får explicit besked — så den kan falla tillbaka till förhandsgranskning eller be dig installera en tunnel. Den returnerade URL:en är alltid tunnel-URL:en när tunneling är på, med en notering om att den lokala URL:en endast gäller för värden.

Som skyddsnät efterbehandlar varje respond_*-verktyg sitt meddelande: varje localhost- eller 127.0.0.1-URL som smyger sig in i ett svar skrivs automatiskt om till den matchande tunnel-URL:en när en hanterad server har en. När det inte kan skrivas om får du en varning i loggarna i stället för en trasig länk på telefonen.

Dashboard

#

Den inbyggda webbdashboarden på /dashboard visar en live-översikt över bakgrundsjobb.

Avsiktligt oautentiserad. Både /dashboard och /api/jobs är öppna GET-slutpunkter — vem som helst som når värden kan lista jobb. Begränsa åtkomst på nätverkslagret (Tailscale-ACL, brandvägg, reverse proxy med basic auth) eller sätt DASHBOARD=false om du inte behöver den. PocketHook iOS-appen använder inte dessa slutpunkter.

Den är helt anpassningsbar:

• Snabbredigering — Placera en dashboard.html i workspace/dashboard/ för enkla anpassningar
• Fullt projekt — Skapa ett ramverksprojekt (Svelte, React, Vue osv.) i workspace/dashboard/ med build-utdata till dist/

Be agenten att anpassa din dashboard och den sköter resten — varje användare får en unik, personaliserad dashboard.

Anpassade verktyg

#

Agenten kan installera CLI-verktyg och registrera dem som nya förmågar — utvidgar sig själv utan att ändra serverkoden.

Säg till exempel “installera Playwright och använd det för att ta skärmbilder”. Agenten kommer att:

1. Installera beroendet
2. Skapa en verktygsdefinition (en enkel .md-fil)
3. Använda det nya verktyget i framtida konversationer

Anpassade verktyg laddas om direkt — ingen omstart behövs. Ta bort .md-filen för att ta bort ett verktyg.

Versionshantering

#

All användardata versionshanteras automatiskt:

• Workspace-filer — Spårade med ett lokalt git-repo inuti workspace/. Varje skrivning skapar en auto-commit. Be agenten att “ångra den senaste ändringen” eller använd git revert HEAD manuellt
• Konfigurationsfiler — config/agent-instructions.md, config/personality.md, skills/ och permissions.json säkerhetskopieras före varje ändring. Upp till 20 versioner per fil

Git är valfritt — om det inte är installerat är workspace-ändringar inte versionshanterade. Konfigurationssäkerhetskopiering fungerar alltid.

Anpassa din agent

#

Agentservern levereras med en minimal ramverksbas och förväntar sig att du lägger din egen anpassning ovanpå. Körtiden håller de två åtskilda så ramverksuppdateringar aldrig förstör ditt arbete.

Ramverk vs användare

#

pockethook-agent-server/
├── skills/                      # ramverksleverade skills (skrivskyddat)
├── custom-tools/                # reserverat foer ramverksleverade verktyg (skrivskyddat)
├── config/
│   ├── agent-instructions.md    # ramverkets agentinstruktioner (skrivskyddat)
│   └── personality.md           # ramverkets personlighet (skrivskyddat)
└── data/user/                   # DIN anpassning bor haer (git-ignorerad)
    ├── skills/                  # dina egna skills (oeverrider basen paa filnamn)
    ├── custom-tools/            # dina installerade anpassade verktyg
    ├── instructions.md          # dina tillaegg till agentinstruktionerna
    └── prefs.json               # typade vaerden refererade som {{prefs.key}}

Användaranpassning skrivs via dedikerade typade verktyg (create_user_skill, create_custom_tool) så de resulterande filerna alltid matchar laddarens format. write-verktyget avvisar också varje sökväg under skills/, custom-tools/ eller config/ och dirigerar om agenten till data/user/* — så även direkta filändringar hamnar i användarlagret.

Notering om bas-katalogen custom-tools/. Idag innehåller den bara en mall (_example.md) som laddaren ignorerar — varje verktyg agenten installerar åt dig hamnar i data/user/custom-tools/. Katalogen är reserverad så framtida ramverkssläpp kan leverera valfria inbyggda verktyg utan att förstöra dina installationer. När det händer vinner dina användarlager-filer fortfarande vid namnkollision, så det finns inget att migrera.

Fyra sätt att anpassa på

#

Du behöver aldrig skriva dessa filer för hand. Säg bara till agenten vad du vill ha, så väljer den rätt lager automatiskt.

Typade preferenser med {{prefs.*}}

#

Säg att du skriver en ruttplanerar-skill som behöver veta din standardstartpunkt. I stället för att hårdkoda “Madrid” i själva skillen, referera till preferensen:

- **Startpunkt**: {{prefs.routeOrigin}}, saavida anvaendaren inte anger en annan startpunkt.

Och lagra värdet i data/user/prefs.json:

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

Servern sätter in plats-hållare när skillen laddas. Nästlade nycklar ({{prefs.tunnel.domain}}) fungerar också. Okända nycklar lämnas orörda så typos förblir synliga.

Redigera ramverksbasen direkt

#

Om du självhostar och vill pilla med själva ramverket kan du redigera config/agent-instructions.md, config/personality.md, skills/ eller custom-tools/ direkt — servern stoppar dig inte när du använder en filredigerare. Men agenten kommer inte att skriva till de sökvägarna från en konversation. Och ramverksuppdateringar kommer att skriva över dina ändringar. Föredra användarlagret för allt du vill behålla.

Utvidga servern

#

• Anpassade verktyg — Be agenten att installera CLI-verktyg; de hamnar automatiskt i data/user/custom-tools/
• Lägg till skills — Be agenten att skapa en skill; filen hamnar i data/user/skills/
• Ändra beteende — Be agenten att tillämpa en global regel; den läggs till i data/user/instructions.md
• Konfigurera behörigheter — Kör bun run permissions för att styra vilka verktyg agenten kan använda
• Lägg till inbyggda verktyg — Implementera nya verktygsfunktioner i src/tools.ts för djupare integrationer (kräver en fork av servern)

Konfiguration

#

Alla inställningar lagras i .env (skapad av bun run setup). Viktiga alternativ:

Se den fullständiga konfigurationsreferensen i GitHub-repositoryt.

Köra som tjänst

#

Installera som persistent tjänst som startar automatiskt:

bun run service install

INSTANCE_NAME är som standard projektkatalogens basnamn med pockethook--prefixet borttaget (t.ex. blir en checkout i pockethook-agent-server/ till agent-server). Sätt det explicit för att köra flera checkouts på samma maskin utan kollisioner — varje instans behåller sina egna data/ och loggar.

Hantera med bun run service status, restart, stop eller uninstall.

Säkerhet

#

• HTTPS krävs — PocketHook kräver HTTPS för alla URL:er
• Bearer-token-autentisering — Delad hemlighet mellan app och server
• Rate limiting — Per-token begränsningar förhindrar missbruk
• Sandboxade verktyg — Shell-kommandon och filåtkomst begränsade av behörigheter
• Blockerade mönster — Farliga kommandon (sudo, rm -rf /) blockerade som standard
• Arbetskataloggräns — Agenten kan inte lämna sin tilldelade katalog
• Känsliga filer skyddade — .env, .git, *.key, *.pem blockerade från agentåtkomst
• Automatisk versionshantering — Alla workspace-ändringar git-spåras för enkel återställning