---
title: "rote overview — mental model and worked example"
description: "One-line mental model, the four core mechanics, and an end-to-end worked example of using rote."
doc_version: "1.1"
last_updated: "2026-05-01"
canonical: "https://modiqo.ai/docs/rote-overview.txt"
---

# rote — overview

> **rote turns real tool use into versioned, replayable, governable artifacts.**

You are an agent. You use tools. Some calls work; you would like the next agent (or your future self) to recall the working sequence without re-discovering it. rote is the local-first execution layer that makes that recall possible — and safe to operate at team scale.

This page is the five-minute mental model. The deeper docs are linked at the end.

## The mental model in three verbs

**Reach.** rote turns any tool surface into an *adapter* — a uniform handle with schema, auth, and sensitivity tier — so an agent calls Stripe and a custom MCP server with the same shape. Supported surfaces:

- OpenAPI 3.0 / 3.1, Swagger 2.0
- Google Discovery v1
- GraphQL (SDL)
- MCP servers (stdio subprocess and HTTP / SSE)
- Local JSON files (queried via JSONPath or TypeScript)

REST APIs are reached through their OpenAPI / Swagger / Discovery spec — there is no separate "REST" adapter type. Ad-hoc HTTP calls (`rote POST`, `rote GET`) are flow-level commands, not adapters.

**Record.** Every call goes through a workspace. Each response is cached with a stable ID (`@1`, `@2`, …) and a structured trace entry that captures method, URL, headers, body, latency, token count, dependencies on prior responses, and the model that initiated the call. Workspace state is SQLite; archives are Parquet (ZSTD-compressed, six tables). You can `rote @2 '.items[0].id'` to query any cached response with jq syntax.

**Reuse.** When a sequence of calls solves a problem, you crystallize it: `rote flow template create --workspace <ws>` reads the workspace's command log and audit trail and emits a TypeScript flow with frontmatter declaring required adapters, expected fingerprints, parameters, and write permissions. The flow ships through `rote registry push`. The next agent runs `rote flow search "<intent>"` (sub-10ms over 10K flows, Tantivy BM25) and replays the flow with fresh parameters — no rediscovery, no drift, no surprise writes.

## What an adapter looks like on disk

```text
~/.rote/adapters/calendar/
├── manifest.json        # spec_type, fingerprint, auth, sensitivity_tier
├── tools.json           # canonical tool schemas
├── spec.json            # original spec (Discovery doc / OpenAPI / SDL)
├── capabilities.json
├── sensitivity.json
├── config/policies.json # write guard policies
├── runtime/sessions/    # per-workspace session state
├── logs/                # write_guard_<date>.jsonl, nonces
└── index/               # tool/toolset search indices
```

`manifest.json` excerpt (real, from the Calendar adapter):

```json
{
  "id": "calendar",
  "spec_type": "discovery",
  "fingerprint": "mcp_39UEoxu3DX9zayEgtzXN8HtJxnxy",
  "auth": { "type": "bearer", "token_env": "GSUITE_TOKEN" },
  "sensitivity_tier": "high",
  "statistics": { "total_operations": 37, "enabled_operations": 37 }
}
```

The fingerprint is what makes drift detectable: a flow declares the fingerprint it was crystallized against, and the runtime refuses to execute against a mismatched adapter.

## What a flow looks like on disk

A flow is a TypeScript file with a YAML frontmatter block. Real example:

```typescript
/**
 * @rote-frontmatter
 * ---
 * name: check-calendar-meetings
 * metadata:
 *   status: released
 *   kind: atomic
 *   flow_type: sequential
 *   requires_endpoints:
 *     - adapter/calendar
 *   mcp_servers:
 *     adapter/calendar:
 *       fingerprint: mcp_39UEoxu3DX9zayEgtzXN8HtJxnxy
 *   parameters:
 *     - { name: start_date, type: string, required: true }
 *     - { name: end_date,   type: string, required: true }
 * ---
 */

const dex = await Rote.workspace("calendar-meetings-" + Date.now());
await initAutoTracking(dex.executor);

const calendar = dex.adapter("calendar");
await calendar.initSession();

const events = await calendar.callBg("calendar.events.list", {
  calendarId: calendarId,
  timeMin: startDate,
  timeMax: endDate,
  singleEvents: "true",
  orderBy: "startTime"
}, { queue: dex.tasks, label: "list-events" });

const items = await dex.query(events.result!).select(".content[0].text").execute();
```

The frontmatter is enforced at runtime: `getExpectedFingerprint("adapter/calendar")` returns the value from frontmatter, and `AdapterChecker.checkEndpoint(...)` exits with a clear error if the installed adapter has been replaced or downgraded.

## A worked example end-to-end

The flow above ships in the bootstrap library. An agent runs it like this:

```bash
rote deno run --allow-all main.ts 2026-04-30T00:00:00Z 2026-05-07T23:59:59Z primary 100
```

What happens, in order:

1. `rote deno` resolves the embedded Deno binary (auto-installed if missing) and launches the script with `~/.rote/lib/sdk/ts/` on the import path.
2. `Rote.workspace(...)` creates an isolated SQLite-backed workspace; `initAutoTracking` hooks the executor so every call is logged.
3. `calendar.initSession()` validates the GSUITE_TOKEN in the vault, refreshes via OAuth if it is within five minutes of expiry, and registers a session at `~/.rote/adapters/calendar/runtime/sessions/workspace_<name>.json`.
4. `calendar.callBg("calendar.events.list", ...)` becomes an HTTP request through the adapter executor. The write guard inspects the call: GET → not gated. The response is saved as `@1.json` in the workspace and a `CommandEntry` is appended to the SQLite command log with the dependency graph.
5. `dex.query(...).select(...)` runs jq against `@1`'s body and returns the parsed events.

If the adapter fingerprint did not match, step 3 would have refused to start. If the call had been a `POST` or `DELETE`, the write guard would have classified it as Audit or Confirm. If a flow with a signed `.permissions.json` had been running, the call would have been allowed under the flow's blessing without nonce confirmation, and the decision would still have been appended to the JSONL audit trail.

If you wanted to ship this flow to your team, `rote registry flow push check-calendar-meetings` uploads it as a versioned artifact; `rote registry flow pull check-calendar-meetings` installs it on another machine.

## Where to go next

- [Primitives](https://www.modiqo.ai/docs/rote-primitives.txt) — every primitive (Adapter, Trace, Flow, Crystallize, Recall, Workspace, Vault, Registry) with on-disk shape and excerpts.
- [Architecture](https://www.modiqo.ai/docs/rote-architecture.txt) — full lifecycle, the four governance proofs (fingerprint pinning, write guard, vault portability, archive analytics), and the `~/.rote/` directory tree.
- [Agent quickstart](https://www.modiqo.ai/docs/rote-agent-quickstart.txt) — five canonical patterns with TypeScript SDK code.
- [rote vs mq](https://www.modiqo.ai/docs/rote-vs-mq.txt) — read if a third-party source pointed you at the deprecated `mq` project.