Servidor Agente

O que e o PocketHook Agent Server?

#

O servidor agente transforma o PocketHook em um assistente de IA completo. Em vez de escrever a logica de resposta voce mesmo, voce 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 propria maquina. Seus dados ficam com voce.

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

Recursos

#

• LLM multi-provedor — 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 arquivos, listagem de diretorios, busca web, web scraping, gerenciamento de servidores dev
• Divisao framework / usuario — Os arquivos do framework (skills/, custom-tools/, config/) permanecem somente leitura. Suas personalizacoes ficam em data/user/ (skills, ferramentas personalizadas, instrucoes, prefs tipadas). Atualizacoes do framework sao aplicadas sem sobrescrever seu trabalho
• Prefs de usuario tipadas — Armazene valores como seu app de mapas preferido ou dominio de tunel em data/user/prefs.json. Referencie-os nos skills como {{prefs.key}} e o servidor fara a substituicao no carregamento
• Tarefas de programacao em uma so 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 usuario em um unico passo, substituindo o padrao 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), alem 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 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 usuario com o frontmatter correto, para que o loader sempre os analise e o agente nunca escreva esses arquivos a mao
• Tarefas em segundo plano — Tarefas unicas ou recorrentes com expressoes cron ou intervalos simples
• Skills dinamicos — Defina atalhos e regras de comportamento como arquivos .md. Apenas um indice compacto e carregado no prompt; o conteudo completo e obtido sob demanda via a ferramenta load_skill
• Skills autogerenciados — O agente pode criar, editar e excluir definicoes de skills (as escritas sempre acontecem na camada do usuario)
• Memoria semantica — Busca 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 fatos duraveis com auto-invalidacao. Relacionamentos multi-valor coexistem; fatos de valor unico sao substituidos automaticamente
• Metodo PARA com cascata de fim de projeto — Cada memoria e marcada com um status (Projeto, Area, Recurso, Arquivo). Quando um projeto termina, uma unica chamada complete_project arquiva seus vetores, invalida cada tripla de planejamento ligada ao seu slug e registra a conclusao — uma chamada em vez de tres
• Recuperacao hibrida — Combina busca por palavras-chave FTS5 com busca semantica por vetores usando fusao de classificacao reciproca
• Memoria de longo prazo — SQLite + busca de texto completo FTS5 como fallback quando a memoria semantica esta desabilitada
• Gerenciamento de servidores dev com contrato de tunel — Inicie, pare e liste servidores dev. Quando tunnel: true e solicitado, o servidor impoe isso antes e depois da inicializacao — um servidor localhost inalcancavel nunca fica rodando silenciosamente
• Sanitizacao automatica de URL — Se o agente deixar uma URL localhost em uma resposta, as ferramentas respond_* a reescrevem para a URL de tunel correspondente para que seu telefone sempre receba um link acessivel
• Ferramentas personalizadas — O agente pode instalar ferramentas CLI e registra-las como novas capacidades
• Versionamento — Versionamento git automatico para arquivos do workspace; backups de configuracao para skills e permissoes
• Dashboard web — Visao ao vivo de tarefas em segundo plano, personalizavel por usuario. /dashboard e /api/jobs nao sao autenticados por design — restrinja o acesso na camada de rede (ACL do Tailscale, firewall, proxy reverso 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 requisicoes por token com limiares configuraveis

Requisitos

#

• Runtime Bun
• Uma chave de API ou credenciais OAuth para seu provedor 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 provedor, modelo, token de auth, porta
bun run setup

# Iniciar servidor + tunel HTTPS
bun run dev:tunnel

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

Uma vez rodando, copie as URLs exibidas nas Configuracoes do PocketHook:

Como Funciona

#

1. Voce envia uma mensagem no PocketHook
2. O servidor a encaminha para 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 arquivos, buscar na web, agendar tarefas em segundo plano, lembrar fatos ou iniciar servidores dev
4. A resposta e 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 maquina — sem chave de API, sem dados saindo 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 busca 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 a cada turno
• Sessoes expiram apos SESSION_TTL_MINUTES, mas a memoria de longo prazo persiste para sempre

Ajuste isso de forma interativa com bun run memory.

Memoria semantica

#

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

Cada memoria e convertida em um 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 voce faz uma pergunta, a extracao de entidades foca a busca vetorial nos wings mais relevantes. Os resultados sao mesclados 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 fatos 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
• Fatos do grafo de conhecimento sao injetados junto com as memorias recuperadas em cada conversa

Quando voce 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 memoria e marcada com um status PARA:

• Projeto — Trabalho ativo com prazo definido
• Area — Responsabilidades continuas
• 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 daquele projeto enquanto preserva o material de referencia para uso futuro.

Cascata de fim de projeto

#

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

1. Arquiva os vetores do projeto (eventos, decisoes, 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 conclusao como uma nova tripla: (user, "cancelled_visit_barcelona", "2026-04-15").

A correspondencia respeita limites — um projeto diferente chamado revisit_barcelona fica intacto. O agente nao precisa mais orquestrar tres chamadas separadas na ordem certa, entao modelos menores tambem acertam.

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

Skills

#

Skills sao arquivos .md em skills/ que definem Shortcuts do iOS que o agente pode acionar e/ou regras de comportamento. Eles 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 voce 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 tambem podem ser regras de comportamento sem atalhos (por exemplo, “como planejar uma viagem em familia”). Use shortcuts: [] para esses.

O agente pode criar e gerenciar skills quando solicitado — peca para ele “criar um skill para controlar minhas luzes” e ele escrevera o arquivo .md para voce. Skills novos ou editados sempre ficam na sua camada de usuario (data/user/skills/), entao atualizacoes do framework nunca os sobrescrevem. Veja a secao 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 e ideal para acoes que criam conteudo sincronizado pelo iCloud — notas, lembretes, eventos de calendario — porque o resultado sincroniza automaticamente em todos os seus dispositivos sem precisar que o app PocketHook faca nada.

Como funciona:

1. O agente decide que um atalho deve rodar (por exemplo, “crie 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 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 forcar a sincronizacao do iCloud e o fecha apos 5 segundos
4. O usuario recebe uma mensagem de confirmacao no chat; o atalho em si nao e enviado ao dispositivo

Requisitos:

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

Quando usar target: mac:

• Acoes sincronizadas pelo iCloud (Notas, Lembretes, Calendario) — o resultado chega a todos os dispositivos de qualquer jeito
• Processamentos longos que voce quer manter fora do dispositivo iOS
• Qualquer atalho que nao precise interagir com a UI do iPhone

Quando manter target: device (padrao):

• Atalhos que precisam de recursos exclusivos do iPhone (camera, localizacao precisa, automacoes locais de apps)
• Atalhos que pedem entrada interativa do usuario
• Atalhos que usam App Intents de apps exclusivos do iOS

Tarefas em Segundo Plano

#

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

• “Verifique o clima toda manha as 8h e crie uma nota”
• “Execute este script a cada hora”
• “Me lembre de verificar 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 ele 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.), ele proativamente oferece servi-lo:

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

O agente gerencia 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 inicia um servidor com exposicao por tunel solicitada, o runtime impoe isso: se nenhuma ferramenta de tunel (Tailscale, ngrok, cloudflared) estiver instalada, o servidor se recusa a iniciar. Se a configuracao do tunel falhar apos a inicializacao, o processo orfao e finalizado e o agente e informado explicitamente — para que ele possa recorrer ao modo preview ou pedir que voce instale um tunel. A URL retornada e sempre a URL do tunel quando o tunneling esta ativo, com uma nota dizendo que a URL local e apenas para o host.

Como rede de seguranca, cada ferramenta respond_* pos-processa sua mensagem: qualquer URL localhost ou 127.0.0.1 que escape para uma resposta e reescrita para a URL de tunel correspondente automaticamente quando um servidor gerenciado tem uma. Quando nao consegue reescrever, voce recebe um aviso nos logs em vez de um link quebrado no seu telefone.

Dashboard

#

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

Nao autenticado por design. Tanto /dashboard quanto /api/jobs sao endpoints GET abertos — qualquer um que consiga alcancar o host pode listar tarefas. Restrinja o acesso na camada de rede (ACL do Tailscale, firewall, proxy reverso com autenticacao basica) ou defina DASHBOARD=false se nao precisar. O app PocketHook para iOS nao usa esses 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 seu dashboard e ele cuidara do resto — cada usuario recebe um dashboard unico e personalizado.

Ferramentas Personalizadas

#

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

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

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

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

Versionamento

#

Todos os dados do usuario sao versionados automaticamente:

• Arquivos 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
• Arquivos de configuracao — config/agent-instructions.md, config/personality.md, skills/ e permissions.json sao copiados antes de cada modificacao. Ate 20 versoes por arquivo

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

Personalizando seu agente

#

O servidor agente vem com uma base de framework minima e espera que voce adicione suas proprias personalizacoes por cima. O runtime mantem os dois separados para que atualizacoes do framework nunca destruam seu trabalho.

Framework vs usuario

#

pockethook-agent-server/
├── skills/                      # skills fornecidos pelo framework (somente leitura)
├── custom-tools/                # reservado para ferramentas do framework (somente leitura)
├── config/
│   ├── agent-instructions.md    # instrucoes do agente do framework (somente leitura)
│   └── personality.md           # personalidade do framework (somente leitura)
└── data/user/                   # SUA personalizacao fica aqui (ignorado pelo git)
    ├── skills/                  # seus proprios skills (sobrescrevem os base pelo nome do arquivo)
    ├── custom-tools/            # suas ferramentas personalizadas instaladas
    ├── instructions.md          # suas adicoes as instrucoes do agente
    └── prefs.json               # valores tipados referenciados como {{prefs.key}}

A personalizacao do usuario e 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 tambem rejeita qualquer caminho sob skills/, custom-tools/ ou config/ e redireciona o agente para data/user/* — assim, ate edicoes diretas de arquivos terminam na camada do usuario.

Nota sobre o diretorio base custom-tools/. Hoje ele contem apenas um template (_example.md) que o loader ignora — toda ferramenta que o agente instala para voce vai para data/user/custom-tools/. O diretorio esta reservado para que lancamentos futuros do framework possam enviar ferramentas integradas opcionais sem atropelar suas instalacoes. Quando isso acontecer, seus arquivos na camada do usuario continuam vencendo em caso de colisao de nome de ferramenta, entao nao ha nada para migrar.

Quatro formas de personalizar

#

Voce nunca precisa escrever esses arquivos a mao. Basta dizer ao agente o que voce quer e ele escolhe a camada certa automaticamente.

Preferencias tipadas com {{prefs.*}}

#

Digamos que voce escreva um skill de planejador de rotas que precisa saber seu ponto de partida padrao. Em vez de fixar “Madri” no skill, referencie a pref:

- **Ponto de partida**: {{prefs.routeOrigin}}, a menos que o usuario 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 e carregado. Chaves aninhadas ({{prefs.tunnel.domain}}) tambem funcionam. Chaves desconhecidas sao deixadas como estao para que erros de digitacao permanecam visiveis.

Editando a base do framework diretamente

#

Se voce esta auto-hospedando e quer mexer no proprio framework, pode editar config/agent-instructions.md, config/personality.md, skills/ ou custom-tools/ diretamente — o servidor nao te impede quando voce usa um editor de arquivos. Mas o agente nao vai escrever nesses caminhos a partir de uma conversa. E atualizacoes do framework vao sobrescrever suas edicoes. Prefira a camada do usuario para qualquer coisa que queira manter.

Estender o Servidor

#

• Ferramentas personalizadas — Peca ao agente para instalar ferramentas CLI; elas vao para data/user/custom-tools/ automaticamente
• Adicionar skills — Peca ao agente para criar um skill; o arquivo vai para data/user/skills/
• Mudar comportamento — Peca ao agente para aplicar uma regra global; ela e anexada 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 forkar o servidor)

Configuracao

#

Todas as configuracoes 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 padrao e o basename do diretorio do projeto com o prefixo pockethook- removido (por exemplo, um checkout em pockethook-agent-server/ se torna agent-server). Defina explicitamente para executar varios checkouts na mesma maquina sem colisoes — cada instancia mantem seu proprio data/ e logs.

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

Seguranca

#

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