CLI

bash

npx memnox <command>          # no install
npm install -g memnox         # or install it
memnox --help                 # the tree, at any depth
memnox <command> --help

Options that appear on almost every command

These six are not repeated in each entry below. Any command that talks to the runtime accepts them, and each has a sensible default, so you can usually ignore all of them.

Option

--url <url>

Which runtime to talk to. Defaults to http://127.0.0.1:7466, the one on this machine. Point it elsewhere to ask a shared runtime instead.

--token <token>

The agent credential. Defaults to MEMNOX_AGENT_TOKEN, then to the token memnox setup wrote into ~/.memnox/config.json. You rarely pass it by hand.

--admin-token <token>

A separate, stronger credential, needed only for commands that read or change the whole runtime: audit history, reload, agent management. A runtime bound to loopback with no admin token set does not ask for it.

--project <name>

The governance scope to act within. Defaults to whatever project this directory declares, which is what memnox setup --project wrote.

--env <environment>

The environment the action belongs to, e.g. production. Rules can match on it, and risk is escalated one level in production.

--json

Return the structured form instead of the human one. Available wherever a structured answer makes sense, and the right choice inside a script. The human output is allowed to change its wording; the JSON is not.

Reading these commands

<angle brackets> are values you supply and [square brackets] are optional. Commands below list what each of their own placeholders means, but these five recur everywhere, and each one has a place it comes from.

Placeholder

<id>

Whichever id the command is about: an approval, an agent, a decision. Every command that takes one has a sibling that lists them, so memnox approvals gives you the id for memnox approve.

<sessionId>

One agent run. Printed on every line of memnox audit, and the value your own code passes as sessionId when it calls the SDK.

<eventId>

One audit event. The first column of memnox audit.

<agent>

An editor or agent by name: claude-code, cursor. Omit it and Memnox installs for whichever ones it finds.

<pack>

A policy pack name, from memnox policy packs.

Setting up

$memnox setup

Scaffold policies from what it detects in the repository, register a local agent, install editor hooks, register the MCP server, and start the runtime. The one command that does everything.

What it does

--enforce: Apply verdicts from the very first request. Without it, setup starts in observe-only mode: rules are evaluated and recorded, but nothing is ever withheld. Leave it off until you have watched a day of real traffic.
--no-detect: Write the generic starter rules instead of reading the repository to guess which ones fit. Use it when detection picks the wrong stack.
--no-hook: Do not install editor hooks. Nothing gates Claude Code or Cursor afterwards; you are only scaffolding.
--no-mcp: Do not register the Memnox MCP server with your agent. Your agent then cannot ask Memnox anything on its own.
--no-graph: Skip building the code graph. Blast-radius rules need it, so --protected-path reachability is unavailable until you run memnox graph build.
--no-serve: Scaffold and install, but do not start the runtime. Hooks will fail open until something serves.

Where things go

-f, --file <path>: Where to write the policy file.(default: memnox.policies.yaml)
--project <name>: The governance unit this repository belongs to. Repositories sharing a name share one scope, so a service split across three repos is still one project in the audit log.
--protected-path <pattern>: A glob whose changes need approval, e.g. src/payments/**. Repeatable, and it replaces whatever detection chose rather than adding to it.
-p, --port <port>: Port the runtime listens on.(default: 7466)
-H, --host <host>: Address to bind. The loopback default is not reachable from another machine, which is deliberate for a laptop.(default: 127.0.0.1)

$memnox quickstart [agent]

Policies and editor hooks in one step, without starting a server.

$memnox init

Scaffold a policy file only. Nothing is installed and nothing runs.

$memnox protect <agent>

Install hooks for the editors you have.

<agent>: claude-code or cursor. Omit it and Memnox installs for whichever ones it detects.

$memnox hook <agent>

The hook entry point. Editors invoke this, you never do.

Running the runtime

$memnox serve

Run the gateway. Every guard is an explicit flag here, so a server deployment never gains one because a local default moved.

Listening and files

-p, --port <port>: Port to listen on.(default: 7466)
-H, --host <host>: Address to bind. Change it to 0.0.0.0 to accept connections from other machines, and set --admin-token before you do.(default: 127.0.0.1)
--policies <path>: A YAML policy file to load. Repeatable, because one project may span several repositories.
--data-dir <path>: Where local stores are written when no database is configured.(default: .memnox)
--base-path <path>: Serve every /v1 route under a prefix, e.g. /orbit. Lets several runtimes share one hostname behind a proxy.

What happens when nothing matches

--default-effect <effect>: The verdict for an action no rule mentions. Only allow or block. Set it to block where the gate is load-bearing, so an incomplete rule set refuses rather than permits.(default: allow)
--enforcement <spec>: Per-environment mode, e.g. default=monitor,production=enforce. off skips evaluation entirely and audits the action as ungoverned, monitor decides and records but never withholds, enforce applies the verdict.(default: enforce)
--rate-limit <rpm>: Requests per minute per agent on the check endpoint. 0 disables the limit.
--audit-retention-days <days>: Prune audit events older than this. 0 keeps everything forever, so check your retention policy before setting it.

Storage

--database-url <url>: Postgres connection string. Without it every store is a local file, which is fine for one machine and wrong for more than one.
--redis-url <url>: Redis connection string. Required with more than one replica: it is what makes rate limits and locks shared rather than per-pod.

Who may call the admin routes

--admin-token <token>: Require this bearer token on admin routes. Also readable from MEMNOX_ADMIN_TOKEN, which is how containers pass it without putting it in the process list.
--allow-local-admin: Serve admin routes unauthenticated when no token is set. A loopback bind already behaves this way; this extends it to other binds, so use it only on a network you trust completely.
--agent-jwt-secret <secret>: Accept HS256 agent JWTs signed with this value, instead of issued tokens.
--agent-jwt-issuer <issuer>: The iss an agent JWT must carry to be accepted.

TLS, and identity by certificate

--tls-cert <path>: TLS server certificate. Pair it with --tls-key to serve HTTPS.
--tls-key <path>: TLS server private key.
--tls-ca <path>: CA bundle used to verify client certificates. Supplying it turns on mTLS, and the certificate's subject CN becomes the agent's name, so identity comes from the connection rather than from a token.

Guards, each opted into by name

--behavior-guard: Watch the shape of a session: bursts, repetition, escalating scope. Deterministic counting, no model.
--trust-guard: Require approval for risky actions from agents with a low trust score.
--verification-guard: Require approval for destructive actions while an agent is not reporting back what its earlier actions did.
--dependency-guard: Govern dependency.add: known-vulnerable versions and disallowed licenses.
--dependency-license-lookup: Let that guard read licenses from the npm registry. Off by default because it makes an outbound request per package.
--protected-path <pattern>: Require approval for any change that reaches this path, including indirectly through imports. Repeatable. Reachability needs --code-graph.
--code-graph <path>: The snapshot written by memnox graph build. Without it, blast radius is only what the change literally touches.
--token-budget <tokens>: Cap cumulative llm.spend tokens per session.
--no-content-shield: Turn OFF scanning written content for secrets and personal data. On by default; this disables it.
--no-shell-guard: Turn OFF reading past shell indirection, so bash -c "$(curl …)" is no longer unwrapped before matching. On by default.
--no-memory: Turn OFF enforcement of recorded decisions. On by default.

Encryption at rest

--keyring-file <path>: A JSON keyring: one active key plus retired keys kept so old records stay readable. This is the form that supports rotation, so prefer it.
--data-key <key>: Encrypt local stores with a single key. Deprecated: it is unsalted and cannot be rotated, and it appears in the process list.
--data-key-file <path>: Read that key from a file instead, so it never reaches argv.
--encryption-mode <mode>: How to treat records written before encryption was on. off ignores envelopes, permissive reads both plain and encrypted, strict refuses anything unencrypted.

Notifications and search

--approval-webhook <url>: Slack-compatible webhook posted to whenever an approval is raised.
--slack-signing-secret <secret>: Enables approving from inside Slack. The secret is what proves a button press really came from Slack.
--embedding-key <key>: Your own embedding key. Turns decision search from keyword-only into hybrid keyword + semantic. Nothing else in the runtime calls a model.
--embedding-model <model>: Which embedding model to use.(default: text-embedding-3-small)
--embedding-dimensions <n>: Embedding width. It must match the model, or every search returns nothing.(default: 1536)

Seeing what happened

$memnox status

Runtime address, policy count and version, project, credential state, recent decisions, waiting approvals, and how many actions would have been stopped if enforcing.

Runtime   : http://127.0.0.1:7466
Policies  : 10 (version e852ac2d63d0)
Project   : acme-checkout
Credential: stored (config)
Decisions : 214 recent
Waiting   : 1 approval(s)
Observed  : 9 would have been stopped if enforcing

$memnox audit

Every decision, newest first. --project scopes across repositories.

2026-07-31T23:03:24Z  BLOCK  local-editor: shell.execute rm -rf / — Destructive
                             shell commands are blocked for AI agents.
2026-07-31T23:03:24Z  ALLOW  local-editor: shell.execute ls -la — no policy matched

$memnox audit verify

Walk the hash chain. Reports the first event where content and hash disagree.

$memnox explain <eventId>

Why this event got this verdict: the rules that matched, and the signals that escalated it.

<eventId>: An audit event id, the first column of memnox audit. Omit it to explain the most recent event.

$memnox replay <sessionId>

Every decision in one agent session, in order. An incident is rarely one event.

<sessionId>: The session column in memnox audit, and the sessionId your own code passes to the SDK. One agent run start to finish.

$memnox insights

Aggregates over local audit history: what is being attempted, blocked and approved.

Asking before acting

$memnox context <action> <target>

What governs this, before you do it. Records nothing and raises no approval.

<action>: The action verb you are about to take: file.write, deploy.service, database.drop.
<target>: What it acts on: a path, a service, an environment. Optional, but the answer is much sharper with it.

bash

memnox context file.write 'src/app/(auth)/login/page.tsx'

$memnox check <action> <target>

The verdict for an action, without performing it.

<action>: The action verb, e.g. deploy.service.
<target>: What it acts on. Optional.

Policies

$memnox validate <file>

Is the policy file well formed. Returns the full error list, not the first failure.

<file>: A policy file to check. Defaults to memnox.policies.yaml in the current project.

$memnox policy version

The content hash of the current rule set, the same value stamped on every audit event as policyVersion.

$memnox reload

Re-read the policy files without restarting the runtime. Top-level, not under policy.

--url <url>: The runtime to tell.(default: http://127.0.0.1:7466)
--admin-token <token>: Its admin token, if it requires one.

$memnox policy packs

List the 33 policy packs available to install.

$memnox policy install <pack>

Append a pack to your policy file. It composes with your own rules under most-restrictive-wins.

<pack>: A pack name from memnox policy packs, e.g. production-safety. Several may be named at once.

$memnox policy simulate <file>

Replay your real audit history through a candidate rule set and report every decision that would differ. Reading history is what this command does, so there is no flag to turn it on.

<file>: The candidate policy file to test, meaning the edited copy rather than the one already in force. May also be given as -f <path>. There is no default: name a file or the command tells you to.

-f, --file <path>: The same candidate file, as a flag instead of a positional argument.
--against <path>: The baseline to compare against, meaning the rule set the candidate is diffed with.(default: memnox.policies.yaml)
--limit <n>: How many recent audit events to replay. More events means a slower, more representative answer.
--default-effect <effect>: The verdict to assume for an action neither rule set mentions, so the comparison is not distorted by unmatched events.(default: allow)
--url <url>: The runtime to read audit history from.(default: http://127.0.0.1:7466)
--admin-token <token>: The admin token, if that runtime requires one to read its audit history.

Also available as memnox simulate <file>. It is the same command one word deep, because this is the step that makes a policy change safe to ship.

Approvals

$memnox approvals

What is waiting.

$memnox approvals list

The same, explicitly.

$memnox approve <id> --by <name>

Grant it. Grants accumulate toward a quorum, and one person counts once.

<id>: The approval id, from memnox approvals or the approvalId the runtime returned to the agent.
--by <name>: Who is granting it. Defaults to $USER, and this is the name the audit trail keeps.

$memnox deny <id>

Refuse it. A single denial ends the request, whatever the quorum.

<id>: The approval id, from memnox approvals.

$memnox approvals status <id>

Where one request has got to: pending · granted 1/2 (dana) · approved.

<id>: The approval id, from memnox approvals.

$memnox approvals health

How long requests are waiting. Rising latency means the rule is routed to people who are not looking.

$memnox approvals resolve <id>

Approve or deny a pending request. The same thing approve and deny do, in one command.

<id>: The approval id, from memnox approvals.

--by <name>: Who is resolving it. This is the name the audit trail keeps, so it should be a person.(default: $USER)
--deny: Deny instead of approve. Without it, this command approves.

$memnox approvals override <id> --reason "<text>"

Break-glass: push an action past a pending approval.

<id>: The approval id, from memnox approvals.
--reason "<text>": Why, in your own words. Mandatory. It is stored on the approval and read later by whoever investigates the incident this opens.

Agents

$memnox agents register --name <name>

Register an agent and print its credential once. There is no command that shows the token again, so copy it now or rotate later.

--name <name>: What this agent is called in every audit line, e.g. ci-deployer. Pick something you would recognise at 3am.
--kind <kind>: One of claude-code, cursor, openai-agent, mcp, custom. Descriptive only: it grants nothing. Defaults to custom.

Capabilities are not set here. The wildcard patterns an agent may never exceed are supplied at registration through POST /v1/agents, which the CLI does not expose. See Protect your agents.

$memnox agents list

Every registered agent, with trust score and status.

$memnox agents suspend <id>

Block it without deleting it. No approval overrides a suspension.

<id>: The agent id, from memnox agents list.

$memnox agents activate <id>

Reverse a suspension.

<id>: The agent id, from memnox agents list.

$memnox agents rotate <id>

Issue a new credential. The old one retires on return, so the agent keeps working until it picks the new one up.

<id>: The agent id, from memnox agents list.

Decision memory

$memnox memory add "<decision>"

Record a decision as a machine-checkable constraint.

"<decision>": The decision in one sentence, as your team would say it: "No PII in application logs". It is matched as text, so write it the way somebody would search for it.

$memnox memory list

What is recorded.

$memnox memory search "<query>"

Find a recorded decision. Keyword matching by default, hybrid keyword and semantic when an embedding key is configured on the runtime.

"<query>": What you are looking for, in the words your team would use: "logging", "refunds". The same query always returns the same results, which is what makes it safe for an advisor to consult.

$memnox memory health

Which decisions are stale, frequently violated, or never referenced.

$memnox memory digest

A readable summary of what the organization has decided.

$memnox memory retire <id>

Mark a decision superseded. The record stays, because organizations change their minds rather than forget.

<id>: The decision id, from memnox memory list.

$memnox memory remove <id>

Delete one outright. Prefer retiring, which keeps the history.

<id>: The decision id, from memnox memory list.

Code graph and blast radius

$memnox graph build <directory>

Write .memnox/code-graph.json, the file-level import graph.

<directory>: The root to walk. Defaults to the current directory.

$memnox graph explain <file>

What a change here reaches. Editing a utility is editing payment code if payments import it.

<file>: A path in your repository, e.g. src/utils/money.ts. Relative to where you are.

$memnox graphify status

Whether the optional deeper analyzer is installed.

$memnox graphify install

Install Graphify via uv, pipx or pip3. Running this is the consent, nothing installs it as a side effect.

$memnox graphify build [directory]

Build the AST graph across 36 languages. No LLM, no network, no API key.

$memnox graphify use [directory]

Point at an existing Graphify output.

MCP

$memnox mcp

The MCP server itself, over stdio. Your client launches it, you do not.

$memnox mcp install <client>

<client>: The MCP client to write config for, e.g. claude-code, cursor, windsurf. Omit it and Memnox installs for whichever ones it finds.

$memnox mcp uninstall <client>

Remove the entry from that client's config.

<client>: The MCP client to remove it from, e.g. cursor.

Reporting and compliance

$memnox report

A governance evidence bundle built from the audit trail, markdown or JSON.

$memnox compliance controls

Every mapped control against SOC 2, ISO 27001, HIPAA and GDPR, with its status and its evidence.

$memnox compliance summary

One line per framework: what is ready and what is not. For a status page or a weekly read.

$memnox ci

Scans the branch's git diff for secrets and personal data, and exits 1 on a blocking finding. Run it beside your tests. It is a content scan, not a full policy evaluation, so it catches what a diff can show and not what an agent would attempt at runtime.

--base <ref>: The git ref to diff against, which is what counts as "the changes".(default: $MEMNOX_DIFF_BASE, else HEAD~1)
--staged: Scan what is staged rather than a diff against a ref. This is the form a pre-commit hook wants.
--json: Machine-readable findings instead of the human report.
--no-fail: Report findings but always exit 0. Use it to watch a pipeline for a week before letting it break the build.

Control plane

$memnox login

Sign this machine in to your organization's control plane, through the browser.

$memnox logout

Forget the control-plane credential on this machine.

$memnox whoami

Which runtime and which organization this machine is talking to.

$memnox pull

Fetch your organization's rules and apply them to this machine.

$memnox suggestions

The review queue from the terminal: organization decisions waiting for a human.

$memnox timeline

What agents and sources did across the workspace, newest first.

Encryption keys

$memnox keys generate

Print a new keyring, or add a key to an existing one.

$memnox keys status

Count stored records by the key that encrypted them.

$memnox keys rewrap

Re-encrypt every record under the active key.

Retiring a key is: generate → make it active → rewrap → remove the old one once status shows nothing left under it.

Intelligence (optional, BYOK)

$memnox draft "<instruction>"

Draft a policy from plain language. It prints validated YAML for you to read and commit, and installs nothing.

"<instruction>": The rule you want, in a sentence: "nobody should force-push to main without a review".

$memnox intent "<goal>"

Turn a goal into candidate actions. It proposes, risk classification rates them, and policy still decides.

"<goal>": What you are trying to do, in a sentence: "roll back the checkout service".

Where things live

Path

memnox.policies.yaml

Your rules, in the repository

~/.memnox/config.json

The agent token, mode 0600

~/.memnox/policies.json

Registered policy file paths, per project

.memnox/code-graph.json

The import graph

Policy YAML

The format validate and simulate operate on.

Contributing to the runtime

Adding a command, an advisor or a pack.