Skip to content

Environment variables

A flag counts as set when its value is 1, true, yes or on (any case).

VariableRead byEffect
AGENT_MEM_DATA_DIReverythingthe data folder instead of the system default; every process agent-mem starts gets it
AGENT_MEM_DISABLEhooksthe hook returns at once: nothing recorded, nothing injected
AGENT_MEM_INTERNALhooksset by agent-mem for its own processes and model calls, so they are never recorded; do not set it yourself
AGENT_MEM_NO_SPAWNhooks, setuphooks start no observer, indexer or viewer; setup writes the login item without starting it
AGENT_MEM_PROJECT_DIRMCP serverthe project to search in, when the agent does not set CLAUDE_PROJECT_DIR
AGENT_MEM_DEBUGCLIprint the full traceback instead of a one-line explanation
AGENT_MEM_FAKE_LLMobserver, testspath of a JSON list of canned model answers for the fake provider
AGENT_MEM_EXEsetup, upgradethe agent-mem binary written into hook files. The Docker launcher sets it to itself, since setup runs inside the container
AGENT_MEM_MODEL_DIRsearch, observerfolder of the embedding and spaCy models instead of <data>/models; the Docker image keeps them outside the data volume, so a new image brings new ones
AGENT_MEM_IN_DOCKERviewer, panel, doctorflag set by the Docker image: login hints name agent-mem login <agent> (the fact-writing CLIs live in the container), and AGENT_MEM_VIEWER_BIND applies
AGENT_MEM_VIEWER_BINDvieweraddress the viewer listens on, only together with AGENT_MEM_IN_DOCKER (the image sets 0.0.0.0; Docker publishes the port to the host’s 127.0.0.1 only). Elsewhere the viewer always stays on 127.0.0.1

The data folder defaults:

OSDefault
macOS~/Library/Application Support/agent-mem
Linux$XDG_DATA_HOME/agent-mem, else ~/.local/share/agent-mem
Windows%LOCALAPPDATA%\agent-mem, else ~/AppData/Local/agent-mem

agent-mem --data-dir <folder> <command> overrides it for one command.

VariableUsed for
CLAUDE_CONFIG_DIRwhere Claude Code’s settings.json, transcripts and memory/*.md notes live (default ~/.claude)
CLAUDE_PROJECT_DIRthe MCP server’s project, set by Claude Code
CODEX_HOMECodex’s hooks.json, config.toml, sessions and memories (default ~/.codex)
COPILOT_HOMECopilot’s hooks, mcp-config.json, session state and login (default ~/.copilot)
XDG_CONFIG_HOMEOpenCode’s plugin and opencode.json, the systemd user unit (default ~/.config)
XDG_DATA_HOMEthe data folder on Linux
LOCALAPPDATA, APPDATAthe data folder and the Startup folder on Windows
NO_COLORplain text in the Claude Code panel
PATHfinding claude, codex, copilot, ollama, uv; copied into the viewer’s login item
ProcessEnvironment
observer, indexer, viewer started by a hookAGENT_MEM_INTERNAL=1, AGENT_MEM_DATA_DIR
claude -p, codex exec, copilot -s for factsAGENT_MEM_INTERNAL=1; every CLAUDECODE* variable removed so Claude Code does not think it runs nested; Copilot gets a private temporary COPILOT_HOME
mem0MEM0_TELEMETRY=False, MEM0_DIR=<data>/mem0
viewer login itemAGENT_MEM_DATA_DIR, AGENT_MEM_INTERNAL=1, the PATH from setup