# Operações do Skill

Revise o catálogo de operações do Skill independente, os escopos necessários, os códigos de saída determinísticos e os limites de runtime.

- Canonical: https://docs.xmemo.dev/pt-br/docs/skills/operations
- Locale: pt-BR
- Content-Locale: pt-BR
- Canonical-Content-Digest: 6dd1506da83ca3c235a2b184eef2543b5c83a2510312e734028559bf4772ef75
- Edition-Digest: b5a7fe6a87b2986a1a9bd564907ade56fb0b0ebc1cde67f4730970ece3b0c691
- Source-Revision: sha256:7b422494897f606128295ed70568337bc1353a0d7822638452970f4081f9e0ef

## Operações HTTPS diretas e cabeçalhos de autenticação

O Skill independente se comunica diretamente com o XMemo por HTTPS. Os endpoints REST públicos aceitam cabeçalhos Authorization: Bearer <token> ou X-API-Key: <key>, enquanto o runtime do Skill independente formata automaticamente as solicitações de saída usando Authorization: Bearer <token> da credencial resolvida.

- Transporte do runtime do Skill: Injeta automaticamente Authorization: Bearer <token> em todas as solicitações para https://xmemo.dev/v1/skill/operations.
- Flexibilidade da API REST: Clientes HTTP independentes que chamam endpoints REST diretamente podem fornecer Authorization: Bearer <token> ou X-API-Key: <key>.
- Contrato de descoberta: O modelo de runtime e os endpoints de operações podem ser descobertos em /.well-known/agent-discovery.json e /.well-known/memory-os.json.

```http
# 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>
```

## Inventário completo de comandos por tarefa

O pacote do Skill independente (v1.1.35) fornece 32 comandos. Cada comando é listado abaixo com sua string de uso literal de help.mjs e seu escopo de autorização necessário.

- Autenticação e configuração: 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].
- Memória e busca: 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 or 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).
- Contexto 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).
- Continuidade de tarefas e snapshots: 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>] (legacy alias), state-restore --key <key> (legacy alias), 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).
- Tarefas pendentes (TODOs): todo-add --content <text> (memory:write), todo-list (memory:read), todo-done --id <todo_id> (memory:write).
- Livro-razão financeiro e análises: 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).
- Diagnósticos e criação de perfil: doctor [--anonymous] (no scope required), profile [--status <later|never>] (no scope required).

```bash
# 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
```

## Códigos de saída determinísticos

Todos os comandos do Skill independente seguem códigos de saída estritos e determinísticos em execuções interativas e programáticas.

- Código 0 (Sucesso): Operação bem-sucedida, conjuntos de resultados vazios válidos retornados, --help ou --version.
- Código 1 (Erro do usuário): Erro de validação de parâmetro, argumentos mutuamente exclusivos, conteúdo superior a 524.288 bytes, ausência do --confirm obrigatório no forget, arquivo de entrada ausente/ilegível ou resposta HTTP 4xx.
- Código 2 (Erro de autenticação): Credenciais ausentes, token expirado ou inválido, HTTP 401 Unauthorized, HTTP 403 Forbidden ou falha na validação de autenticação do doctor.
- Código 3 (Erro de servidor / rede): Resposta HTTP 5xx, falha na conexão de rede (ECONNREFUSED, ENOTFOUND, ETIMEDOUT) ou payload de resposta excedendo o teto de segurança (> 8 MiB).

## Segurança de conteúdo, stubs de documentos e confirmação de exclusão

O Skill independente aplica proteções rígidas antes de emitir solicitações de rede para garantir a segurança dos dados e a estabilidade do cliente.

- Teto de gravação de 512 KiB: O conteúdo da memória é limitado a 524.288 bytes (MAX_MEMORY_CONTENT_BYTES). Entradas que excedem esse teto saem imediatamente com o código 1 antes de qualquer solicitação de rede ser despachada.
- Fontes de entrada mutuamente exclusivas: remember aceita --content <text>, --content - (stdin canalizado) ou --file <path>. Fornecer mais de uma fonte é abortado localmente com código de saída 1.
- Stubs de memória apoiados por documentos: Quando recall ou search corresponde a memórias apoiadas por documentos, retorna um stub compacto de linha única (Document-backed memory: <title>). Passe --expand-documents para expandir até 3 stubs e até 20.000 caracteres no total, ou use read --id <id> para leitura paginada direcionada.
- Proteção de confirmação obrigatória: forget --id <id> --confirm exige estritamente --confirm. Omitir essa flag é abortado localmente com o código de saída 1 e zero solicitações de rede.
- Opções de execução globais: Todos os comandos aceitam --json (saída JSON bruta), --terminal (preservar a formatação humana quando canalizado), --timeout-ms <ms>, --base-url <url> e --version.