memnox

<p align="center"> <img width="1920" height="1080" alt="memnox-architecture-dark-16x9" src="https://github.com/user-attachments/assets/21141ee8-06c4-4c99-a5af-a54fab10d4a8" /> </p> <p align="center">_{BEFORE YOU LEAVE AN AGENT RUNNING}</p> <h1 align="center"> Your agents can already do the work.<br> _{Memnox makes it safe to let them <b>do it without you</b>.} </h1> <p align="center"> <img src="assets/agents/claude-code.svg" width="44" height="44" alt="Claude Code" title="Claude Code">&nbsp;&nbsp; <img src="assets/agents/codex.svg" width="44" height="44" alt="Codex" title="Codex">&nbsp;&nbsp; <img src="assets/agents/cursor.svg" width="44" height="44" alt="Cursor" title="Cursor">&nbsp;&nbsp; <img src="assets/agents/cline.svg" width="44" height="44" alt="Cline" title="Cline">&nbsp;&nbsp; <img src="assets/agents/hermes.svg" width="44" height="44" alt="Hermes" title="Hermes">&nbsp;&nbsp; <img src="assets/agents/openclaw.svg" width="44" height="44" alt="OpenClaw" title="OpenClaw"> </p> <p align="center"> _{Claude Code · Codex · Cursor · Gemini CLI · Windsurf, and what Cline, Hermes, OpenClaw and Ruflo can reach} </p> <p align="center"> <strong>Set it up once. Every agent is governed inside the session it already works in.</strong><br> No model decides anything. Your code and your secrets never leave your machine. </p>

---

Memnox is an open source runtime that tells you what you can safely let your AI coding agent do next. It rules on every tool call Claude Code, Codex, Cursor, Gemini CLI or Windsurf makes, before the call runs, with one of three verdicts: allow, ask or deny. It runs on your machine, needs no account, and no model decides anything.

You already have agents that read your files, run your shell, push to your repositories and call your MCP servers. Memnox sits inside each of their sessions: what is allowed goes ahead, what is denied is refused with a way forward, and what needs a person asks you in the prompt you are already looking at. Once you have said yes to the same thing often enough, memnox next names it as something you could stop being asked about.

You do not learn a new tool to get that. You set it up once and keep working the way you work now.

Set up once

npm install -g memnox
memnox setup

That is the last Memnox command you need. setup finds the agents on this machine and goes through them one at a time: what each can already reach, what you want to call it, and whether to put it under Memnox. Nothing is changed for an agent you say no to.

Claude Code
            claude-code
id          agt_claude-code
config      ~/.claude.json
mcp         github
can use     shell, filesystem, git, network, mcp
can reach   ~/.aws/credentials, network

  Call it something acme will recognise, or press Enter to keep "Claude Code"  > Backend Coder
  Put Backend Coder under Memnox now?  [Y/n] y

For each agent you accept, it puts a hook in front of every tool call, gives the agent a small MCP server (memnox-session) it can ask Memnox through, and adds a /fingerprint command. Then you open Claude Code, Codex, Cursor, Gemini CLI or Windsurf the way you always do. There is nothing to launch and nothing to remember.

Node 22 or newer, on macOS or Linux. On Windows, run it inside WSL, and ADR 0001 says why.

What you get, inside every session

| When | What Memnox does | What you typed | |---|---|---| | A session starts | The agent is told the boundary it works in, the rules in force, what your team has settled and how this repository is built, so it plans around them instead of walking into them | nothing | | The agent reaches for something your rules refuse | The call never runs. The agent is told why and what to use instead, so it finishes the task rather than stalling | nothing | | Something needs a person | You are asked in your agent's own permission prompt, or in the conversation, or in your Slack or Discord DM. Yes once, yes for the session, or no | a yes or a no | | The agent writes code that breaks how this repository is built | Refused before it lands, or sent straight back to be put right, even when the agent switches from its edit tool to the shell | nothing | | Your prompt touches something your team already decided | The decision is put in front of the agent, with who confirmed it and where | nothing | | Two agents go for the same file | The second is told who holds it and what they have been doing | nothing | | You want to know why, what happened, or to undo it | Ask the agent in plain words: "why was that refused?", "what have you done this session?", "undo what you did" | a sentence |

One session, start to finish

You open Claude Code in a repository and ask it to add order cancellation. Before it reads a file, it has been told where it stands:

Memnox: Memnox rules on this session in enforce mode: a rule that refuses stops the call, and one that asks puts the question to the person.
Project boundary: ~/work/shop. A write outside it asks first.
Your workspace has settled 1 decision(s), policies and owners. Before you change code, ask the memnox-session "brief" tool about the paths, or "memory" about the subject, and cite what it says.
This repository states how its code is written, in .memnox/code-fingerprint.yaml. Follow it; a write that breaks an enforced line is refused.

Your prompt mentions payment retries, which your team settled in Slack, so that decision is put in front of the agent too:

Your workspace settled this about payment retries: "Declined payments are never retried." (a decision, confirmed by ada@acme.com, on 2026-05-02, source https://acme.slack.com/archives/C01/p17).

In a hurry, the agent writes the update straight into the HTTP handler. The repository sends every database write through an Action, so the write never lands:

Memnox: This repository's code fingerprint: all database writes go through Actions, which own transactions and event persistence (rule fingerprint:writes-only-in-actions)
Instead: call actionFactory.create(XAction.class).run(params)

It writes the Action instead, and when the work is done it tries to force push:

verdict     DENY
reason      you chose to deny this: it rewrites history somebody else may already have pulled
instead     push a branch and open a PR

So it pushes a branch and opens a PR. You typed one prompt. Every one of those answers came back inside the conversation, and each is in the record when you ask the agent "why was that refused?"

How it reaches each agent

Each agent's own hook asks Memnox before every tool call: a file read or write, a shell command, a web fetch, an MCP call. The answer comes back in the agent's own format, so the agent treats it like any other result.

When a rule refuses, the call never runs and the agent is told why and what to use instead, so it carries on with the task rather than retrying.

When a rule asks, Claude Code shows its own permission prompt with Memnox's reason in it. Say yes once, or for the rest of the session; a second yes to the same thing stops the asking for that session. An agent with no prompt of its own relays the question in the conversation, and you reply yes, allow for this session or no. Turn on memnox config set approvals both and it reaches your Slack or Discord DM too, where the first answer wins.

When your prompt names something the workspace already settled, or just before the agent's first write to a file it covers, the decision is added to the conversation with who confirmed it and where.

Ask Memnox through the agent, in plain words. Every agent gets memnox-session, with eight tools:

| You say | Tool | |---|---| | "Why was that refused?" | why | | "Where does Memnox stand?" | status | | "What have you done this session?" | replay | | "Would git push --force be allowed here?" | decisions | | "What did we decide about retries, and who said so?" | memory | | "Brief me on src/payments before you start" | brief | | "Record how this repository's code is written" | fingerprint | | "Undo what you did this session" | rewind |

Every tool but rewind and fingerprint only reads. rewind waits for your yes before it moves a file, and fingerprint writes a repository's first fingerprint and never changes one that exists. None of them can allow, approve or change a rule, and an agent that tries memnox allow, memnox mode off or an edit to a rule file from its shell is refused before any rule is read, since an agent that could would approve itself.

| Agent | Checked before it runs | A question goes to | Told at session start | |---|---|---|---| | Claude Code | every tool | its own permission prompt | yes | | Codex | every tool its hook reports | the conversation | yes | | Gemini CLI | every tool | the conversation | yes | | Cursor | commands, MCP calls, file reads and writes | its own prompt for commands and MCP calls | yes | | Windsurf | commands, MCP calls, file reads and writes | memnox approve, the workspace or your DM | no, only what memnox-session says when it connects |

The five seams

Below the hooks, five seams sit in the path an agent's action already takes, so an agent does not have to cooperate for them to see it. Each turns what the agent tried into an action a rule matches, and each answers allow, ask or deny.

| Agent action | Seam | How it is put in the path | Action a rule matches | What it cannot see | |---|---|---|---|---| | Calls a tool on an MCP server | MCP proxy | memnox mcp wrap repoints every MCP config on the machine, keeping a backup | mcp.* | a tool that lies about its name in tools/list, which is classified by the lie | | Runs git, docker, kubectl, gh, npm and the rest of the 19 classified binaries | PATH interceptors | memnox setup puts them on the agent's PATH, and offers your login PATH too | shell.execute, and per verb, such as git.push-force | a binary called by absolute path around the PATH | | Sends an HTTP request | Egress proxy | memnox run starts it on loopback and points the agent at it | http.request | the body inside HTTPS, and a tool that ignores HTTPS_PROXY | | Asks git for a credential before reaching a remote | Git credential helper | memnox-git-credential, which holds no secret and can hand none out | git.credential | a push over SSH, which never asks git for a credential | | Opens chromium, chromedriver, geckodriver, google-chrome or msedgedriver | Browser driver | the PATH interceptors, which rule on the host rather than the script | browser.navigate | what the page does once the host is allowed |

A verdict of deny names what to use instead. A verdict of ask holds the call for a person, and for the browser that is once per host per session. The threat model states each limit in full.

A change to your rules reaches an open session on its next tool call. MCP servers the agent already started, and the note it read at the start, catch up when you restart the agent. Everything from inside the session has the whole story.

Holding agents to the way your code is written

Every repository has rules nobody wrote down where an agent would read them: writes go through one layer, time is always UTC, nothing returns null. An agent new to the code breaks them in the first hour, and a reviewer catches it days later if at all. Memnox turns them into a code fingerprint the first agent records and every agent after it is held to.

Why this is not another CLAUDE.md

CLAUDE.md, AGENTS.md, GEMINI.md and .cursor/rules tell an agent what it should do. They are loaded into the model's context, and following them is the agent's job. Nothing happens when it does not, until a reviewer notices.

CLAUDE.md, AGENTS.md, .cursor/rules