Memroot

memroot.dev · Console

Persistent engineering memory for coding agents. The memory belongs to you and your project, not to one agent, and follows you across Claude Code, Codex and Grok. This package is the command-line tool that connects them.

Quick start

npx memroot@latest setup

Setup finds your agent CLIs, previews the user-scope install, then installs the plugin from the public Memroot marketplace and registers the MCP server https://api.memroot.dev/mcp for each agent you pick. Authorize once per agent, then restart it:

• Claude Code: sign in in the browser during setup (from a terminal, setup runs claude mcp login memroot). If that did not finish, run /mcp, select memroot and authenticate.
• Codex: sign in in the browser during setup, then trust the Memroot hooks in /hooks.
• Grok: run /mcps, select memroot and press i (not yet verified against production).

In scripts, name the agents and pass --yes. --dry-run only prints the plan:

npx memroot@latest setup --agent claude --agent codex --yes
npx memroot@latest setup --agent grok --yes --dry-run

Requires Node.js 22 or later on macOS or Linux, and the CLI of each agent you select. Windows is not supported.

Plugin updates

npx memroot@latest update

This refreshes the plugin, MCP registration and managed instructions of every set-up agent, and turns capture on as setup does. --agent limits it to one agent; --dry-run only prints the plan. Restart the agent afterwards and review any new hook permissions.

Or update one agent with its own plugin manager:

claude plugin update memroot@memroot --scope user
codex plugin marketplace upgrade memroot
grok plugin update memroot

Setup turns on Claude Code's background marketplace updates (extraKnownMarketplaces.memroot.autoUpdate) unless you already set it to false.

npx memroot@latest doctor checks everything setup and update install, plus sign-in, project and capture. It only reads, prints no secrets or transcripts, marks each check PASS, WARN or FAIL with a fix, and exits non-zero on a FAIL.

What you get

• Recall. Before non-trivial work the agent retrieves past decisions, conventions, root causes and failed approaches.
• Automatic saves. The agent saves durable lessons and tells you in one line. Tell it not to and it stops.
• Session capture. On by default, with an opt-out. Redacted on your machine before upload.
• No API keys. Browser sign-in, one project per connection. Review and revoke connections in the console.

Commands

| Command | What it does | | --- | --- | | setup | Install the plugins and register the MCP server | | update | Update every set-up agent's plugin, MCP link and instructions | | import | Ask each set-up agent to save the lessons in its own memory to Memroot, once | | doctor | Check each agent's plugin, hooks, skills, MCP link and rules, plus login, project and capture | | status | Show cloud sign-in, capture and agent install state | | capture on, off, status | Turn session capture on or off, or inspect it | | login, logout, whoami | Sign the CLI in or out, or show the account | | token | Print a fresh access token for agent adapters |

npx memroot --help lists every option.

Choose or create a project

A project stands for a product, not a folder or repository. You choose it once per computer, and every agent, hook, the capture worker and the CLI use it until you change it. Use /memroot:project in Claude Code, $memroot-project in Codex, the memroot-project skill in Grok, or the CLI:

memroot project login            # authorize the Memroot CLI connection (not capture)
memroot project list
memroot project use "My Shop"    # select for this computer
memroot project use              # the current selection, or the only project
memroot project create "My Blog" # create and select
memroot project status

• Automatic choice happens only when you have exactly one project. Nothing is picked from the folder or list order.
• Memory calls. The plugin's hook approves Memroot memory calls in Claude Code and Codex and sets their project_id (in Grok it fixes a missing or wrong id). Your deny and ask rules still apply; add an ask rule for mcp__memroot__* to be prompted. With nothing selected, the call is refused.
• Storage. ~/.memroot/project-selection.json (0600), per account and API base. memroot logout clears it, and a project you lose access to is dropped. Selecting needs no capture consent and reads no transcript.
• Consent. Project commands ask for consent to your current and future personal projects and bounded creation. An older one-project grant is reauthorized, never widened.
• Creating respects your plan's project limit. If a response is lost, retry with the same name.
• Agent connections are separate from the CLI's. To use new projects, reauthorize an older one: claude mcp logout memroot then claude mcp login memroot; codex mcp logout memroot then codex mcp login memroot; for Grok, revoke the old connection in Memroot, then /mcps, select Memroot and press i. Don't remove or overwrite the MCP configuration instead.
• Capture uploads carry the account, project and an opaque selection revision, so an older worker cannot fall back to the first project.

Import your agents' own memory

Copy what your agents already learned into Memroot. Sign them in and select a project first.

memroot import            # lists what it found, then asks [y/N]
memroot import --dry-run  # only lists the files and the exact agent commands
memroot import --agent claude --yes

• Reads Claude Code auto memory, Codex ~/.codex/memories, and Grok memory and topics. It skips instruction files (CLAUDE.md, AGENTS.md, rules) and Memroot's own files.
• Redacts secrets and personal identifiers (email addresses, your user and host names) on your computer, best effort.
• Runs your own agents headless, in bounded runs, on your agent subscriptions. The redacted text goes to each agent's provider (Anthropic, OpenAI or xAI) under your account. Each agent sees only its own memory, without file paths, and can only call the Memroot save tools (no file, shell, web or other MCP access).
• Saves the lessons as agent saves ("Agent save") to the selected project, each counting toward your plan's memory writes. Memroot's hooks limit the run to saving and keep every save on the selected project, so Claude Code's hooks must be on and Codex must trust them in /hooks.
• Reports each agent's count beside the saves Memroot confirmed (not for Grok).
• Reruns send only new or changed files. --again resends everything.

Needs Memroot plugin 0.8.0 or later (memroot update). Without a terminal, pass --yes.

Session capture

Setup and update show the disclosure, authorize a separate "Memroot CLI" connection and turn capture on for every set-up agent. Without a terminal or that connection, they tell you to run memroot capture on.

• Opt out with --no-capture or memroot capture off (which deletes queued work). A saved opt-out is never overridden. Revoking "Memroot CLI" in the console or memroot logout also stops uploads.
• New terms pause capture (memroot capture status shows it) until setup, update or capture on records them.
• When it runs: at session end; around compaction; at turn ends, every 8 new turns or after 20 minutes with 2 or more; when a Claude Code subagent finishes and a turn-end capture is due; when Claude Code or Grok has waited about a minute for you (at most every 5 minutes, with 2 or more new turns); and on resume or fork.
• What it reads. Only finished turns not captured before, never turns from before capture was on or while it was off, and never history a fork copied.
• Codex skips Memroot hooks, including ones an update adds, until you trust them in /hooks.
• Local redaction. A bundled worker keeps user and assistant text, tool names and file paths, never tool output. It removes secrets, personal email addresses and home paths, and stops if that fails.
• Your own agent extracts. Your agent CLI runs headless, without tools, on at most 48,000 characters, using your agent quota. The redacted excerpt goes to that agent's provider. Another agent's CLI is used only with --allow-cross-agent-extraction.
• Uploads typed memories, never raw transcripts. Each is labeled session-extracted, with up to 3 evidence quotes (200 characters each), repo-relative paths and symbols, your git remote and salted session hashes. One retrieval query with only the repository name is also sent.
• Destination. The selected project. Work queued before you select one waits up to 72 hours for it.
• Limits. 50 memories per run and 2,500 per rolling 24 hours, each one write against your plan's memory limit. When Memroot reports the plan limit, the worker stops and retries a day later.

Capture has not yet been verified end to end against production.

Privacy

• Each agent runs its own OAuth sign-in and keeps its own MCP credentials. Setup never reads or copies them.
• The CLI's refresh token lives only in the OS credential store (macOS Keychain, or libsecret on Linux). Without one, sign-in fails.
• Hooks make no network request and never open a transcript. Logs hold only hashes, counts, durations and error codes.

See the privacy notice and terms.

Details

• Files. Plugins live in each agent's plugin cache (each has a README with hook details). Installer receipts and old copies: ~/.local/share/memroot. Capture jobs: ~/.local/state/memroot/capture. Both follow XDG_DATA_HOME and XDG_STATE_HOME. Settings, consent and project selection: ~/.memroot.
• Repeating setup repairs the install and resumes a cancelled sign-in. It moves a verified older local install to the marketplace, keeping its files. It never overwrites a conflicting marketplace, modified files, a disabled plugin or a different memroot MCP entry.
• Removing. Uninstall the plugin with the agent's plugin manager. For the MCP server, revoke and confirm the connection in the console, then run claude mcp remove memroot; codex mcp logout memroot and codex mcp remove memroot; or grok mcp remove memroot. memroot logout removes only the CLI's own credentials.
• Stale global install. update and doctor warn when the memroot on your PATH is older, and print the npm install -g memroot@<version> fix.
• Troubleshooting. Run npx memroot doctor. If an agent command fails, update that agent and retry. After an interrupted run, and once no setup is running, remove the .setup-lock directory named in the error.

Links

• Website: https://memroot.dev
• Console: https://console.memroot.dev
• Help: [email protected]
• Security reports: [email protected]

License

Proprietary, all rights reserved; this is not open-source software. You may install and run it to use Memroot, as set out in the LICENSE file. The licenses of the bundled open-source components are in dist/THIRD-PARTY-NOTICES.txt.