Servidor Agent

¿Qué es PocketHook Agent Server?

#

El servidor agent convierte PocketHook en un asistente IA completo. En lugar de escribir la lógica de respuesta tú mismo, conectas un LLM (Claude, GPT, Gemini, etc.) que procesa mensajes, llama herramientas y devuelve respuestas estructuradas de PocketHook — incluyendo activación de Atajos.

El servidor corre en tu propia máquina. Tus datos se quedan contigo.

Esto es un punto de partida. El servidor viene con un conjunto base de herramientas y está diseñado para ser extendido por ti. Agrega tus propias integraciones — correo, calendarios, documentos, APIs — y hazlo tuyo.

Características

#

• LLM multi-proveedor — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (local), LM Studio (local)
• Autenticación OAuth — GitHub Copilot y OpenAI Codex vía flujo de código de dispositivo / navegador
• Herramientas de agente — Comandos shell, lectura/escritura de archivos, listado de directorios, búsqueda web, web scraping, gestión de servidores dev
• Separación framework / usuario — Los archivos del framework (skills/, custom-tools/, config/) permanecen de solo lectura. Tus personalizaciones viven bajo data/user/ (skills, herramientas personalizadas, instrucciones, prefs tipadas). Las actualizaciones del framework se aplican sin sobrescribir tu trabajo
• Prefs de usuario tipadas — Almacena valores como tu app de mapas preferida o tu dominio de túnel en data/user/prefs.json. Refiérete a ellos en los skills como {{prefs.key}} y el servidor los sustituye al cargar
• Tareas de programación en una sola llamada — La meta-herramienta run_code_job crea una tarea en segundo plano de tipo prompt (ejecutada por tu LLM configurado) y le envía al usuario el acuse en un solo paso, reemplazando el frágil patrón “respond + create-job”
• Herramientas de protocolo tipadas — Seis herramientas respond_* dedicadas (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), más herramientas tipadas para tareas (create_once_job, create_cron_job) y herramientas tipadas de workspace (create_project, list_projects, delete_project). Los esquemas rechazan URLs malformadas, sintaxis de botones errónea y combinaciones inválidas de type/schedule antes de que lleguen al dispositivo
• Escritores tipados para personalización — create_user_skill y create_custom_tool construyen el markdown de la capa de usuario con el frontmatter correcto, de modo que el loader siempre los parsea y el agente nunca escribe estos archivos a mano
• Tareas en segundo plano — Tareas únicas o recurrentes con expresiones cron o intervalos simples
• Skills dinámicos — Define atajos y reglas de comportamiento como archivos .md. Solo un índice compacto se carga en el prompt; el contenido completo se obtiene bajo demanda vía la herramienta load_skill
• Skills autogestionados — El agente puede crear, editar y eliminar definiciones de skills (las escrituras aterrizan siempre en la capa de usuario)
• Memoria semántica — Búsqueda basada en vectores con embeddings (Ollama, LM Studio u OpenAI). Los recuerdos son auto-clasificados en dimensiones de wing/room/hall/status por el LLM
• Grafo de conocimiento — Almacén de triples temporales para hechos duraderos con auto-invalidación. Las relaciones multi-valor coexisten; los hechos de valor único se reemplazan automáticamente
• Método PARA con cascada de cierre de proyecto — Cada recuerdo se etiqueta con un estado (Proyecto, Área, Recurso, Archivo). Cuando un proyecto termina, una sola llamada a complete_project archiva sus vectores, invalida todos los triples de planificación atados a su slug y registra la finalización — una llamada en lugar de tres
• Recall híbrido — Combina búsqueda por palabras clave FTS5 con búsqueda semántica por vectores usando fusión de rango recíproco
• Memoria a largo plazo — SQLite + búsqueda de texto completo FTS5 como respaldo cuando la memoria semántica está deshabilitada
• Gestión de servidores dev con contrato de túnel — Inicia, detiene y lista servidores dev. Cuando se solicita tunnel: true, el servidor lo exige tanto en la verificación previa como después del arranque — nunca se queda corriendo en silencio un servidor localhost inalcanzable
• Saneamiento automático de URLs — Si el agente deja una URL localhost en una respuesta, las herramientas respond_* la reescriben a la URL de túnel correspondiente para que tu teléfono siempre reciba un enlace accesible
• Herramientas personalizadas — El agente puede instalar herramientas CLI y registrarlas como nuevas capacidades
• Versionado — Versionado git automático para archivos del workspace; respaldos de configuración para skills y permisos
• Dashboard web — Vista en vivo de tareas en segundo plano, personalizable por usuario. /dashboard y /api/jobs están sin autenticación por diseño — restringe el acceso en la capa de red (ACL de Tailscale, firewall, proxy inverso con basic auth) o establece DASHBOARD=false si no lo necesitas
• Túneles HTTPS — Soporte integrado para Tailscale, ngrok y Cloudflare Tunnel
• Servicio del sistema — Instala como servicio persistente en macOS, Linux o Windows
• Limitación de tasa — Límites de peticiones por token con umbrales configurables

Requisitos

#

• Runtime Bun
• Una clave API o credenciales OAuth para tu proveedor LLM
• (Opcional) Tailscale, ngrok o cloudflared para túneles HTTPS

Inicio Rápido

#

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

# Configuración interactiva — elige proveedor, modelo, token de auth, puerto
bun run setup

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

El asistente de configuración te guiará para elegir un proveedor LLM, configurar la autenticación y establecer los permisos de herramientas.

Una vez corriendo, copia las URLs mostradas en Ajustes de PocketHook:

Cómo Funciona

#

1. Envías un mensaje en PocketHook
2. El servidor lo reenvía a tu LLM elegido con el historial de conversación, recuerdos recuperados y herramientas disponibles
3. El LLM procesa el mensaje — puede ejecutar comandos shell, leer/escribir archivos, buscar en la web, programar tareas en segundo plano, recordar hechos o iniciar servidores dev
4. La respuesta se devuelve en formato PocketHook (msg + shortcut + data + url)
5. PocketHook muestra el mensaje y ejecuta cualquier Atajo en tu dispositivo

Proveedores LLM Soportados

#

Cambia de proveedor en cualquier momento con bun run switch. Ollama y LM Studio corren completamente en tu máquina — sin clave API, sin datos que salgan de tu red.

Memoria

#

El sistema de memoria tiene tres capas, cada una con un propósito diferente.

El diseño de la memoria semántica combina ideas de MemPalace (una arquitectura de palacio de memoria que organiza recuerdos en alas, pasillos y habitaciones) y el método PARA de Tiago Forte (Proyectos, Áreas, Recursos, Archivo) para la gestión del ciclo de vida del conocimiento.

Memoria de conversación

#

SQLite con búsqueda de texto completo FTS5. Todos los mensajes se almacenan con marcas de tiempo e IDs de sesión.

• Corto plazo — Los últimos MAX_HISTORY mensajes se mantienen en memoria por sesión
• Largo plazo — Todos los mensajes persisten en SQLite, buscables vía coincidencia de palabras clave FTS5
• Recall por turno — Cuando la memoria semántica está activada, MAX_RECALL controla cuántos recuerdos relevantes se inyectan en el prompt en cada turno
• Las sesiones expiran después de SESSION_TTL_MINUTES, pero la memoria a largo plazo persiste para siempre

Ajusta esto interactivamente con bun run memory.

Memoria semántica

#

Requiere VECTOR_MEMORY=true y un proveedor de embeddings (Ollama, LM Studio u OpenAI).

Cada recuerdo se convierte en un vector y se auto-clasifica por el LLM en cuatro dimensiones:

• Wing — La entidad: user, person:john, project:blog, place:london
• Room — El tipo: facts, preferences, events, decisions, requests
• Hall — El tema: personal, tech, health, travel, food, work
• Status — Clasificación PARA: project, area, resource, archive

Cuando haces una pregunta, la extracción de entidades enfoca la búsqueda vectorial en los wings más relevantes. Los resultados se fusionan con los resultados de palabras clave FTS5 usando fusión de rango recíproco — para obtener lo mejor de ambos, coincidencia por palabras clave y semántica.

Grafo de conocimiento

#

Un almacén de triples temporales para hechos estructurados y duraderos:

• Triples: (sujeto, predicado, objeto) con marcas de tiempo valid_from / valid_until
• Los predicados de valor único (lives_in, partner) auto-invalidan el valor anterior al actualizar
• Los predicados de multi-valor (child, friend, hobby) coexisten sin invalidación
• Los hechos del grafo de conocimiento se inyectan junto con los recuerdos recuperados en cada conversación

Cuando le dices al agente “Me mudé a Berlín”, invalida el triple antiguo de lives_in y crea uno nuevo — automáticamente.

Ciclo de vida PARA

#

Cada recuerdo se etiqueta con un estado PARA:

• Proyecto — Trabajo activo con límite de tiempo
• Área — Responsabilidades continuas
• Recurso — Material de referencia (listas, recomendaciones, tutoriales)
• Archivo — Proyectos completados o cancelados

Cuando un proyecto se completa, el agente usa similitud semántica para archivar solo los recuerdos de ese proyecto mientras preserva el material de referencia para uso futuro.

Cascada de cierre de proyecto

#

Di “voy a cancelar mi viaje a Barcelona” y una sola llamada de herramienta se encarga de todo:

1. Archiva los vectores del proyecto (eventos, decisiones y peticiones ligados a Barcelona).
2. Invalida todos los triples activos del grafo de conocimiento cuyo predicado coincida con el slug del proyecto (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Registra la finalización como un nuevo triple: (user, "cancelled_visit_barcelona", "2026-04-15").

La coincidencia respeta los límites de palabra — un proyecto distinto llamado revisit_barcelona queda intacto. El agente ya no tiene que orquestar tres llamadas separadas en el orden correcto, así que los modelos más pequeños también lo hacen bien.

Si VECTOR_MEMORY está deshabilitado o el proveedor de embeddings no está disponible, el sistema recurre a solo FTS5 sin errores.

Skills

#

Los skills son archivos .md en skills/ que definen Atajos de iOS que el agente puede activar y/o reglas de comportamiento. Usan carga dinámica: solo un índice compacto (título, descripción, lista de atajos) se inyecta en el prompt del sistema. El agente carga el contenido completo bajo demanda vía la herramienta load_skill, manteniendo el uso de tokens bajo a medida que agregas más skills.

Cada archivo 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 del frontmatter

#

Los skills también pueden ser reglas de comportamiento sin atajos (por ejemplo, “cómo planear un viaje familiar”). Usa shortcuts: [] para estos.

El agente puede crear y gestionar skills cuando se le pide — pídele que “cree un skill para controlar mis luces” y escribirá el archivo .md por ti. Los skills nuevos y editados aterrizan siempre en tu capa de usuario (data/user/skills/), de modo que las actualizaciones del framework nunca los sobrescriben. Consulta la sección Personalizando tu agente más abajo.

Ejecutar atajos en el servidor Mac

#

Cuando un skill tiene target: mac, los atajos se ejecutan silenciosamente en el servidor Mac vía la CLI shortcuts run en lugar de enviarse al dispositivo iOS. Esto es ideal para acciones que crean contenido sincronizado por iCloud — notas, recordatorios, eventos de calendario — porque el resultado se sincroniza automáticamente con todos tus dispositivos sin que la app de PocketHook tenga que hacer nada.

Cómo funciona:

1. El agente decide que un atajo debe ejecutarse (por ejemplo, “crea una nota con los apuntes de la junta de hoy”)
2. El servidor invoca shortcuts run "shortcutName" con los datos pasados como JSON por stdin, usando el mismo formato envolvente que usa PocketHook iOS
3. Si sync_app está configurado, el servidor abre brevemente esa app en segundo plano (open -gj -a Notes) para forzar la sincronización de iCloud, y la cierra después de 5 segundos
4. El usuario recibe un mensaje de confirmación en el chat; el atajo en sí no se envía al dispositivo

Requisitos:

• El servidor debe correr en macOS — shortcuts run es exclusivo de macOS. En otras plataformas, el servidor registra una advertencia y recurre a la ejecución en el dispositivo
• El atajo debe estar instalado en Shortcuts.app en la Mac servidor
• El atajo debe esperar un Diccionario como entrada (PocketHook envuelve los datos en { context, timestamp, app, data })

Cuándo usar target: mac:

• Acciones sincronizadas por iCloud (Notas, Recordatorios, Calendario) — el resultado llega a todos los dispositivos de todos modos
• Procesamiento largo que quieras mantener fuera del dispositivo iOS
• Cualquier atajo que no necesite interactuar con la UI del iPhone

Cuándo mantener target: device (por defecto):

• Atajos que necesitan funciones exclusivas del iPhone (cámara, ubicación precisa, automatizaciones locales de apps)
• Atajos que piden entrada interactiva al usuario
• Atajos que usan App Intents de apps solo para iOS

Tareas en Segundo Plano

#

Pide al agente que programe tareas y él se encargará del resto:

• “Checa el clima cada mañana a las 8am y crea una nota”
• “Ejecuta este script cada hora”
• “Recuérdame checar mi correo en 30 minutos”

Las tareas soportan expresiones cron (0 8 * * *) e intervalos simples (30m, 1h, 2d). Los resultados se entregan a PocketHook cuando consulta el endpoint /jobs.

Dos tipos de ejecución:

• Shell — Ejecuta un comando bash, captura la salida. Puede activar un Atajo al completarse
• Prompt — Procesado por el agente IA con acceso completo a herramientas, almacena la respuesta completa de PocketHook

Servidores Dev

#

Cuando el agente crea un proyecto web en el workspace (Hugo, Astro, Next.js, Flask, Go, etc.), ofrece proactivamente servirlo:

• Vista previa — Inicia un servidor dev local en un puerto auto-asignado para vista rápida
• Público — Inicia el servidor y lo expone vía túnel HTTPS para que sea accesible desde cualquier lugar

El agente gestiona el ciclo de vida: iniciar, detener y listar servidores en ejecución. Todos los servidores se limpian cuando el servidor principal se detiene.

Contrato de túnel

#

Cuando el agente arranca un servidor solicitando exposición por túnel, el runtime lo exige: si no hay ninguna herramienta de túnel instalada (Tailscale, ngrok, cloudflared), el servidor se niega a arrancar. Si la configuración del túnel falla tras el spawn, el proceso huérfano se detiene y se le informa al agente de forma explícita — para que pueda caer a modo vista previa o pedirte que instales un túnel. La URL devuelta es siempre la URL del túnel cuando la tunelización está activa, con una nota de que la URL local es solo de host.

Como red de seguridad, cada herramienta respond_* post-procesa su mensaje: cualquier URL de localhost o 127.0.0.1 que se cuele en una respuesta se reescribe automáticamente a la URL de túnel correspondiente cuando un servidor gestionado tiene una. Si no puede reescribirla, recibes un aviso en los logs en lugar de un enlace roto en tu teléfono.

Dashboard

#

El dashboard web integrado en /dashboard muestra una vista en vivo de las tareas en segundo plano.

Sin autenticación por diseño. Tanto /dashboard como /api/jobs son endpoints GET abiertos — cualquiera que pueda alcanzar el host puede listar las tareas. Restringe el acceso en la capa de red (ACL de Tailscale, firewall, proxy inverso con basic auth) o establece DASHBOARD=false si no lo necesitas. La app de PocketHook para iOS no usa estos endpoints.

Es completamente personalizable:

• Edición rápida — Coloca un dashboard.html en workspace/dashboard/ para personalizaciones simples
• Proyecto completo — Crea un proyecto con framework (Svelte, React, Vue, etc.) en workspace/dashboard/ con salida de build a dist/

Pide al agente que personalice tu dashboard y él se encargará del resto — cada usuario obtiene un dashboard único y personalizado.

Herramientas Personalizadas

#

El agente puede instalar herramientas CLI y registrarlas como nuevas capacidades — extendiéndose a sí mismo sin modificar el código del servidor.

Por ejemplo, di “instala Playwright y úsalo para tomar capturas de pantalla”. El agente:

1. Instalará la dependencia
2. Creará una definición de herramienta (un simple archivo .md)
3. Usará la nueva herramienta en conversaciones futuras

Las herramientas personalizadas se recargan en caliente — no se necesita reiniciar. Elimina el archivo .md para quitar una herramienta.

Versionado

#

Todos los datos de usuario se versionan automáticamente:

• Archivos del workspace — Rastreados con un repositorio git local dentro de workspace/. Cada escritura crea un auto-commit. Pide al agente que “deshaga el último cambio” o usa git revert HEAD manualmente
• Archivos de configuración — config/agent-instructions.md, config/personality.md, skills/ y permissions.json se respaldan antes de cada modificación. Hasta 20 versiones por archivo

Git es opcional — si no está instalado, los cambios del workspace no se versionan. Los respaldos de configuración siempre funcionan.

Personalizando tu agente

#

El servidor agent viene con una base mínima del framework y espera que coloques tu personalización por encima. El runtime mantiene ambos separados para que las actualizaciones del framework nunca aplasten tu trabajo.

Framework frente a usuario

#

pockethook-agent-server/
├── skills/                      # skills del framework (solo lectura)
├── custom-tools/                # reservado para herramientas del framework (solo lectura)
├── config/
│   ├── agent-instructions.md    # instrucciones del agente del framework (solo lectura)
│   └── personality.md           # personalidad del framework (solo lectura)
└── data/user/                   # TU personalización vive aquí (ignorado por git)
    ├── skills/                  # tus propios skills (tienen prioridad por nombre de archivo)
    ├── custom-tools/            # tus herramientas personalizadas instaladas
    ├── instructions.md          # tus adiciones a las instrucciones del agente
    └── prefs.json               # valores tipados referenciados como {{prefs.key}}

La personalización del usuario se escribe mediante herramientas tipadas dedicadas (create_user_skill, create_custom_tool) para que los archivos resultantes siempre coincidan con el formato del loader. La herramienta write también rechaza cualquier ruta bajo skills/, custom-tools/ o config/ y redirige al agente a data/user/* — así, incluso las ediciones directas de archivos terminan en la capa de usuario.

Nota sobre el directorio base custom-tools/. Hoy solo contiene una plantilla (_example.md) que el loader ignora — cada herramienta que el agente instala por ti va a data/user/custom-tools/. El directorio queda reservado para que futuras versiones del framework puedan incluir herramientas integradas opcionales sin pisar tus instalaciones. Cuando eso ocurra, tus archivos de la capa de usuario siguen ganando en caso de colisión por nombre de herramienta, así que no hay nada que migrar.

Cuatro formas de personalizar

#

No tienes que escribir estos archivos a mano. Solo dile al agente lo que quieres y él elige la capa adecuada automáticamente.

Preferencias tipadas con {{prefs.*}}

#

Imagina que escribes un skill planificador de rutas que necesita saber tu punto de partida por defecto. En lugar de incrustar “Ciudad de México” en el skill, haz referencia a la pref:

- **Punto de partida**: {{prefs.routeOrigin}}, salvo que el usuario especifique un origen distinto.

Y guarda el valor en data/user/prefs.json:

{
  "routeOrigin": "Ciudad de México, México",
  "preferredMapsApp": "apple",
  "tunnel": { "domain": "my-host.ts.net" }
}

El servidor sustituye los marcadores al cargar el skill. Las claves anidadas ({{prefs.tunnel.domain}}) también funcionan. Las claves desconocidas se dejan tal cual para que las erratas queden visibles.

Editando directamente la base del framework

#

Si te autoalojas y quieres ajustar el propio framework, puedes editar config/agent-instructions.md, config/personality.md, skills/ o custom-tools/ directamente — el servidor no te detiene si usas un editor de archivos. Pero el agente no escribirá en esas rutas desde una conversación. Y las actualizaciones del framework sobrescribirán tus ediciones. Prefiere la capa de usuario para cualquier cosa que quieras conservar.

Extender el Servidor

#

• Herramientas personalizadas — Pide al agente que instale herramientas CLI; aterrizan automáticamente en data/user/custom-tools/
• Agregar skills — Pide al agente que cree un skill; el archivo va a data/user/skills/
• Cambiar comportamiento — Pide al agente que aplique una regla global; se añade a data/user/instructions.md
• Configurar permisos — Ejecuta bun run permissions para controlar qué herramientas puede usar el agente
• Agregar herramientas integradas — Implementa nuevas funciones de herramientas en src/tools.ts para integraciones más profundas (requiere hacer fork del servidor)

Configuración

#

Todos los ajustes se almacenan en .env (creado por bun run setup). Opciones principales:

Consulta la referencia completa de configuración en el repositorio de GitHub.

Ejecutar como Servicio

#

Instala como un servicio persistente que se inicia automáticamente:

bun run service install

INSTANCE_NAME por defecto es el basename del directorio del proyecto con el prefijo pockethook- quitado (por ejemplo, un checkout en pockethook-agent-server/ se convierte en agent-server). Establécelo explícitamente para ejecutar varios checkouts en la misma máquina sin colisiones — cada instancia mantiene su propio data/ y logs.

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

Seguridad

#

• HTTPS requerido — PocketHook exige HTTPS para todas las URLs
• Autenticación por token Bearer — Secreto compartido entre la app y el servidor
• Limitación de tasa — Límites por token previenen abuso
• Herramientas en sandbox — Comandos shell y acceso a archivos restringidos por permisos
• Patrones bloqueados — Comandos peligrosos (sudo, rm -rf /) bloqueados por defecto
• Límite de directorio de trabajo — El agente no puede escapar de su directorio designado
• Archivos sensibles protegidos — .env, .git, *.key, *.pem bloqueados para el agente
• Versionado automático — Todos los cambios del workspace se rastrean con git para fácil reversión