Skill-Operationen

Direkte HTTPS-Operationen und Authentifizierungs-Header

Die eigenständige Skill kommuniziert direkt über HTTPS mit XMemo. Öffentliche REST-Endpunkte akzeptieren entweder Authorization: Bearer <token>- oder X-API-Key: <key>-Header, während die eigenständige Skill-Laufzeitumgebung ausgehende Anfragen automatisch mit Authorization: Bearer <token> aus den aufgelösten Anmeldedaten formatiert.

• Transport der Skill-Laufzeitumgebung: Injiziert automatisch Authorization: Bearer <token> in alle Anfragen an https://xmemo.dev/v1/skill/operations.
• Flexibilität der REST-API: Eigenständige HTTP-Clients, die REST-Endpunkte direkt aufrufen, können entweder Authorization: Bearer <token> oder X-API-Key: <key> bereitstellen.
• Erkennungsvertrag: Laufzeitmodell- und Operations-Endpunkte können unter /.well-known/agent-discovery.json und /.well-known/memory-os.json ermittelt werden.

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

Vollständiges Befehlsinventar nach Aufgabe

Das eigenständige Skill-Paket (v1.1.35) stellt 32 Befehle bereit. Jeder Befehl ist unten mit seiner unveränderten Syntaxzeichenfolge aus help.mjs und dem erforderlichen Autorisierungs-Scope aufgeführt.

• Authentifizierung & Einrichtung: 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].
• Speicher & Suche: 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).
• Knowledge-Kontext: 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).
• Aufgabenkontinuität & 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).
• Aufgaben-TODOs: todo-add --content <text> (memory:write), todo-list (memory:read), todo-done --id <todo_id> (memory:write).
• Finanzbuchhaltung & Analysen: 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).
• Diagnose & Profiling: doctor [--anonymous] (no scope required), profile [--status <later|never>] (no scope required).

# 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

Deterministische Exit-Codes

Alle eigenständigen Skill-Befehle folgen bei interaktiven und programmatischen Ausführungen strengen, deterministischen Exit-Codes.

• Code 0 (Erfolg): Vorgang erfolgreich abgeschlossen, gültige leere Ergebnissätze zurückgegeben, --help oder --version.
• Code 1 (Benutzerfehler): Parameterüberprüfungsfehler, sich gegenseitig ausschließende Argumente, Inhalt über 524.288 Bytes, fehlendes obligatorisches --confirm bei forget, fehlende/unlesbare Eingabedatei oder HTTP-4xx-Antwort.
• Code 2 (Authentifizierungsfehler): Fehlende Anmeldedaten, abgelaufenes oder ungültiges Token, HTTP 401 Unauthorized, HTTP 403 Forbidden oder Authentifizierungsfehler bei doctor.
• Code 3 (Server- / Netzwerkfehler): HTTP-5xx-Antwort, Netzwerkverbindungsfehler (ECONNREFUSED, ENOTFOUND, ETIMEDOUT) oder Antwort-Payload überschreitet Sicherheitsgrenze (> 8 MiB).

Inhaltssicherheit, Dokument-Stubs und Löschbestätigung

Die eigenständige Skill setzt vor dem Absenden von Netzwerkanfragen strenge Sicherheitsmechanismen durch, um Datensicherheit und Client-Stabilität zu gewährleisten.

• 512-KiB-Schreibgrenze: Speicherinhalte sind auf 524.288 Bytes (MAX_MEMORY_CONTENT_BYTES) beschränkt. Eingaben, die diese Obergrenze überschreiten, werden sofort mit Code 1 beendet, bevor eine Netzwerkanfrage gesendet wird.
• Sich gegenseitig ausschließende Eingabequellen: remember akzeptiert --content <text>, --content - (über Pipe übergebenes stdin) oder --file <path>. Das Bereitstellen mehrerer Quellen bricht lokal mit Exit-Code 1 ab.
• Dokumentgestützte Speicher-Stubs: Wenn recall oder search dokumentgestützte Speicher findet, wird ein kompakter einzeiliger Stub zurückgegeben (Document-backed memory: <title>). Übergeben Sie --expand-documents, um bis zu 3 Stubs und insgesamt bis zu 20.000 Zeichen zu erweitern, oder verwenden Sie read --id <id> für gezieltes paginiertes Lesen.
• Obligatorischer Bestätigungsschutz: forget --id <id> --confirm erfordert zwingend --confirm. Das Weglassen dieses Flags bricht lokal mit Exit-Code 1 und ohne Netzwerkanfragen ab.
• Globale Ausführungsoptionen: Alle Befehle akzeptieren --json (rohe JSON-Ausgabe), --terminal (menschliches Format bei Pipes beibehalten), --timeout-ms <ms>, --base-url <url> und --version.