Servidor Agente

O que é o PocketHook Agent Server?

#

O servidor agente transforma o PocketHook em um assistente de IA completo. Em vez de escrever a lógica de resposta você mesmo, você conecta um LLM (Claude, GPT, Gemini, etc.) que processa mensagens, chama ferramentas e retorna respostas estruturadas do PocketHook — incluindo acionamento de Shortcuts.

O servidor roda na sua própria máquina. Seus dados ficam com você.

Isso é um ponto de partida. O servidor vem com um conjunto base de ferramentas e foi projetado para ser estendido por você. Adicione suas próprias integrações — email, calendários, documentos, APIs — e faça-o seu.

Recursos

#

• LLM multi-provedor — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (local), LM Studio (local)
• Modelo rápido — Execute um segundo modelo leve para tarefas internas (classificação de memória, extração de entidades) junto ao seu modelo principal de chat — controle total sobre custo e latência
• Extensão do Safari — Emparelhe uma extensão de Safari para macOS notarizada para que o agente possa abrir abas, inspecionar páginas, clicar, preencher formulários e capturar screenshots na sua sessão real de navegador, no nível de permissão que você escolher
• Autenticação OAuth — GitHub Copilot e OpenAI Codex via fluxo de código de dispositivo / navegador
• Ferramentas de agente — Comandos shell, leitura/escrita de arquivos, listagem de diretórios, busca web, web scraping, gerenciamento de servidores dev
• Divisão framework / usuário — Os arquivos do framework (skills/, custom-tools/, config/) permanecem somente leitura. Suas personalizações ficam em data/user/ (skills, ferramentas personalizadas, instruções, prefs tipadas). Atualizações do framework são aplicadas sem sobrescrever seu trabalho
• Prefs de usuário tipadas — Armazene valores como seu app de mapas preferido ou domínio de túnel em data/user/prefs.json. Referencie-os nos skills como {{prefs.key}} e o servidor fará a substituição no carregamento
• Tarefas de programação em uma só chamada — A meta-ferramenta run_code_job cria uma tarefa em segundo plano do tipo prompt (executada pelo seu LLM configurado) e envia o aviso ao usuário em um único passo, substituindo o padrão propenso a erros “respond + create-job”
• Ferramentas de protocolo tipadas — Seis ferramentas respond_* dedicadas (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), além de 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 malformadas, sintaxe de botões e combinações type/schedule antes que cheguem ao dispositivo
• Escritores tipados para personalização — create_user_skill e create_custom_tool constroem o markdown da camada de usuário com o frontmatter correto, para que o loader sempre os analise e o agente nunca escreva esses arquivos à mão
• Tarefas em segundo plano — Tarefas únicas ou recorrentes com expressões cron ou intervalos simples
• Skills dinâmicos — Defina atalhos e regras de comportamento como arquivos .md. Apenas um índice compacto é carregado no prompt; o conteúdo completo é obtido sob demanda via a ferramenta load_skill
• Skills autogerenciados — O agente pode criar, editar e excluir definições de skills (as escritas sempre acontecem na camada do usuário)
• Memória semântica — Busca baseada em vetores com embeddings (Ollama, LM Studio ou OpenAI). As memórias são auto-classificadas em dimensões de wing/room/hall/status pelo LLM
• Grafo de conhecimento — Armazenamento de triplas temporais para fatos duráveis com auto-invalidação. Relacionamentos multi-valor coexistem; fatos de valor único são substituídos automaticamente
• Método PARA com cascata de fim de projeto — Cada memória é marcada com um status (Projeto, Área, Recurso, Arquivo). Quando um projeto termina, uma única chamada complete_project arquiva seus vetores, invalida cada tripla de planejamento ligada ao seu slug e registra a conclusão — uma chamada em vez de três
• Recuperação híbrida — Combina busca por palavras-chave FTS5 com busca semântica por vetores usando fusão de classificação recíproca
• Memória de longo prazo — SQLite + busca de texto completo FTS5 como fallback quando a memória semântica está desabilitada
• Gerenciamento de servidores dev com contrato de túnel — Inicie, pare e liste servidores dev. Quando tunnel: true é solicitado, o servidor impõe isso antes e depois da inicialização — um servidor localhost inalcançável nunca fica rodando silenciosamente
• Sanitização automática de URL — Se o agente deixar uma URL localhost em uma resposta, as ferramentas respond_* a reescrevem para a URL de túnel correspondente para que seu telefone sempre receba um link acessível
• Ferramentas personalizadas — O agente pode instalar ferramentas CLI e registrá-las como novas capacidades
• Versionamento — Versionamento git automático para arquivos do workspace; backups de configuração para skills e permissões
• Dashboard web — Visão ao vivo de tarefas em segundo plano, personalizável por usuário. /dashboard e /api/jobs não são autenticados por design — restrinja o acesso na camada de rede (ACL do Tailscale, firewall, proxy reverso com autenticação básica) ou defina DASHBOARD=false se não precisar
• Túneis HTTPS — Suporte integrado para Tailscale, ngrok e Cloudflare Tunnel
• Serviço do sistema — Instale como serviço persistente no macOS, Linux ou Windows
• Limitação de taxa — Limites de requisições por token com limiares configuráveis

Requisitos

#

• Runtime Bun
• Uma chave de API ou credenciais OAuth para seu provedor LLM
• (Opcional) Tailscale, ngrok ou cloudflared para túneis HTTPS

Início Rápido

#

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

# Configuração interativa — escolha provedor, modelo, token de auth, porta
bun run setup

# Iniciar servidor + túnel HTTPS
bun run dev:tunnel

O assistente de configuração vai guiá-lo na escolha de um provedor LLM, configuração da autenticação e definição das permissões de ferramentas — incluindo se deseja instalar a extensão do Safari (opcional, pode ser pulada, apenas macOS).

Execute bun run help a qualquer momento para ver a lista completa de comandos, ou bun run config para ver sua configuração atual rapidamente (com os segredos ocultos).

Uma vez rodando, copie as URLs exibidas nas Configurações do PocketHook:

Como Funciona

#

1. Você envia uma mensagem no PocketHook
2. O servidor a encaminha para seu LLM escolhido com o histórico de conversa, memórias recuperadas e ferramentas disponíveis
3. O LLM processa a mensagem — pode executar comandos shell, ler/escrever arquivos, buscar na web, agendar tarefas em segundo plano, lembrar fatos ou iniciar servidores dev
4. A resposta é retornada no formato PocketHook (msg + shortcut + data + url)
5. O PocketHook exibe a mensagem e executa quaisquer Shortcuts no seu dispositivo

Provedores LLM Suportados

#

Troque de provedor a qualquer momento com bun run switch. Ollama e LM Studio rodam inteiramente na sua máquina — sem chave de API, sem dados saindo da sua rede.

Memória

#

O sistema de memória tem três camadas, cada uma com um propósito diferente.

O design da memória semântica combina ideias do MemPalace (uma arquitetura de palácio de memória que organiza memórias em alas, corredores e salas) e o método PARA de Tiago Forte (Projetos, Áreas, Recursos, Arquivo) para gestão do ciclo de vida do conhecimento.

Memória de conversa

#

SQLite com busca de texto completo FTS5. Todas as mensagens são armazenadas com timestamps e IDs de sessão.

• Curto prazo — As últimas MAX_HISTORY mensagens são mantidas em memória por sessão
• Longo prazo — Todas as mensagens persistem no SQLite, pesquisáveis via correspondência de palavras-chave FTS5
• Recuperação por turno — Quando a memória semântica está ativa, MAX_RECALL controla quantas memórias relevantes são injetadas no prompt a cada turno
• Sessões expiram após SESSION_TTL_MINUTES, mas a memória de longo prazo persiste para sempre

Ajuste isso de forma interativa com bun run memory.

Memória semântica

#

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

Cada memória é convertida em um vetor e auto-classificada pelo LLM em quatro dimensões:

• Wing — A entidade: user, person:john, project:blog, place:london
• Room — O tipo: facts, preferences, events, decisions, requests
• Hall — O tópico: personal, tech, health, travel, food, work
• Status — Classificação PARA: project, area, resource, archive

Quando você faz uma pergunta, a extração de entidades foca a busca vetorial nos wings mais relevantes. Os resultados são mesclados com os resultados de palavras-chave FTS5 usando fusão de classificação recíproca — para obter o melhor de ambos, correspondência por palavras-chave e semântica.

Grafo de conhecimento

#

Um armazenamento de triplas temporais para fatos estruturados e duráveis:

• Triplas: (sujeito, predicado, objeto) com timestamps valid_from / valid_until
• Predicados de valor único (lives_in, partner) auto-invalidam o valor anterior ao atualizar
• Predicados de multi-valor (child, friend, hobby) coexistem sem invalidação
• Fatos do grafo de conhecimento são injetados junto com as memórias recuperadas em cada conversa

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

Ciclo de vida PARA

#

Cada memória é marcada com um status PARA:

• Projeto — Trabalho ativo com prazo definido
• Área — Responsabilidades contínuas
• Recurso — Material de referência (listas, recomendações, tutoriais)
• Arquivo — Projetos concluídos ou cancelados

Quando um projeto é concluído, o agente usa similaridade semântica para arquivar apenas as memórias daquele projeto enquanto preserva o material de referência para uso futuro.

Cascata de fim de projeto

#

Diga “Estou cancelando minha viagem a Barcelona” e uma única chamada de ferramenta cuida de tudo:

1. Arquiva os vetores do projeto (eventos, decisões, pedidos ligados a Barcelona).
2. Invalida cada tripla ativa do grafo de conhecimento cujo predicado corresponda ao slug do projeto (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Registra a conclusão como uma nova tripla: (user, "cancelled_visit_barcelona", "2026-04-15").

A correspondência respeita limites — um projeto diferente chamado revisit_barcelona fica intacto. O agente não precisa mais orquestrar três chamadas separadas na ordem certa, então modelos menores também acertam.

Se VECTOR_MEMORY está desabilitado ou o provedor de embeddings está inacessível, o sistema recorre a apenas FTS5 sem erros.

Skills

#

Skills são arquivos .md em skills/ que definem Shortcuts do iOS que o agente pode acionar e/ou regras de comportamento. Eles usam carregamento dinâmico: apenas um índice compacto (título, descrição, lista de atalhos) é injetado no prompt do sistema. O agente carrega o conteúdo completo sob demanda via a ferramenta load_skill, mantendo o uso de tokens baixo à medida que você adiciona mais skills.

Cada arquivo de skill 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

#

Skills também podem ser regras de comportamento sem atalhos (por exemplo, “como planejar uma viagem em família”). Use shortcuts: [] para esses.

O agente pode criar e gerenciar skills quando solicitado — peça para ele “criar um skill para controlar minhas luzes” e ele escreverá o arquivo .md para você. Skills novos ou editados sempre ficam na sua camada de usuário (data/user/skills/), então atualizações do framework nunca os sobrescrevem. Veja a seção Personalizando seu agente abaixo.

Executando atalhos no servidor Mac

#

Quando um skill tem target: mac, os atalhos rodam silenciosamente no servidor Mac via a CLI shortcuts run em vez de serem enviados ao dispositivo iOS. Isso é ideal para ações que criam conteúdo sincronizado pelo iCloud — notas, lembretes, eventos de calendário — porque o resultado sincroniza automaticamente em todos os seus dispositivos sem precisar que o app PocketHook faça nada.

Como funciona:

1. O agente decide que um atalho deve rodar (por exemplo, “crie uma nota com os apontamentos da reunião de hoje”)
2. O servidor invoca shortcuts run "shortcutName" com os dados passados como JSON via stdin, usando o mesmo formato wrapper que o PocketHook iOS usa
3. Se sync_app estiver configurado, o servidor abre brevemente esse app em segundo plano (open -gj -a Notes) para forçar a sincronização do iCloud e o fecha após 5 segundos
4. O usuário recebe uma mensagem de confirmação no chat; o atalho em si não é enviado ao dispositivo

Requisitos:

• O servidor deve estar rodando em macOS — shortcuts run é exclusivo do macOS. Em outras plataformas, o servidor registra um aviso e recai para execução no dispositivo
• O atalho precisa estar instalado no Shortcuts.app no Mac servidor
• O atalho deve esperar um Dicionário como entrada (PocketHook encapsula os dados em { context, timestamp, app, data })

Quando usar target: mac:

• Ações sincronizadas pelo iCloud (Notas, Lembretes, Calendário) — o resultado chega a todos os dispositivos de qualquer jeito
• Processamentos longos que você quer manter fora do dispositivo iOS
• Qualquer atalho que não precise interagir com a UI do iPhone

Quando manter target: device (padrão):

• Atalhos que precisam de recursos exclusivos do iPhone (câmera, localização precisa, automações locais de apps)
• Atalhos que pedem entrada interativa do usuário
• Atalhos que usam App Intents de apps exclusivos do iOS

Tarefas em Segundo Plano

#

Peça ao agente para agendar tarefas e ele cuidará do resto:

• “Verifique o clima toda manhã às 8h e crie uma nota”
• “Execute este script a cada hora”
• “Me lembre de verificar meu email em 30 minutos”

As tarefas suportam expressões cron (0 8 * * *) e intervalos simples (30m, 1h, 2d). Os resultados são entregues ao PocketHook quando ele consulta o endpoint /jobs.

Dois tipos de execução:

• Shell — Executa um comando bash, captura a saída. 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.), ele proativamente oferece servi-lo:

• Preview — Inicia um servidor dev local em uma porta auto-atribuída para visualização rápida
• Público — Inicia o servidor e o expõe via túnel HTTPS para que seja acessível de qualquer lugar

O agente gerencia o ciclo de vida: iniciar, parar e listar servidores em execução. Todos os servidores são limpos quando o servidor principal para.

Contrato de túnel

#

Quando o agente inicia um servidor com exposição por túnel solicitada, o runtime impõe isso: se nenhuma ferramenta de túnel (Tailscale, ngrok, cloudflared) estiver instalada, o servidor se recusa a iniciar. Se a configuração do túnel falhar após a inicialização, o processo órfão é finalizado e o agente é informado explicitamente — para que ele possa recorrer ao modo preview ou pedir que você instale um túnel. A URL retornada é sempre a URL do túnel quando o tunneling está ativo, com uma nota dizendo que a URL local é apenas para o host.

Como rede de segurança, cada ferramenta respond_* pós-processa sua mensagem: qualquer URL localhost ou 127.0.0.1 que escape para uma resposta é reescrita para a URL de túnel correspondente automaticamente quando um servidor gerenciado tem uma. Quando não consegue reescrever, você recebe um aviso nos logs em vez de um link quebrado no seu telefone.

Dashboard

#

O dashboard web integrado em /dashboard mostra uma visão ao vivo das tarefas em segundo plano.

Não autenticado por design. Tanto /dashboard quanto /api/jobs são endpoints GET abertos — qualquer um que consiga alcançar o host pode listar tarefas. Restrinja o acesso na camada de rede (ACL do Tailscale, firewall, proxy reverso com autenticação básica) ou defina DASHBOARD=false se não precisar. O app PocketHook para iOS não usa esses endpoints.

É totalmente personalizável:

• Edição rápida — Coloque um dashboard.html em workspace/dashboard/ para personalizações simples
• Projeto completo — Crie um projeto com framework (Svelte, React, Vue, etc.) em workspace/dashboard/ com saída de build para dist/

Peça ao agente para personalizar seu dashboard e ele cuidará do resto — cada usuário recebe um dashboard único e personalizado.

Ferramentas Personalizadas

#

O agente pode instalar ferramentas CLI e registrá-las como novas capacidades — estendendo a si mesmo sem modificar o código do servidor.

Por exemplo, diga “instale o Playwright e use para tirar capturas de tela”. O agente:

1. Instalará a dependência
2. Criará uma definição de ferramenta (um simples arquivo .md)
3. Usará a nova ferramenta em conversas futuras

Ferramentas personalizadas são recarregadas a quente — sem necessidade de reiniciar. Exclua o arquivo .md para remover uma ferramenta.

Versionamento

#

Todos os dados do usuário são versionados automaticamente:

• Arquivos do workspace — Rastreados com um repositório git local dentro de workspace/. Cada escrita cria um auto-commit. Peça ao agente para “desfazer a última alteração” ou use git revert HEAD manualmente
• Arquivos de configuração — config/agent-instructions.md, config/personality.md, skills/ e permissions.json são copiados antes de cada modificação. Até 20 versões por arquivo

Git é opcional — se não estiver instalado, as alterações do workspace não são versionadas. Backups de configuração sempre funcionam.

Personalizando seu agente

#

O servidor agente vem com uma base de framework mínima e espera que você adicione suas próprias personalizações por cima. O runtime mantém os dois separados para que atualizações do framework nunca destruam seu trabalho.

Framework vs usuário

#

pockethook-agent-server/
├── skills/                      # skills fornecidos pelo framework (somente leitura)
├── custom-tools/                # reservado para ferramentas do framework (somente leitura)
├── config/
│   ├── agent-instructions.md    # instruções do agente do framework (somente leitura)
│   └── personality.md           # personalidade do framework (somente leitura)
└── data/user/                   # SUA personalização fica aqui (ignorado pelo git)
    ├── skills/                  # seus próprios skills (sobrescrevem os base pelo nome do arquivo)
    ├── custom-tools/            # suas ferramentas personalizadas instaladas
    ├── instructions.md          # suas adições às instruções do agente
    └── prefs.json               # valores tipados referenciados como {{prefs.key}}

A personalização do usuário é escrita por meio de ferramentas tipadas dedicadas (create_user_skill, create_custom_tool) para que os arquivos resultantes sempre correspondam ao formato do loader. A ferramenta write também rejeita qualquer caminho sob skills/, custom-tools/ ou config/ e redireciona o agente para data/user/* — assim, até edições diretas de arquivos terminam na camada do usuário.

Nota sobre o diretório base custom-tools/. Hoje ele contém apenas um template (_example.md) que o loader ignora — toda ferramenta que o agente instala para você vai para data/user/custom-tools/. O diretório está reservado para que lançamentos futuros do framework possam enviar ferramentas integradas opcionais sem atropelar suas instalações. Quando isso acontecer, seus arquivos na camada do usuário continuam vencendo em caso de colisão de nome de ferramenta, então não há nada para migrar.

Quatro formas de personalizar

#

Você nunca precisa escrever esses arquivos à mão. Basta dizer ao agente o que você quer e ele escolhe a camada certa automaticamente.

Preferências tipadas com {{prefs.*}}

#

Digamos que você escreva um skill de planejador de rotas que precisa saber seu ponto de partida padrão. Em vez de fixar “Madri” no skill, referencie a pref:

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

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

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

O servidor substitui os placeholders quando o skill é carregado. Chaves aninhadas ({{prefs.tunnel.domain}}) também funcionam. Chaves desconhecidas são deixadas como estão para que erros de digitação permaneçam visíveis.

Editando a base do framework diretamente

#

Se você está auto-hospedando e quer mexer no próprio framework, pode editar config/agent-instructions.md, config/personality.md, skills/ ou custom-tools/ diretamente — o servidor não te impede quando você usa um editor de arquivos. Mas o agente não vai escrever nesses caminhos a partir de uma conversa. E atualizações do framework vão sobrescrever suas edições. Prefira a camada do usuário para qualquer coisa que queira manter.

Estender o Servidor

#

• Ferramentas personalizadas — Peça ao agente para instalar ferramentas CLI; elas vão para data/user/custom-tools/ automaticamente
• Adicionar skills — Peça ao agente para criar um skill; o arquivo vai para data/user/skills/
• Mudar comportamento — Peça ao agente para aplicar uma regra global; ela é anexada a data/user/instructions.md
• Configurar permissões — Execute bun run permissions para controlar quais ferramentas o agente pode usar
• Adicionar ferramentas integradas — Implemente novas funções de ferramentas em src/tools.ts para integrações mais profundas (requer forkar o servidor)

Configuração

#

Todas as configurações são armazenadas em .env (criado por bun run setup). Opções principais:

Consulte a referência completa de configuração no repositório do GitHub.

Executar como Serviço

#

Instale como um serviço persistente que inicia automaticamente:

bun run service install

INSTANCE_NAME por padrão é o basename do diretório do projeto com o prefixo pockethook- removido (por exemplo, um checkout em pockethook-agent-server/ se torna agent-server). Defina explicitamente para executar vários checkouts na mesma máquina sem colisões — cada instância mantém seu próprio data/ e logs.

Gerencie com bun run service status, restart, stop ou uninstall.

Segurança

#

• HTTPS obrigatório — O PocketHook exige HTTPS para todas as URLs
• Autenticação por token Bearer — Segredo compartilhado entre o app e o servidor
• Limitação de taxa — Limites por token previnem abuso
• Ferramentas em sandbox — Comandos shell e acesso a arquivos restritos por permissões
• Padrões bloqueados — Comandos perigosos (sudo, rm -rf /) bloqueados por padrão
• Limite de diretório de trabalho — O agente não pode escapar do seu diretório designado
• Arquivos sensíveis protegidos — .env, .git, *.key, *.pem bloqueados para o agente
• Versionamento automático — Todas as alterações do workspace são rastreadas com git para fácil reversão