Servidor Agente

O que e o PocketHook Agent Server?

#

O servidor agente transforma o PocketHook num assistente de IA completo. Em vez de escrever a logica de resposta voce mesmo, liga um LLM (Claude, GPT, Gemini, etc.) que processa mensagens, chama ferramentas e devolve respostas estruturadas do PocketHook — incluindo acionamento de Shortcuts.

O servidor corre na sua propria maquina. Os seus dados ficam consigo.

Isto e um ponto de partida. O servidor vem com um conjunto base de ferramentas e foi concebido para ser estendido por si. Adicione as suas proprias integracoes — email, calendarios, documentos, APIs — e faca-o seu.

Funcionalidades

#

• LLM multi-fornecedor — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (local), LM Studio (local)
• Autenticacao OAuth — GitHub Copilot e OpenAI Codex via fluxo de codigo de dispositivo / navegador
• Ferramentas de agente — Comandos shell, leitura/escrita de ficheiros, listagem de diretorios, pesquisa web, web scraping, gestao de servidores dev
• Separacao framework / utilizador — Os ficheiros do framework (skills/, custom-tools/, config/) permanecem em modo so-leitura. As suas personalizacoes vivem em data/user/ (competencias, ferramentas personalizadas, instrucoes, prefs tipadas). As atualizacoes do framework sao aplicadas sem sobrescrever o seu trabalho
• Preferencias de utilizador tipadas — Guarde valores como a sua app de mapas preferida ou o seu dominio de tunel em data/user/prefs.json. Referencie-os nas competencias como {{prefs.key}} e o servidor substitui-os ao carregar
• Tarefas de programacao numa so chamada — A meta-ferramenta run_code_job cria uma tarefa em segundo plano do tipo prompt (executada pelo seu LLM configurado) e envia ao utilizador a confirmacao num unico passo, substituindo o fragil padrao “respond + create-job”
• Ferramentas de protocolo tipadas — Seis ferramentas respond_* dedicadas (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), mais ferramentas tipadas para tarefas (create_once_job, create_cron_job) e ferramentas tipadas para o workspace (create_project, list_projects, delete_project). Os esquemas rejeitam URLs malformados, sintaxe de botoes e combinacoes type/schedule antes que cheguem ao dispositivo
• Escritores tipados para personalizacao — create_user_skill e create_custom_tool constroem o markdown da camada de utilizador com o frontmatter correto, para que o loader os analise sempre e o agente nunca escreva estes ficheiros a mao
• Tarefas em segundo plano — Tarefas unicas ou recorrentes com expressoes cron ou intervalos simples
• Competencias dinamicas — Defina atalhos e regras de comportamento como ficheiros .md. Apenas um indice compacto e carregado no prompt; o conteudo completo e obtido sob demanda via a ferramenta load_skill
• Competencias autogeridas — O agente pode criar, editar e eliminar definicoes de competencias (as escritas aterram sempre na camada de utilizador)
• Memoria semantica — Pesquisa baseada em vetores com embeddings (Ollama, LM Studio ou OpenAI). As memorias sao auto-classificadas em dimensoes de wing/room/hall/status pelo LLM
• Grafo de conhecimento — Armazenamento de triplas temporais para factos duraveis com auto-invalidacao. Relacionamentos multi-valor coexistem; factos de valor unico sao substituidos automaticamente
• Metodo PARA com cascata de fecho de projeto — Cada memoria e marcada com um estado (Projeto, Area, Recurso, Arquivo). Quando um projeto termina, uma unica chamada a complete_project arquiva os seus vetores, invalida todas as triplas de planeamento ligadas ao seu slug e regista a conclusao — uma chamada em vez de tres
• Recuperacao hibrida — Combina pesquisa por palavras-chave FTS5 com pesquisa semantica por vetores usando fusao de classificacao reciproca
• Memoria de longo prazo — SQLite + pesquisa de texto completo FTS5 como alternativa quando a memoria semantica esta desativada
• Gestao de servidores dev com contrato de tunel — Inicie, pare e liste servidores dev. Quando se pede tunnel: true, o servidor impoe-no tanto na verificacao previa como apos o arranque — um servidor localhost inacessivel nunca fica a correr em silencio
• Saneamento automatico de URLs — Se o agente deixar um URL localhost numa resposta, as ferramentas respond_* reescrevem-no para o URL de tunel correspondente, para que o seu telefone receba sempre um link acessivel
• Ferramentas personalizadas — O agente pode instalar ferramentas CLI e registra-las como novas capacidades
• Versionamento — Versionamento git automatico para ficheiros do workspace; copias de seguranca de configuracao para competencias e permissoes
• Painel web — Vista ao vivo de tarefas em segundo plano, personalizavel por utilizador. /dashboard e /api/jobs nao estao autenticados por desenho — restrinja o acesso na camada de rede (ACL do Tailscale, firewall, proxy inverso com autenticacao basica) ou defina DASHBOARD=false se nao precisar
• Tuneis HTTPS — Suporte integrado para Tailscale, ngrok e Cloudflare Tunnel
• Servico do sistema — Instale como servico persistente no macOS, Linux ou Windows
• Limitacao de taxa — Limites de pedidos por token com limiares configuraveis

Requisitos

#

• Runtime Bun
• Uma chave de API ou credenciais OAuth para o seu fornecedor LLM
• (Opcional) Tailscale, ngrok ou cloudflared para tuneis HTTPS

Inicio Rapido

#

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

# Configuracao interativa — escolha fornecedor, modelo, token de auth, porta
bun run setup

# Iniciar servidor + tunel HTTPS
bun run dev:tunnel

O assistente de configuracao ira guia-lo na escolha de um fornecedor LLM, configuracao da autenticacao e definicao das permissoes de ferramentas.

Uma vez a correr, copie os URLs apresentados nas Definicoes do PocketHook:

Como Funciona

#

1. Envia uma mensagem no PocketHook
2. O servidor encaminha-a para o seu LLM escolhido com o historico de conversa, memorias recuperadas e ferramentas disponiveis
3. O LLM processa a mensagem — pode executar comandos shell, ler/escrever ficheiros, pesquisar na web, agendar tarefas em segundo plano, memorizar factos ou iniciar servidores dev
4. A resposta e devolvida no formato PocketHook (msg + shortcut + data + url)
5. O PocketHook apresenta a mensagem e executa quaisquer Shortcuts no seu dispositivo

Fornecedores LLM Suportados

#

Mude de fornecedor a qualquer momento com bun run switch. Ollama e LM Studio correm inteiramente na sua maquina — sem chave de API, sem dados a sair da sua rede.

Memoria

#

O sistema de memoria tem tres camadas, cada uma com um proposito diferente.

O design da memoria semantica combina ideias do MemPalace (uma arquitetura de palacio de memoria que organiza memorias em alas, corredores e salas) e o metodo PARA de Tiago Forte (Projetos, Areas, Recursos, Arquivo) para gestao do ciclo de vida do conhecimento.

Memoria de conversa

#

SQLite com pesquisa de texto completo FTS5. Todas as mensagens sao armazenadas com timestamps e IDs de sessao.

• Curto prazo — As ultimas MAX_HISTORY mensagens sao mantidas em memoria por sessao
• Longo prazo — Todas as mensagens persistem no SQLite, pesquisaveis via correspondencia de palavras-chave FTS5
• Recuperacao por turno — Quando a memoria semantica esta ativa, MAX_RECALL controla quantas memorias relevantes sao injetadas no prompt em cada turno
• As sessoes expiram apos SESSION_TTL_MINUTES, mas a memoria de longo prazo persiste para sempre

Ajuste isto de forma interativa com bun run memory.

Memoria semantica

#

Requer VECTOR_MEMORY=true e um fornecedor de embeddings (Ollama, LM Studio ou OpenAI).

Cada memoria e convertida num vetor e auto-classificada pelo LLM em quatro dimensoes:

• Wing — A entidade: user, person:john, project:blog, place:london
• Room — O tipo: facts, preferences, events, decisions, requests
• Hall — O topico: personal, tech, health, travel, food, work
• Status — Classificacao PARA: project, area, resource, archive

Quando faz uma pergunta, a extracao de entidades foca a pesquisa vetorial nos wings mais relevantes. Os resultados sao fundidos com os resultados de palavras-chave FTS5 usando fusao de classificacao reciproca — para obter o melhor de ambos, correspondencia por palavras-chave e semantica.

Grafo de conhecimento

#

Um armazenamento de triplas temporais para factos estruturados e duraveis:

• Triplas: (sujeito, predicado, objeto) com timestamps valid_from / valid_until
• Predicados de valor unico (lives_in, partner) auto-invalidam o valor anterior ao atualizar
• Predicados de multi-valor (child, friend, hobby) coexistem sem invalidacao
• Factos do grafo de conhecimento sao injetados juntamente com as memorias recuperadas em cada conversa

Quando diz ao agente “Mudei-me para Berlim”, ele invalida a tripla antiga de lives_in e cria uma nova — automaticamente.

Ciclo de vida PARA

#

Cada memoria e marcada com um estado PARA:

• Projeto — Trabalho ativo com prazo definido
• Area — Responsabilidades continuadas
• Recurso — Material de referencia (listas, recomendacoes, tutoriais)
• Arquivo — Projetos concluidos ou cancelados

Quando um projeto e concluido, o agente usa similaridade semantica para arquivar apenas as memorias desse projeto enquanto preserva o material de referencia para uso futuro.

Cascata de fecho de projeto

#

Diga “vou cancelar a minha viagem a Barcelona” e uma unica chamada de ferramenta trata de tudo:

1. Arquiva os vetores do projeto (eventos, decisoes e pedidos ligados a Barcelona).
2. Invalida todas as triplas ativas do grafo de conhecimento cujo predicado corresponda ao slug do projeto (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Regista a conclusao como uma nova tripla: (user, "cancelled_visit_barcelona", "2026-04-15").

A correspondencia respeita os limites de palavra — um projeto diferente chamado revisit_barcelona fica intacto. O agente ja nao tem de orquestrar tres chamadas separadas pela ordem correta, por isso os modelos mais pequenos tambem acertam.

Se VECTOR_MEMORY esta desativado ou o fornecedor de embeddings esta inacessivel, o sistema recorre a apenas FTS5 sem erros.

Competencias

#

As competencias sao ficheiros .md em skills/ que definem Shortcuts do iOS que o agente pode acionar e/ou regras de comportamento. Usam carregamento dinamico: apenas um indice compacto (titulo, descricao, lista de atalhos) e injetado no prompt do sistema. O agente carrega o conteudo completo sob demanda via a ferramenta load_skill, mantendo o uso de tokens baixo a medida que adiciona mais competencias.

Cada ficheiro de competencia usa 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

Campos do frontmatter

#

As competencias tambem podem ser regras de comportamento sem atalhos (por exemplo, “como planear uma viagem em familia”). Use shortcuts: [] para estas.

O agente pode criar e gerir competencias quando solicitado — peca-lhe para “criar uma competencia para controlar as minhas luzes” e ele escrevera o ficheiro .md por si. As competencias novas e editadas aterram sempre na sua camada de utilizador (data/user/skills/), para que as atualizacoes do framework nunca as sobrescrevam. Consulte a seccao Personalizar o seu agente mais abaixo.

Executar atalhos no servidor Mac

#

Quando uma competencia tem target: mac, os atalhos sao executados silenciosamente no servidor Mac atraves da CLI shortcuts run em vez de serem enviados para o dispositivo iOS. Isto e ideal para accoes que criam conteudo sincronizado por iCloud — notas, lembretes, eventos de calendario — porque o resultado sincroniza automaticamente em todos os seus dispositivos sem que a app PocketHook tenha de fazer nada.

Como funciona:

1. O agente decide que um atalho deve ser executado (por exemplo, “cria uma nota com os apontamentos da reuniao de hoje”)
2. O servidor invoca shortcuts run "shortcutName" com os dados passados como JSON via stdin, usando o mesmo formato de encapsulamento que o PocketHook iOS usa
3. Se sync_app estiver definido, o servidor abre brevemente essa app em segundo plano (open -gj -a Notes) para forcar a sincronizacao do iCloud, e fecha-a apos 5 segundos
4. O utilizador recebe uma mensagem de confirmacao no chat; o atalho em si nao e enviado para o dispositivo

Requisitos:

• O servidor tem de estar a correr em macOS — shortcuts run e exclusivo do macOS. Em outras plataformas, o servidor regista um aviso e recai para a execucao no dispositivo
• O atalho tem de estar instalado na Shortcuts.app no Mac do servidor
• O atalho deve esperar um Dicionario como entrada (PocketHook encapsula os dados em { context, timestamp, app, data })

Quando usar target: mac:

• Accoes sincronizadas por iCloud (Notas, Lembretes, Calendario) — o resultado chega a todos os dispositivos de qualquer forma
• Processamentos demorados que queira manter fora do dispositivo iOS
• Qualquer atalho que nao precise de interagir com a interface do iPhone

Quando manter target: device (predefinicao):

• Atalhos que necessitam de funcionalidades exclusivas do iPhone (camara, localizacao precisa, automacoes locais de apps)
• Atalhos que pedem entrada interactiva ao utilizador
• Atalhos que usam App Intents de apps exclusivas de iOS

Tarefas em Segundo Plano

#

Peca ao agente para agendar tarefas e ele tratara do resto:

• “Verifica o tempo todas as manhas as 8h e cria uma nota”
• “Executa este script a cada hora”
• “Lembra-me de verificar o meu email em 30 minutos”

As tarefas suportam expressoes cron (0 8 * * *) e intervalos simples (30m, 1h, 2d). Os resultados sao entregues ao PocketHook quando consulta o endpoint /jobs.

Dois tipos de execucao:

• Shell — Executa um comando bash, captura a saida. Pode acionar um Shortcut ao completar
• Prompt — Processado pelo agente de IA com acesso completo a ferramentas, armazena a resposta completa do PocketHook

Servidores Dev

#

Quando o agente cria um projeto web no workspace (Hugo, Astro, Next.js, Flask, Go, etc.), oferece proativamente servi-lo:

• Pre-visualizacao — Inicia um servidor dev local numa porta auto-atribuida para visualizacao rapida
• Publico — Inicia o servidor e expoe-no via tunel HTTPS para que seja acessivel de qualquer lugar

O agente gere o ciclo de vida: iniciar, parar e listar servidores em execucao. Todos os servidores sao limpos quando o servidor principal para.

Contrato de tunel

#

Quando o agente arranca um servidor pedindo exposicao por tunel, o runtime impoe-no: se nao houver nenhuma ferramenta de tunel instalada (Tailscale, ngrok, cloudflared), o servidor recusa-se a arrancar. Se a configuracao do tunel falhar apos o spawn, o processo orfao e parado e o agente e informado de forma explicita — para que possa recorrer ao modo pre-visualizacao ou pedir-lhe que instale um tunel. O URL devolvido e sempre o URL do tunel quando a tunelizacao esta ativa, com uma nota de que o URL local e apenas do host.

Como rede de seguranca, cada ferramenta respond_* pos-processa a sua mensagem: qualquer URL de localhost ou 127.0.0.1 que se infiltre numa resposta e reescrito automaticamente para o URL de tunel correspondente quando um servidor gerido o tem. Quando nao consegue reescreve-lo, recebe um aviso nos logs em vez de um link partido no seu telefone.

Painel

#

O painel web integrado em /dashboard mostra uma vista ao vivo das tarefas em segundo plano.

Nao autenticado por desenho. Tanto /dashboard como /api/jobs sao endpoints GET abertos — qualquer pessoa que consiga aceder ao host pode listar tarefas. Restrinja o acesso na camada de rede (ACL do Tailscale, firewall, proxy inverso com autenticacao basica) ou defina DASHBOARD=false se nao precisar. A app PocketHook para iOS nao usa estes endpoints.

E totalmente personalizavel:

• Edicao rapida — Coloque um dashboard.html em workspace/dashboard/ para personalizacoes simples
• Projeto completo — Crie um projeto com framework (Svelte, React, Vue, etc.) em workspace/dashboard/ com saida de build para dist/

Peca ao agente para personalizar o seu painel e ele tratara do resto — cada utilizador recebe um painel unico e personalizado.

Ferramentas Personalizadas

#

O agente pode instalar ferramentas CLI e registra-las como novas capacidades — estendendo-se a si mesmo sem modificar o codigo do servidor.

Por exemplo, diga “instala o Playwright e usa-o para tirar capturas de ecra”. O agente:

1. Instalara a dependencia
2. Criara uma definicao de ferramenta (um simples ficheiro .md)
3. Usara a nova ferramenta em conversas futuras

Ferramentas personalizadas sao recarregadas a quente — sem necessidade de reiniciar. Elimine o ficheiro .md para remover uma ferramenta.

Versionamento

#

Todos os dados do utilizador sao versionados automaticamente:

• Ficheiros do workspace — Rastreados com um repositorio git local dentro de workspace/. Cada escrita cria um auto-commit. Peca ao agente para “desfazer a ultima alteracao” ou use git revert HEAD manualmente
• Ficheiros de configuracao — config/agent-instructions.md, config/personality.md, skills/ e permissions.json sao copiados de seguranca antes de cada modificacao. Ate 20 versoes por ficheiro

Git e opcional — se nao estiver instalado, as alteracoes do workspace nao sao versionadas. Copias de seguranca de configuracao funcionam sempre.

Personalizar o seu agente

#

O servidor agent vem com uma base minima do framework e espera que aplique a sua personalizacao por cima. O runtime mantem os dois separados para que as atualizacoes do framework nunca esmaguem o seu trabalho.

Framework vs. utilizador

#

pockethook-agent-server/
├── skills/                      # competencias do framework (so leitura)
├── custom-tools/                # reservado para ferramentas do framework (so leitura)
├── config/
│   ├── agent-instructions.md    # instrucoes do agente do framework (so leitura)
│   └── personality.md           # personalidade do framework (so leitura)
└── data/user/                   # A SUA personalizacao vive aqui (ignorado pelo git)
    ├── skills/                  # as suas proprias competencias (prevalecem por nome de ficheiro)
    ├── custom-tools/            # as suas ferramentas personalizadas instaladas
    ├── instructions.md          # as suas adicoes as instrucoes do agente
    └── prefs.json               # valores tipados referenciados como {{prefs.key}}

A personalizacao do utilizador e escrita atraves de ferramentas tipadas dedicadas (create_user_skill, create_custom_tool) para que os ficheiros resultantes correspondam sempre ao formato do loader. A ferramenta write tambem rejeita qualquer caminho sob skills/, custom-tools/ ou config/ e redireciona o agente para data/user/* — assim, ate as edicoes diretas de ficheiros aterram na camada de utilizador.

Nota sobre o diretorio base custom-tools/. Hoje so contem um modelo (_example.md) que o loader ignora — cada ferramenta que o agente instala por si vai para data/user/custom-tools/. O diretorio fica reservado para que futuras versoes do framework possam trazer ferramentas integradas opcionais sem pisar as suas instalacoes. Quando isso acontecer, os seus ficheiros da camada de utilizador continuam a ganhar em caso de colisao por nome de ferramenta, por isso nao ha nada a migrar.

Quatro formas de personalizar

#

Nao precisa de escrever estes ficheiros a mao. Basta dizer ao agente o que quer e ele escolhe a camada certa automaticamente.

Preferencias tipadas com {{prefs.*}}

#

Imagine que escreve uma competencia planeadora de rotas que precisa de saber o seu ponto de partida por omissao. Em vez de incluir “Lisboa” diretamente na competencia, referencie a pref:

- **Ponto de partida**: {{prefs.routeOrigin}}, a menos que o utilizador especifique uma origem diferente.

E guarde o valor em data/user/prefs.json:

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

O servidor substitui os marcadores quando a competencia e carregada. As chaves aninhadas ({{prefs.tunnel.domain}}) tambem funcionam. As chaves desconhecidas ficam intactas para que as gralhas continuem visiveis.

Editar diretamente a base do framework

#

Se se auto-hospeda e quer afinar o proprio framework, pode editar config/agent-instructions.md, config/personality.md, skills/ ou custom-tools/ diretamente — o servidor nao o impede quando usa um editor de ficheiros. Mas o agente nao escrevera nesses caminhos a partir de uma conversa. E as atualizacoes do framework vao sobrescrever as suas edicoes. Prefira a camada de utilizador para tudo o que quiser preservar.

Estender o Servidor

#

• Ferramentas personalizadas — Peca ao agente para instalar ferramentas CLI; aterram automaticamente em data/user/custom-tools/
• Adicionar competencias — Peca ao agente para criar uma competencia; o ficheiro vai para data/user/skills/
• Alterar comportamento — Peca ao agente para aplicar uma regra global; e acrescentada a data/user/instructions.md
• Configurar permissoes — Execute bun run permissions para controlar quais ferramentas o agente pode usar
• Adicionar ferramentas integradas — Implemente novas funcoes de ferramentas em src/tools.ts para integracoes mais profundas (requer fazer fork do servidor)

Configuracao

#

Todas as definicoes sao armazenadas em .env (criado por bun run setup). Opcoes principais:

Consulte a referencia completa de configuracao no repositorio do GitHub.

Executar como Servico

#

Instale como um servico persistente que inicia automaticamente:

bun run service install

INSTANCE_NAME por omissao e o basename do diretorio do projeto com o prefixo pockethook- removido (por exemplo, um checkout em pockethook-agent-server/ torna-se agent-server). Defina-o explicitamente para executar varios checkouts na mesma maquina sem colisoes — cada instancia mantem o seu proprio data/ e logs.

Faca a gestao com bun run service status, restart, stop ou uninstall.

Seguranca

#

• HTTPS obrigatorio — O PocketHook exige HTTPS para todos os URLs
• Autenticacao por token Bearer — Segredo partilhado entre a app e o servidor
• Limitacao de taxa — Limites por token previnem abusos
• Ferramentas em sandbox — Comandos shell e acesso a ficheiros restritos por permissoes
• Padroes bloqueados — Comandos perigosos (sudo, rm -rf /) bloqueados por defeito
• Limite de diretorio de trabalho — O agente nao pode escapar do seu diretorio designado
• Ficheiros sensiveis protegidos — .env, .git, *.key, *.pem bloqueados para o agente
• Versionamento automatico — Todas as alteracoes do workspace sao rastreadas com git para facil reversao