Skill 작업

Direct HTTPS 작업 및 인증 헤더

독립 실행형 Skill은 HTTPS를 통해 XMemo와 직접 통신합니다. 공개 REST 엔드포인트는 Authorization: Bearer <token> 또는 X-API-Key: <key> 헤더를 수락하며, 독립 실행형 Skill 런타임은 확인된 credential의 Authorization: Bearer <token>을 사용하여 아웃바운드 요청을 자동으로 포맷합니다.

• Skill 런타임 전송: https://xmemo.dev/v1/skill/operations에 대한 모든 요청에 Authorization: Bearer <token>을 자동으로 주입합니다.
• REST API 유연성: REST 엔드포인트를 직접 호출하는 독립형 HTTP 클라이언트는 Authorization: Bearer <token> 또는 X-API-Key: <key>를 제공할 수 있습니다.
• 검색 계약: 런타임 모델 및 작업 엔드포인트는 /.well-known/agent-discovery.json 및 /.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>

작업별 전체 명령어 목록

독립 실행형 Skill 패키지(v1.1.35)는 32개의 명령어를 제공합니다. 각 명령어는 help.mjs의 원본 사용법 문자열 및 필요한 인증 scope와 함께 아래에 나열되어 있습니다.

• 인증 및 설정: 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].
• 메모리 및 검색: 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 컨텍스트: 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).
• 작업 연속성 및 스냅샷: 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).
• 작업 TODO: todo-add --content <text> (memory:write), todo-list (memory:read), todo-done --id <todo_id> (memory:write).
• 재무 원장 및 분석: 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).
• 진단 및 프로파일링: 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

결정론적 종료 코드

모든 독립 실행형 Skill 명령어는 대화형 및 프로그래밍 방식 실행 전반에서 엄격하고 결정론적인 종료 코드를 준수합니다.

• 코드 0 (성공): 작업이 성공했거나 유효한 빈 결과 집합이 반환됨, --help 또는 --version.
• 코드 1 (사용자 오류): 매개변수 유효성 검사 오류, 상호 배타적인 인수, 524,288바이트를 초과하는 콘텐츠, forget 시 필수 --confirm 누락, 입력 파일 누락/읽기 불가 또는 HTTP 4xx 응답.
• 코드 2 (인증 오류): credential 누락, 만료되었거나 유효하지 않은 토큰, HTTP 401 Unauthorized, HTTP 403 Forbidden 또는 doctor 인증 유효성 검사 실패.
• 코드 3 (서버 / 네트워크 오류): HTTP 5xx 응답, 네트워크 연결 실패(ECONNREFUSED, ENOTFOUND, ETIMEDOUT) 또는 안전 상한을 초과하는 응답 페이로드(> 8 MiB).

콘텐츠 안전성, 문서 스터브 및 삭제 확인

독립 실행형 Skill은 데이터 안전성과 클라이언트 안정성을 보장하기 위해 네트워크 요청을 발행하기 전에 엄격한 가드레일을 적용합니다.

• 512 KiB 쓰기 상한: 메모리 콘텐츠는 524,288바이트(MAX_MEMORY_CONTENT_BYTES)로 제한됩니다. 이 상한을 초과하는 입력은 네트워크 요청이 전송되기 전에 코드 1로 즉시 종료됩니다.
• 상호 배타적인 입력 소스: remember 명령은 --content <text>, --content -(파이프된 stdin) 또는 --file <path>를 수락합니다. 둘 이상의 소스를 제공하면 종료 코드 1로 로컬에서 중단됩니다.
• 문서 기반 메모리 스터브: recall 또는 search가 문서 기반 메모리와 일치하면 한 줄로 된 간결한 스터브(Document-backed memory: <title>)를 반환합니다. 최대 3개의 스터브와 총 최대 20,000자까지 확장하려면 --expand-documents를 전달하거나, 대상 지정 페이지 매김 읽기에는 read --id <id>를 사용하십시오.
• 필수 확인 가드: forget --id <id> --confirm 명령에는 엄격하게 --confirm 플래그가 필요합니다. 이 플래그를 생략하면 네트워크 요청 없이 종료 코드 1로 로컬에서 중단됩니다.
• 전역 실행 옵션: 모든 명령은 --json(원시 JSON 출력), --terminal(파이프 시 사용자에게 친숙한 형식 유지), --timeout-ms <ms>, --base-url <url> 및 --version을 수락합니다.