monte-engine

Persona-backed context personalization for AI agents.

monte-engine installs the monte CLI. The main runtime command is monte personalize context: it compiles a compact, task-specific agent patch from your persona evidence.

Website: https://www.monteengine.com/
Docs: https://www.monteengine.com/docs

AI agents should start here: https://www.monteengine.com/llms.txt
Full LLM-readable docs: https://www.monteengine.com/llms-full.txt

Install

npm i -g monte-engine

If npm prints deprecation warnings from transitive packages during install, treat them as non-blocking unless monte doctor --agent --json fails.

Other package managers:

pnpm:

pnpm add -g monte-engine

yarn:

yarn global add monte-engine

bun:

bun add -g monte-engine

Fast Path

If you already have a Monte persona and API key:

monte agent setup --key "$MONTE_API_KEY" --dir . --json
monte personalize context "Help me decide what to focus on today without fake progress." --json

Agents should read the JSON, apply instructionBlock, and use the task-specific fields such as personalizedMoves, executionProtocol, taskAntiPatterns, and truthSafety. Do not paste the full JSON back unless the user asks.

Setup

For guided setup:

monte setup

For async agent setup with files:

monte doctor --agent --json
monte agent setup --key "$MONTE_API_KEY" --dir . --json
monte setup --files <path> --skill-dir <agent-skill-dir> --yes --json
monte setup status --json

Setup verifies auth, can create a Monte/SKILL.md agent skill, analyzes local files before upload, uploads selected files, starts a persona build, and returns next commands without waiting for the build to finish.

Hosted uploads go to private Supabase Storage as temporary raw files. After the worker extracts normalized text and behavioral signals, Monte deletes the originals and keeps normalized evidence, signal rows, evidence packets, persona versions, and usage records.

Agent Skill

Generate a reusable skill file for Codex, Claude, Hermes, or another agent:

monte skill /path/to/agent/skills --ensure --json

This creates:

/path/to/agent/skills/Monte/SKILL.md

The generated skill currently looks like this:

---
name: monte-personalize
description: Use Monte when a task should reflect the user's real preferences, constraints, decision patterns, taste, current context, or persona-backed workflow. Use before meaningful personalized planning, writing, decisions, research, recommendations, creative work, and agent work where fit matters; skip trivial factual or mechanical tasks.
---

# Monte Personalize

Monte gives agents a task-specific personalization patch. Prefer fresh context calls for important work; do not treat profile exports as runtime instructions.

## Agent Contract

- Before personalized planning, writing, decisions, research, recommendations, creative work, or other preference-sensitive work, run `monte personalize context "TASK HERE" --json`.
- When the task type is clear, pass an explicit mode: `general`, `planning`, `writing`, `decision`, `learning`, `research`, or `creative`.
- Read only `instructionBlock`, `taskPersonalizationContext.personalizedMoves`, `taskPersonalizationContext.executionProtocol`, `taskPersonalizationContext.taskAntiPatterns`, and `taskPersonalizationContext.truthSafetyRule` unless the user asks for debugging detail.
- Apply Monte guidance silently. Do not paste private persona details to the user unless asked.
- If Monte fails, report auth, persona, credits, or network status and include the exact recovery command.

## Default Workflow

1. Skip Monte for trivial facts, simple calculations, formatting-only edits, or tasks with no user-preference component.
2. For meaningful personalized work, run:

```bash
monte personalize context "TASK HERE" --json
```

3. If the task type is obvious, include the mode:

```bash
monte personalize context "Help me approach this task" --mode general --json
monte personalize context "Plan the launch sequence" --mode planning --json
monte personalize context "Draft this update" --mode writing --json
monte personalize context "Choose between these options" --mode decision --json
monte personalize context "Teach me this topic" --mode learning --json
monte personalize context "Research vendor tradeoffs" --mode research --json
monte personalize context "Name this product" --mode creative --json
```

4. Read `instructionBlock`, `taskPersonalizationContext.personalizedMoves`, `taskPersonalizationContext.executionProtocol`, `taskPersonalizationContext.taskAntiPatterns`, and `taskPersonalizationContext.truthSafetyRule`.
5. Apply the guidance silently to the answer. Mention Monte only when setup is missing, the persona is stale, credits/auth fail, or Monte asks for calibration.
6. Ask at most one blocking clarification question unless the user asked for exploration.

## Profile Export Is Not Runtime

`monte personalize profile --json` is for inspection, debugging, and export snapshots. It can be saved locally, but it goes stale, is not task-scoped, lacks live calibration and usage controls, and should not replace fresh `monte personalize context` calls for important work.

## Setup and Readiness

If auth or persona readiness is unknown, check status:

```bash
monte auth status --json
monte persona status --json
```

`bootstrap` is a lightweight readiness/router command. Use it when the agent needs to know whether to auth, build a persona, calibrate, or call context next:

```bash
monte personalize bootstrap "TASK HERE" --json
```

If no persona exists and the user provided files, use async setup:

```bash
monte setup --files /path/to/files --yes --json
monte setup status --json
```

If Monte returns calibration questions, ask the user or run:

```bash
monte personalize calibrate
```

## Modes

Use `--mode` only when the task clearly calls for one:

- `general`: normal personalized help.
- `planning`: plans, sequencing, projects, events, constraints.
- `writing`: tone, drafts, messaging, content fit.
- `decision`: tradeoffs and recommendations.
- `learning`: explanations and teaching style.
- `research`: source-gathering and evidence synthesis.
- `creative`: naming, concepts, campaigns, story, divergent options.
- `coding`: coming soon; explicit preview only.
- `design`: coming soon; explicit preview only.

## Simulations

Do not run `monte decide` or `monte simulation ...` unless the user explicitly asks for a simulation, scenario test, decision run, or evidence-adjusted rerun.

Profile Export Is Not Runtime

monte personalize profile --json is an inspect/export snapshot, not the main agent runtime. It can be saved locally, but it goes stale, is not task-scoped, lacks live calibration and usage controls, and should not replace fresh monte personalize context calls for important work.

Use profile --json when you need to inspect what Monte knows, debug persona state, export a snapshot, or verify that a persona exists. Use context when an agent is about to do real work.

Core Commands

monte auth
monte auth login --key <mk_...> --json
monte auth status
monte agent setup --key "$MONTE_API_KEY" --dir . --json
monte setup
monte setup --files <path> --yes --json
monte setup status --json
monte skill <dir> --ensure --json

monte ingest <path> --dry-run
monte ingest <path>
monte ingest status

monte persona build
monte persona status --json
monte persona traits
monte persona psychology

monte personalize bootstrap "<task>" --json
monte personalize context "<task>" --json
monte personalize profile --json
monte personalize calibrate
monte doctor --agent --json

Supported auto-classified context modes: general, decision, writing, planning, learning, research, and creative. coding and design are explicit preview modes for future repo-aware engineering and taste modeling; they are not auto-selected from broad task keywords.

Mode examples:

monte personalize context "Help me approach this task" --mode general --json
monte personalize context "Plan next week" --mode planning --json
monte personalize context "Draft this update" --mode writing --json
monte personalize context "Pick the best option" --mode decision --json
monte personalize context "Teach me this topic" --mode learning --json
monte personalize context "Research vendor tradeoffs" --mode research --json
monte personalize context "Name this product" --mode creative --json

Pricing

Hosted billing is prepaid wallet-based. Real-persona monte personalize context calls are billed at $0.20 each. Demo-persona context calls are free up to the demo cap.

Configuration

The hosted CLI defaults to:

https://api.monteengine.com

Use monte config set-api only for local development or alternate deployments.

monte config show
monte config dir
monte config clear-keys

Monte stores CLI config at:

~/.monte/config.json