memry

memry

memry gives your AI coding agents a persistent memory that carries over between sessions and projects. Decisions, bug fixes and discoveries saved in one session are available in the next one, so you do not have to explain the same context again.

Requirements

• macOS, Linux or Windows (amd64 or arm64)
• At least one supported agent. For Claude Code, its CLI (claude) must be on your PATH.

Install

With Homebrew:

brew install mrtheroi/tap/memry

memry setup

Other ways to install memry, a single binary with no other dependency:

• With Go: go install github.com/mrtheroi/memry-cli/cmd/memry@latest. The binary lands in $(go env GOPATH)/bin, which must be on your PATH.
• From a release: download the memry_ _ _ .tar.gz archive for your system, check it against checksums.txt, and put the memry binary from it on your PATH, for example:

  tar -xzf memry_1.0.0_darwin_arm64.tar.gz memry

sudo install -m 0755 memry /usr/local/bin/memry

On Windows, see Windows.

Your agents run memry from the path it is installed at, so outside Homebrew keep the binary where it is, or run memry setup again after you move it.

memry setup asks for your email, sends you a 6-digit login code, then asks which agents you use and connects memry to each one you select (the ones found on your machine are preselected; press space to select, enter to confirm). Start a new session in your agent afterwards to use it.

To choose the agents without the prompt, for example in a script, pass their keys:

memry setup --agents=claude-code,codex

Run memry setup again to change the selection; memry is removed from agents you deselect.

Claude Code plugin

This repository is also a Claude Code plugin marketplace. Its memry plugin adds a /memry:setup skill that walks you through installing the CLI and running memry setup.

From your terminal:

claude plugin marketplace add mrtheroi/memry-cli

claude plugin install memry@memry

Or inside a Claude Code session:

/plugin marketplace add mrtheroi/memry-cli

/plugin install memry@memry

On Claude Code 2.1.275 or later, one in-session command does both: /plugin install memry --marketplace mrtheroi/memry-cli.

The plugin does not register the MCP server itself; memry setup does, so memry is never connected twice.

Self-hosted

On a self-hosted memry server, your admin creates a token for you instead of the email login. Connect with:

memry setup --url https://memry.company.internal --token

--url is required with --token, so the token is never sent to the public server. Setup asks for the token without showing it, checks it with the server before saving it, then asks which agents you use as usual. For scripts, set the MEMRY_TOKEN environment variable: with --token and no value, setup uses it instead of the prompt, also with --no-interaction, and the token stays out of the process list. --token= also skips the prompt (and wins over MEMRY_TOKEN), but the token then lands in your shell history and the process list.

MEMRY_TOKEN="$token" memry setup --url https://memry.company.internal --token --no-interaction

MEMRY_TOKEN is only read together with --token, so it never changes the email login.

Use an https:// URL. Setup sends your token or login code to the server, and memry mcp sends the saved token with every request, so a plain http:// URL is only accepted for this machine (localhost, a 127.x.x.x address or [::1]). For any other http:// server setup stops before asking or sending anything: "Refusing to send credentials over plain HTTP to . Use an https:// URL, or pass --insecure to allow it (for example on a trusted LAN).". Pass --insecure only on a network you trust: the credentials then travel in clear text. The same rule applies to MEMRY_URL.

Windows

Install with WinGet, then run setup in a new terminal so the memry command is on your PATH:

winget install Memry.Memry

memry setup

Other ways to install it:

• With Go: go install github.com/mrtheroi/memry-cli/cmd/memry@latest. The binary lands in %GOPATH%\bin (go env GOPATH), which must be on your PATH.
• From a release: download memry_ _windows_ .zip (amd64 or arm64), check it against checksums.txt (signed with cosign, see the cosign command in the release process), and put memry.exe from it on your PATH.

Update with winget upgrade Memry.Memry. To uninstall, run memry uninstall, then winget uninstall memry; for a manual install, memry uninstall prints the path of the memry.exe to delete.

What differs from macOS and Linux:

• Config file. %USERPROFILE%\.config\memry\config.json, readable only by your user. memry finds your home in USERPROFILE, then HOME, then two levels above LOCALAPPDATA; without any, it stops with "Could not find your home directory; set USERPROFILE or HOME." (on every OS, an unset home is an error). Use --config or MEMRY_CONFIG to put it elsewhere.
• Claude Code. Setup registers memry as a local memry mcp server (claude mcp add --transport stdio --scope user memry -- mcp) and adds the same SessionStart hook. Both claude.exe and claude.cmd are supported.
• The hook runs `memry` by its name, so memry must be on your PATH. WinGet guarantees it; with go install, add %GOPATH%\bin to your PATH. Claude Code hands its own PATH to the hook, so after installing, restart the terminal or editor (VS Code, JetBrains) you start Claude Code from; a window opened before the install does not see memry, and the hook then loads no context without any error. If you run Claude Code with CMD instead of Git Bash, CMD searches the current directory first, so do not start sessions in a folder that contains an untrusted memry.exe.
• Antivirus and SmartScreen. memry.exe is not Authenticode-signed, so SmartScreen or your antivirus may warn about it. To check a download, verify the signed checksums.txt as described in CONTRIBUTING.md and compare the archive's SHA-256.
• Terminals without color support. In a legacy console, the agent question is replaced by Agents: (pass --agents to choose). and keeps the defaults; use --agents to choose.

Custom config file

By default memry keeps your login in ~/.config/memry/config.json. To use another file, set the MEMRY_CONFIG environment variable or pass the global --config (or --config= ) option to setup, uninstall and delete-account:

memry setup --config ~/work/memry.json

The precedence is --config, then MEMRY_CONFIG, then the default; each applies to that one process. Setup passes the file on to the commands it registers in your agents, so they read the same login.

Supported agents

Setup only adds memry's own entries: everything else in those files is kept, and memry uninstall removes just what setup added. Your login token is never written to an agent's files.

How it works

• Login by email code. You sign in with a one-time code sent to your email; there is no password to remember.
• Agent integration. Setup registers a memry MCP server in each agent you select, which gives the agent the tools to save and search memories.
• Context at session start. Each new session loads the recent memories of the current project, so your agent picks up where you left off. Claude Code loads them with a hook (also on resumed and compacted sessions); the other agents are instructed to load them as their first step.
• Projects. By default, a repository's project is its directory name. To group several repositories into one project (for example, the backend and frontend of one product), add a .memry.json file at the root of each repository:

  {"project": "my-product"}

Usage metrics (opt-in)

memry sends no telemetry. If you want the memry dashboard to chart your Claude Code token usage and cost, turn it on explicitly:

memry usage enable    # off by default

memry usage status # on or off as far as memry can see, and where to (never prints the token) memry usage disable # turn it off again

memry usage enable tells you what is sent, asks your memry server for a usage token (it can only send usage metrics) and sets Claude Code's OpenTelemetry metrics export in the env of ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR/settings.json, a relative CLAUDE_CONFIG_DIR resolved against the current directory): CLAUDE_CODE_ENABLE_TELEMETRY, OTEL_METRICS_EXPORTER, OTEL_EXPORTER_OTLP_METRICS_PROTOCOL, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_HEADERS, and every OTEL_METRICS_INCLUDE_* gate set to false. Restart Claude Code to apply it. The settings file holds the usage token, so memry leaves it readable by your user only.

What is sent and what is kept

• Claude Code decides what it sends, as documented in its monitoring guide: metrics such as token usage, cost, sessions and lines of code, with identity attributes such as your email and organization id and metric-specific attributes. That list is not exhaustive and may grow with new Claude Code versions. memry turns off the optional attribute gates it can.
• The memry server is the guarantee. It keeps only the token and cost data points (the count or cost, the model, the token type, the query source and the time window), tied to your memry account, and discards everything else on receipt. It stores no raw attributes: only a keyed hash of them, to tell series apart.
• memry does not turn on Claude Code's logs or traces, so no prompts or code are sent through it.

What memry checks, and what it cannot see

Before asking for a token, enable checks the environment of the shell it runs in, your settings.json and Claude Code's file-based managed settings (managed-settings.json and managed-settings.d/*.json in /Library/Application Support/ClaudeCode on macOS, `/etc/claude-co