Serveur agent

Qu’est-ce que PocketHook Agent Server ?

#

Le serveur agent transforme PocketHook en un assistant IA complet. Au lieu d’écrire vous-même la logique de réponse, vous connectez un LLM (Claude, GPT, Gemini, etc.) qui traite les messages, appelle des outils et renvoie des réponses PocketHook structurées — y compris le déclenchement de Raccourcis.

Le serveur fonctionne sur votre propre machine. Vos données restent chez vous.

Ceci est un point de départ. Le serveur est livré avec un ensemble d’outils de base et est conçu pour être étendu par vos soins. Ajoutez vos propres intégrations — e-mail, calendriers, documents, API — et faites-en le vôtre.

Fonctionnalités

#

• LLM multi-fournisseurs — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (local), LM Studio (local)
• Authentification OAuth — GitHub Copilot et OpenAI Codex via code appareil / flux navigateur
• Outils d’agent — Commandes shell, lecture/écriture de fichiers, listage de répertoires, recherche web, scraping web, gestion de serveurs de développement
• Séparation framework / utilisateur — Les fichiers du framework (skills/, custom-tools/, config/) restent en lecture seule. Vos personnalisations vivent sous data/user/ (compétences, outils personnalisés, instructions, prefs typées). Les mises à jour du framework s’appliquent sans écraser votre travail
• Prefs utilisateur typées — Stockez des valeurs comme votre application de cartes préférée ou votre domaine de tunnel dans data/user/prefs.json. Référencez-les dans les compétences sous la forme {{prefs.key}} et le serveur effectue la substitution au chargement
• Tâches de programmation en un seul appel — Le méta-outil run_code_job crée une tâche en arrière-plan de type prompt (exécutée par votre LLM configuré) et envoie l’accusé à l’utilisateur en une seule étape, remplaçant le motif « respond + create-job » propice aux erreurs
• Outils de protocole typés — Six outils respond_* dédiés (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), plus des outils de tâches typés (create_once_job, create_cron_job) et des outils d’espace de travail typés (create_project, list_projects, delete_project). Les schémas rejettent les URLs malformées, la syntaxe de boutons et les combinaisons type/schedule avant qu’elles n’atteignent l’appareil
• Écrivains typés pour la personnalisation — create_user_skill et create_custom_tool construisent le markdown de la couche utilisateur avec le bon frontmatter, de sorte que le chargeur les analyse toujours et que l’agent n’écrive jamais ces fichiers à la main
• Tâches en arrière-plan — Tâches ponctuelles ou récurrentes avec expressions cron ou intervalles simples
• Compétences dynamiques — Définissez des raccourcis et des règles de comportement sous forme de fichiers .md. Seul un index compact est chargé dans le prompt ; le contenu complet est récupéré à la demande via l’outil load_skill
• Compétences auto-gérées — L’agent peut créer, modifier et supprimer des définitions de compétences (les écritures atterrissent toujours dans la couche utilisateur)
• Mémoire sémantique — Recherche vectorielle avec embeddings (Ollama, LM Studio ou OpenAI). Les souvenirs sont auto-classés en dimensions aile/pièce/couloir/statut par le LLM
• Graphe de connaissances — Stockage de triplets temporels pour les faits durables avec invalidation automatique. Les relations multi-valeurs coexistent ; les faits à valeur unique se remplacent automatiquement
• Méthode PARA avec cascade de fin de projet — Chaque souvenir est étiqueté avec un statut (Projet, Domaine, Ressource, Archive). Quand un projet se termine, un seul appel complete_project archive ses vecteurs, invalide tous les triplets de planification liés à son slug, et enregistre l’achèvement — un appel au lieu de trois
• Rappel hybride — Combine la recherche par mots-clés FTS5 avec la recherche sémantique vectorielle via fusion de rangs réciproques
• Mémoire à long terme — SQLite + recherche plein texte FTS5 comme solution de repli lorsque la mémoire sémantique est désactivée
• Gestion de serveurs de développement avec contrat de tunnel — Démarrer, arrêter et lister les serveurs de développement. Quand tunnel: true est demandé, le serveur l’impose en pré-vol et post-démarrage — un serveur localhost injoignable ne reste jamais en cours silencieusement
• Nettoyage automatique des URL — Si l’agent laisse une URL localhost dans une réponse, les outils respond_* la réécrivent vers l’URL de tunnel correspondante pour que votre téléphone obtienne toujours un lien accessible
• Outils personnalisés — L’agent peut installer des outils CLI et les enregistrer comme nouvelles capacités
• Versionnage — Versionnage git automatique pour les fichiers de l’espace de travail ; sauvegardes de configuration pour les compétences et permissions
• Tableau de bord web — Vue d’ensemble en temps réel des tâches en arrière-plan, personnalisable par utilisateur. /dashboard et /api/jobs ne sont pas authentifiés par conception — restreignez l’accès au niveau du réseau (ACL Tailscale, pare-feu, reverse proxy avec authentification basique) ou définissez DASHBOARD=false si vous n’en avez pas besoin
• Tunneling HTTPS — Support intégré pour Tailscale, ngrok et Cloudflare Tunnel
• Service système — Installation en tant que service persistant sur macOS, Linux ou Windows
• Limitation de débit — Limites de requêtes par jeton avec seuils configurables

Prérequis

#

• Runtime Bun
• Une clé API ou des identifiants OAuth pour votre fournisseur LLM
• (Optionnel) Tailscale, ngrok ou cloudflared pour le tunneling HTTPS

Démarrage rapide

#

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

# Configuration interactive — choisissez le fournisseur, le modèle, le jeton d'authentification, le port
bun run setup

# Démarrer le serveur + tunnel HTTPS
bun run dev:tunnel

L’assistant de configuration vous guidera dans le choix d’un fournisseur LLM, la configuration de l’authentification et la mise en place des permissions d’outils.

Une fois le serveur démarré, copiez les URLs affichées dans les Paramètres de PocketHook :

Comment ça fonctionne

#

1. Vous envoyez un message dans PocketHook
2. Le serveur le transmet à votre LLM choisi avec l’historique de conversation, les souvenirs rappelés et les outils disponibles
3. Le LLM traite le message — il peut exécuter des commandes shell, lire/écrire des fichiers, rechercher sur le web, planifier des tâches en arrière-plan, mémoriser des faits ou démarrer des serveurs de développement
4. La réponse est retournée au format PocketHook (msg + shortcut + data + url)
5. PocketHook affiche le message et exécute les Raccourcis éventuels sur votre appareil

Fournisseurs LLM supportés

#

Changez de fournisseur à tout moment avec bun run switch. Ollama et LM Studio fonctionnent entièrement sur votre machine — pas de clé API nécessaire, aucune donnée ne quitte votre réseau.

Mémoire

#

Le système de mémoire comporte trois couches, chacune servant un objectif différent.

La conception de la mémoire sémantique combine des idées de MemPalace (une architecture de palais de la mémoire qui organise les souvenirs en ailes, couloirs et pièces) et de la méthode PARA de Tiago Forte (Projets, Domaines, Ressources, Archives) pour la gestion du cycle de vie des connaissances.

Mémoire de conversation

#

SQLite avec recherche plein texte FTS5. Tous les messages sont stockés avec horodatages et identifiants de session.

• Court terme — Les MAX_HISTORY derniers messages conservés en mémoire par session
• Long terme — Tous les messages persistés dans SQLite, recherchables via correspondance par mots-clés FTS5
• Rappel par tour — Lorsque la mémoire sémantique est activée, MAX_RECALL contrôle combien de souvenirs pertinents sont injectés dans le prompt à chaque tour
• Les sessions expirent après SESSION_TTL_MINUTES, mais la mémoire à long terme persiste indéfiniment

Ajustez ces paramètres de manière interactive avec bun run memory.

Mémoire sémantique

#

Nécessite VECTOR_MEMORY=true et un fournisseur d’embeddings (Ollama, LM Studio ou OpenAI).

Chaque souvenir est intégré sous forme de vecteur et auto-classé par le LLM selon quatre dimensions :

• Aile — L’entité : user, person:john, project:blog, place:london
• Pièce — Le type : facts, preferences, events, decisions, requests
• Couloir — Le sujet : personal, tech, health, travel, food, work
• Statut — Classification PARA : project, area, resource, archive

Lorsque vous posez une question, l’extraction d’entités concentre la recherche vectorielle sur les ailes les plus pertinentes. Les résultats sont fusionnés avec les résultats de mots-clés FTS5 via la fusion de rangs réciproques — vous obtenez ainsi le meilleur de la correspondance par mots-clés et sémantique.

Graphe de connaissances

#

Un stockage de triplets temporels pour les faits structurés et durables :

• Triplets : (sujet, prédicat, objet) avec horodatages valid_from / valid_until
• Les prédicats à valeur unique (lives_in, partner) invalident automatiquement l’ancienne valeur lors de la mise à jour
• Les prédicats multi-valeurs (child, friend, hobby) coexistent sans invalidation
• Les faits du graphe de connaissances sont injectés aux côtés des souvenirs rappelés dans chaque conversation

Quand vous dites à l’agent « J’ai déménagé à Berlin », il invalide l’ancien triplet lives_in et en crée un nouveau — automatiquement.

Cycle de vie PARA

#

Chaque souvenir est étiqueté avec un statut PARA :

• Projet — Travail actif, limité dans le temps
• Domaine — Responsabilités continues
• Ressource — Documents de référence (listes, recommandations, guides pratiques)
• Archive — Projets terminés ou annulés

Lorsqu’un projet est terminé, l’agent utilise la similarité sémantique pour archiver uniquement les souvenirs de ce projet tout en préservant les documents de référence pour une utilisation future.

Cascade de fin de projet

#

Dites « J’annule mon voyage à Barcelone » et un seul appel d’outil s’occupe de tout :

1. Archive les vecteurs du projet (événements, décisions, demandes liés à Barcelone).
2. Invalide chaque triplet actif du graphe de connaissances dont le prédicat correspond au slug du projet (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Enregistre l’achèvement sous forme de nouveau triplet : (user, "cancelled_visit_barcelona", "2026-04-15").

La correspondance respecte les limites — un autre projet nommé revisit_barcelona reste intact. L’agent n’a plus à orchestrer trois appels distincts dans le bon ordre, donc les modèles plus petits y arrivent aussi.

Si VECTOR_MEMORY est désactivé ou si le fournisseur d’embeddings est inaccessible, le système bascule sur FTS5 seul sans erreur.

Compétences

#

Les compétences sont des fichiers .md dans skills/ qui définissent les Raccourcis iOS que l’agent peut déclencher et/ou des règles de comportement. Elles utilisent le chargement dynamique : seul un index compact (titre, description, liste de raccourcis) est injecté dans le prompt système. L’agent charge le contenu complet à la demande via l’outil load_skill, maintenant une faible utilisation de jetons même avec de nombreuses compétences.

Chaque fichier de compétence utilise un en-tête 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

Champs du frontmatter

#

Les compétences peuvent aussi être des règles de comportement sans raccourcis (par ex. « comment planifier un voyage en famille »). Utilisez shortcuts: [] pour celles-ci.

L’agent peut créer et gérer des compétences sur demande — demandez-lui de « créer une compétence pour contrôler mes lumières » et il écrira le fichier .md pour vous. Les compétences nouvelles et modifiées atterrissent toujours dans votre couche utilisateur (data/user/skills/), ainsi les mises à jour du framework ne les écrasent jamais. Voir la section Personnaliser votre agent ci-dessous.

Exécuter des raccourcis sur le serveur Mac

#

Quand une compétence a target: mac, les raccourcis s’exécutent silencieusement sur le serveur Mac via la CLI shortcuts run au lieu d’être envoyés à l’appareil iOS. C’est idéal pour les actions qui créent du contenu synchronisé via iCloud — notes, rappels, événements de calendrier — car le résultat se synchronise automatiquement sur tous vos appareils sans que l’application PocketHook n’ait rien à faire.

Comment ça fonctionne :

1. L’agent décide qu’un raccourci doit s’exécuter (par ex. « crée une note avec les notes de la réunion du jour »)
2. Le serveur invoque shortcuts run "shortcutName" avec les données passées en JSON sur stdin, en utilisant le même format d’enveloppe que PocketHook iOS
3. Si sync_app est défini, le serveur ouvre brièvement cette application en arrière-plan (open -gj -a Notes) pour forcer la synchronisation iCloud, puis la ferme après 5 secondes
4. L’utilisateur reçoit un message de confirmation dans le chat ; le raccourci lui-même n’est pas envoyé à l’appareil

Prérequis :

• Le serveur doit tourner sur macOS — shortcuts run est exclusif à macOS. Sur d’autres plateformes, le serveur émet un avertissement et bascule sur l’exécution côté appareil
• Le raccourci doit être installé dans Shortcuts.app sur le Mac serveur
• Le raccourci doit attendre un Dictionnaire en entrée (PocketHook encapsule les données dans { context, timestamp, app, data })

Quand utiliser target: mac :

• Actions synchronisées via iCloud (Notes, Rappels, Calendrier) — le résultat atteint tous les appareils de toute façon
• Traitements longs que vous souhaitez garder hors de l’appareil iOS
• Tout raccourci qui n’a pas besoin d’interagir avec l’interface de l’iPhone

Quand garder target: device (par défaut) :

• Raccourcis qui nécessitent des fonctionnalités propres à l’iPhone (appareil photo, localisation précise, automatisations d’apps locales)
• Raccourcis qui demandent une saisie interactive à l’utilisateur
• Raccourcis qui utilisent des App Intents d’applications exclusives à iOS

Tâches en arrière-plan

#

Demandez à l’agent de planifier des tâches et il s’occupe du reste :

• « Vérifie la météo chaque matin à 8h et crée une note »
• « Exécute ce script toutes les heures »
• « Rappelle-moi de vérifier mes e-mails dans 30 minutes »

Les tâches supportent les expressions cron (0 8 * * *) et les intervalles simples (30m, 1h, 2d). Les résultats sont livrés à PocketHook lorsqu’il interroge le point d’accès /jobs.

Deux types d’exécution :

• Shell — Exécute une commande bash, capture la sortie. Peut déclencher un Raccourci à la fin
• Prompt — Traité par l’agent IA avec accès complet aux outils, stocke la réponse PocketHook complète

Serveurs de développement

#

Lorsque l’agent crée un projet web dans l’espace de travail (Hugo, Astro, Next.js, Flask, Go, etc.), il propose proactivement de le servir :

• Aperçu — Démarre un serveur de développement local sur un port assigné automatiquement pour un visionnage rapide
• Public — Démarre le serveur et l’expose via tunnel HTTPS pour qu’il soit accessible de partout

L’agent gère le cycle de vie : démarrage, arrêt et liste des serveurs en cours d’exécution. Tous les serveurs sont nettoyés lorsque le serveur principal s’arrête.

Contrat de tunnel

#

Quand l’agent démarre un serveur avec exposition via tunnel demandée, le runtime l’impose : si aucun outil de tunnel (Tailscale, ngrok, cloudflared) n’est installé, le serveur refuse de démarrer. Si la configuration du tunnel échoue après le lancement, le processus orphelin est arrêté et l’agent est informé explicitement — afin qu’il puisse revenir au mode aperçu ou vous demander d’installer un tunnel. L’URL retournée est toujours l’URL du tunnel lorsque le tunneling est activé, avec une note précisant que l’URL locale est réservée à l’hôte.

En guise de filet de sécurité, chaque outil respond_* post-traite son message : toute URL localhost ou 127.0.0.1 qui se glisse dans une réponse est réécrite automatiquement vers l’URL de tunnel correspondante quand un serveur géré en possède une. Quand la réécriture est impossible, vous obtenez un avertissement dans les logs plutôt qu’un lien cassé sur votre téléphone.

Tableau de bord

#

Le tableau de bord web intégré à /dashboard affiche une vue d’ensemble en temps réel des tâches en arrière-plan.

Non authentifié par conception. /dashboard et /api/jobs sont tous deux des points d’accès GET ouverts — quiconque peut atteindre l’hôte peut lister les tâches. Restreignez l’accès au niveau du réseau (ACL Tailscale, pare-feu, reverse proxy avec authentification basique) ou définissez DASHBOARD=false si vous n’en avez pas besoin. L’application iOS PocketHook n’utilise pas ces points d’accès.

Il est entièrement personnalisable :

• Modification rapide — Placez un dashboard.html dans workspace/dashboard/ pour des personnalisations simples
• Projet complet — Créez un projet avec framework (Svelte, React, Vue, etc.) dans workspace/dashboard/ avec la sortie de compilation vers dist/

Demandez à l’agent de personnaliser votre tableau de bord et il s’occupe du reste — chaque utilisateur obtient un tableau de bord unique et personnalisé.

Outils personnalisés

#

L’agent peut installer des outils CLI et les enregistrer comme nouvelles capacités — s’étendant lui-même sans modifier le code du serveur.

Par exemple, dites « installe Playwright et utilise-le pour prendre des captures d’écran ». L’agent va :

1. Installer la dépendance
2. Créer une définition d’outil (un simple fichier .md)
3. Utiliser le nouvel outil dans les conversations futures

Les outils personnalisés sont rechargés à chaud — aucun redémarrage nécessaire. Supprimez le fichier .md pour retirer un outil.

Versionnage

#

Toutes les données utilisateur sont versionnées automatiquement :

• Fichiers de l’espace de travail — Suivis avec un dépôt git local dans workspace/. Chaque écriture crée un commit automatique. Demandez à l’agent d’« annuler la dernière modification » ou utilisez git revert HEAD manuellement
• Fichiers de configuration — config/agent-instructions.md, config/personality.md, skills/ et permissions.json sont sauvegardés avant chaque modification. Jusqu’à 20 versions par fichier

Git est optionnel — s’il n’est pas installé, les modifications de l’espace de travail ne sont pas versionnées. Les sauvegardes de configuration fonctionnent toujours.

Personnaliser votre agent

#

Le serveur agent est livré avec une base de framework minimale et s’attend à ce que vous superposiez vos propres personnalisations par-dessus. Le runtime garde les deux séparés pour que les mises à jour du framework n’écrasent jamais votre travail.

Framework vs utilisateur

#

pockethook-agent-server/
├── skills/                      # compétences fournies par le framework (lecture seule)
├── custom-tools/                # réservé pour les outils fournis par le framework (lecture seule)
├── config/
│   ├── agent-instructions.md    # instructions d'agent du framework (lecture seule)
│   └── personality.md           # personnalité du framework (lecture seule)
└── data/user/                   # VOS personnalisations vivent ici (ignoré par git)
    ├── skills/                  # vos propres compétences (surpassent la base par nom de fichier)
    ├── custom-tools/            # vos outils personnalisés installés
    ├── instructions.md          # vos ajouts aux instructions de l'agent
    └── prefs.json               # valeurs typées référencées sous {{prefs.key}}

La personnalisation utilisateur est écrite via des outils typés dédiés (create_user_skill, create_custom_tool) afin que les fichiers résultants correspondent toujours au format du chargeur. L’outil write rejette également tout chemin sous skills/, custom-tools/ ou config/ et redirige l’agent vers data/user/* — ainsi, même les modifications directes de fichiers atterrissent dans la couche utilisateur.

Note à propos du répertoire de base custom-tools/. Aujourd’hui il ne contient qu’un modèle (_example.md) que le chargeur ignore — chaque outil que l’agent installe pour vous va dans data/user/custom-tools/. Le répertoire est réservé pour que de futures versions du framework puissent livrer des outils intégrés optionnels sans écraser vos installations. Le moment venu, vos fichiers de la couche utilisateur l’emportent toujours en cas de collision de nom d’outil, il n’y a donc rien à migrer.

Quatre façons de personnaliser

#

Vous n’avez jamais à écrire ces fichiers à la main. Dites simplement à l’agent ce que vous voulez et il choisit automatiquement la bonne couche.

Préférences typées avec {{prefs.*}}

#

Disons que vous écrivez une compétence de planificateur d’itinéraire qui a besoin de connaître votre point de départ par défaut. Au lieu de coder en dur « Madrid » dans la compétence, référencez la pref :

- **Point de départ** : {{prefs.routeOrigin}}, sauf si l'utilisateur précise une autre origine.

Et stockez la valeur dans data/user/prefs.json :

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

Le serveur substitue les placeholders lors du chargement de la compétence. Les clés imbriquées ({{prefs.tunnel.domain}}) fonctionnent aussi. Les clés inconnues sont laissées intactes pour que les coquilles restent visibles.

Modifier directement la base du framework

#

Si vous auto-hébergez et voulez bricoler le framework lui-même, vous pouvez modifier config/agent-instructions.md, config/personality.md, skills/ ou custom-tools/ directement — le serveur ne vous en empêche pas quand vous utilisez un éditeur de fichiers. Mais l’agent n’écrira pas sur ces chemins depuis une conversation. Et les mises à jour du framework écraseront vos modifications. Préférez la couche utilisateur pour tout ce que vous voulez conserver.

Étendre le serveur

#

• Outils personnalisés — Demandez à l’agent d’installer des outils CLI ; ils atterrissent automatiquement dans data/user/custom-tools/
• Ajouter des compétences — Demandez à l’agent de créer une compétence ; le fichier va dans data/user/skills/
• Modifier le comportement — Demandez à l’agent d’appliquer une règle globale ; elle est ajoutée à data/user/instructions.md
• Configurer les permissions — Exécutez bun run permissions pour contrôler quels outils l’agent peut utiliser
• Ajouter des outils intégrés — Implémentez de nouvelles fonctions d’outils dans src/tools.ts pour des intégrations plus profondes (nécessite un fork du serveur)

Configuration

#

Tous les paramètres sont stockés dans .env (créé par bun run setup). Options principales :

Consultez la référence complète de configuration dans le dépôt GitHub.

Exécution en tant que service

#

Installez en tant que service persistant qui démarre automatiquement :

bun run service install

INSTANCE_NAME prend par défaut le basename du répertoire du projet avec le préfixe pockethook- retiré (par exemple, un checkout dans pockethook-agent-server/ devient agent-server). Définissez-le explicitement pour exécuter plusieurs checkouts sur la même machine sans collisions — chaque instance conserve son propre data/ et ses logs.

Gérez avec bun run service status, restart, stop ou uninstall.

Sécurité

#

• HTTPS requis — PocketHook impose HTTPS pour toutes les URLs
• Authentification par jeton Bearer — Secret partagé entre l’application et le serveur
• Limitation de débit — Limites par jeton pour prévenir les abus
• Outils sandboxés — Commandes shell et accès aux fichiers restreints par les permissions
• Motifs bloqués — Commandes dangereuses (sudo, rm -rf /) bloquées par défaut
• Limite du répertoire de travail — L’agent ne peut pas sortir de son répertoire désigné
• Fichiers sensibles protégés — .env, .git, *.key, *.pem bloqués pour l’accès de l’agent
• Versionnage automatique — Toutes les modifications de l’espace de travail sont suivies par git pour un retour arrière facile