mnemom agent

​

Install once

npm install -g @mnemom/mnemom
mnemom login

​

Redeem an invitation

mnemom agent --invite <token>

​

Run

cd your-project
mnemom agent

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

• 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

mnemom agent fix-auth --no-yolo

​

Resume a session

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

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

​

Implicit goal mode (experimental)

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

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

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 "…"

​

Preflight: mnemom agent doctor

mnemom agent doctor

​

Account and µ balance

​

Defaults out of the box

​

Saved settings: mnemom agent config

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

​

Precedence

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

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

[guardrails]
max_turns = 200
budget_usd = 25

​

Your governed agent

1. 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;
2. checks whether that agent is claimed. An agent that is already claimed is left where it is and never claimed again;
3. 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 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.

​

Default cards

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

​

Managing agents

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>
mnemom agent export [id-or-name]                      # download the agent's full record

​

Sessions: mnemom agent sessions / show

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

​

Share your agent’s record

https://www.mnemom.ai/agents/<agent-id>/reputation
https://api.mnemom.ai/v1/reputation/<agent-id>/verify

mnemom agent export                       # the agent you launch with, all time, JSON
mnemom agent export my-coder --since 30d  # the last 30 days
mnemom agent export my-coder --format csv --from 2026-09-01 --to 2026-09-30

​

Launch shapes

​

Contracts and guardrails

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

​

Limits

​

Seal lifetime

​

Updating a sealed contract

​

How to update

POST https://api.mnemom.ai/v1/agent/sessions/{conversationId}/contract?agent_id=<agent id>

• conversationId is the conversation the session runs under and agent_id is the governed agent’s id. mnemom agent show prints both. Add &org_id=<org id> when the agent is not in your primary organization.
• The caller must be an owner or admin of the agent’s organization, authenticated with a Bearer token or an X-Mnemom-Api-Key like any other API call. An API key scoped to gateway traffic only is always refused, with 403 session_credential_forbidden, so a session cannot update its own contract with the key it uses to reach the gateway.
• The same update is available as the update_contract tool on the control-plane MCP server. It takes the same fields and follows the same rules.

{
  "contract": {
    "statement": "Refactor the auth module without changing its public API",
    "requirements": ["All existing tests keep passing"],
    "allowed_paths": ["src/auth/**"],
    "forbidden_paths": ["**/*.env"],
    "max_turns": 300,
    "budget_usd": 25
  },
  "expected_version": 1
}

curl -X POST "https://api.mnemom.ai/v1/agent/sessions/$CONVERSATION_ID/contract?agent_id=$AGENT_ID" \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d @contract-update.json

​

What an update changes

• Ceilings replace, they don’t merge. An update’s turn, spend, stall and time ceilings (max_turns, budget_usd, stall_turns, time_limit_s) replace the live contract’s ceilings outright. To raise the turn ceiling while keeping the existing spend ceiling, resend both. An omitted ceiling means the contract no longer sets one, not “leave the old one in place”: that guardrail then falls back to the cell’s default, as described in Ceilings, or is off if the cell has none.
• Mode is the one field that carries over when omitted. If the update doesn’t name a mode, the session’s current nudge/enforce mode is kept unchanged. If you name a mode explicitly, that value wins instead. This includes naming nudge to downgrade an enforce session.
• Time is counted from the first seal. time_limit_s measures from when the contract was first sealed, not from the update. Setting "time_limit_s": 3600 on a session that has already run for two hours puts it over the ceiling at once. An update that resends a time_limit_s at or below the time already elapsed keeps the ceiling crossed. An update that omits time_limit_s removes the time ceiling entirely, because an update replaces the contract and time_limit_s has no cell default to fall back to. To keep a time ceiling, resend time_limit_s on every update.

• a subagent or teammate turn, which is graded on that thread’s next request;
• a main-thread turn whose end-of-response judging failed or did not finish within two minutes, which is graded on the next request instead (see Final-turn judging).

​

Ceilings: nudge vs enforce

• A refused request is not counted as a turn, so retrying it never moves the turn counter.
• The 429 carries x-should-retry: false and no Retry-After header, so SDK clients that retry a 429 on their own don’t loop on it: the request will keep being refused until the ceiling is raised.
• The turn that crossed the ceiling is still judged; only the request after it is refused.
• The session cannot raise its own ceiling; only the contract’s owner can, through the update path. Because the check compares the live counters against the live ceilings fresh on every request, rather than remembering that a ceiling once fired, raising the ceiling unblocks the very next request with no other action needed.

​

Fence coverage

• Edit, Write, MultiEdit and NotebookEdit are always writes, and their file path is always checked. Read, Grep, Glob, LS, WebFetch, WebSearch and TodoRead are always reads and are never checked against a fence.
• Inside a Bash call, the gateway reads these write forms out of the command text and checks their targets:
  • output redirects: >, >> and >|;
  • tee and the files it writes;
  • the destination of cp, mv and install (the last operand, or the directory given with -t/--target-directory), and every directory install -d creates;
  • the destination of rsync, which is always its last operand (for rsync, -t means “keep times”, not a target). An rsync to a remote host:path is not a local write and is not checked, and rsync -n, --dry-run or --list-only writes nothing.
  These forms are found across &&, ; and pipes, after a cd (relative targets resolve against it), behind command wrappers (sudo, env, nice, nohup, time, exec, command, and xargs with a replace string such as -I, -i, --replace or -J), and after a leading read such as git status &&. If a command is too long to read in full, the fence-check line in your traces names the part that was not read.
• Other write-shaped commands, such as mkdir, touch, sed -i, ln or running a script, are not fence-checked. The fence-check line counts them as writes that were not checked, and the judge decides from the full turn.
• A target written with a shell variable or command substitution is resolved in two steps: first from the same command (variable assignments and exports earlier in it, $(pwd) and $(mktemp)), then from variables set by earlier Bash commands in the session. ~ and $HOME resolve only when HOME is set in one of those commands, or when the session’s earlier commands name exactly one home directory (/Users/<name> or /home/<name>). A target still unresolved after that sets no automatic verdict. This includes a file xargs appends from its input. The judge decides from the full turn, and the fence-check line names the target as unresolved rather than silently passing over it.
• A resolved write that lands outside every allowed path, or under a forbidden one, is always at least a violation verdict. The allowed-path check applies only when the contract has at least one --allow rule. The mechanical check can only raise the judge’s verdict on a fenced write, never lower it, and on its own it never blocks the request either way. See Ceilings above for what does.

​

Temporary and scratch files

mnemom agent refactor-auth \
  --goal "Refactor the auth module without changing its public API" \
  --allow "src/auth/**" \
  --allow "/tmp/**"

​

Final-turn judging

• Subagent and teammate turns. Their responses are counted when they end, but each turn is judged on that thread’s next request.
• A main-thread turn whose judging failed or stalled. If the end-of-response judging fails, or has not finished after two minutes, the next request judges the turn instead.

• Incomplete responses. A stream that is cut off, errors or is aborted is not judged. The turn is counted as unjudged.
• The last turn of a subagent or teammate. A subagent’s or teammate’s turns are judged on that thread’s next request, so each thread’s final turn has none and is counted as unjudged.
• Withheld responses. A response the gateway withheld, or held for review, never reached your client, so it is not judged and does not appear in the unjudged count.

​

Lead-directed sessions

mnemom agent ship-fix \
  --goal "Fix the flaky retry test" \
  --lead-directed \
  --requirement "Open the PR; do not merge it"

On the lead’s direction, this session may push its own branches and open draft or ready pull requests, from a git worktree, never the primary checkout; it may not merge them.

​

Context folding

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

​

Context profiles

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

​

How Claude Code signs in

​

Flags

​

Related

• 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