MemTask CLI

MemTask CLI is the primary capture and handoff surface for local agents, IDE agents, terminal agents, CI jobs, scripts, and VM workers. It opens capture sessions, pushes context events, builds reviewable packets, scans them, approves versions, and dispatches approved packets to A2A, MCP, HTTP, API Markdown, or human fallback drivers.

Install

npm install -g @novator-ai/memtask-cli@latest

Upgrade an existing install:

memtask upgrade
memtask upgrade --run

During local development:

npm --workspace @novator-ai/memtask-cli run build
node packages/cli/dist/bin/memtask.js --help

Configure

memtask login --email [email protected]
memtask config show
memtask doctor

Use a non-default backend when testing:

memtask login --api-url https://YOUR_CONVEX_SITE.convex.site/cli/v1 --email [email protected]
memtask config set api-url https://YOUR_CONVEX_SITE.convex.site

api-url accepts either the root backend URL or the full /cli/v1 URL. The config file is stored at ~/.memtask/config.json with 0600 permissions. You can override it with MEMTASK_CONFIG.

Commands

memtask config show
memtask upgrade
memtask config set api-url https://mem-task.com
memtask config set gateway-url https://mem-task.com
memtask config unset worker
memtask inbox add --from notes.md
cat error.log | memtask inbox add --from - --workflow failure
memtask inbox list
memtask capture start --agent codex-local --task "debug production API timeout"
memtask capture push <capture-session-id> --type log --from error.log
memtask capture build <capture-session-id> --target coding-agent
memtask capture stop <capture-session-id>
agent-packet inspect <packet-id>
agent-packet scan <packet-id>
agent-packet approve <packet-id> --target coding-agent
agent-packet dispatch <packet-id> --approval <approval-id> --driver mcp
agent-packet export <packet-id> --format markdown
memtask inbox list
memtask review list
memtask review status <packet-id>
memtask run <packet-id> --preview
memtask run <packet-id> --wait
memtask packet pull <packet-id> --out packet.md
memtask packet pull <packet-id> --target coding-agent --out packet.md
memtask packet pull <packet-id> --target mcp --format json
memtask packet inspect <packet-id>
memtask packet inspect <packet-id> --target webhook
memtask packet delete <packet-id>
memtask result push <packet-id> --summary result.md --artifact patch.diff
memtask result accept <packet-id>
memtask agent connect --name "Local agent"
memtask agent run --exec 'your-agent-command'
memtask doctor --deep --json

Legacy room and public handoff url commands have been removed from the documented workflow. New workflows should use memtask capture ..., memtask agent ..., and agent-packet ....

Context packets

MemTask context packets use memtask.handoff_packet.v1 today and are moving toward the stricter Context Packet schema. The same captured task can be rendered for different consumers without exposing every message or artifact to every agent.

# Give a contractor a bounded markdown packet.
memtask packet pull <packet-id> --target human --out contractor-packet.md

# Export a coding-focused packet into a local agent.
agent-packet export <packet-id> --format markdown | codex exec -

# Give an MCP consumer structured JSON.
memtask packet pull <packet-id> --target mcp --format json --out packet.json
memtask packet delete <packet-id>

# Dispatch only after scan and approval.
agent-packet scan <packet-id>
agent-packet approve <packet-id> --target coding-agent
agent-packet dispatch <packet-id> --approval <approval-id> --driver webhook --endpoint https://example.com/memtask

# Inspect what will be included before sharing.
memtask packet inspect <packet-id> --target a2a

Targets:

• human: goal, boundaries, deliverables, safe context.
• agent: general external agent packet.
• coding-agent: technical context, files, errors, tests, acceptance checks.
• mcp: structured packet for tool input and memtask.submit_result style returns.
• webhook: callback-oriented packet with a result contract.
• a2a: agent-to-agent envelope with task states and review gates.

Every target includes Memory Firewall metadata, routing hints, guardrails, and a return-to-MemTask contract.

Supported workflow aliases:

• auto or omit --workflow
• support, support-to-code
• failure, failure-room
• founder, founder-ticket
• review, scope, bug, general

Worker Commands

Create an external-agent connection:

memtask worker connect --name "Local coding agent"

memtask agent connect is an alias for the same external-agent setup.

By default, worker connect stores the gateway token in ~/.memtask/config.json and prints only a masked preview. To export credentials for a VM or CI worker, run it in a trusted terminal with:

memtask worker connect --show-token

Rotate the token for the current connection, for example when a VM is polling with an old token:

memtask worker reconnect --show-token

Run a pull worker once:

memtask worker run --once --exec 'your-agent-command'

memtask agent run --exec 'your-agent-command' is the same pull-worker loop with agent-oriented naming.

MemTask pipes the scoped task packet to stdin and sends stdout back to the Web review queue. Any command-line agent can be used here as long as it can read from stdin or is wrapped by a small script. For older integrations, MEMTASK_PACKET_PATH is still available as a compatibility escape hatch.

Run continuously:

memtask worker run --exec 'your-agent-command'

Compatibility variables for wrapper authors. Most users do not need these because MemTask stores credentials and pipes the packet to stdin:

• MEMTASK_PACKET_PATH
• MEMTASK_INVOCATION_ID
• MEMTASK_STEP_ID
• MEMTASK_CONNECTION_ID
• MEMTASK_GATEWAY_BASE_URL

The command stdout becomes the result returned to Review. A non-zero exit code returns a failed result with stdout/stderr attached.

Reliability and environments

GET requests retry transient HTTP 408/429/5xx failures by default. Tune this with:

export MEMTASK_HTTP_RETRIES=3
export MEMTASK_HTTP_RETRY_BASE_MS=500

For production backend changes, update the API once:

memtask config set api-url https://YOUR_PRODUCTION_DOMAIN
memtask doctor --deep

For a separate worker gateway:

memtask config set gateway-url https://YOUR_GATEWAY_DOMAIN
memtask worker run --once --print-only

Replay a run:

memtask replay <run-id>
memtask replay <run-id> --json

Token handling

worker connect no longer prints the full gateway token by default. It stores the token in ~/.memtask/config.json and shows a masked preview. Use --show-token only in a trusted terminal when exporting credentials to a VM or CI secret manager.

Use worker reconnect --show-token to rotate the token for the current connection without creating another connection. Update the VM or CI secret store with the printed MEMTASK_GATEWAY_TOKEN, then restart the worker.

Publishing

After creating the npm org/scope:

npm login
npm --workspace @novator-ai/memtask-cli run prepublishOnly
npm --workspace @novator-ai/memtask-cli pack --dry-run
npm --workspace @novator-ai/memtask-cli publish --access public

If the npm scope changes, update packages/cli/package.json name first.