Claude Code — greatmemory docs

Give Claude Code persistent memory across sessions with one command.

Setup

Install greatmemory first (local quickstart), then register it as an MCP server:

# Available in the current project only (default scope)
claude mcp add greatmemory -- gmem mcp

# Or available in every project on this machine
claude mcp add --scope user greatmemory -- gmem mcp

Everything after -- is the command Claude Code runs to start the server — here, greatmemory's stdio MCP mode.

By default each project gets its own memory store, because gmem mcp resolves its data dir relative to the working directory (./.greatmemory). For one shared store across all projects, pin the data dir:

claude mcp add --scope user --env GM_DATA_DIR="$HOME/.greatmemory" greatmemory -- gmem mcp

Verify with claude mcp list — greatmemory should show as connected.

What you get

Five tools appear in Claude Code: remember, recall, get_context, get_profile, and forget (parameters in the MCP reference).

Usage

Just talk to Claude:

You: Remember that our staging database is Postgres 17 with pgvector, and deploys go through the release branch.

Claude calls remember and confirms it stored the note.

Days later, in a fresh session:

You: What do you know about our staging setup?

Claude calls recall (or get_context) and answers from memory: staging runs Postgres 17 with pgvector; deploys go through the release branch.

You can also ask "what do you know about me?" or "summarize what you've remembered for this project" — Claude will use get_profile. A useful habit is asking for a get_profile at the start of long sessions so standing facts are in context from the first turn.

Troubleshooting

Do I need gmem serve running? No. gmem mcp (stdio) is self-contained: Claude Code launches the process and it opens the database directly from GM_DATA_DIR. The HTTP server is only needed for the REST API or the /mcp HTTP transport.

Tools don't appear. Check claude mcp list for errors. The most common cause is gmem not being on the PATH Claude Code uses — pass an absolute path instead:

claude mcp add greatmemory -- ~/.cargo/bin/gmem mcp

First call is slow. On first use the embedding model is downloaded into <data_dir>/models. One-time cost; pre-warm it by running gmem serve once.

Memories differ between projects. That's the default per-project data dir. Set GM_DATA_DIR to a fixed absolute path (see above) for a single shared store.

Sharing one store with a running server. stdio mode and serve each open the database independently. If you want multiple clients on one live instance, connect Claude Code to the HTTP transport of a running server instead:

claude mcp add --transport http greatmemory http://127.0.0.1:7437/mcp

Scope and transport flags reflect current Claude Code releases — run claude mcp add --help if a flag has moved.