Agentserver

Hva er PocketHook Agent Server?

#

Agentserveren gjor PocketHook til en fullverdig AI-assistent. I stedet for a skrive responslogikk selv, kobler du til en LLM (Claude, GPT, Gemini osv.) som behandler meldinger, kaller verktoy og returnerer strukturerte PocketHook-svar — inkludert Shortcut-utlosere.

Serveren kjorer pa din egen maskin. Dataene dine forblir hos deg.

Dette er et utgangspunkt. Serveren leveres med et kjernesett med verktoy og er designet for a utvides av deg. Legg til dine egne integrasjoner — e-post, kalendere, dokumenter, APIer — og gjor den til din.

Funksjoner

#

• Multi-leverandor LLM — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (lokal), LM Studio (lokal)
• OAuth-autentisering — GitHub Copilot og OpenAI Codex via enhetskode-/nettleserflyt
• Agentverktoy — Shell-kommandoer, fillesing/skriving, katalogoppforing, websok, web scraping, dev-serveradministrasjon
• Rammeverk/bruker-deling — Rammeverksfiler (skills/, custom-tools/, config/) forblir skrivebeskyttet. Dine tilpasninger bor under data/user/ (ferdigheter, tilpassede verktoy, instruksjoner, typede preferanser). Rammeverksoppdateringer lander rent uten a overskrive arbeidet ditt
• Typede brukerpreferanser — Lagre verdier som din foretrukne kartapp eller tunneldomene i data/user/prefs.json. Referer til dem i ferdigheter som {{prefs.key}}, og serveren setter dem inn ved innlasting
• Programmeringsoppgaver i ett kall — Meta-verktoyet run_code_job oppretter en bakgrunnsjobb av prompt-typen (kjort av din konfigurerte LLM) og sender brukeren bekreftelsen i ett trinn, og erstatter det feilutsatte monsteret “respond + create-job”
• Typede protokollverktoy — Seks dedikerte respond_*-verktoy (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), pluss typede jobbverktoy (create_once_job, create_cron_job) og typede workspace-verktoy (create_project, list_projects, delete_project). Skjemaer avviser feilformede URL-er, knappesyntaks og type/schedule-kombinasjoner for de nar enheten
• Typede skribenter for tilpasning — create_user_skill og create_custom_tool bygger brukerlagets markdown med korrekt frontmatter, sa lasteren alltid parser dem og agenten aldri skriver disse filene for hand
• Bakgrunnsjobber — Engangs- eller gjentagende oppgaver med cron-uttrykk eller enkle intervaller
• Dynamiske ferdigheter — Definer Shortcuts og atferdsregler som .md-filer. Bare en kompakt indeks lastes inn i prompten; fullt innhold hentes pa foresporsel via load_skill-verktoyet
• Selvadministrerende ferdigheter — Agenten kan opprette, redigere og slette ferdighetsdefinisjoner (skrivinger lander alltid i brukerlaget)
• Semantisk minne — Vektorbasert sok med embeddings (Ollama, LM Studio eller OpenAI). Minner klassifiseres automatisk av LLM-en i wing/room/hall/status-dimensjoner
• Kunnskapsgraf — Temporalt triple-store for varige fakta med automatisk invalidering. Flerverdi-relasjoner sameksisterer; enkeltverdi-fakta erstattes automatisk
• PARA-metoden med prosjektavslutnings-kaskade — Hvert minne tagges med en status (Prosjekt, Omrade, Ressurs, Arkiv). Nar et prosjekt avsluttes, arkiverer ett enkelt complete_project-kall vektorene, ugyldiggjor hvert planleggingstriple knyttet til prosjektets slug og registrerer fullforelsen — ett kall i stedet for tre
• Hybrid gjenkalling — Kombinerer FTS5-sokordssok med vektor-semantisk sok ved hjelp av reciprocal rank fusion
• Langtidsminne — SQLite + FTS5-fulltekstsok som fallback nar semantisk minne er deaktivert
• Dev-serveradministrasjon med tunnelkontrakt — Start, stopp og list dev-servere. Nar tunnel: true bes om, handhever serveren det bade for-flyving og etter-spawn — en utilgjengelig localhost-server blir aldri staende stille i gang
• Automatisk URL-rensing — Hvis agenten etterlater en localhost-URL i et svar, skriver respond_*-verktoyene den om til den matchende tunnel-URL-en, sa telefonen din alltid far en naabar lenke
• Tilpassede verktoy — Agenten kan installere CLI-verktoy og registrere dem som nye evner
• Versjonering — Automatisk git-versjonering for workspace-filer; konfigurasjonsbackup for ferdigheter og tillatelser
• Webdashbord — Live-oversikt over bakgrunnsjobber, tilpassbart per bruker. /dashboard og /api/jobs er bevisst uautentiserte — begrens tilgang pa nettverkslaget (Tailscale-ACL, brannmur, reverse proxy med basic auth) eller sett DASHBOARD=false hvis du ikke trenger det
• HTTPS-tunneling — Innebygd stotte for Tailscale, ngrok og Cloudflare Tunnel
• Systemtjeneste — Installer som persistent tjeneste pa macOS, Linux eller Windows
• Frekvensbegrensning — Per-token foresporselsgrenser med konfigurerbare terskler

Krav

#

• Bun runtime
• En API-nokkel eller OAuth-legitimasjon for LLM-leverandoren din
• (Valgfritt) Tailscale, ngrok eller cloudflared for HTTPS-tunneling

Hurtigstart

#

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

# Interaktivt oppsett — velg leverandor, modell, auth-token, port
bun run setup

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

Oppsettsveiviseren guider deg gjennom valg av LLM-leverandor, konfigurering av autentisering og oppsett av verktoytillatelser.

Nar serveren kjorer, kopier de viste URL-ene til PocketHook-innstillinger:

Hvordan det fungerer

#

1. Du sender en melding i PocketHook
2. Serveren videresender den til din valgte LLM med samtalehistorikk, hentede minner og tilgjengelige verktoy
3. LLM-en behandler meldingen — den kan kjore shell-kommandoer, lese/skrive filer, soke pa nettet, planlegge bakgrunnsjobber, huske fakta eller starte dev-servere
4. Svaret returneres i PocketHook-format (msg + shortcut + data + url)
5. PocketHook viser meldingen og kjorer alle Shortcuts pa enheten din

Stottede LLM-leverandorer

#

Bytt leverandor nar som helst med bun run switch. Ollama og LM Studio kjorer helt pa maskinen din — ingen API-nokkel nodvendig, ingen data forlater nettverket ditt.

Minne

#

Minnesystemet har tre lag, som hver tjener et ulikt formal.

Designet av det semantiske minnet kombinerer ideer fra MemPalace (en minnepalassarkitektur som organiserer minner i wings, halls og rooms) og Tiago Fortes PARA-metode (Prosjekter, Omrader, Ressurser, Arkiv) for kunnskapslivssyklusstyring.

Samtaleminne

#

SQLite med FTS5-fulltekstsok. Alle meldinger lagres med tidsstempler og sesjons-IDer.

• Korttid — Siste MAX_HISTORY meldinger holdt i minnet per sesjon
• Langtid — Alle meldinger lagret i SQLite, sokbare via FTS5-sokordmatching
• Gjenkalling per tur — Nar semantisk minne er pa, styrer MAX_RECALL hvor mange relevante minner som injiseres i prompten hver tur
• Sesjoner utloper etter SESSION_TTL_MINUTES, men langtidsminnet bestar for alltid

Juster disse interaktivt med bun run memory.

Semantisk minne

#

Krever VECTOR_MEMORY=true og en embedding-leverandor (Ollama, LM Studio eller OpenAI).

Hvert minne integreres som en vektor og klassifiseres automatisk av LLM-en i fire dimensjoner:

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

Nar du stiller et sporsmal, fokuserer entitetsekstraksjon vektorsoket pa de mest relevante wings. Resultater slas sammen med FTS5-sokordresultater via reciprocal rank fusion — sa du far det beste av bade sokords- og semantisk sok.

Kunnskapsgraf

#

Et temporalt triple-store for strukturerte, varige fakta:

• Tripler: (subjekt, predikat, objekt) med valid_from / valid_until tidsstempler
• Enkeltverdi-predikater (lives_in, partner) ugyldiggjor automatisk den gamle verdien ved oppdatering
• Flerverdi-predikater (child, friend, hobby) sameksisterer uten ugyldiggjoring
• Kunnskapsgraffakta injiseres sammen med hentede minner i hver samtale

Nar du forteller agenten “Jeg har flyttet til Berlin”, ugyldiggjor den det gamle lives_in-trippelet og oppretter et nytt — automatisk.

PARA-livssyklus

#

Hvert minne tagges med en PARA-status:

• Prosjekt — Aktivt, tidsbundet arbeid
• Omrade — Pagende ansvarsomrader
• Ressurs — Referansemateriale (lister, anbefalinger, veiledninger)
• Arkiv — Fullforte eller avbrutte prosjekter

Nar et prosjekt fullfores, bruker agenten semantisk likhet for a bare arkivere det prosjektets minner mens referansemateriale bevares for fremtidig bruk.

Prosjektavslutnings-kaskade

#

Si “Jeg avbestiller turen min til Barcelona”, og ett enkelt verktoykall handterer alt:

1. Arkiverer prosjektets vektorer (events, decisions, requests knyttet til Barcelona).
2. Ugyldiggjor hvert aktive kunnskapsgraftriple hvis predikat matcher prosjektets slug (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Registrerer fullforelsen som et nytt triple: (user, "cancelled_visit_barcelona", "2026-04-15").

Matchingen er grensebevisst — et annet prosjekt kalt revisit_barcelona blir urort. Agenten trenger ikke lenger a orkestrere tre separate kall i riktig rekkefolge, sa mindre modeller far det ogsa til.

Hvis VECTOR_MEMORY er deaktivert eller embedding-leverandoren er utilgjengelig, faller systemet feilfritt tilbake til FTS5-only.

Ferdigheter

#

Ferdigheter er .md-filer i skills/ som definerer iOS-Shortcuts agenten kan utlose og/eller atferdsregler. De bruker dynamisk lasting: bare en kompakt indeks (tittel, beskrivelse, shortcutliste) injiseres i systemprompten. Agenten laster fullt innhold pa foresporsel via load_skill-verktoyet, sa tokenforbruket holdes lavt nar du legger til flere ferdigheter.

Hver ferdighetsfil bruker 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-felter

#

Ferdigheter kan ogsa vaere atferdsregler uten shortcuts (f.eks. “hvordan planlegge en familieferie”). Bruk shortcuts: [] for disse.

Agenten kan opprette og administrere ferdigheter nar du ber om det — be den om a “opprette en ferdighet for a styre lysene mine” og den skriver .md-filen for deg. Nye og redigerte ferdigheter lander alltid i brukerlaget ditt (data/user/skills/), sa rammeverksoppdateringer aldri overskriver dem. Se avsnittet Customizing your agent nedenfor.

Kjore shortcuts pa Mac-serveren

#

Nar en ferdighet har target: mac, kjores shortcuts stille pa Mac-serveren via CLI-verktoyet shortcuts run i stedet for a sendes til iOS-enheten. Dette er ideelt for handlinger som oppretter iCloud-synkronisert innhold — notater, paminnelser, kalenderhendelser — fordi resultatet synkroniseres til alle enhetene dine automatisk uten at PocketHook-appen ma gjore noe.

Slik fungerer det:

1. Agenten bestemmer at en shortcut skal kjores (f.eks. “opprett et notat med dagens moteopptak”)
2. Serveren kaller shortcuts run "shortcutNavn" med dataene sendt som JSON pa stdin, i samme wrapper-format som PocketHook iOS bruker
3. Hvis sync_app er satt, apner serveren kort den appen i bakgrunnen (open -gj -a Notes) for a tvinge iCloud-synkronisering, og lukker den etter 5 sekunder
4. Brukeren mottar en bekreftelsesmelding i chatten; selve shortcut’en sendes ikke til enheten

Krav:

• Serveren ma kjore pa macOS — shortcuts run finnes kun pa macOS. Pa andre plattformer logger serveren en advarsel og faller tilbake til enhetskjoring
• Shortcut’en ma vaere installert i Shortcuts.app pa Mac-serveren
• Shortcut’en bor forvente et Dictionary som inndata (PocketHook pakker data inn i { context, timestamp, app, data })

Nar du bor bruke target: mac:

• iCloud-synkroniserte handlinger (Notes, Reminders, Calendar) — resultatet nar uansett alle enheter
• Langvarig behandling du vil holde unna iOS-enheten
• Alle shortcuts som ikke trenger a interagere med iPhone’s brukergrensesnitt

Nar du bor beholde target: device (standard):

• Shortcuts som trenger iPhone-spesifikke funksjoner (kamera, noyaktig posisjon, lokale app-automatiseringer)
• Shortcuts som ber brukeren om interaktiv input
• Shortcuts som bruker App Intents fra iOS-kun-apper

Bakgrunnsjobber

#

Be agenten om a planlegge oppgaver, og den ordner resten:

• “Sjekk vaeret hver morgen klokken 8 og lag et notat”
• “Kjor dette skriptet hver time”
• “Minn meg pa a sjekke e-posten min om 30 minutter”

Jobber stotter cron-uttrykk (0 8 * * *) og enkle intervaller (30m, 1h, 2d). Resultater leveres til PocketHook nar den poller /jobs-endepunktet.

To kjoringstyper:

• Shell — Kjorer en bash-kommando, fanger opp utdata. Kan utlose en Shortcut ved fullforelse
• Prompt — Behandlet av AI-agenten med full verktoytilgang, lagrer det komplette PocketHook-svaret

Dev-servere

#

Nar agenten oppretter et webprosjekt i workspace (Hugo, Astro, Next.js, Flask, Go osv.), tilbyr den proaktivt a servere det:

• Forhandsvisning — Starter en lokal dev-server pa en automatisk tildelt port for rask visning
• Offentlig — Starter serveren og eksponerer den via HTTPS-tunnel sa den er tilgjengelig overalt

Agenten styrer livssyklusen: start, stopp og list kjorende servere. Alle servere ryddes opp nar hovedserveren stoppes.

Tunnelkontrakt

#

Nar agenten starter en server med tunneleksponering bedt om, handhever kjoretiden det: hvis ingen tunnelverktoy (Tailscale, ngrok, cloudflared) er installert, nekter serveren a starte. Hvis tunneloppsett feiler etter spawn, stoppes den foreldrelose prosessen, og agenten far beskjed eksplisitt — sa den kan falle tilbake til forhandsvisning eller be deg installere en tunnel. Den returnerte URL-en er alltid tunnel-URL-en nar tunneling er pa, med en merknad om at den lokale URL-en kun gjelder for verten.

Som et sikkerhetsnett etterbehandler hvert respond_*-verktoy sin melding: enhver localhost- eller 127.0.0.1-URL som sniker seg inn i et svar blir automatisk omskrevet til den matchende tunnel-URL-en nar en administrert server har en. Nar det ikke kan skrive om, far du en advarsel i loggene i stedet for en odelagt lenke pa telefonen.

Dashbord

#

Det innebygde webdashbordet pa /dashboard viser en live-oversikt over bakgrunnsjobber.

Bevisst uautentisert. Bade /dashboard og /api/jobs er apne GET-endepunkter — hvem som helst som kan na verten kan liste jobber. Begrens tilgang pa nettverkslaget (Tailscale-ACL, brannmur, reverse proxy med basic auth) eller sett DASHBOARD=false hvis du ikke trenger det. PocketHook iOS-appen bruker ikke disse endepunktene.

Det er fullt tilpassbart:

• Hurtigredigering — Plasser en dashboard.html i workspace/dashboard/ for enkle tilpasninger
• Fullt prosjekt — Opprett et rammeverksprosjekt (Svelte, React, Vue osv.) i workspace/dashboard/ med build-utdata til dist/

Be agenten om a tilpasse dashbordet ditt, og den ordner resten — hver bruker far et unikt, personalisert dashbord.

Tilpassede verktoy

#

Agenten kan installere CLI-verktoy og registrere dem som nye evner — utvider seg selv uten a endre serverkoden.

Si for eksempel “installer Playwright og bruk det til a ta skjermbilder”. Agenten vil:

1. Installere avhengigheten
2. Opprette en verktoydefinisjon (en enkel .md-fil)
3. Bruke det nye verktoyet i fremtidige samtaler

Tilpassede verktoy lastes inn pa nytt umiddelbart — ingen omstart nodvendig. Slett .md-filen for a fjerne et verktoy.

Versjonering

#

Alle brukerdata versjoneres automatisk:

• Workspace-filer — Sporet med et lokalt git-repo inne i workspace/. Hver skriving oppretter en auto-commit. Be agenten om a “angre den siste endringen” eller bruk git revert HEAD manuelt
• Konfigurasjonsfiler — config/agent-instructions.md, config/personality.md, skills/ og permissions.json sikkerhetskopieres for hver endring. Opptil 20 versjoner per fil

Git er valgfritt — hvis det ikke er installert, er workspace-endringer ikke versjonert. Konfigurasjonsbackup fungerer alltid.

Tilpass agenten din

#

Agentserveren leveres med en minimal rammeverksbase og forventer at du legger din egen tilpasning oppa. Kjoretiden holder de to adskilt sa rammeverksoppdateringer aldri odelegger arbeidet ditt.

Rammeverk vs bruker

#

pockethook-agent-server/
├── skills/                      # rammeverksleverte ferdigheter (skrivebeskyttet)
├── custom-tools/                # reservert for rammeverksleverte verktoy (skrivebeskyttet)
├── config/
│   ├── agent-instructions.md    # rammeverkets agentinstruksjoner (skrivebeskyttet)
│   └── personality.md           # rammeverkets personlighet (skrivebeskyttet)
└── data/user/                   # DIN tilpasning bor her (git-ignorert)
    ├── skills/                  # dine egne ferdigheter (overstyrer base pa filnavn)
    ├── custom-tools/            # dine installerte tilpassede verktoy
    ├── instructions.md          # dine tillegg til agentinstruksjonene
    └── prefs.json               # typede verdier referert som {{prefs.key}}

Brukertilpasning skrives via dedikerte typede verktoy (create_user_skill, create_custom_tool), sa de resulterende filene alltid matcher lasterens format. write-verktoyet avviser ogsa enhver sti under skills/, custom-tools/ eller config/ og dirigerer agenten til data/user/* — sa selv direkte filredigeringer ender i brukerlaget.

Merknad om base-mappen custom-tools/. I dag inneholder den bare en mal (_example.md) som lasteren ignorerer — hvert verktoy agenten installerer for deg havner i data/user/custom-tools/. Mappen er reservert slik at fremtidige rammeverksutgivelser kan levere valgfrie innebygde verktoy uten a odelegge dine installasjoner. Nar det skjer, vinner brukerlagsfilene dine fortsatt ved navnekollisjon, sa det er ingenting a migrere.

Fire mater a tilpasse pa

#

Du trenger aldri a skrive disse filene for hand. Bare si til agenten hva du vil, og den velger rett lag automatisk.

Typede preferanser med {{prefs.*}}

#

Si at du skriver en ruteplanlegger-ferdighet som trenger a vite ditt standard utgangspunkt. I stedet for a hardkode “Madrid” i selve ferdigheten, referer til preferansen:

- **Utgangspunkt**: {{prefs.routeOrigin}}, med mindre brukeren angir et annet utgangspunkt.

Og lagre verdien i data/user/prefs.json:

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

Serveren setter inn plassholdere nar ferdigheten lastes. Nestede nokler ({{prefs.tunnel.domain}}) fungerer ogsa. Ukjente nokler blir urort, sa skrivefeil forblir synlige.

Redigere rammeverksbasen direkte

#

Hvis du selvhoster og vil fikle med selve rammeverket, kan du redigere config/agent-instructions.md, config/personality.md, skills/ eller custom-tools/ direkte — serveren stopper deg ikke nar du bruker en filredigerer. Men agenten vil ikke skrive til de stiene fra en samtale. Og rammeverksoppdateringer vil overskrive redigeringene dine. Foretrekk brukerlaget for alt du vil beholde.

Utvide serveren

#

• Tilpassede verktoy — Be agenten om a installere CLI-verktoy; de havner i data/user/custom-tools/ automatisk
• Legg til ferdigheter — Be agenten om a opprette en ferdighet; filen gar i data/user/skills/
• Endre atferd — Be agenten om a anvende en global regel; den legges til i data/user/instructions.md
• Konfigurer tillatelser — Kjor bun run permissions for a styre hvilke verktoy agenten kan bruke
• Legg til innebygde verktoy — Implementer nye verktoyfunksjoner i src/tools.ts for dypere integrasjoner (krever a forke serveren)

Konfigurasjon

#

Alle innstillinger lagres i .env (opprettet av bun run setup). Viktige alternativer:

Se den fullstendige konfigurasjonsreferansen i GitHub-repositoriet.

Kjore som tjeneste

#

Installer som persistent tjeneste som starter automatisk:

bun run service install

INSTANCE_NAME er som standard prosjektmappens basenavn med pockethook--prefikset fjernet (f.eks. blir en checkout i pockethook-agent-server/ til agent-server). Sett det eksplisitt for a kjore flere checkouts pa samme maskin uten kollisjoner — hver instans beholder sitt eget data/ og logger.

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

Sikkerhet

#

• HTTPS pakrevd — PocketHook krever HTTPS for alle URLer
• Bearer-token-autentisering — Delt hemmelighet mellom app og server
• Frekvensbegrensning — Per-token grenser forhindrer misbruk
• Sandboxede verktoy — Shell-kommandoer og filtilgang begrenset av tillatelser
• Blokkerte monstre — Farlige kommandoer (sudo, rm -rf /) blokkert som standard
• Arbeidskataloggrense — Agenten kan ikke forlate sin tildelte katalog
• Sensitive filer beskyttet — .env, .git, *.key, *.pem blokkert fra agenttilgang
• Automatisk versjonering — Alle workspace-endringer git-spores for enkel tilbakerulling