Agentserver

Wat is PocketHook Agent Server?

#

De agentserver maakt van PocketHook een volledige AI-assistent. In plaats van zelf responslogica te schrijven, verbind je een LLM (Claude, GPT, Gemini, enz.) dat berichten verwerkt, tools aanroept en gestructureerde PocketHook-responses retourneert — inclusief Shortcut-triggers.

De server draait op je eigen machine. Je gegevens blijven bij jou.

Dit is een startpunt. De server wordt geleverd met een kernset tools en is ontworpen om door jou uitgebreid te worden. Voeg je eigen integraties toe — e-mail, agenda’s, documenten, APIs — en maak het van jou.

Functies

#

• Multi-provider LLM — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (lokaal), LM Studio (lokaal)
• OAuth-authenticatie — GitHub Copilot en OpenAI Codex via device-code-/browser-flow
• Agenttools — Shell-commando’s, bestanden lezen/schrijven, mappenlijst, webzoeken, web scraping, dev-serverbeheer
• Framework-/gebruikerssplitsing — Frameworkbestanden (skills/, custom-tools/, config/) blijven alleen-lezen. Jouw aanpassingen staan onder data/user/ (skills, custom tools, instructies, getypeerde prefs). Framework-updates landen netjes zonder jouw werk te overschrijven
• Getypeerde gebruikersprefs — Bewaar waarden zoals je favoriete kaarten-app of tunneldomein in data/user/prefs.json. Refereer eraan in skills als {{prefs.key}} en de server substitueert ze bij het laden
• Programmeertaken in één aanroep — De meta-tool run_code_job maakt een achtergrondtaak van het type prompt aan (uitgevoerd door je geconfigureerde LLM) en stuurt de gebruiker de bevestiging in één stap — vervangt het foutgevoelige “respond + create-job”-patroon
• Getypeerde protocoltools — Zes dedicated respond_*-tools (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), plus getypeerde job-tools (create_once_job, create_cron_job) en getypeerde workspace-tools (create_project, list_projects, delete_project). Schemas weigeren misvormde URLs, button-syntax en type/schedule-combinaties voordat ze het apparaat bereiken
• Getypeerde writers voor aanpassingen — create_user_skill en create_custom_tool bouwen de markdown van de gebruikerslaag met correcte frontmatter, zodat de loader ze altijd parseert en de agent deze bestanden nooit met de hand schrijft
• Achtergrondtaken — Eenmalige of terugkerende taken met cron-expressies of eenvoudige intervallen
• Dynamische skills — Definieer Shortcuts en gedragsregels als .md-bestanden. Alleen een compacte index wordt in de prompt geladen; volledige inhoud wordt op verzoek opgehaald via de load_skill-tool
• Zelfbeherende skills — De agent kan skilldefinities aanmaken, bewerken en verwijderen (schrijfacties landen altijd in de gebruikerslaag)
• Semantisch geheugen — Vectorgebaseerd zoeken met embeddings (Ollama, LM Studio of OpenAI). Herinneringen worden automatisch geclassificeerd door het LLM in wing/room/hall/status-dimensies
• Kennisgraaf — Temporele triple-store voor duurzame feiten met auto-invalidatie. Multi-waarde-relaties bestaan naast elkaar; enkelvoudige feiten worden automatisch vervangen
• PARA-methode met projecteinde-cascade — Elke herinnering wordt voorzien van een status (Project, Gebied, Bron, Archief). Wanneer een project eindigt, archiveert één complete_project-aanroep de vectoren ervan, invalideert elke planningstriple die bij de slug past en legt de afsluiting vast — één aanroep in plaats van drie
• Hybride recall — Combineert FTS5-zoekwoordzoeking met vector-semantisch zoeken via reciprocal rank fusion
• Langetermijngeheugen — SQLite + FTS5-volltextzoeken als fallback wanneer semantisch geheugen is uitgeschakeld
• Dev-serverbeheer met tunnelcontract — Start, stop en lijst dev-servers. Wanneer tunnel: true wordt gevraagd, dwingt de server dit vooraf en na de spawn af — een onbereikbare localhost-server blijft nooit stilzwijgend draaien
• Automatische URL-opschoning — Als de agent een localhost-URL in een antwoord laat staan, herschrijven de respond_*-tools deze naar de bijbehorende tunnel-URL, zodat je telefoon altijd een bereikbare link krijgt
• Aangepaste tools — De agent kan CLI-tools installeren en registreren als nieuwe mogelijkheden
• Versiebeheer — Automatische git-versiebeheer voor werkruimtebestanden; configuratie-backups voor skills en machtigingen
• Webdashboard — Live-overzicht van achtergrondtaken, aanpasbaar per gebruiker. /dashboard en /api/jobs zijn met opzet niet geauthenticeerd — beperk toegang op netwerkniveau (Tailscale-ACL, firewall, reverse proxy met basic auth) of zet DASHBOARD=false als je het niet nodig hebt
• HTTPS-tunneling — Ingebouwde ondersteuning voor Tailscale, ngrok en Cloudflare Tunnel
• Systeemservice — Installeer als persistente service op macOS, Linux of Windows
• Rate limiting — Per-token aanvraaglimits met configureerbare drempels

Vereisten

#

• Bun runtime
• Een API-sleutel of OAuth-inloggegevens voor je LLM-provider
• (Optioneel) Tailscale, ngrok of cloudflared voor HTTPS-tunneling

Snelstart

#

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

# Interactieve setup — kies provider, model, auth-token, poort
bun run setup

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

De setup-wizard begeleidt je bij het kiezen van een LLM-provider, het configureren van authenticatie en het instellen van toolmachtigingen.

Zodra de server draait, kopieer de weergegeven URLs naar PocketHook-instellingen:

Hoe het werkt

#

1. Je stuurt een bericht in PocketHook
2. De server stuurt het door naar je gekozen LLM met gespreksgeschiedenis, opgehaalde herinneringen en beschikbare tools
3. Het LLM verwerkt het bericht — het kan shell-commando’s uitvoeren, bestanden lezen/schrijven, op het web zoeken, achtergrondtaken plannen, feiten onthouden of dev-servers starten
4. Het antwoord wordt teruggegeven in PocketHook-formaat (msg + shortcut + data + url)
5. PocketHook toont het bericht en voert alle Shortcuts uit op je apparaat

Ondersteunde LLM-providers

#

Wissel op elk moment van provider met bun run switch. Ollama en LM Studio draaien volledig op je machine — geen API-sleutel nodig, geen gegevens verlaten je netwerk.

Geheugen

#

Het geheugensysteem heeft drie lagen, elk met een ander doel.

Het ontwerp van het semantisch geheugen combineert ideeen van MemPalace (een geheugenpaleis-architectuur die herinneringen organiseert in wings, halls en rooms) en Tiago Forte’s PARA-methode (Projecten, Gebieden, Bronnen, Archief) voor kennislevenscyclusbeheer.

Gespreksgeheugen

#

SQLite met FTS5-volltextzoeken. Alle berichten worden opgeslagen met tijdstempels en sessie-ID’s.

• Korte termijn — Laatste MAX_HISTORY berichten bewaard in het geheugen per sessie
• Lange termijn — Alle berichten opgeslagen in SQLite, doorzoekbaar via FTS5-zoekwoordmatching
• Recall per beurt — Wanneer semantisch geheugen aanstaat, bepaalt MAX_RECALL hoeveel relevante herinneringen per beurt in de prompt worden geinjecteerd
• Sessies verlopen na SESSION_TTL_MINUTES, maar langetermijngeheugen blijft voor altijd bestaan

Stem deze interactief af met bun run memory.

Semantisch geheugen

#

Vereist VECTOR_MEMORY=true en een embedding-provider (Ollama, LM Studio of OpenAI).

Elke herinnering wordt ingebed als een vector en automatisch door het LLM geclassificeerd in vier dimensies:

• Wing — De entiteit: user, person:john, project:blog, place:london
• Room — Het type: facts, preferences, events, decisions, requests
• Hall — Het onderwerp: personal, tech, health, travel, food, work
• Status — PARA-classificatie: project, area, resource, archive

Wanneer je een vraag stelt, focust de entiteitsextractie de vectorzoeking op de meest relevante wings. Resultaten worden samengevoegd met FTS5-zoekwoordresultaten via reciprocal rank fusion — zodat je het beste van zowel zoekwoord- als semantisch zoeken krijgt.

Kennisgraaf

#

Een temporele triple-store voor gestructureerde, duurzame feiten:

• Triples: (onderwerp, predikaat, object) met valid_from / valid_until tijdstempels
• Enkelvoudige predikaten (lives_in, partner) invalideren automatisch de oude waarde bij update
• Meervoudige predikaten (child, friend, hobby) bestaan naast elkaar zonder invalidatie
• Kennisgraaf-feiten worden geinjecteerd naast opgehaalde herinneringen in elk gesprek

Wanneer je de agent vertelt “Ik ben naar Berlijn verhuisd”, invalideert het het oude lives_in-triple en maakt een nieuw — automatisch.

PARA-levenscyclus

#

Elke herinnering wordt getagd met een PARA-status:

• Project — Actief, tijdgebonden werk
• Gebied — Lopende verantwoordelijkheden
• Bron — Referentiemateriaal (lijsten, aanbevelingen, handleidingen)
• Archief — Voltooide of geannuleerde projecten

Wanneer een project voltooid is, gebruikt de agent semantische gelijkenis om alleen de herinneringen van dat project te archiveren, terwijl referentiemateriaal bewaard blijft voor toekomstig gebruik.

Projecteinde-cascade

#

Zeg “Ik annuleer mijn reis naar Barcelona” en één enkele tool-aanroep regelt alles:

1. Archiveert de vectoren van het project (events, beslissingen, verzoeken gekoppeld aan Barcelona).
2. Invalideert elke actieve kennisgraaf-triple waarvan het predikaat overeenkomt met de projectslug (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Legt de afsluiting vast als een nieuwe triple: (user, "cancelled_visit_barcelona", "2026-04-15").

Het matchen houdt rekening met grenzen — een ander project genaamd revisit_barcelona blijft onaangeroerd. De agent hoeft niet langer drie afzonderlijke aanroepen in de juiste volgorde te orkestreren, dus ook kleinere modellen krijgen het goed.

Als VECTOR_MEMORY is uitgeschakeld of de embedding-provider onbereikbaar is, valt het systeem terug op FTS5-only zonder fouten.

Skills

#

Skills zijn .md-bestanden in skills/ die iOS-Shortcuts definieren die de agent kan triggeren en/of gedragsregels. Ze gebruiken dynamisch laden: alleen een compacte index (titel, beschrijving, shortcutlijst) wordt geinjecteerd in de systeemprompt. De agent laadt volledige inhoud op verzoek via de load_skill-tool, zodat het tokengebruik laag blijft naarmate je meer skills toevoegt.

Elk skillbestand gebruikt 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-velden

#

Skills kunnen ook gedragsregels zijn zonder shortcuts (bijv. “hoe plan je een familiereis”). Gebruik shortcuts: [] hiervoor.

De agent kan skills aanmaken en beheren wanneer daarom gevraagd wordt — vraag hem om “maak een skill aan voor het bedienen van mijn lampen” en hij schrijft het .md-bestand voor je. Nieuwe en bewerkte skills landen altijd in jouw gebruikerslaag (data/user/skills/), zodat framework-updates ze nooit overschrijven. Zie de sectie Je agent aanpassen hieronder.

Shortcuts uitvoeren op de Mac-server

#

Wanneer een skill target: mac heeft, draaien shortcuts stilletjes op de Mac-server via de shortcuts run-CLI in plaats van naar het iOS-apparaat te worden gestuurd. Dit is ideaal voor acties die via iCloud-gesynchroniseerde inhoud aanmaken — notities, herinneringen, agenda-items — omdat het resultaat automatisch met al je apparaten synchroniseert zonder dat de PocketHook-app iets hoeft te doen.

Hoe het werkt:

1. De agent besluit dat een shortcut moet draaien (bijv. “maak een notitie met de vergaderaantekeningen van vandaag”)
2. De server roept shortcuts run "shortcutName" aan met de data die als JSON via stdin wordt meegegeven, met hetzelfde wrapper-formaat dat PocketHook iOS gebruikt
3. Als sync_app is ingesteld, opent de server die app kort op de achtergrond (open -gj -a Notes) om iCloud-synchronisatie af te dwingen en sluit hem daarna na 5 seconden
4. De gebruiker krijgt een bevestigingsbericht in de chat; de shortcut zelf wordt niet naar het apparaat gestuurd

Vereisten:

• De server moet op macOS draaien — shortcuts run is alleen op macOS beschikbaar. Op andere platforms logt de server een waarschuwing en valt terug op uitvoering op het apparaat
• De shortcut moet zijn geinstalleerd in Shortcuts.app op de server-Mac
• De shortcut moet een Dictionary als invoer verwachten (PocketHook verpakt data in { context, timestamp, app, data })

Wanneer target: mac gebruiken:

• iCloud-gesynchroniseerde acties (Notities, Herinneringen, Agenda) — het resultaat bereikt sowieso elk apparaat
• Langdurige verwerking die je buiten het iOS-apparaat wilt houden
• Elke shortcut die niet met de iPhone-interface hoeft te communiceren

Wanneer target: device (standaard) behouden:

• Shortcuts die iPhone-specifieke functies nodig hebben (camera, nauwkeurige locatie, lokale app-automatiseringen)
• Shortcuts die interactieve invoer van de gebruiker vragen
• Shortcuts die App Intents van iOS-only apps gebruiken

Achtergrondtaken

#

Vraag de agent om taken te plannen en hij regelt de rest:

• “Controleer het weer elke ochtend om 8 uur en maak een notitie”
• “Voer dit script elk uur uit”
• “Herinner me eraan om mijn e-mail over 30 minuten te checken”

Taken ondersteunen cron-expressies (0 8 * * *) en eenvoudige intervallen (30m, 1h, 2d). Resultaten worden afgeleverd bij PocketHook wanneer het het /jobs-eindpunt pollt.

Twee uitvoeringstypen:

• Shell — Voert een bash-commando uit, vangt uitvoer op. Kan een Shortcut triggeren bij voltooiing
• Prompt — Verwerkt door de AI-agent met volledige tooltoegang, slaat de complete PocketHook-response op

Dev-servers

#

Wanneer de agent een webproject in de werkruimte aanmaakt (Hugo, Astro, Next.js, Flask, Go, enz.), biedt hij proactief aan om het te serveren:

• Preview — Start een lokale dev-server op een automatisch toegewezen poort voor snel bekijken
• Publiek — Start de server en stelt deze bloot via HTTPS-tunnel zodat deze overal bereikbaar is

De agent beheert de levenscyclus: starten, stoppen en lijst van draaiende servers. Alle servers worden opgeruimd wanneer de hoofdserver stopt.

Tunnelcontract

#

Wanneer de agent een server start met tunnelblootstelling aangevraagd, dwingt de runtime dit af: als er geen tunneltool (Tailscale, ngrok, cloudflared) is geïnstalleerd, weigert de server te starten. Als het instellen van de tunnel mislukt na de spawn, wordt het weesproces gestopt en wordt de agent expliciet op de hoogte gesteld — zodat hij kan terugvallen op previewmodus of je kan vragen een tunnel te installeren. De geretourneerde URL is altijd de tunnel-URL wanneer tunneling aanstaat, met een opmerking dat de lokale URL alleen op de host werkt.

Als vangnet nabewerkt elke respond_*-tool zijn bericht: elke localhost- of 127.0.0.1-URL die in een antwoord sluipt, wordt automatisch herschreven naar de bijbehorende tunnel-URL wanneer een beheerde server er een heeft. Als herschrijven niet lukt, krijg je een waarschuwing in de logs in plaats van een kapotte link op je telefoon.

Dashboard

#

Het ingebouwde webdashboard op /dashboard toont een live-overzicht van achtergrondtaken.

Met opzet niet geauthenticeerd. Zowel /dashboard als /api/jobs zijn open GET-eindpunten — iedereen die de host kan bereiken kan taken oplijsten. Beperk toegang op netwerkniveau (Tailscale-ACL, firewall, reverse proxy met basic auth) of zet DASHBOARD=false als je het niet nodig hebt. De PocketHook iOS-app gebruikt deze eindpunten niet.

Het is volledig aanpasbaar:

• Snel bewerken — Plaats een dashboard.html in workspace/dashboard/ voor eenvoudige aanpassingen
• Vol project — Maak een frameworkproject (Svelte, React, Vue, enz.) in workspace/dashboard/ met build-uitvoer naar dist/

Vraag de agent om je dashboard aan te passen en hij regelt de rest — elke gebruiker krijgt een uniek, gepersonaliseerd dashboard.

Aangepaste tools

#

De agent kan CLI-tools installeren en registreren als nieuwe mogelijkheden — zichzelf uitbreidend zonder de servercode aan te passen.

Zeg bijvoorbeeld “installeer Playwright en gebruik het om screenshots te maken”. De agent zal:

1. De dependency installeren
2. Een tooldefinitie aanmaken (een eenvoudig .md-bestand)
3. De nieuwe tool gebruiken in toekomstige gesprekken

Aangepaste tools worden hot-reloaded — geen herstart nodig. Verwijder het .md-bestand om een tool te verwijderen.

Versiebeheer

#

Alle gebruikersgegevens worden automatisch geversioneerd:

• Werkruimtebestanden — Bijgehouden met een lokale git-repo in workspace/. Elke schrijfactie maakt een auto-commit. Vraag de agent om “maak de laatste wijziging ongedaan” of gebruik git revert HEAD handmatig
• Configuratiebestanden — config/agent-instructions.md, config/personality.md, skills/ en permissions.json worden voor elke wijziging geback-upt. Tot 20 versies per bestand

Git is optioneel — als het niet is geinstalleerd, zijn werkruimtewijzigingen niet geversioneerd. Configuratie-backups werken altijd.

Je agent aanpassen

#

De agentserver wordt geleverd met een minimale frameworkbasis en verwacht dat je er je eigen aanpassingen bovenop legt. De runtime houdt de twee gescheiden, zodat framework-updates nooit jouw werk overschrijven.

Framework vs. gebruiker

#

pockethook-agent-server/
├── skills/                      # door het framework geleverde skills (alleen-lezen)
├── custom-tools/                # gereserveerd voor door het framework geleverde tools (alleen-lezen)
├── config/
│   ├── agent-instructions.md    # framework-agentinstructies (alleen-lezen)
│   └── personality.md           # framework-persoonlijkheid (alleen-lezen)
└── data/user/                   # JOUW aanpassing komt hier (genegeerd door git)
    ├── skills/                  # je eigen skills (overschrijven de basis op bestandsnaam)
    ├── custom-tools/            # je geïnstalleerde custom tools
    ├── instructions.md          # je toevoegingen aan de agentinstructies
    └── prefs.json               # getypeerde waarden, gerefereerd als {{prefs.key}}

Gebruikersaanpassingen worden geschreven via dedicated getypeerde tools (create_user_skill, create_custom_tool), zodat de resulterende bestanden altijd overeenkomen met het formaat van de loader. De write-tool weigert ook elk pad onder skills/, custom-tools/ of config/ en stuurt de agent door naar data/user/* — zodat zelfs directe bestandsbewerkingen in de gebruikerslaag belanden.

Opmerking over de basis-custom-tools/-map. Vandaag bevat deze alleen een template (_example.md) die de loader negeert — elke tool die de agent voor je installeert gaat naar data/user/custom-tools/. De map is gereserveerd zodat toekomstige framework-releases optionele ingebouwde tools kunnen leveren zonder jouw installaties te overschrijven. Wanneer dat gebeurt, winnen jouw bestanden in de gebruikerslaag nog steeds bij naamconflicten, dus er valt niets te migreren.

Vier manieren om aan te passen

#

Je hoeft deze bestanden nooit met de hand te schrijven. Vertel de agent gewoon wat je wilt en hij kiest automatisch de juiste laag.

Getypeerde voorkeuren met {{prefs.*}}

#

Stel dat je een routeplanner-skill schrijft die je standaard startpunt moet kennen. In plaats van “Madrid” hard te coderen in de skill, refereer naar de pref:

- **Startpunt**: {{prefs.routeOrigin}}, tenzij de gebruiker een andere oorsprong opgeeft.

En sla de waarde op in data/user/prefs.json:

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

De server vervangt placeholders wanneer de skill wordt geladen. Geneste sleutels ({{prefs.tunnel.domain}}) werken ook. Onbekende sleutels blijven onaangeroerd zodat typefouten zichtbaar blijven.

De frameworkbasis rechtstreeks bewerken

#

Als je zelf host en het framework zelf wilt aanpassen, kun je config/agent-instructions.md, config/personality.md, skills/ of custom-tools/ rechtstreeks bewerken — de server houdt je niet tegen als je een bestandseditor gebruikt. Maar de agent schrijft vanuit een gesprek niet naar die paden. En framework-updates zullen jouw bewerkingen overschrijven. Geef de voorkeur aan de gebruikerslaag voor alles wat je wilt behouden.

Server uitbreiden

#

• Aangepaste tools — Vraag de agent om CLI-tools te installeren; ze landen automatisch in data/user/custom-tools/
• Skills toevoegen — Vraag de agent om een skill te maken; het bestand komt in data/user/skills/
• Gedrag aanpassen — Vraag de agent om een globale regel toe te passen; die wordt toegevoegd aan data/user/instructions.md
• Machtigingen configureren — Voer bun run permissions uit om te bepalen welke tools de agent mag gebruiken
• Ingebouwde tools toevoegen — Implementeer nieuwe toolfuncties in src/tools.ts voor diepere integraties (vereist forken van de server)

Configuratie

#

Alle instellingen worden opgeslagen in .env (aangemaakt door bun run setup). Belangrijke opties:

Zie de volledige configuratiereferentie in de GitHub-repository.

Als service draaien

#

Installeer als persistente service die automatisch start:

bun run service install

INSTANCE_NAME is standaard de basisnaam van de projectmap zonder de pockethook--prefix (bijv. een checkout in pockethook-agent-server/ wordt agent-server). Stel het expliciet in om meerdere checkouts op dezelfde machine te draaien zonder botsingen — elke instantie behoudt zijn eigen data/ en logs.

Beheer met bun run service status, restart, stop of uninstall.

Beveiliging

#

• HTTPS vereist — PocketHook dwingt HTTPS af voor alle URLs
• Bearer-tokenauthenticatie — Gedeeld geheim tussen app en server
• Rate limiting — Per-token limits voorkomen misbruik
• Sandboxed tools — Shell-commando’s en bestandstoegang beperkt door machtigingen
• Geblokkeerde patronen — Gevaarlijke commando’s (sudo, rm -rf /) standaard geblokkeerd
• Werkmap-grens — Agent kan zijn aangewezen map niet verlaten
• Gevoelige bestanden beschermd — .env, .git, *.key, *.pem geblokkeerd voor agenttoegang
• Automatisch versiebeheer — Alle werkruimtewijzigingen worden git-bijgehouden voor eenvoudig terugdraaien