Server Agent

Cos’e PocketHook Agent Server?

#

Il server agent trasforma PocketHook in un assistente IA completo. Invece di scrivere la logica di risposta tu stesso, colleghi un LLM (Claude, GPT, Gemini, ecc.) che elabora i messaggi, chiama strumenti e restituisce risposte strutturate di PocketHook — inclusa l’attivazione dei Comandi Rapidi.

Il server gira sulla tua macchina. I tuoi dati restano con te.

Questo e un punto di partenza. Il server viene fornito con un set base di strumenti ed e progettato per essere esteso da te. Aggiungi le tue integrazioni — email, calendari, documenti, API — e rendilo tuo.

Funzionalita

#

• LLM multi-fornitore — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (locale), LM Studio (locale)
• Autenticazione OAuth — GitHub Copilot e OpenAI Codex tramite flusso codice dispositivo / browser
• Strumenti agent — Comandi shell, lettura/scrittura file, elenco directory, ricerca web, web scraping, gestione server dev
• Separazione framework / utente — I file del framework (skills/, custom-tools/, config/) restano in sola lettura. Le tue personalizzazioni vivono sotto data/user/ (competenze, strumenti personalizzati, istruzioni, prefs tipizzate). Gli aggiornamenti del framework si applicano senza sovrascrivere il tuo lavoro
• Prefs utente tipizzate — Memorizza valori come la tua app di mappe preferita o il dominio del tunnel in data/user/prefs.json. Referenziali nelle competenze come {{prefs.key}} e il server effettua la sostituzione al caricamento
• Attivita di programmazione in una sola chiamata — Il meta-strumento run_code_job crea un’attivita in background di tipo prompt (eseguita dal tuo LLM configurato) e invia la conferma all’utente in un unico passaggio, sostituendo il pattern “respond + create-job” soggetto a errori
• Strumenti di protocollo tipizzati — Sei strumenti respond_* dedicati (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), piu strumenti per le attivita tipizzati (create_once_job, create_cron_job) e strumenti per il workspace tipizzati (create_project, list_projects, delete_project). Gli schemi rifiutano URL malformati, sintassi dei pulsanti e combinazioni type/schedule prima che raggiungano il dispositivo
• Scrittori tipizzati per la personalizzazione — create_user_skill e create_custom_tool costruiscono il markdown del livello utente con il frontmatter corretto, in modo che il loader li analizzi sempre e l’agente non scriva mai questi file a mano
• Attivita in background — Attivita singole o ricorrenti con espressioni cron o intervalli semplici
• Competenze dinamiche — Definisci scorciatoie e regole di comportamento come file .md. Solo un indice compatto viene caricato nel prompt; il contenuto completo viene recuperato su richiesta tramite lo strumento load_skill
• Competenze autogestite — L’agente puo creare, modificare e eliminare definizioni di competenze (le scritture finiscono sempre nel livello utente)
• Memoria semantica — Ricerca basata su vettori con embeddings (Ollama, LM Studio o OpenAI). I ricordi vengono auto-classificati in dimensioni wing/room/hall/status dal LLM
• Grafo della conoscenza — Archivio di triple temporali per fatti durevoli con auto-invalidazione. Le relazioni multi-valore coesistono; i fatti a valore singolo vengono sostituiti automaticamente
• Metodo PARA con cascata di fine progetto — Ogni ricordo viene etichettato con uno stato (Progetto, Area, Risorsa, Archivio). Quando un progetto finisce, una singola chiamata complete_project archivia i suoi vettori, invalida ogni tripla di pianificazione legata al suo slug e registra il completamento — una chiamata invece di tre
• Recupero ibrido — Combina ricerca per parole chiave FTS5 con ricerca semantica vettoriale usando fusione di classificazione reciproca
• Memoria a lungo termine — SQLite + ricerca full-text FTS5 come fallback quando la memoria semantica e disabilitata
• Gestione server dev con contratto di tunnel — Avvia, ferma e elenca server dev. Quando viene richiesto tunnel: true, il server lo impone prima e dopo l’avvio — un server localhost irraggiungibile non resta mai in esecuzione silenziosamente
• Sanificazione automatica degli URL — Se l’agente lascia un URL localhost in una risposta, gli strumenti respond_* lo riscrivono nell’URL di tunnel corrispondente in modo che il tuo telefono riceva sempre un link raggiungibile
• Strumenti personalizzati — L’agente puo installare strumenti CLI e registrarli come nuove capacita
• Versionamento — Versionamento git automatico per file del workspace; backup di configurazione per competenze e permessi
• Dashboard web — Vista dal vivo delle attivita in background, personalizzabile per utente. /dashboard e /api/jobs non sono autenticati per design — limita l’accesso a livello di rete (ACL Tailscale, firewall, reverse proxy con autenticazione di base) o imposta DASHBOARD=false se non ne hai bisogno
• Tunnel HTTPS — Supporto integrato per Tailscale, ngrok e Cloudflare Tunnel
• Servizio di sistema — Installa come servizio persistente su macOS, Linux o Windows
• Limitazione del tasso — Limiti di richieste per token con soglie configurabili

Requisiti

#

• Runtime Bun
• Una chiave API o credenziali OAuth per il tuo fornitore LLM
• (Opzionale) Tailscale, ngrok o cloudflared per tunnel HTTPS

Avvio Rapido

#

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

# Configurazione interattiva — scegli fornitore, modello, token di auth, porta
bun run setup

# Avviare server + tunnel HTTPS
bun run dev:tunnel

La procedura guidata ti guida nella scelta di un fornitore LLM, nella configurazione dell’autenticazione e nell’impostazione dei permessi degli strumenti.

Una volta in esecuzione, copia gli URL visualizzati nelle Impostazioni di PocketHook:

Come Funziona

#

1. Invii un messaggio in PocketHook
2. Il server lo inoltra al tuo LLM scelto con la cronologia delle conversazioni, i ricordi recuperati e gli strumenti disponibili
3. Il LLM elabora il messaggio — puo eseguire comandi shell, leggere/scrivere file, cercare sul web, pianificare attivita in background, ricordare fatti o avviare server dev
4. La risposta viene restituita nel formato PocketHook (msg + shortcut + data + url)
5. PocketHook mostra il messaggio ed esegue eventuali Comandi Rapidi sul tuo dispositivo

Fornitori LLM Supportati

#

Cambia fornitore in qualsiasi momento con bun run switch. Ollama e LM Studio girano interamente sulla tua macchina — nessuna chiave API necessaria, nessun dato esce dalla tua rete.

Memoria

#

Il sistema di memoria ha tre livelli, ciascuno con uno scopo diverso.

Il design della memoria semantica combina idee da MemPalace (un’architettura a palazzo della memoria che organizza i ricordi in ali, corridoi e stanze) e il metodo PARA di Tiago Forte (Progetti, Aree, Risorse, Archivio) per la gestione del ciclo di vita della conoscenza.

Memoria di conversazione

#

SQLite con ricerca full-text FTS5. Tutti i messaggi vengono archiviati con timestamp e ID di sessione.

• Breve termine — Gli ultimi MAX_HISTORY messaggi vengono mantenuti in memoria per sessione
• Lungo termine — Tutti i messaggi persistono in SQLite, ricercabili tramite corrispondenza parole chiave FTS5
• Recupero per turno — Quando la memoria semantica e attiva, MAX_RECALL controlla quanti ricordi rilevanti vengono iniettati nel prompt a ogni turno
• Le sessioni scadono dopo SESSION_TTL_MINUTES, ma la memoria a lungo termine persiste per sempre

Regola questi parametri in modo interattivo con bun run memory.

Memoria semantica

#

Richiede VECTOR_MEMORY=true e un fornitore di embeddings (Ollama, LM Studio o OpenAI).

Ogni ricordo viene convertito in un vettore e auto-classificato dal LLM in quattro dimensioni:

• Wing — L’entita: user, person:john, project:blog, place:london
• Room — Il tipo: facts, preferences, events, decisions, requests
• Hall — L’argomento: personal, tech, health, travel, food, work
• Status — Classificazione PARA: project, area, resource, archive

Quando fai una domanda, l’estrazione delle entita focalizza la ricerca vettoriale sui wing piu rilevanti. I risultati vengono fusi con i risultati delle parole chiave FTS5 usando la fusione di classificazione reciproca — per ottenere il meglio di entrambi, corrispondenza per parole chiave e semantica.

Grafo della conoscenza

#

Un archivio di triple temporali per fatti strutturati e durevoli:

• Triple: (soggetto, predicato, oggetto) con timestamp valid_from / valid_until
• I predicati a valore singolo (lives_in, partner) auto-invalidano il valore precedente all’aggiornamento
• I predicati multi-valore (child, friend, hobby) coesistono senza invalidazione
• I fatti del grafo della conoscenza vengono iniettati insieme ai ricordi recuperati in ogni conversazione

Quando dici all’agente “Mi sono trasferito a Berlino”, invalida la vecchia tripla lives_in e ne crea una nuova — automaticamente.

Ciclo di vita PARA

#

Ogni ricordo viene etichettato con uno stato PARA:

• Progetto — Lavoro attivo con scadenza
• Area — Responsabilita in corso
• Risorsa — Materiale di riferimento (elenchi, raccomandazioni, guide)
• Archivio — Progetti completati o annullati

Quando un progetto viene completato, l’agente usa la similarita semantica per archiviare solo i ricordi di quel progetto, preservando il materiale di riferimento per uso futuro.

Cascata di fine progetto

#

Di’ “Sto annullando il mio viaggio a Barcellona” e una singola chiamata di strumento si occupa di tutto:

1. Archivia i vettori del progetto (eventi, decisioni, richieste legati a Barcellona).
2. Invalida ogni tripla attiva del grafo della conoscenza il cui predicato corrisponde allo slug del progetto (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Registra il completamento come nuova tripla: (user, "cancelled_visit_barcelona", "2026-04-15").

La corrispondenza rispetta i confini — un progetto diverso chiamato revisit_barcelona resta intatto. L’agente non deve piu orchestrare tre chiamate separate nell’ordine giusto, cosi anche i modelli piu piccoli ci riescono.

Se VECTOR_MEMORY e disabilitato o il fornitore di embeddings non e raggiungibile, il sistema torna a solo FTS5 senza errori.

Competenze

#

Le competenze sono file .md in skills/ che definiscono i Comandi Rapidi iOS che l’agente puo attivare e/o regole di comportamento. Usano il caricamento dinamico: solo un indice compatto (titolo, descrizione, elenco scorciatoie) viene iniettato nel prompt di sistema. L’agente carica il contenuto completo su richiesta tramite lo strumento load_skill, mantenendo basso l’uso dei token man mano che aggiungi piu competenze.

Ogni file di competenza usa il 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

Campi del frontmatter

#

Le competenze possono anche essere regole di comportamento senza scorciatoie (ad esempio, “come pianificare un viaggio di famiglia”). Usa shortcuts: [] per queste.

L’agente puo creare e gestire competenze quando richiesto — chiedigli di “creare una competenza per controllare le mie luci” e scrivera il file .md per te. Le competenze nuove e modificate finiscono sempre nel tuo livello utente (data/user/skills/), cosi gli aggiornamenti del framework non le sovrascrivono mai. Vedi la sezione Personalizzare il tuo agente qui sotto.

Eseguire scorciatoie sul server Mac

#

Quando una competenza ha target: mac, le scorciatoie vengono eseguite silenziosamente sul server Mac tramite la CLI shortcuts run invece di essere inviate al dispositivo iOS. Questo e ideale per azioni che creano contenuti sincronizzati via iCloud — note, promemoria, eventi di calendario — perche il risultato si sincronizza automaticamente su tutti i tuoi dispositivi senza che l’app PocketHook debba fare nulla.

Come funziona:

1. L’agente decide che una scorciatoia deve essere eseguita (ad esempio, “crea una nota con gli appunti della riunione di oggi”)
2. Il server invoca shortcuts run "shortcutName" con i dati passati come JSON su stdin, usando lo stesso formato wrapper che usa PocketHook iOS
3. Se sync_app e impostato, il server apre brevemente quell’app in background (open -gj -a Notes) per forzare la sincronizzazione iCloud, e la chiude dopo 5 secondi
4. L’utente riceve un messaggio di conferma nella chat; la scorciatoia in se non viene inviata al dispositivo

Requisiti:

• Il server deve girare su macOS — shortcuts run e disponibile solo su macOS. Su altre piattaforme, il server registra un avviso e ricade sull’esecuzione lato dispositivo
• La scorciatoia deve essere installata in Shortcuts.app sul Mac del server
• La scorciatoia deve aspettarsi un Dizionario in input (PocketHook incapsula i dati in { context, timestamp, app, data })

Quando usare target: mac:

• Azioni sincronizzate via iCloud (Note, Promemoria, Calendario) — il risultato raggiunge comunque ogni dispositivo
• Elaborazioni lunghe che vuoi tenere fuori dal dispositivo iOS
• Qualsiasi scorciatoia che non deve interagire con l’interfaccia dell’iPhone

Quando mantenere target: device (predefinito):

• Scorciatoie che richiedono funzioni esclusive dell’iPhone (fotocamera, posizione precisa, automazioni locali di app)
• Scorciatoie che chiedono input interattivo all’utente
• Scorciatoie che usano App Intents di app esclusive per iOS

Attivita in Background

#

Chiedi all’agente di pianificare attivita e si occupera del resto:

• “Controlla il meteo ogni mattina alle 8 e crea una nota”
• “Esegui questo script ogni ora”
• “Ricordami di controllare la mia email tra 30 minuti”

Le attivita supportano espressioni cron (0 8 * * *) e intervalli semplici (30m, 1h, 2d). I risultati vengono consegnati a PocketHook quando interroga l’endpoint /jobs.

Due tipi di esecuzione:

• Shell — Esegue un comando bash, cattura l’output. Puo attivare un Comando Rapido al completamento
• Prompt — Elaborato dall’agente IA con accesso completo agli strumenti, memorizza la risposta completa di PocketHook

Server Dev

#

Quando l’agente crea un progetto web nel workspace (Hugo, Astro, Next.js, Flask, Go, ecc.), offre proattivamente di servirlo:

• Anteprima — Avvia un server dev locale su una porta auto-assegnata per una visualizzazione rapida
• Pubblico — Avvia il server e lo espone tramite tunnel HTTPS per renderlo accessibile ovunque

L’agente gestisce il ciclo di vita: avviare, fermare e elencare i server in esecuzione. Tutti i server vengono ripuliti quando il server principale si ferma.

Contratto di tunnel

#

Quando l’agente avvia un server con esposizione tramite tunnel richiesta, il runtime lo impone: se nessuno strumento di tunnel (Tailscale, ngrok, cloudflared) e installato, il server rifiuta di partire. Se la configurazione del tunnel fallisce dopo l’avvio, il processo orfano viene fermato e l’agente viene informato esplicitamente — cosi puo ripiegare sulla modalita anteprima o chiederti di installare un tunnel. L’URL restituito e sempre l’URL del tunnel quando il tunneling e attivo, con una nota che l’URL locale e riservato all’host.

Come rete di sicurezza, ogni strumento respond_* post-elabora il proprio messaggio: qualsiasi URL localhost o 127.0.0.1 che si insinua in una risposta viene riscritto automaticamente nell’URL di tunnel corrispondente quando un server gestito ne ha uno. Quando non puo riscriverlo, ricevi un avviso nei log invece di un link rotto sul tuo telefono.

Dashboard

#

La dashboard web integrata in /dashboard mostra una vista dal vivo delle attivita in background.

Non autenticata per design. Sia /dashboard che /api/jobs sono endpoint GET aperti — chiunque possa raggiungere l’host puo elencare le attivita. Limita l’accesso a livello di rete (ACL Tailscale, firewall, reverse proxy con autenticazione di base) o imposta DASHBOARD=false se non ne hai bisogno. L’app PocketHook per iOS non usa questi endpoint.

E completamente personalizzabile:

• Modifica rapida — Posiziona un dashboard.html in workspace/dashboard/ per personalizzazioni semplici
• Progetto completo — Crea un progetto con framework (Svelte, React, Vue, ecc.) in workspace/dashboard/ con output di build in dist/

Chiedi all’agente di personalizzare la tua dashboard e si occupera del resto — ogni utente ottiene una dashboard unica e personalizzata.

Strumenti Personalizzati

#

L’agente puo installare strumenti CLI e registrarli come nuove capacita — estendendo se stesso senza modificare il codice del server.

Per esempio, di’ “installa Playwright e usalo per fare screenshot”. L’agente:

1. Installera la dipendenza
2. Creera una definizione di strumento (un semplice file .md)
3. Usera il nuovo strumento nelle conversazioni future

Gli strumenti personalizzati vengono ricaricati a caldo — nessun riavvio necessario. Elimina il file .md per rimuovere uno strumento.

Versionamento

#

Tutti i dati dell’utente vengono versionati automaticamente:

• File del workspace — Tracciati con un repository git locale dentro workspace/. Ogni scrittura crea un auto-commit. Chiedi all’agente di “annullare l’ultima modifica” o usa git revert HEAD manualmente
• File di configurazione — config/agent-instructions.md, config/personality.md, skills/ e permissions.json vengono sottoposti a backup prima di ogni modifica. Fino a 20 versioni per file

Git e opzionale — se non e installato, le modifiche del workspace non vengono versionate. I backup di configurazione funzionano sempre.

Personalizzare il tuo agente

#

Il server agent arriva con una base framework minima e si aspetta che tu ci metta sopra le tue personalizzazioni. Il runtime tiene le due cose separate in modo che gli aggiornamenti del framework non distruggano mai il tuo lavoro.

Framework vs utente

#

pockethook-agent-server/
├── skills/                      # competenze fornite dal framework (sola lettura)
├── custom-tools/                # riservato agli strumenti forniti dal framework (sola lettura)
├── config/
│   ├── agent-instructions.md    # istruzioni dell'agente del framework (sola lettura)
│   └── personality.md           # personalita del framework (sola lettura)
└── data/user/                   # LE TUE personalizzazioni vivono qui (ignorato da git)
    ├── skills/                  # le tue competenze (sovrascrivono la base per nome file)
    ├── custom-tools/            # i tuoi strumenti personalizzati installati
    ├── instructions.md          # le tue aggiunte alle istruzioni dell'agente
    └── prefs.json               # valori tipizzati referenziati come {{prefs.key}}

La personalizzazione utente viene scritta tramite strumenti tipizzati dedicati (create_user_skill, create_custom_tool) cosi che i file risultanti corrispondano sempre al formato del loader. Lo strumento write rifiuta anche qualsiasi percorso sotto skills/, custom-tools/ o config/ e reindirizza l’agente a data/user/* — cosi anche le modifiche dirette ai file finiscono nel livello utente.

Nota sulla directory base custom-tools/. Oggi contiene solo un template (_example.md) che il loader ignora — ogni strumento che l’agente installa per te va in data/user/custom-tools/. La directory e riservata cosi le versioni future del framework possono rilasciare strumenti integrati opzionali senza disturbare le tue installazioni. Quando succedera, i tuoi file del livello utente vincono comunque in caso di collisione di nome strumento, quindi non c’e nulla da migrare.

Quattro modi per personalizzare

#

Non devi mai scrivere questi file a mano. Basta che dici all’agente cosa vuoi e lui sceglie automaticamente il livello giusto.

Preferenze tipizzate con {{prefs.*}}

#

Mettiamo che tu scriva una competenza di pianificatore di percorso che deve conoscere il tuo punto di partenza predefinito. Invece di incorporare “Madrid” nella competenza, referenzia la pref:

- **Punto di partenza**: {{prefs.routeOrigin}}, a meno che l'utente non specifichi un'origine diversa.

E memorizza il valore in data/user/prefs.json:

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

Il server sostituisce i segnaposto quando la competenza viene caricata. Anche le chiavi annidate ({{prefs.tunnel.domain}}) funzionano. Le chiavi sconosciute vengono lasciate intatte cosi gli errori di battitura restano visibili.

Modificare direttamente la base del framework

#

Se fai self-hosting e vuoi modificare il framework stesso, puoi editare config/agent-instructions.md, config/personality.md, skills/ o custom-tools/ direttamente — il server non te lo impedisce quando usi un editor di file. Ma l’agente non scrivera su quei percorsi da una conversazione. E gli aggiornamenti del framework sovrascriveranno le tue modifiche. Preferisci il livello utente per tutto cio che vuoi mantenere.

Estendere il Server

#

• Strumenti personalizzati — Chiedi all’agente di installare strumenti CLI; finiscono in data/user/custom-tools/ automaticamente
• Aggiungere competenze — Chiedi all’agente di creare una competenza; il file va in data/user/skills/
• Cambiare comportamento — Chiedi all’agente di applicare una regola globale; viene aggiunta a data/user/instructions.md
• Configurare permessi — Esegui bun run permissions per controllare quali strumenti l’agente puo usare
• Aggiungere strumenti integrati — Implementa nuove funzioni strumento in src/tools.ts per integrazioni piu profonde (richiede di forkare il server)

Configurazione

#

Tutte le impostazioni sono memorizzate in .env (creato da bun run setup). Opzioni principali:

Consulta il riferimento completo alla configurazione nel repository GitHub.

Eseguire come Servizio

#

Installa come servizio persistente che si avvia automaticamente:

bun run service install

INSTANCE_NAME per default e il basename della directory del progetto con il prefisso pockethook- rimosso (ad esempio, un checkout in pockethook-agent-server/ diventa agent-server). Impostalo esplicitamente per eseguire piu checkout sulla stessa macchina senza collisioni — ogni istanza mantiene il proprio data/ e i log.

Gestisci con bun run service status, restart, stop o uninstall.

Sicurezza

#

• HTTPS obbligatorio — PocketHook richiede HTTPS per tutti gli URL
• Autenticazione token Bearer — Segreto condiviso tra app e server
• Limitazione del tasso — Limiti per token prevengono abusi
• Strumenti in sandbox — Comandi shell e accesso ai file limitati dai permessi
• Pattern bloccati — Comandi pericolosi (sudo, rm -rf /) bloccati per impostazione predefinita
• Limite directory di lavoro — L’agente non puo uscire dalla directory designata
• File sensibili protetti — .env, .git, *.key, *.pem bloccati per l’agente
• Versionamento automatico — Tutte le modifiche del workspace sono tracciate con git per un facile ripristino