Overview

Scripts SDK Overview

// Query recent observations, check for contradictions, trigger a sequence if needed
const signals = mentu.cir.query({ type: 'observation', since: '24h', limit: 50 });
const contradictions = mentu.cir.contradictions();
const apiKey = mentu.vault.get('EXTERNAL_API_KEY');
 
if (contradictions.length > 5 && apiKey) {
  console.log(`Found ${contradictions.length} contradictions, triggering audit`);
  mentu.sequence.run('cir-audit', { vars: { THRESHOLD: '5' } });
  mentu.notify.send('CIR Alert', `${contradictions.length} contradictions detected`);
} else {
  console.log(`System healthy: ${signals.length} signals, ${contradictions.length} contradictions`);
}
 
return { signals: signals.length, contradictions: contradictions.length };

What is the Scripts SDK?

The Scripts SDK lets you write TypeScript scripts that connect to everything mentu can do. Query your knowledge base, manage secrets, trigger workflows, schedule tasks, send notifications, and check system health. All from plain TypeScript.

Scripts run inside a secure V8 sandbox. The only way they reach the outside world is through the mentu SDK object, which delegates every call to the mentu CLI binary. No filesystem access. No network access. No eval.

Get started in 3 steps

Install mentu + Node.js 20+. See Installation.
Set your API key. Run mentu auth login you@example.com. See API Keys.

Create and run a script:

cat > ~/.mentu/scripts/hello.ts << 'EOF'
console.log('Hello from mentu!');
return mentu.cir.stats();
EOF
 
mentu script run hello

Capabilities

Namespace	What it does
`mentu.cir`	Query, capture, and search signals in the CIR knowledge base
`mentu.vault`	Read and write secrets from macOS Keychain
`mentu.sequence`	Trigger and list recipe sequences
`mentu.temporal`	Manage scheduled tasks
`mentu.ledger`	Verify ledger integrity
`mentu.notify`	Send macOS desktop notifications
`mentu.webhook`	Register, list, test, and delete webhooks on api.mentu.ai
`mentu.worker`	Deploy and manage Cloudflare Workers
`mentu.ratchet`	Check code quality ratchets against baselines
`mentu.plugin`	List loaded plugins and their hooks
`mentu.dispatch`	Dispatch async commands via CIR execution queue
`mentu.health`	Run system health checks
`mentu.vars`	Read-only runtime variables from `--var` flags
`mentu.workspace`	Workspace path (`{ path: string }`)

Scripts can also access MCP servers via the servers proxy:

const result = await servers.crawlio.call('search_api', { query: 'test' });

Script vs recipe vs sequence

	Script	Recipe	Sequence
Language	TypeScript	JSON template	JSON manifest
Logic	Imperative (conditionals, loops, composition)	Declarative (single prompt)	Declarative (ordered step list)
Best for	Complex workflows, conditional branching, API composition	Single-shot LLM tasks	Multi-step LLM pipelines
Runtime	V8 sandbox (Node.js)	mentu CLI	mentu CLI
Access	All SDK namespaces + MCP servers	LLM context only	LLM context + step variables

Use scripts when you need imperative logic: if/else branching, loops, composing multiple CIR queries, reading vault secrets to decide what to do next, or calling external services through MCP.

Use recipes for single LLM prompts with template variables.

Use sequences to chain multiple recipes into a pipeline where each step's output feeds the next.

Security model

Scripts execute in a V8 sandbox with deny-all defaults:

No filesystem access. require, fs, process, __dirname are not available.
No network access. fetch, http, net are not available.
No code generation. eval() and new Function() throw EvalError.
Frozen prototypes. Object.prototype and Array.prototype are sealed, Function.prototype is frozen.
Output limits. 50KB code size, 10MB output cap.
Timeout enforcement. Configurable per-script (default 300s), 30s cap per sleep() call.

The only way scripts reach external systems is through the mentu SDK (which shells out to the CLI binary) or the servers proxy (which routes through the MCP child manager). Both are injected as frozen globals that scripts cannot modify.

See Script Runner for full internals.

PreviousSet Your API Key NextSDK Reference