Opérations de la Skill

Opérations HTTPS directes et en-têtes d'authentification

La Skill autonome communique directement avec XMemo via HTTPS. Les points de terminaison REST publics acceptent soit les en-têtes Authorization: Bearer <token> ou X-API-Key: <key>, tandis que le runtime de la Skill autonome formate automatiquement les requêtes sortantes à l'aide de Authorization: Bearer <token> à partir de l'identifiant résolu.

• Transport du runtime de la Skill : Injecte automatiquement Authorization: Bearer <token> dans toutes les requêtes vers https://xmemo.dev/v1/skill/operations.
• Flexibilité de l'API REST : Les clients HTTP autonomes appelant directement les points de terminaison REST peuvent fournir soit Authorization: Bearer <token>, soit X-API-Key: <key>.
• Contrat de découverte : Le modèle de runtime et les points de terminaison d'opérations sont découvrables sur /.well-known/agent-discovery.json et /.well-known/memory-os.json.

# Skill runtime uses Bearer token authorization:
POST /v1/skill/operations
Authorization: Bearer <skill-token>
Content-Type: application/json

# Direct REST endpoints also accept X-API-Key:
GET /v1/memories/search?query=onboarding&limit=5
X-API-Key: <your-assigned-api-key>

Inventaire complet des commandes par tâche

Le package de la Skill autonome (v1.1.35) fournit 32 commandes. Chaque commande est listée ci-dessous avec sa chaîne d'utilisation textuelle issue de help.mjs et sa portée d'autorisation requise.

• Authentification et configuration : login --allow-plaintext, register --reason <unattended|declined> --allow-plaintext, logout [--revoke-environment-token], auth status [--verify], auth add --from-stdin --allow-plaintext, auth claim-status [--allow-plaintext], auth claim-confirm [--allow-plaintext], auth claim-deny [--allow-plaintext].
• Mémoire et recherche : read --id <id> [--offset <n>] [--limit <n>] [--bucket <bucket>] [--scope <scope>] (memory:read), update --id <id> [--content <text>] [--path <path>] [--metadata <json>] [--bucket <bucket>] [--scope <scope>] (memory:write), forget --id <id> [--reason <text>] --confirm (memory:delete ou memory:write), remember (--content <text> | --content - | --file <path>) [--path <path>] [--metadata <json-object>] (memory:write), recall --query <text> [--limit <n>] [--explain <true|false>] [--prefer_working <true|false>] [--expand-documents] [--compact] (memory:read), search --query <text> [--limit <n>] [--explain <true|false>] [--prefer_working <true|false>] [--expand-documents] [--compact] (memory:read).
• Contexte de Knowledge : recall-context --query <text> [--max_items <n>] [--max_tokens <n>] [--prefer_working <true|false>] [--include_knowledge <true|false>] (memory:read; opting into Knowledge with --include_knowledge true requires knowledge:read).
• Continuité des tâches et instantanés : save-state --key <key> [--content <text>] [--ttl_seconds <0..604800>] (memory:write, alias: state-save), restore-state --key <key> (memory:read, alias: state-restore), state-save --key <key> [--content <text>] [--ttl_seconds <0..604800>] (alias hérité), state-restore --key <key> (alias hérité), restart-snapshot [--state_key <key>] [--session_id <id>] [--ttl_seconds <0..2592000>] (memory:write), restart-restore [--snapshot_id <id> | --source_session_id <id>] [--target_session_id <id>] (memory:read).
• Tâches à faire (TODOs) : todo-add --content <text> (memory:write), todo-list (memory:read), todo-done --id <todo_id> (memory:write).
• Grand livre financier et analyses : expense-add --item <text> --amount <number> --currency <code> (ledger:write), ledger-list [--month <YYYY-MM>] [--from <date>] [--to <date>] [--currency <code>] [--category <name>] [--type <type>] [--min-amount <n>] [--max-amount <n>] [--limit <n>] [--offset <n>] (ledger:read), ledger-summary [--months <n>] [--currency <code>] [--type <type>] (ledger:read), overview (memory:read), activity [--limit <n>] (memory:read), stats [--scope <scope>] [--path <path>] [--bucket <bucket>] [--memory-type <type>] [--status <status>] [--source <src>] [--since <iso>] [--until <iso>] [--group-by <dims>] [--top-n <1..200>] [--team-id <id>] (memory:read).
• Diagnostics et profilage : doctor [--anonymous] (aucun scope requis), profile [--status <later|never>] (aucun scope requis).

# Memory read and write operations:
node scripts/xmemo-skill.mjs remember --content "Production build uses node 22.22" --path "ops/build"
node scripts/xmemo-skill.mjs recall --query "build node version" --limit 3
node scripts/xmemo-skill.mjs read --id mem_01hxyz... --offset 0 --limit 1000
node scripts/xmemo-skill.mjs update --id mem_01hxyz... --content "Production build uses node 22.22.0 LTS"
node scripts/xmemo-skill.mjs forget --id mem_01hxyz... --confirm

# Context assembly with optional Knowledge inclusion:
node scripts/xmemo-skill.mjs recall-context --query "TLS root configuration" --include_knowledge true

# Task continuity and restart snapshots:
node scripts/xmemo-skill.mjs save-state --key active_task --content "Refactoring migration script"
node scripts/xmemo-skill.mjs restart-snapshot --state_key active_task --session_id sess_alpha_0928

# Ledger and analytics:
node scripts/xmemo-skill.mjs expense-add --item "Cloud hosting" --amount 120 --currency USD
node scripts/xmemo-skill.mjs overview
node scripts/xmemo-skill.mjs doctor

Codes de sortie déterministes

Toutes les commandes de la Skill autonome respectent des codes de sortie stricts et déterministes lors des exécutions interactives et programmatiques.

• Code 0 (Succès) : Opération réussie, ensembles de résultats vides valides renvoyés, --help ou --version.
• Code 1 (Erreur utilisateur) : Erreur de validation de paramètre, arguments mutuellement exclusifs, contenu dépassant 524 288 octets, absence du --confirm obligatoire sur forget, fichier d'entrée manquant/illisible ou réponse HTTP 4xx.
• Code 2 (Erreur d'authentification) : Identifiants manquants, jeton expiré ou non valide, HTTP 401 Unauthorized, HTTP 403 Forbidden ou échec de validation d'authentification doctor.
• Code 3 (Erreur serveur / réseau) : Réponse HTTP 5xx, échec de connexion réseau (ECONNREFUSED, ENOTFOUND, ETIMEDOUT) ou charge utile de réponse dépassant le plafond de sécurité (> 8 MiB).

Sécurité du contenu, talons de documents et confirmation de suppression

La Skill autonome applique des garde-fous stricts avant d'émettre des requêtes réseau afin de garantir la sécurité des données et la stabilité du client.

• Plafond d'écriture de 512 KiB : Le contenu de la mémoire est limité à 524 288 octets (MAX_MEMORY_CONTENT_BYTES). Les entrées dépassant ce plafond se terminent immédiatement avec le code 1 avant toute transmission de requête réseau.
• Sources d'entrée mutuellement exclusives : remember accepte --content <text>, --content - (stdin redirigé) ou --file <path>. Fournir plusieurs sources s'interrompt localement avec le code de sortie 1.
• Talons de mémoire adossés à des documents : Lorsque recall ou search correspond à des mémoires adossées à des documents, un talon compact d'une seule ligne est renvoyé (Document-backed memory: <title>). Transmettez --expand-documents pour étendre jusqu'à 3 talons et jusqu'à 20 000 caractères au total, ou utilisez read --id <id> pour une lecture paginée ciblée.
• Protection de confirmation obligatoire : forget --id <id> --confirm requiert strictement --confirm. L'omission de cette option s'interrompt localement avec le code de sortie 1 sans aucune requête réseau.
• Options d'exécution globales : Toutes les commandes acceptent --json (sortie JSON brute), --terminal (conserver le formatage lisible lors des redirections), --timeout-ms <ms>, --base-url <url> et --version.