Serveur agent

C’est quoi 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 retourne des réponses PocketHook structurées — incluant le déclenchement de Raccourcis.

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

C’est un point de départ. Le serveur vient avec un ensemble d’outils de base et est conçu pour être étendu par vous. Ajoutez vos propres intégrations — courriel, 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 d’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 appli 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 fait 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 (roulée par votre LLM configuré) et envoie l’accusé à l’utilisateur en une seule étape, remplaçant le pattern « 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 URL malformées, la syntaxe de boutons et les combinaisons type/schedule avant qu’elles atteignent l’appareil
• Écrivains typés pour la personnalisation — create_user_skill et create_custom_tool bâtissent le markdown de la couche utilisateur avec le bon frontmatter, fait que le chargeur les analyse toujours et que l’agent écrit 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 autogé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 chaque triplet de planification lié à son slug, et enregistre la fin — 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 quand 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 avant et après le démarrage — un serveur localhost inaccessible reste jamais à rouler en silence
• 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 reçoive 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 config 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 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 mettez DASHBOARD=false si vous en avez pas besoin
• Tunneling HTTPS — Support intégré pour Tailscale, ngrok et Cloudflare Tunnel
• Service système — Installation comme 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 va vous guider 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 parti, copiez les URLs affichées dans les Paramètres de PocketHook :

Comment ça marche

#

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 rouler des commandes shell, lire/écrire des fichiers, chercher sur le web, planifier des tâches en arrière-plan, mémoriser des faits ou partir 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 n’importe quand avec bun run switch. Ollama et LM Studio roulent entièrement sur votre machine — pas de clé API nécessaire, aucune donnée ne sort de votre réseau.

Mémoire

#

Le système de mémoire a 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 gardés en mémoire par session
• Long terme — Tous les messages persistés dans SQLite, cherchables via correspondance par mots-clés FTS5
• Rappel par tour — Quand 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 pour toujours

Ajustez ça 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é comme 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

Quand 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 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 à la mise à jour
• Les prédicats multi-valeurs (child, friend, hobby) coexistent sans invalidation
• Les faits du graphe de connaissances sont injectés avec les 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 complétés ou annulés

Quand un projet est complété, l’agent utilise la similarité sémantique pour archiver seulement les souvenirs de ce projet tout en préservant les documents de référence pour 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 reliés à Barcelone).
2. Invalide chaque triplet actif du graphe de connaissances dont le prédicat matche le slug du projet (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Enregistre la fin comme un nouveau triplet : (user, "cancelled_visit_barcelona", "2026-04-15").

Le matchage respecte les bornes — un autre projet nommé revisit_barcelona reste intact. L’agent a plus à orchestrer trois appels séparés dans le bon ordre, donc les plus petits modèles y arrivent aussi.

Si VECTOR_MEMORY est désactivé ou si le fournisseur d’embeddings est pas accessible, le système tombe sur FTS5 seulement 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, gardant l’utilisation de jetons basse même avec beaucoup de 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 quand on lui demande — demandez-lui de « créer une compétence pour contrôler mes lumières » et il va écrire le fichier .md pour vous. Les compétences nouvelles et modifiées atterrissent toujours dans votre couche utilisateur (data/user/skills/), fait que les mises à jour du framework les écrasent jamais. Voir la section Personnaliser votre agent plus bas.

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é par iCloud — notes, rappels, événements de calendrier — parce que le résultat se synchronise automatiquement sur tous tes appareils sans que l’application PocketHook ait à faire quoi que ce soit.

Comment ça marche :

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 d’aujourd’hui »)
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 app 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 s’attendre à recevoir un Dictionnaire en entrée (PocketHook encapsule les données dans { context, timestamp, app, data })

Quand utiliser target: mac :

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

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

• Raccourcis qui nécessitent des fonctionnalités propres au iPhone (caméra, localisation précise, automatisations d’apps locales)
• Raccourcis qui demandent une entrée 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 »
• « Roule ce script à chaque heure »
• « Rappelle-moi de vérifier mes courriels 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 quand il interroge le point d’accès /jobs.

Deux types d’exécution :

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

Serveurs de développement

#

Quand l’agent crée un projet web dans l’espace de travail (Hugo, Astro, Next.js, Flask, Go, etc.), il offre 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 qui roulent. Tous les serveurs sont nettoyés quand le serveur principal arrête.

Contrat de tunnel

#

Quand l’agent part un serveur avec exposition via tunnel demandée, le runtime l’impose : si aucun outil de tunnel (Tailscale, ngrok, cloudflared) est installé, le serveur refuse de partir. Si la configuration du tunnel échoue après le lancement, le processus orphelin est arrêté et l’agent est informé explicitement — pour qu’il puisse retomber sur le mode aperçu ou vous demander d’installer un tunnel. L’URL retournée est toujours l’URL du tunnel quand le tunneling est activé, avec une note disant que l’URL locale est juste pour l’hôte.

Comme 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 a une. Quand la réécriture est pas possible, vous avez un avertissement dans les logs au lieu d’un lien brisé sur votre téléphone.

Tableau de bord

#

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

Pas authentifié par conception. /dashboard et /api/jobs sont les deux des endpoints GET ouverts — n’importe qui qui 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 mettez DASHBOARD=false si vous en avez pas besoin. L’application iOS PocketHook utilise pas ces endpoints.

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 est pas installé, les modifications de l’espace de travail sont pas versionnées. Les sauvegardes de config marchent toujours.

Personnaliser votre agent

#

Le serveur agent vient avec une base de framework minimale et s’attend à ce que vous ajoutiez vos propres personnalisations par-dessus. Le runtime garde les deux séparés pour que les mises à jour du framework viennent jamais écraser 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 (écrasent 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 par des outils typés dédiés (create_user_skill, create_custom_tool) fait que les fichiers résultants matchent toujours le format du chargeur. L’outil write rejette aussi tout chemin sous skills/, custom-tools/ ou config/ et redirige l’agent vers data/user/* — fait que même les modifications directes de fichiers atterrissent dans la couche utilisateur.

Note au sujet du répertoire de base custom-tools/. Aujourd’hui il contient juste 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 des versions futures du framework puissent livrer des outils intégrés optionnels sans écraser vos installations. Quand ça arrivera, vos fichiers de la couche utilisateur gagnent toujours en cas de collision de nom d’outil, fait qu’il y a rien à migrer.

Quatre façons de personnaliser

#

Vous avez jamais à écrire ces fichiers à la main. Dites juste à 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 de trajet 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}}, à moins que 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 remplace les placeholders quand la compétence est chargée. Les clés imbriquées ({{prefs.tunnel.domain}}) marchent aussi. Les clés inconnues sont laissées telles quelles pour que les fautes de frappe restent visibles.

Modifier directement la base du framework

#

Si vous auto-hébergez et voulez patenter le framework lui-même, vous pouvez modifier config/agent-instructions.md, config/personality.md, skills/ ou custom-tools/ directement — le serveur vous empêche pas quand vous utilisez un éditeur de fichiers. Mais l’agent écrira pas à ces chemins à partir d’une conversation. Et les mises à jour du framework vont écraser vos modifications. Préférez la couche utilisateur pour toute affaire que vous voulez garder.

Étendre le serveur

#

• Outils personnalisés — Demandez à l’agent d’installer des outils CLI ; ils atterrissent dans data/user/custom-tools/ automatiquement
• Ajouter des compétences — Demandez à l’agent de créer une compétence ; le fichier va dans data/user/skills/
• Changer le comportement — Demandez à l’agent d’appliquer une règle globale ; elle est ajoutée à data/user/instructions.md
• Configurer les permissions — Roulez 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 de forker le 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 comme service

#

Installez comme service persistant qui démarre automatiquement :

bun run service install

INSTANCE_NAME est par défaut le basename du répertoire du projet avec le préfixe pockethook- enlevé (par exemple, un checkout dans pockethook-agent-server/ devient agent-server). Mettez-le explicitement pour rouler plusieurs checkouts sur la même machine sans collisions — chaque instance garde 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’appli 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 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