claude-mem for Claude Code: how the new installer works, and the extra step for third-party APIs

claude-mem is an open-source memory plugin for Claude Code. In the background it turns what each session did into notes, and when you open a new session in the same project it brings the key points in automatically. The project is thedotmack/claude-mem on GitHub, under the Apache-2.0 licence, with about 117k stars when checked on 2026-11-13. The latest release was 15.18.3, published on 2026-11-12. Besides Claude Code it supports Codex, Cursor, OpenCode and more than a dozen other tools.

It changes quickly, and many tutorials online no longer match. Two things trip people up most:

1. The new installer asks who should write your memory. The default suggestion is claude-mem's own hosted service, which needs a sign-in, and its 30-day trial asks for a payment method. You can skip it; see below.
2. If Claude Code uses a third-party API rather than an Anthropic login, claude-mem does not follow the base URL you set for Claude Code. Everything looks fine after install, but no notes get written. You have to set the URL again in claude-mem's own config.

How it works

1. You use Claude Code as usual. Hooks pass each tool call (which file was read, what changed, which command ran) to a small local background service.
2. That service runs a second AI, which the docs call the observer, to turn the activity into short notes, plus a summary when the session ends.
3. When you start a new session in the same project, Claude Code gets an index of those notes and fetches details by ID only when it needs them.

So the first session only records; memory shows up from the second session on. To load a whole repo up front, send /learn-codebase (about 5 minutes on a typical repo, optional). Everything is stored on your machine under ~/.claude-mem. Cloud sync is off unless you turn it on.

Install

Requirements: Node.js 20.19 or later in the 20.x line, or 22.12 or later. The installer adds Bun and uv if they are missing.

Option 1: the installer (recommended)

npx claude-mem install

It finds the coding tools on your machine, asks which ones to set up, and then asks who should write your memory (next section). Restart Claude Code afterwards.

Option 2: the plugin marketplace inside Claude Code

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

With this route the launcher is compiled on first start, so the first session may run without memory and the second one is fine. Running npx claude-mem install once avoids that gap.

Don't use npm install -g claude-mem. It installs only the library. It does not register the hooks or start the background service, so nothing gets recorded.

On Windows, npm not being recognised means Node.js is missing or not on PATH; reinstall it and open a new terminal. If hooks report Executable not found in $PATH: "claude-mem", run npx claude-mem doctor and follow what it says.

Choosing who writes your memory

Writing notes calls a model, so you choose whose tokens pay for it:

To skip the claude-mem account, choose local memory in the browser setup, or run:

npx claude-mem install --provider claude

If Claude Code uses a third-party Anthropic-compatible API, choose this option too, then add the settings in the next section.

The extra step for third-party APIs

With the Anthropic plan option, the note-taking AI sends its requests through the Claude Agent SDK. It does not read the ANTHROPIC_BASE_URL you set for Claude Code, and it ignores variables exported in your shell (it deliberately blocks an inherited ANTHROPIC_API_KEY so a stray key is never billed by mistake). You have to repeat the settings in claude-mem's own files. The example below uses CCSub; for another provider, swap in its URL and key.

Step 1: add the URL and key to ~/.claude-mem/.env (create the file if it doesn't exist)

ANTHROPIC_BASE_URL=https://www.ccsub.net
ANTHROPIC_AUTH_TOKEN=your-api-key

Use the same base URL as in Claude Code, without /v1. CCSub also accepts the key as ANTHROPIC_API_KEY; set one of the two.

Step 2: pin the model in ~/.claude-mem/settings.json

{
  "CLAUDE_MEM_PROVIDER": "claude",
  "CLAUDE_MEM_MODEL": "a model ID your provider supports"
}

CLAUDE_MEM_MODEL defaults to haiku, and claude-mem does not translate model names: if your provider doesn't recognise the name, requests fail. Pick a full model ID from your provider's list (CCSub's is on the models page). Note-taking doesn't need the strongest model; a low-priced one is enough.

Step 3: restart the background service

npx claude-mem restart

To check it works, do a few steps of work in Claude Code, then look at your provider's request log. On CCSub, the Usage page in the dashboard will show a batch of extra requests from note-taking. If there are none, check the logs in ~/.claude-mem/logs/. When the provider rejects a request, the error is written there as-is; claude-mem never quietly falls back to Anthropic's own endpoint.

Two common errors:

• Unknown model: CLAUDE_MEM_MODEL isn't an ID your provider supports. Fix it as in step 2.
• thinking rejected with a 400: claude-mem turns thinking off for note-taking requests by default, and some services don't accept that parameter. It drops the parameter and retries automatically after such a 400. If the error keeps coming back, add "CLAUDE_MEM_OBSERVER_THINKING": "omit" to settings.json.

If you'd rather not use the Anthropic protocol, set CLAUDE_MEM_PROVIDER to openai-compatible and configure CLAUDE_MEM_OPENAI_COMPAT_BASE_URL, CLAUDE_MEM_OPENAI_COMPAT_API_KEY and CLAUDE_MEM_OPENAI_COMPAT_MODEL to use your provider's OpenAI-compatible endpoint.

Cost: how many extra tokens?

More than most people expect, and it is charged to whichever memory provider you chose:

• Every tool call triggers a note-taking request. By default each request carries one tool call.
• The note-taking AI runs as one ongoing conversation. Each request carries the earlier part of that conversation, and a new conversation starts only when the old one fills up. The official docs measured about 26k tokens for one request at the current default limit, once the conversation is full.
• There is one more request for the summary when a session ends.

A Claude Code session often makes dozens or hundreds of tool calls, so on per-token billing this adds up. CCSub bills cache reads and writes at the input rate, so requests like these, which resend earlier content each time, don't get cheaper through cache hits. Ways to spend less:

• Pick a low-priced model (step 2 above).
• Switch to the lighter mode: "CLAUDE_MEM_MODE": "code--chill" keeps only what would be painful to rediscover, so it writes fewer notes.
• Batch requests: set CLAUDE_MEM_CLAUDE_OBSERVATION_BATCH_SIZE to something like 4 so several tool calls go into one request (allowed range 1–32).
• Shorten the conversation limit: lower CLAUDE_MEM_OBSERVER_MAX_CONVERSATION_CHARS (default 100000 characters) so each request carries less history.
• Pause recording: "CLAUDE_MEM_OBSERVER_ENABLED": "false" stops new notes; existing memory and search still work.

The reliable answer is your own bill. On CCSub, add up these requests for a time range on the Usage page to see roughly how much extra a day costs.

Notes in another language

Notes are written in English by default. To get them in Chinese, for example, add this to ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_MODE": "code--zh"
}

Restart Claude Code to apply it. The built-in light mode, code--chill, exists only in English, so you choose between fewer notes and notes in your language unless you write a custom mode.

Privacy and what's on by default

• To keep something out of memory, wrap it in <private> and </private>.
• Anonymous usage analytics are on by default. Turn them off with npx claude-mem telemetry disable.
• Screenshots from tool results are kept by default in ~/.claude-mem/media-v1/. Turn off Keep images under Images on the settings page to stop that.
• Auto-update runs daily by default. To stop it, set "CLAUDE_MEM_AUTO_UPDATE": "false" in settings.json.
• Memory stays on your machine; cloud sync is opt-in.

Troubleshooting

No memory in a new session? The first session only records, so check the second one. If there's still nothing, run npx claude-mem doctor; it checks Bun, uv, the hook launcher and the background service. On a third-party API, go through the extra step above first.

memory hooks are not active? Run npx claude-mem install as the message says, then restart Claude Code. These hooks need Claude Code 2.1.139 or later; check with claude --version.

Daily quota running out faster than before? The extra usage is note-taking. Tune it with the settings in the cost section, or pause recording for a day to compare.

Does it depend on your API provider?

claude-mem doesn't change Claude Code's own API settings; Claude Code keeps using the service you configured. It adds a separate note-taking AI, and that part needs its own URL and key. With an Anthropic login, the default install is enough. With a third-party API, remember the extra step.

If you haven't set up Claude Code yet, see the Claude Code setup guide; for Codex, see the Codex CLI guide.