mnemom agent

mnemom agent launches your coding-agent CLI (Claude Code today) with its model traffic routed through the Mnemom gateway. Every session runs under a governed agent identity, shows up in your traces, and can carry a sealed per-session goal contract that the gateway grades each turn against and re-anchors the agent when it drifts. It is designed to be one command: install once, then mnemom agent.

Install once

npm install -g @mnemom/mnemom
mnemom login

Access to mnemom agent is still by invitation (see below). mnemom login opens a browser sign-in (device-code fallback on headless machines); set MNEMOM_API_KEY instead for CI. The CLI keeps itself up to date in the background. If the Mnemom API needs a newer CLI than the one you run, the CLI stops. In an interactive terminal, with a plain npm install -g install and auto-update on (the default), it updates itself and asks you to run the command again. Otherwise (CI, scripts, piped output, or other installs) it prints the upgrade command, npm i -g @mnemom/mnemom@latest, for you to run. See Updates.

You need a coding-agent CLI to launch. Install Claude Code first (claude on your PATH), or point at any install with --cli <name|/full/path>.

Redeem an invitation

Mnemom Agent is rolling out to an invited cohort. If you received an invitation, redeem it once:

mnemom agent --invite <token>

That signs you in (or creates your Mnemom account), unlocks Mnemom Agent for your organization, and credits your starter µ. mnemom agent invite <token> does the same as a sub-verb. Without an invitation, mnemom agent stops before launching anything. It says Mnemom Agent isn’t enabled for your organization yet and shows how to redeem an invitation. Nothing is started or charged. To request an invitation, contact us at mnemom.ai/contact. mnemom agent doctor shows the same access check. Mnemom staff (@mnemom.ai accounts) are enabled by default and skip this step.

Run

cd your-project
mnemom agent

With no arguments in a terminal, mnemom agent asks for one thing and then launches: a session name, which labels the session in your traces and in mnemom agent sessions. Enter takes the current folder name. Goal alignment is not prompted for. Pass --goal to turn it on: the gateway seals your one-line goal as a contract and nudges the agent back when it drifts, for a little µ per turn. Without --goal the session runs governed with goal alignment off. Either way the launch prints goal alignment: on or off. Skip the prompt when you already know what you want:

mnemom agent fix-auth                                    # named, no goal
mnemom agent fix-auth --goal "make login work on Safari" # named, goal on

Non-interactive runs (pipes, CI) never prompt; they need a session name. Before Claude Code starts, mnemom agent makes sure the agent the session runs as is claimed in your org (see Your governed agent). It never starts a session on an unclaimed agent. Your first launch in a terminal can also ask two one-time questions:

How Claude Code should sign in to Anthropic, when there is a choice. See Sign-in options.
Whether to look at what Mnemom would have saved on your recent sessions. See Savings estimates.

Permission prompts

By default, mnemom agent starts Claude Code with --dangerously-skip-permissions, so Claude Code does not ask before it edits files or runs commands. Claude Code calls this Bypass Permissions mode. The first time, it shows a warning and asks you to accept it before the session starts. Claude Code recommends this mode only in a sandboxed container or VM. To keep Claude Code’s permission prompts, pass --no-yolo:

mnemom agent fix-auth --no-yolo

--no-yolo applies to that launch only; there is no saved setting for it, so pass it on every launch where you want the prompts. mnemom agent --dry-run shows which mode a launch would use (yolo: on or off).

Resume a session

Each mnemom agent launch starts a new Claude Code session, even when you reuse a session name. To pick up where you left off, relaunch through mnemom agent and pass Claude Code’s resume flag after --:

mnemom agent fix-auth -- --continue             # the most recent session in this folder
mnemom agent fix-auth -- --resume <session-id>  # a specific session

When Claude Code exits normally, the last line mnemom agent prints is the command to resume it, for example:

Resume with: mnemom agent fix-auth -- --resume <session-id>  (keeps it governed; `claude --resume` runs outside Mnemom)

If you named an agent with --agent, the command includes it. mnemom agent show <name> prints the same command.

Claude Code prints its own hint just above that line: claude --resume <session-id>. Do not run that command: it reopens the conversation outside Mnemom, with no governance, no µ billing and nothing in your traces. Use the mnemom agent command instead.

The resumed session runs governed, like any other launch, and the conversation carries on where it stopped. Resuming with -- --resume <session-id> or -- --continue keeps that session’s context profile unless you pass --context-profile (CLI 0.17.12 and later; earlier versions keep it only on --resume <session-id>). If the session has no recorded profile, or there is no earlier session in this folder, your default profile applies (see Context profiles). A sealed goal does not carry over: pass --goal again to seal one for the resumed session. If you have turned on implicit goal mode, relaunching an implicit session by the same name asks “Resume previous session?”. Answer yes to continue that session and its inferred goal. See Implicit goal mode for details.

Implicit goal mode (experimental)

A sealed goal (--goal) is one way to turn on goal alignment. The other is implicit mode: no statement to write up front — the gateway infers the goal from your messages and revises it as you steer. Guardrail ceilings (--max-turns, --budget, --stall) still apply. Implicit mode is an experimental, opt-in feature. It is never on by default, on any cell, including cells where the gateway supports it. It runs only after you opt in. Experimental features may change or be removed in any release, with no deprecation period. To opt in, turn on the experimental feature:

mnemom experimental enable implicit   # opt in (stored in ~/.mnemom/config.json)
mnemom experimental list              # see every experimental feature and whether it is on

Once you have opted in, a launch with no --goal runs in implicit mode:

mnemom agent fix-auth                 # goal alignment on, implicit, nothing sealed
mnemom agent fix-auth --no-implicit   # goal alignment off for this launch

To use implicit mode only on the launches where you ask for it, also run mnemom agent config set goal_mode off (or set goal_mode = "off" in ~/.mnemom/launcher.toml), then pass --implicit on those launches. To opt out, run mnemom experimental disable implicit. Until you opt in, --implicit is refused with a pointer to mnemom experimental enable implicit, and a saved goal_mode = "implicit" is ignored with the same pointer. --implicit cannot be combined with --goal/--requirement/--allow/--forbid/--goal-id — a sealed contract always wins on the gateway, so the launch refuses the combination rather than silently ignore --implicit. With the feature on, mnemom agent goal reads and steers the inferred goal of a session:

mnemom agent goal show [ref]          # the live inferred goal (add --history for revisions)
mnemom agent goal pin [ref]           # stop new messages revising it (--off unpins)
mnemom agent goal reset [ref]         # clear it, or replace it with --statement "…"

What counts as your words, approvals, pin and reset, the mnemom agent goal show|pin|reset commands and the known limits are on Implicit goal mode. In implicit mode the launcher tells the gateway which recent turns you typed and which Claude Code inserted (a scheduled tick, a skill body, hook output), read from Claude Code’s own transcript. In terminal mode it runs a small local proxy in front of the gateway to do this. Set MNEMOM_AGENT_TURN_HEADER=0 to turn it off. mnemom agent sessions and mnemom agent show report a session’s goal mode as ON (sealed), IMPLICIT, or OFF — see Sessions below.

Preflight: `mnemom agent doctor`

mnemom agent doctor

A read-only check with an actionable hint for anything not ready: your settings file, the coding-agent CLI, your Anthropic key source, gateway health (a 200 plus the x-mnemom-verdict header that proves governance is live), a gateway that belongs to a different Mnemom deployment than the rest of the CLI, your Mnemom Agent access for the active org, and the CLI’s auto-update status. It writes nothing, never reads your key’s value, and exits non-zero when the machine is not launch-ready, so a script can gate on it.

Account and µ balance

mnemom agent runs on µ and has no free tier. Before launching it checks the µ balance on the org the agent lives in (by default your personal org). With no µ, the launch stops with a top-up link; top up at https://mnemom.ai/settings/billing and the balance updates the moment the top-up completes. An accepted invitation credits your starter µ automatically.

Defaults out of the box

Default	Value	Override
Gateway	`https://gateway.mnemom.ai` (the gateway the rest of the CLI uses)	`--gateway <url>`, `MNEMOM_AGENT_GATEWAY`, `config set gateway`
Launch shape	Terminal — a governed session in this terminal.	`config set launch`
Permissions	Claude Code’s permission prompts are off (`--dangerously-skip-permissions`). See Permission prompts	`--no-yolo` (per launch)
Agent	a governed `agent-<you>` agent, claimed into your org before the first session	`--agent <slug>`, `config set agent`
Sign-in	Anthropic API key, unless you pick another option on first launch	`--auth`, `config set auth`
Key source	env → saved store → prompt	`config set key_source`

A launch always uses one Mnemom deployment end to end: the gateway must belong to the same deployment the CLI signs in to and reads your agents and sessions from. A --gateway (or saved gateway) on a different deployment is refused at launch and by mnemom agent setup, with the fix; a local gateway on localhost is exempt.

Saved settings: `mnemom agent config`

Configure the launcher once and stop retyping flags. Settings live in a human-editable TOML file at ~/.mnemom/launcher.toml. Your Anthropic key is never stored there; it lives separately in ~/.mnemom/launcher.json (mode 0600), so the file you open and share never carries a credential.

mnemom agent config list                 # show your current settings
mnemom agent config get model            # print one value
mnemom agent config set gateway https://gateway.mnemom.ai
mnemom agent config set launch terminal
mnemom agent config set guardrails.max_turns 200
mnemom agent config unset model          # remove one value
mnemom agent config edit                 # open ~/.mnemom/launcher.toml in $EDITOR
mnemom agent config path                 # print the file path

Settable keys

Key	Meaning
`gateway`	Gateway host (default `https://gateway.mnemom.ai`)
`model`	Model to launch (CLI alias or concrete id, e.g. `claude-sonnet-5`)
`agent`	Governed agent identity slug (`x-mnemom-agent`)
`effort`	Reasoning effort (`low`\|`medium`\|`high`\|`xhigh`\|`max`)
`cli`	Coding-agent CLI to launch (name or full path; default `claude`)
`launch`	Launch shape — `terminal`
`auth`	How Claude Code signs in to Anthropic: `api-key` (default), `subscription` or `console`. See Sign-in options
`key_source`	Where to source the Anthropic key (`env`\|`store`\|`prompt`)
`goal_mode`	What a launch with no `--goal`/`--implicit`/`--no-implicit` does — `implicit` or `off`. Ignored until you opt in to the experimental `implicit` feature, so implicit mode is never on by default. After you opt in, an unset value means `implicit`; set `off` to use implicit mode only with `--implicit`
`context`	Context folding default — `true`/`false` (default `true`; also settable per-launch with `--context`/`--no-context`)
`context_profile`	How the gateway folds context — `balanced`, `aggressive`, `adaptive` or `off`; unset means the gateway’s own default (also `--context-profile`, `MNEMOM_AGENT_CONTEXT_PROFILE`)
`compact_at`	Gateway compaction target — a token count from 50k to just under 1M (`200k` works), or `1m`/`off` for none (default: none). A target needs the experimental `compaction-intercept` feature (also `--compact-at`, `MNEMOM_COMPACT_AT`)
`guardrails.max_turns`	Contract guardrail: turn ceiling (positive integer)
`guardrails.budget_usd`	Contract guardrail: spend ceiling in USD (positive number)
`guardrails.stall_turns`	Contract guardrail: consecutive no-write turns (positive integer)

Precedence

Settings resolve highest-wins:

command-line flag  >  environment variable  >  ~/.mnemom/launcher.toml  >  built-in default

Guardrails saved in config apply only when a session has a goal, so a saved ceiling never forces an unrequested contract. An example ~/.mnemom/launcher.toml:

gateway = "https://gateway.mnemom.ai"
model = "claude-sonnet-5"
agent = "agent-sam"
launch = "terminal"

[guardrails]
max_turns = 200
budget_usd = 25

Your governed agent

Every mnemom agent session runs as a claimed agent. An unclaimed agent belongs to no org and is billed to no one, so the launcher never starts a session on one. If you do not name an agent, the launcher uses agent-<your handle>, derived from your Mnemom login. Before Claude Code starts, on every launch, it:

asks the gateway which agent it serves for this launch’s credential and agent name. With an Anthropic API key, the answer is cached after the first launch. With a Claude subscription sign-in, the gateway is asked every time;
checks whether that agent is claimed. An agent that is already claimed is left where it is and never claimed again;
if it is not claimed, claims it into the org this launch bills: your active org (set with mnemom org use), else your personal org. Your active org setting is not changed. A newly claimed agent also gets its default cards.

The launcher prints one line naming the agent and saying whether it was already claimed or has just been claimed, and into which org. Each agent it confirms as claimed is recorded on this machine. The launch stops, and Claude Code is not started, when the answer is definite:

the agent for this credential and name belongs to another Mnemom account. Pick a name of your own with --agent <name>;
the agent is not claimed and can’t be claimed, for example because this launch has no org to claim it into. The message says what went wrong;
the gateway does not support the subscription identity check yet. Launch with --auth api-key instead.

If Mnemom or the gateway can’t be reached, or returns a temporary error, the launcher retries. If it still can’t get an answer, it launches on the agent this machine last confirmed as claimed for the same credential, agent name and gateway, and prints a warning saying so. If there is no such record, the launch stops and asks you to try again. It never falls back to an agent it knows is unclaimed. This works the same way in a terminal, a script or CI. There is no prompt to confirm the claim.

Default cards

A newly claimed agent gets a default coding posture. Both cards are published off, because alignment and protection analysis are billed: the alignment card has autonomy_mode and integrity_mode set to off and principal.relationship: delegated_authority; the protection card has mode: off, with thresholds 0.60 / 0.80 / 0.95 and all four screen surfaces declared so it is ready when you turn it on. Turn them on with mnemom card and mnemom protection. The goal contract does the nudging.

mnemom agent setup                  # check (and if needed claim) the agent and refresh its cards; no launch
mnemom agent my-session --setup     # the same, then launch
mnemom agent my-session --no-setup  # skip the default-card writes for this launch

--no-setup only skips the card writes. The agent is still checked and, if needed, claimed. mnemom agent setup uses an Anthropic API key. Bring your own agent any time with --agent <slug>.

Managing agents

The agent-management verbs live under the same namespace:

mnemom agent list [--org <slug|id>] [--all]           # agents in your active org (--all: every org)
mnemom agent claim <id-or-name> --key <key> [--org <slug>]
mnemom agent move <id-or-name> --to <slug|id>

Sessions: `mnemom agent sessions` / `show`

Every real launch is appended to a local ledger, ~/.mnemom/sessions.jsonl. Entries older than 30 days are removed at the next launch; change that with mnemom config set sessions.retention_days <days> (or MNEMOM_SESSIONS_RETENTION_DAYS).

mnemom agent sessions          # the last 20 launches, newest first
mnemom agent sessions --all    # every launch
mnemom agent sessions --json

mnemom agent show              # the newest session
mnemom agent show fix-auth     # by session name (newest match wins)
mnemom agent show a1b2c3d4     # by a unique conversation-id prefix
mnemom agent show --json

show merges the local launch record with the gateway’s live goal state for that conversation — the sealed contract (if any), the latest verdict, and guardrail gauges (turns 3/10, etc., flagged when a ceiling was crossed) — so you can check on a session after the fact without re-reading your terminal scrollback. It also prints the command that resumes the session through mnemom agent (see Resume a session). Each row’s Goal column, and show’s goal-mode field, read ON (sealed contract), IMPLICIT, or OFF. For an implicit-mode session, show also prints the statement the gateway inferred.

Launch shapes

Contracts and guardrails

A goal (--goal) seals a contract on the first turn; add requirements, path rules and guardrail ceilings on the command line. Passing any contract flag makes --goal required.

mnemom agent refactor-auth \
  --goal "Refactor the auth module without changing its public API" \
  --requirement "All existing tests keep passing" \
  --allow "src/auth/**" \
  --forbid "**/*.env" \
  --max-turns 200 --budget 25

The CLI prints the contract statement and its sha256[0:16] so you can confirm what was sealed. The gateway echoes the full hash back on every response as x-mnemom-contract-hash.

Limits

What	Limit	If exceeded
Goal statement	4,000 characters	first turn rejected with `400` (`statement_too_long`)
Whole contract (statement + requirements + paths + ceilings, as canonical JSON)	8,192 bytes	first turn rejected with `400` (`contract_too_large`)
`--max-turns`, `--stall`	any positive whole number	the CLI refuses the flag before launching
`--budget`	any positive USD amount (decimals allowed)	the CLI refuses the flag before launching
Requirements, `--allow`, `--forbid`	no count limit; only the 8,192-byte total applies	—

The contract is sealed on the first turn of a session and cannot change afterwards: a later request that sends a different or invalid contract header is ignored and the sealed contract keeps governing, so a client hiccup mid-session never kills a governed session. To change the contract, start a new session.

What guardrails do

Guardrails (--max-turns, --budget, --stall) observe and nudge, never block. Each ceiling is checked once per turn; when one is crossed the gateway appends a short [mnemom guardrail] line to your next message telling the agent which ceiling it hit, and marks the crossing on the response headers and in your traces. The session keeps running. A ceiling you leave unset falls back to the cell’s default for that guardrail, if the cell has one; otherwise it is simply off.

Context folding

Context folding summarizes older turns so a long session keeps fitting the model’s context window. It is on by default. Unless you choose a profile, the gateway’s own default profile applies.

mnemom agent long-session --no-context   # turn folding off for this launch
mnemom agent long-session --context      # force folding on (overrides launcher.toml/env)
mnemom agent config set context false    # make "off" the standing default

Precedence: --context/--no-context wins, else MNEMOM_AGENT_CONTEXT (0/false/off/no turn it off), else config set context, else on.

Context profiles

--context-profile picks how the gateway folds the session. With no profile set anywhere, nothing is sent and the gateway’s default applies.

Profile	Behaviour
`balanced`	Keeps more of the earlier work verbatim and folds later — for long sessions that revisit earlier files and decisions.
`aggressive`	Folds earlier and keeps a tighter working set — for cost-sensitive sessions and short, focused tasks.
`adaptive`	Sizes the fold to the conversation: no fold below 200k tokens, `aggressive` from 200k to 1M, `balanced` above.
`off`	No gateway folding; compaction is left to the coding agent. Same as `--no-context`.

mnemom agent long-session --context-profile aggressive
mnemom agent config set context_profile aggressive   # standing default

Precedence: --no-context (always off; combining it with any other --context-profile is refused), else --context-profile, else the profile of the session being resumed (with --continue or --resume <session-id>), else MNEMOM_AGENT_CONTEXT_PROFILE / config set context_profile, else off when folding is turned off by context = false or MNEMOM_AGENT_CONTEXT, else the gateway’s default.

How Claude Code signs in

Claude Code can sign in to Anthropic three ways under mnemom agent: an Anthropic API key (the default), your Claude Team or Enterprise subscription, or the API key your Anthropic Console login created. Your first launch in a terminal asks which one when there is a choice, and saves the answer. Sign-in options covers each one, where the API key is looked up, and what you see when something is missing.

Flags

Flag	Meaning
`--invite <token>`	Redeem a Mnemom Agent invitation, then launch if a session name is given
`--auth <mode>`	How Claude Code signs in: `api-key`, `subscription` or `console` — see Sign-in options
`--goal`, `--requirement`, `--allow`, `--forbid`, `--goal-id`	Contract fields (`--goal` required if any are given)
`--implicit` / `--no-implicit`	Turn implicit goal alignment on/off for this launch (`--implicit` needs the opt-in experimental `implicit` feature; not combinable with the contract fields above)
`--max-turns`, `--budget`, `--stall`	Guardrail ceilings
`--agent <slug>`	Governed identity (default `agent-<you>`). Claimed before launch either way
`--cli <name\|path>`	Coding-agent CLI to launch (default `claude`)
`--gateway <url>`	Gateway host override
`--model <alias\|id>`, `--effort <level>`	Model + reasoning effort
`--trim-mcp`	Launch with no MCP servers
`--no-yolo`	Keep Claude Code’s permission prompts: do not pass `--dangerously-skip-permissions`
`--context` / `--no-context`	Force context folding on/off for this launch (on by default)
`--context-profile <profile>`	`balanced`, `aggressive`, `adaptive` or `off` — see Context profiles
`--compact-at <n\|200k\|1m\|off>`	Gateway compaction target for this session, from 50k to just under 1M; `1m` or `off` means none. A target needs the experimental `compaction-intercept` feature
`--conversation-id <id>`	Conversation id to send (default: generated)
`--no-context-hint`	Do not seed Claude Code’s context-hint feature flag
`--no-context-handoff`, `--no-compaction-intercept`	Keep that experimental feature off for this launch, even when your settings turn it on
`--setup` / `--no-setup`	Re-check the agent and refresh its default cards / skip the card writes. The agent is claimed either way — see Your governed agent
`--dry-run`	Print the resolved launch plan and exit
`--first-run`	Show the first-run savings screen again, then exit

Anything after -- is passed straight through to the coding-agent CLI. Flags of experimental features (--implicit, --slack, --context-handoff, --compaction-intercept) are hidden from --help until you turn the feature on with mnemom experimental enable.

Sign-in options — subscription, API key or Anthropic Console
Savings estimates — the first-run savings screen and the in-session counter
CLI reference — the full mnemom command surface
Agent claim flow
Conscience values and org card templates

Overview

Identity & Cards

Posture & Policy

Detection & Safe House

AEGIS

Reputation & Risk

Lifecycle

Gateway

Pricing

Policy

Specifications

Changelog

Install once

Redeem an invitation

Run

Permission prompts

Resume a session

Implicit goal mode (experimental)

Preflight: `mnemom agent doctor`

Account and µ balance

Defaults out of the box

Saved settings: `mnemom agent config`

Settable keys

Precedence

Your governed agent

Default cards

Managing agents

Sessions: `mnemom agent sessions` / `show`

Launch shapes

Contracts and guardrails

Limits

What guardrails do

Context folding

Context profiles

How Claude Code signs in

Flags

​Install once

​Redeem an invitation

​Run

​Permission prompts

​Resume a session

​Implicit goal mode (experimental)

​Preflight: mnemom agent doctor

​Account and µ balance

​Defaults out of the box

​Saved settings: mnemom agent config

​Settable keys

​Precedence

​Your governed agent

​Default cards

​Managing agents

​Sessions: mnemom agent sessions / show

​Launch shapes

​Contracts and guardrails

​Limits

​What guardrails do

​Context folding

​Context profiles

​How Claude Code signs in

​Flags

​Related

Install once

Redeem an invitation

Run

Permission prompts

Resume a session

Implicit goal mode (experimental)

Preflight: `mnemom agent doctor`

Account and µ balance

Defaults out of the box

Saved settings: `mnemom agent config`

Settable keys

Precedence

Your governed agent

Default cards

Managing agents

Sessions: `mnemom agent sessions` / `show`

Launch shapes

Contracts and guardrails

Limits

What guardrails do

Context folding

Context profiles

How Claude Code signs in

Flags

Related