Configuration

Environment variables and settings for Claude-Mem

​

Configuration

​

Settings File

Settings are managed in ~/.claude-mem/settings.json. The file is auto-created with defaults on first run.

​

Choose bundled skills

All bundled skills are enabled by default. To hide unwanted skills from Claude Code’s listing and slash commands, add their folder names to settings.json:

{
  "CLAUDE_MEM_SKILLS_DISABLED": "make-plan,do,smart-explore"
}

A JSON array of names also works. Use bare names such as make-plan, not claude-mem:make-plan. Names are case-sensitive; paths and wildcards are rejected. The environment variable CLAUDE_MEM_SKILLS_DISABLED overrides the file, including an empty value. Save the preference in settings.json if it must survive updates started by a process that does not inherit your shell’s environment.

The installer applies the list to the installed version cache and marketplace copy on install, update, and repair. The published package and source checkout keep every skill. New skills introduced by an update remain enabled unless named in the list. This controls plugin skill discovery, not memory capture or MCP tools.

Four skills always stay enabled, because claude-mem reads their files while it runs. If you list one of them, it is left in place and the installer and SessionStart hook print a warning naming it:

Skill	Read by
mem-search	The /api/instructions endpoint and install --ide codex
how-it-works	The viewer’s “How it works” explainer
request-progress	The My Work refresh
owner-goals	The My Work refresh

Claude Code’s SessionStart hook also reapplies the list after marketplace updates and settings changes. When it reports that selection changed, restart Claude Code to reload its skill listing: the current session may have already loaded the old list. Removing a name, or setting the list to "", restores that skill through the same flow. Other hosts may cache their own copy and need a reinstall/reload.

Skills are moved, not deleted, to .claude-mem-disabled-skills beside the installed skills directory. If an update supplies a new copy in the same directory, the older copy is preserved in .claude-mem-disabled-skills/.history; enabling the skill uses the new copy. These are install-local backups, not a backup of custom edits across reinstalls, which already replace the installed plugin tree. Use the normal updater rather than overlaying a partial plugin tree: if a partial update removes an upstream skill but leaves its parked copy, re-enabling it can restore that older copy.

An invalid setting or unsafe path leaves skill content in place and reports the problem; install and repair still finish. Symbolic links, foreign backup directories, and incomplete skill folders are refused. Concurrent sessions serialize changes with the empty .claude-mem-skill-selection.lock directory. If a process is killed during a change, close the other sessions, inspect the installed tree, remove that empty lock directory, and restart to finish applying the saved selection.

​

Core Settings

Setting	Default	Description
CLAUDE_MEM_MODEL	haiku	Claude model used to compress observations (when using the Claude provider). haiku follows the newest Haiku; a full ID pins one version
CLAUDE_MEM_PROVIDER	claude	AI provider: claude, codex, gemini, openrouter, or openai-compatible
CLAUDE_MEM_PROVIDER_BY_SOURCE	empty	Picks the observer provider per harness: a JSON object that maps a session’s source to a provider, for example "{\"codex\":\"codex\",\"claude\":\"claude\"}". Codex sessions then run on the Codex provider and Claude Code sessions on Claude, whatever CLAUDE_MEM_PROVIDER says. Sources without an entry use CLAUDE_MEM_PROVIDER, and so does an entry whose provider is not configured (for example Gemini without a key). Empty uses CLAUDE_MEM_PROVIDER for every session. Editing settings.json by hand, you can write a plain JSON object instead of a string. A malformed value is rejected by the settings API; found in the file, it is ignored with one warning in the log. The Claude CLI is checked at worker boot when any source maps to claude. The worker’s health status still reports the global provider. See Quota Fallback
CLAUDE_MEM_CLAUDE_AUTH_METHOD	subscription	Claude provider auth mode: subscription, api-key, or gateway
CLAUDE_MEM_CLAUDE_OBSERVATION_BATCH_SIZE	1	Queued observations the Claude provider may send in one observer prompt (1–32). Only events with the same prompt number, agent and working directory are combined, in queue order, and queued events are added only while the prompt stays within two capped fields. Raise it when one session queues events faster than its observer answers. Trade-offs, as with Codex batching: every observation from a batched reply lists the files of all events in the batch, and a reply that fails twice drops the whole batch. An environment variable of the same name overrides settings.json.
CLAUDE_MEM_LLM_TIMEOUT_MS	180000	Per-request deadline (ms, 500–300000) for non-streamed observer requests: Gemini, Codex, and the cmem.ai gateway (plus any OpenAI-compatible endpoint that refuses streaming). It exists to catch a hung request; a slow backend just needs a higher value. OpenRouter and OpenAI-compatible requests are streamed and are not bounded by this setting: they end after the idle window (CLAUDE_MEM_LLM_STREAM_IDLE_TIMEOUT_MS) with no token or keep-alive, with a 300-second cap on the whole request. A settings.json still holding the old 30000 default is moved to the new default once; a 30000 you set after that is kept. An environment variable of the same name overrides settings.json.
CLAUDE_MEM_FIELD_OPTIMIZE_TIMEOUT_MS	180000	Deadline (ms, 500–300000) for condensing one oversized tool field before its observation is sent; on expiry the field is truncated instead. It is a request to the same backend as the observer request, so it has the same default. A settings.json still holding the old 30000 default is moved to the new default once; a 30000 you set after that is kept. An environment variable of the same name overrides settings.json.
CLAUDE_MEM_LLM_STREAM_IDLE_TIMEOUT_MS	90000	Silence (ms, 500–300000) that ends a streamed OpenRouter or OpenAI-compatible request: no token and no keep-alive for this long, and the request is abandoned (a 300-second cap bounds the whole request). Raise it when a self-hosted backend queues requests behind a load balancer — the queue wait is silent, so it reads as idle and the shipped 90 seconds can fire before the backend even starts generating. It is an independent knob, so it does not move CLAUDE_MEM_LLM_TIMEOUT_MS (which streamed requests ignore). An environment variable of the same name overrides settings.json.
CLAUDE_MEM_WORKER_HEARTBEAT_STALE_MS	120000	A silent worker (both health re-probes failed) is spared from the wedged-worker reclaim while its liveness heartbeat is younger than this (ms, 10000–3600000), unless it has finished no HTTP response for 10 minutes. The worker refreshes worker-heartbeat.json every 5 seconds from a timer, so a fresh heartbeat means its event loop is still turning — slow, for example under on-access antivirus, but not dead. A worker with no heartbeat, or one written by a different process, is judged as before. An environment variable of the same name overrides settings.json.
CLAUDE_MEM_MODE	code	Active mode profile (e.g., code--es, email-investigation)
CLAUDE_MEM_CONTEXT_OBSERVATIONS	50	Number of observations to inject
CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES	false	Include observations from every harness in SessionStart context
CLAUDE_MEM_CONTEXT_PROJECTS	current	current reads this checkout’s memory at SessionStart; all reads every project (except excluded ones). The observation cap is shared across projects. Worker runtime only
CLAUDE_MEM_CONTEXT_MAIN_AGENT_ONLY	true	Leave subagent observations out of SessionStart context so their step-logs don’t crowd durable main-session memory out of the window. A subagent row carries both an agent id and an agent type; transcript-watch rows (e.g. Grok Bot seats) stay in. Applies in the server runtime too, where a row counts as a subagent row when the hook event it was generated from carried both. Search and the viewer still show everything.
CLAUDE_MEM_REINFORCE_ALPHA	0	Opt-in ACT-R ranking for SessionStart context. 0 (default) keeps the N most recent observations, unchanged. Above 0 (try 0.5), observations the write path saw re-confirmed on later days can climb into the window: each observation’s creation and re-confirmation days are scored with power-law decay, ln(1 + age^-0.5 + ALPHA · Σ age_k^-0.5). The newest quarter of the window is always kept by recency.
CLAUDE_MEM_WORK_STATE_ENABLED	true	false turns work state off for hosts that track work their own way: SessionStart context leaves out the open lists, and the MCP server leaves the work-state rule (that work_state_write is your canonical to-do list) out of its instructions and neither lists nor runs work_state_write and work_state_read. Lists already written stay in the database and come back when it is turned on again. An environment variable of the same name overrides settings.json. Restart the worker after changing it, and start a new session so the MCP server reads it.
CLAUDE_MEM_AUTO_CLEAR_ENABLED	false	true turns it on. Claude Code only (version 2.1.287 or later, which runs plugin mods). When the conversation reaches CLAUDE_MEM_AUTO_CLEAR_PERCENT of the context window, Claude is asked to save where things stand with work_state_write and end its turn; then /clear runs and continue is sent as your message, so the work carries on in a fresh conversation that starts with the open work state. The conversation is cleared only after a successful save that nothing else followed: if Claude saves nothing, or you stop the turn, nothing is cleared and auto-clear waits for your next /clear. Subagents, -p runs and SDK sessions are never cleared, and a turn you stop never starts it. Your own /clear or /resume cancels a clear that is still to come, and a message you send before it runs holds it back until Claude saves again. Off when work state is off, and while settings.json exists but cannot be read (the last settings read stay in force). An environment variable of the same name overrides settings.json.
CLAUDE_MEM_AUTO_CLEAR_PERCENT	33	Share of the context window, from 1 to 95, at which auto-clear starts. Read again within 30 seconds of a change, with no restart. If a fresh conversation already starts at or past it (a large system prompt against a small window), auto-clear turns itself off until Claude Code restarts instead of clearing in a loop.
CLAUDE_MEM_SEMANTIC_INJECT	false	Add the observations that best match each prompt to that prompt’s context (UserPromptSubmit), on top of SessionStart context.
CLAUDE_MEM_SEMANTIC_INJECT_LIMIT	5	Number of observations added per prompt (1–20).
CLAUDE_MEM_SEMANTIC_INJECT_FORMAT	narrative	narrative adds each match’s title and full narrative. index adds one line per match with its id, title and subtitle and points Claude to get_observations for the details. narrative is the default because it works without Claude making a tool call: in index mode a match it does not expand only contributes its title and subtitle. An index line costs a fraction of a narrative, so index can carry more matches for the same tokens; pair it with a higher limit.
CLAUDE_MEM_SEARCH_RECENCY_DAYS	90	Date-less semantic search (search, search_observations, the timeline) only ranks matches created in the last N days; older matches are left out of the answer. 0 turns the window off so every indexed match stays eligible; a larger N widens it. A request that passes dateStart/dateEnd always uses that range instead of the window. Restart the worker after changing it.
CLAUDE_MEM_FILE_READ_GATE_ENABLED	true	Block whole-file Reads of code files of 32 KB and up that have observation history and send Claude to smart_outline / smart_unfold / get_observations instead (Claude Code only). Targeted Reads with offset/limit still work. false lets every Read through and still adds the file’s timeline as context. See File Read Gate.
CLAUDE_MEM_LINE_ANCHORS_ENABLED	false	Opt-in; only true turns it on. When the worker stores an observation, it then records in the observation’s metadata the path, line number and exact text of up to 3 distinctive lines in the files that observation names, taken from the batch’s Claude Code tool calls and never from model output: a line inside the text an Edit or MultiEdit edit wrote, or a line of a Read with an offset above 1 that its stored tool response holds. A file’s timeline before a Read then ends each such row with where that code is now (@L212), found again by its text (exact, then ignoring whitespace), or (code changed since) when it is gone or now in more than one place: a line number is never guessed. Off, nothing is recorded or read and the timeline is unchanged. The recorded lines are source text and go wherever the observation goes, Cloud Sync included; secrets in them are left out only when auto-redaction (CLAUDE_MEM_REDACT_ENABLED) is on. Set in settings.json, it applies from the next Read and the next stored observation; an environment variable of the same name overrides settings.json, and the worker reads its environment only when it starts. See Line Anchors.
CLAUDE_MEM_WORKER_PORT	37700 + (uid % 100)	Worker service port (per-user default; override for fixed port)
CLAUDE_MEM_WORKER_HOST	127.0.0.1	Worker service host address
CLAUDE_MEM_WORKER_URL	(empty)	Explicit client base URL for the worker API; overrides host and port. Use HTTPS for remote workers. Plain HTTP is accepted only on loopback (including a local port forward). A non-empty URL selects HTTP hook-spool delivery in auto; invalid URLs fail instead of falling back to host and port. A non-empty URL also turns autostart off on that client, so CLAUDE_MEM_WORKER_AUTOSTART does not need setting, and restart refuses to run.
CLAUDE_MEM_WORKER_AUTOSTART	true	Set false when you run the worker yourself (a process manager, a container, worker-service.cjs --daemon). Hooks, the MCP server and start then use a worker that is already running but never launch, kill or recycle one: no lazy spawn, no version-mismatch recycle, no wedged-worker recycle or reclaim. While your worker is down, hooks skip their work quietly instead of counting it as a failure.
CLAUDE_MEM_WORKER_INGEST_TOKEN	empty	Shared token for remote hook-spool delivery. Configure the same value in the worker and each client through settings or the environment. The remote spool endpoint is disabled until the worker has this token. It is masked in settings replies.
CLAUDE_MEM_WORKER_INGEST_MAX_BYTES	5242880 (5 MiB)	Maximum decoded JSON body size for authenticated POST /api/spool/ingest requests, including the envelope. Configure this on the worker and restart it; clients need no change. For 20 MiB, use 20971520. Invalid or non-positive integer values fall back to 5 MiB. Other JSON endpoints retain their 5 MiB limit. Larger limits increase memory and disk use; requests above the limit receive HTTP 413 and clients quarantine the original event.
CLAUDE_MEM_HOOK_SPOOL_TRANSPORT	auto	auto uses HTTP when CLAUDE_MEM_WORKER_URL is set or the worker host is non-loopback, and the filesystem for a local worker. Set http for a loopback port forward configured through host and port, or filesystem only when hooks and worker share the same spool directory.
CLAUDE_MEM_ALLOWED_ORIGINS	(empty)	Comma-separated browser origins (e.g. https://app.example.com) allowed to call the worker API cross-origin, besides http://localhost:* and http://127.0.0.1:*. A page loaded from the worker’s own address (the viewer at http://<lan-ip>:<port>) is always allowed. Other http://localhost:* pages can read the API but not delete: deletes sync to every device, so a DELETE is accepted only from the viewer’s own page, an origin listed here, or a client that sends no Origin header (hooks, the CLI, curl). To block DNS rebinding, the worker also refuses a request whose Host is a DNS name it does not trust. IP addresses, localhost, host.docker.internal, CLAUDE_MEM_WORKER_HOST, the host of CLAUDE_MEM_PUBLIC_URL, and the hosts listed here are trusted. To open the viewer by a machine name, such as http://mybox.local:37777, list that origin here. Restart the worker after changing it.
CLAUDE_MEM_PUBLIC_URL	(empty)	Browser-reachable base URL printed for the viewer (live view, welcome hint, restart link) when the worker runs in a remote sandbox behind a port-forward, e.g. https://37700.host.example. Empty = http://localhost:<port>. The env var wins over the setting. (The hosted server runtime reads the same variable as its own public base URL.)
CLAUDE_MEM_TV_TOKEN	—	Shared secret for Observation TV remote access. Empty = off. With a non-loopback CLAUDE_MEM_WORKER_HOST, only /tv, /tv.html, /stream and GET /api/observations are reachable, and only with this token.
CLAUDE_MEM_DATA_DIR	~/.claude-mem	Data root — every other path (database, chroma, logs, settings.json, worker.pid) derives from this
CLAUDE_MEM_SKIP_TOOLS	ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion	Comma-separated tools to exclude from observations
CLAUDE_MEM_SKIP_BASH_PATTERNS	—	Regular expression matched against each shell command (Claude Code Bash and PowerShell, OpenCode bash, Codex exec_command); on a match the observation is skipped. Empty captures every command. Use alternation for several patterns, e.g. ^(ls|cat|pwd|git status)\b. An invalid regex is ignored, so capture is never dropped
CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS	false	When true, skip every subagent observation (a tool call that carries both an agent id and an agent type). See Subagent & Dynamic Workflow filtering.
CLAUDE_MEM_CODEX_SUBAGENT_INGESTION	false	When true, capture the subagent threads Codex CLI spawns, which its native hooks never report, from their rollout files under ~/.codex/sessions. Off by default: a busy Codex session spawns dozens of subagents a day, and every tool call they make is one more request to your observer provider. CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS=true keeps it off. Restart the worker after changing it.
CLAUDE_MEM_SKIP_AGENT_TYPES	(empty)	Comma-separated subagent agent_type values to skip, e.g. workflow-subagent,Explore,Plan. Main-session observations are unaffected.
CLAUDE_MEM_CAPTURE_ADVISOR_CALLS	false	When true, the Stop hook records each Claude Code advisor tool call (the advice text, the advisor model, and the turn’s prompt) in the local database, readable at GET /api/advisor-calls. The advisor never fires PostToolUse, so the hook reads the end of the transcript for it. <private> content is removed before storage. Worker runtime only; nothing is generated, so it costs no tokens.
CLAUDE_MEM_DELIVERABLES_ENABLED	true	When true, the Stop hook copies the turn’s deliverables (files a work_state_write attached as work_product, and decks, documents, pages, images, video or spreadsheets written outside the source tree) into ~/.claude-mem/deliverables/<project>/, records them, and My Work links them on the request’s card. false turns the copy off; files already in the bucket stay. Worker runtime only, with the worker on this computer; a turn whose prompt is entirely <private> is never copied.
CLAUDE_MEM_REDACT_ENABLED	false	Opt-in auto-redaction: recognized secret patterns are replaced with <redacted type='…'/> markers before storage in tool input and output, prompts, summaries and server-runtime event bodies (not in server-runtime session metadata). See Auto-Redaction for the built-in pattern list
CLAUDE_MEM_REDACT_GENERIC_ENABLED	false	With redaction on, also redact credentials that have no vendor prefix: password=, *_PWD=, *_TOKEN=, *_SECRET=, *_API_KEY= values, bare token= / secret= / api_key= values in config-style positions (JSON keys, env assignments, CLI flags, yaml lines), and Authorization: Bearer …. Lower confidence than the 11 vendor patterns, so it is a separate opt-in
CLAUDE_MEM_REDACT_DISABLED_BUILTINS	(empty)	CSV of built-in pattern names to leave unredacted while the rest stay active, e.g. jwt,slack_token
CLAUDE_MEM_REDACT_CUSTOM_PATTERNS	[]	JSON array of extra { "name", "regex" } patterns, evaluated before the built-ins so they can override a token family
CLAUDE_MEM_REDACT_LOG_MATCHES	false	Log a pattern,count line per redaction scan (the matched bytes are never logged)

​

Subagent & Dynamic Workflow filtering

Claude Code Dynamic Workflows fan a single prompt out to tens-to-hundreds of parallel subagents (agent_type: workflow-subagent). Every tool call by every subagent fires a PostToolUse hook, so claude-mem creates one provider-analyzed observation per call — a single run can emit hundreds-to-thousands of low-signal observations. That can exhaust the configured provider’s free-tier quota (HTTP 429) and drop the rest of the run, including valuable main-session work.

Two settings let you filter these out before any worker round-trip or provider call. Both default to off, so existing behavior is preserved.

• Drop all subagent noise (recommended for heavy workflow users):

  { "CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS": "true" }
  

  This is the robust lever — it catches every subagent tool call (one that carries both an agent id and an agent type) regardless of type. Main-session observations are kept, including claude --agent <type> main threads and transcript-watch hosts such as Grok Bot seats, which carry only one of the two.

• Surgically drop specific agent types (keep some subagents, drop others):

  { "CLAUDE_MEM_SKIP_AGENT_TYPES": "workflow-subagent" }
  

  Add a comma-separated list of agent_type values. The two settings combine as a union: a subagent observation is skipped if the global toggle is on or its agent_type is in the list.

Subagent summaries are already skipped automatically; these settings add the same control for observations. Durable cross-session knowledge generally comes from the main session, so dropping ephemeral subagent steps usually improves signal-to-noise. SessionStart already leaves subagent rows out of injected context by default (CLAUDE_MEM_CONTEXT_MAIN_AGENT_ONLY); these settings go further and skip capturing them at all, which also saves the observer’s provider tokens.

​

Gemini Provider Settings

Setting	Default	Description
CLAUDE_MEM_GEMINI_API_KEY	—	Gemini API key (get free key)
CLAUDE_MEM_GEMINI_API_KEYS	—	Optional: more keys (newline-, comma- or space-separated) to rotate through when one is rate-limited, spent or refused (Multi-Key Rotation)
CLAUDE_MEM_GEMINI_MODEL	gemini-flash-latest	Gemini model: gemini-flash-latest, gemini-flash-lite-latest, gemini-3.5-flash, gemini-3.1-flash-lite, gemini-3-flash-preview

See Gemini Provider for detailed configuration and rate-limit information.

​

Codex Subscription Provider Settings

Run codex login as the user running the worker, then install with npx claude-mem install --provider codex. Add --model gpt-6-luna to choose that model, or select Codex and enter a model in the viewer settings. Codex uses the local CLI subscription login; it does not require an OpenAI API key.

Reinstalling without --model keeps the saved Codex model. On a first install the setting is empty and Codex chooses its default. Clear the Codex Model field in the viewer to return to the default later.

Setting	Default	Description
CLAUDE_MEM_CODEX_MODEL	empty	Codex chooses its default model when empty; otherwise use a model available to your subscription.
CLAUDE_MEM_CODEX_REASONING_EFFORT	low	Reasoning effort: none, minimal, low, medium, high, xhigh, max or ultra, subject to model support; empty uses Codex’s default. Advanced override in settings.json or the environment. An effort or model Codex refuses stops Codex memory until it is changed, and SessionStart says so.
CLAUDE_MEM_CODEX_PATH	codex	CLI executable or path. File or environment only; the viewer settings API cannot change it.
CLAUDE_MEM_CODEX_MAX_CONCURRENT_AGENTS	2	App-server clients that serve requests in parallel (1–8). File only; restart the worker after changing it.
CLAUDE_MEM_CODEX_OBSERVATION_BATCH_SIZE	8	Queued observations Codex may combine into one request (1–32).
CLAUDE_MEM_CODEX_OBSERVATION_BATCH_MAX_CHARS	32000	Character budget for one combined observation request (4000–128000).

The worker uses an isolated codex app-server session for observations and summaries. Codex CLI authentication must be a file-backed ChatGPT login; API-key login is not accepted. Each request uses the shared CLAUDE_MEM_LLM_TIMEOUT_MS deadline. See docs/codex-provider.md in the repository for how failures pause and recover.

​

OpenRouter Provider Settings

Setting	Default	Description
CLAUDE_MEM_OPENROUTER_API_KEY	—	OpenRouter API key (get key)
CLAUDE_MEM_OPENROUTER_API_KEYS	—	Optional: more keys to rotate through when one is rate-limited, spent or refused (Multi-Key Rotation). Never used on the cmem.ai gateway
CLAUDE_MEM_OPENROUTER_MODEL	cohere/north-mini-code:free	Model identifier (supports 100+ models)
CLAUDE_MEM_OPENROUTER_BASE_URL	—	Optional: custom OpenAI-compatible base URL (DeepSeek, LM Studio, IO Intelligence). Settings file or environment only; the viewer displays it read-only
CLAUDE_MEM_OPENROUTER_SITE_URL	—	Optional: URL for analytics
CLAUDE_MEM_OPENROUTER_REASONING_EFFORT	—	Optional: none, minimal, low, medium or high, openrouter.ai only (details)
CLAUDE_MEM_OPENROUTER_APP_NAME	claude-mem	Optional: App name for analytics
CLAUDE_MEM_OPENROUTER_EXTRA_BODY	—	Optional: JSON object of extra request fields, e.g. {"reasoning":{"enabled":false}} (details)

See OpenRouter Provider for detailed configuration, free model list, and usage guide.

​

OpenAI-Compatible Provider Settings

For CLAUDE_MEM_PROVIDER=openai-compatible: any endpoint that speaks /chat/completions, hosted or local.

Setting	Default	Description
CLAUDE_MEM_OPENAI_COMPAT_PRESET	—	Named endpoint preset (list). Empty = custom: set the base URL yourself. Settings file or environment only
CLAUDE_MEM_OPENAI_COMPAT_BASE_URL	—	OpenAI-compatible base URL. Overrides the preset’s. Settings file or environment only; the viewer displays it read-only
CLAUDE_MEM_OPENAI_COMPAT_MODEL	—	Model id, sent as-is. Empty = the preset’s default model
CLAUDE_MEM_OPENAI_COMPAT_OBSERVATION_BATCH_SIZE	1	Queued observations to combine per request (1–32). Default 1 keeps one event per request. Only consecutive events with the same prompt number, agent and working directory are combined, within the model-window character budget. Set in settings.json or an environment variable. See batching trade-offs.
CLAUDE_MEM_OPENAI_COMPAT_API_KEY	—	The key this endpoint issued. Settings file or environment, or OPENAI_COMPAT_API_KEY in ~/.claude-mem/.env; the viewer cannot set it. A local server needs none
CLAUDE_MEM_OPENAI_COMPAT_API_KEYS	—	Optional: more keys to rotate through (Multi-Key Rotation). Settings file or environment, or OPENAI_COMPAT_API_KEYS in ~/.claude-mem/.env

See OpenAI-Compatible Provider for presets and setup.

​

My Work Summary Settings

My Work can generate readable card wording using the configured OpenRouter or OpenAI-compatible chat-completions endpoint. By default it runs only when the primary observer provider is OpenRouter, as before; it never uses another endpoint or a quota-fallback key on its own. Select a provider explicitly to use that endpoint for summaries, including an OpenAI-compatible primary or a provider configured only as a fallback. Explicit selection can incur the endpoint’s usual charges. Generated wording is presentation-only; recorded work and status remain unchanged.

Setting	Default	Description
CLAUDE_MEM_WORK_VIEW_COPY_PROVIDER	empty	Empty uses OpenRouter when CLAUDE_MEM_PROVIDER is openrouter; otherwise generated wording is off. For openai-compatible, the request follows CLAUDE_MEM_OPENAI_COMPAT_REASONING. Set openrouter or openai-compatible to select that endpoint explicitly, or off to disable it.
CLAUDE_MEM_WORK_VIEW_COPY_MODEL	empty	Optional model id used only for My Work wording. Empty uses the selected endpoint’s configured model.

​

My Work Refresh Models

The My Work refresh (goals, grouping, review, focus and story steps) runs on one agent: Claude Code, Codex, Gemini, or the API provider you selected (see CLAUDE_MEM_WORK_VIEW_AGENT below for which one). By default the light steps (grouping, focus) use a small model and the others a stronger one: haiku/sonnet on Claude Code, flash-lite/flash on Gemini, and Codex’s CLI default for the careful steps. On Claude Code the refresh runs on your Claude subscription, so set a model here to cap it, for example haiku. Each setting puts every step of that agent on one model and is read at the start of every refresh.

Setting	Default	Description
CLAUDE_MEM_WORK_VIEW_AGENT	empty	Which agent runs the My Work refresh. Empty uses the agent CLAUDE_MEM_PROVIDER names (claude → Claude Code, codex → Codex, gemini → Gemini) and only that one, so a failed run never moves to another agent’s quota. A provider that is an API endpoint (openrouter, openai-compatible, cmem) uses the first logged-in agent and only that one. Set api to run the refresh on the selected API provider; this spends that provider’s credit every refresh. Set claude-code, codex or gemini to pick a local agent, off to run no agent, or all to let a failed run fall through to every other logged-in agent.
CLAUDE_MEM_WORK_VIEW_CLAUDE_MODEL	empty	Model for every refresh step on Claude Code. Use an alias such as haiku or sonnet. Empty keeps the per-step defaults.
CLAUDE_MEM_WORK_VIEW_CODEX_MODEL	empty	Model id for every refresh step on Codex. Each step keeps its reasoning effort. Empty keeps the per-step defaults.
CLAUDE_MEM_WORK_VIEW_GEMINI_MODEL	empty	Model for every refresh step on Gemini, such as flash-lite. Empty keeps the per-step defaults.
CLAUDE_MEM_WORK_VIEW_API_MODEL	empty	Model for every refresh step on the selected API provider, such as anthropic/claude-sonnet-4. Empty keeps the model your provider is configured with.
CLAUDE_MEM_WORK_VIEW_TEXT_LANGUAGE	empty	Language for the text the refresh writes (request titles, reviews, focus areas, the story), such as Turkish. When set, every step except goals is told to write in it, so separate review batches never pick different languages. Empty uses the language most of your asks are written in, decided once per refresh by the grouping step (which already reads them, so it costs no extra model call) and kept for later refreshes that have nothing to group.

​

Quota Fallback Settings

Setting	Default	Description
CLAUDE_MEM_QUOTA_FALLBACK_PROVIDER	claude	Where observer work goes while the selected provider can’t serve (a spent allowance, rate limits or over-capacity refusals past their retries, an outage, repeated unusable replies), until it recovers: claude (your Anthropic plan, used only when a Claude login or key exists), gemini, openrouter, openai-compatible, or off to wait instead. Empty (from older settings files) = claude. See Quota Fallback
CLAUDE_MEM_QUOTA_FALLBACK_MODEL	—	Claude model for a Claude fallback run. Empty = CLAUDE_MEM_MODEL and tier routing. Ignored for other fallbacks
CLAUDE_MEM_QUOTA_FALLBACK_AUTH_METHOD	—	The Claude credential to run on while the primary one is held for quota: subscription (the Claude Code login, for a spent ANTHROPIC_API_KEY) or api-key (ANTHROPIC_FALLBACK_API_KEY, for a spent or guard-paused login). Tried before CLAUDE_MEM_QUOTA_FALLBACK_PROVIDER. Empty = off. See Quota Fallback

See Quota Fallback for how the fallback starts and ends.

​

Quota Guard Settings

With subscription auth, the observer stops once a usage window reaches its threshold. A window the provider has already rejected always stops it, whatever the threshold. The five-hour window also stops it at 85% or more within 15 minutes of its reset, even below its threshold. API-key auth never stops.

Thresholds are fractions from 0 to 1 (0.93 = 93%). A value outside that range, such as 93, falls back to the default, with a warning in the worker log. A blank value uses the default.

Setting	Default	Description
CLAUDE_MEM_QUOTA_THRESHOLD_FIVE_HOUR	0.95	Five-hour window
CLAUDE_MEM_QUOTA_THRESHOLD_SEVEN_DAY	0.93	Weekly window
CLAUDE_MEM_QUOTA_THRESHOLD_SEVEN_DAY_OPUS	0.93	Weekly Opus window
CLAUDE_MEM_QUOTA_THRESHOLD_SEVEN_DAY_SONNET	0.92	Weekly Sonnet window
CLAUDE_MEM_QUOTA_THRESHOLD_OVERAGE	0.95	Overage, while it is in use

​

Observer Budget Settings

These apply to every observer provider. The observer’s conversation runs in generations. When one fills its budget, claude-mem retires it and starts a fresh one, briefed with the session’s own observations. The budget is the smaller of CLAUDE_MEM_OBSERVER_MAX_CONVERSATION_CHARS and half the observer model’s context window (about 4 characters per token). Each tool call’s parameters and outcome are capped at a tenth of the window, 16,000 characters at most.

Setting	Default	Description
CLAUDE_MEM_OBSERVER_ENABLED	true	false stops new observation and session-summary model calls. Existing memories, search and SessionStart context remain available. In the server runtime, hooks on this machine stop sending events; the server does not read this setting, so jobs it already queued still finish and other clients are unaffected
CLAUDE_MEM_OBSERVER_MAX_CONVERSATION_CHARS	400000	Characters one observer generation may hold before it is retired
CLAUDE_MEM_OBSERVER_CONTEXT_WINDOW	—	Observer model context window in tokens. Empty = resolve it: Claude models 200000 (1000000 for a [1m] model id), Gemini models from a built-in map, OpenRouter models from the OpenRouter models catalogue. Any other OpenAI-compatible endpoint (a local server, a custom gateway) falls back to 131072, so set this for a model with a smaller window, e.g. 16384. Values below 8192 are clamped up to 8192
CLAUDE_MEM_OBSERVER_MAX_OUTPUT_TOKENS	4096	Output-token cap on every OpenRouter, custom-endpoint and Gemini observer request (max_tokens, or max_completion_tokens for endpoints that require it; Gemini maxOutputTokens). Raise it for a reasoning model that spends the cap before it answers. 256–1000000
CLAUDE_MEM_OBSERVE_BARE_PROMPTS	false	false: a user prompt is not sent to the observer on its own; it goes out with the next tool call or summary, in that request. true: one observer request per prompt, as before

If the provider still rejects a request as too long for the model’s window, the observer retires the generation and retries the same work in a fresh one, the same way it handles Claude’s “Prompt is too long”.

For these HTTP providers, the observer’s instructions and output format are sent as the system message, and the user’s request as the first user message. A reply cut off at the output-token cap is logged as a warning that names the cap.

​

Long-Lived Claude Token

With subscription auth, the observer normally reads your Claude Code login from the credential store at every spawn. That login’s access token lasts about 8 hours, and the stored login itself has an end date (claude auth status --json shows it as loginExpiresAt). When it lapses, memory capture stops until you run claude auth login again.

To run the observer without that dependency, create a long-lived token and give it to claude-mem:

1. Run claude setup-token and finish the sign-in. It prints a token tied to your Claude subscription.

2. Add it to ~/.claude-mem/.env:

   CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
   

Env var	Default	Description
CLAUDE_CODE_OAUTH_TOKEN	none	Long-lived token from claude setup-token. Every Claude spawn uses it ahead of the credential store, so no child ever has to refresh a stored login. Not sent to an ANTHROPIC_BASE_URL gateway, and an ANTHROPIC_API_KEY in the same file still takes precedence. A token inherited from the shell is never used; only this file counts

Replace the token when it expires (claude setup-token again). If the token is a JWT whose expiry has passed, the observer logs a warning and falls back to the credential store.

The token applies to every Claude profile. If you set CLAUDE_MEM_CLAUDE_CONFIG_DIR, the observer bills the token’s account rather than that profile’s stored login, but it still tracks quota pauses per profile. Changing the setting therefore starts a fresh quota view even though the account stays the same.

​

Claude Gateway Settings

Gateway credentials live in ~/.claude-mem/.env, not settings.json.

Env var	Default	Description
ANTHROPIC_BASE_URL	none	LiteLLM or Anthropic-compatible gateway URL for the Claude Agent SDK path
ANTHROPIC_AUTH_TOKEN	none	Optional LiteLLM master key or virtual key
ANTHROPIC_API_KEY	none	Direct Anthropic API key; normally omit this in LiteLLM gateway mode
ANTHROPIC_FALLBACK_API_KEY	none	Anthropic API key used only while the Claude Code login is held for quota (CLAUDE_MEM_QUOTA_FALLBACK_AUTH_METHOD=api-key). Never passed to the CLI otherwise

Use LiteLLM Gateway when you want CLAUDE_MEM_PROVIDER=claude to route through LiteLLM while preserving the Claude Agent SDK worker path.

Setting	Default	Description
CLAUDE_MEM_OBSERVER_THINKING	disabled	The thinking parameter the Claude observer sends. disabled saves tokens on Anthropic-native endpoints. omit sends no thinking field, for a gateway whose upstream model always thinks and rejects disabled (for example GLM’s error 1210). adaptive lets the model decide how much to think, the only way to turn thinking on for models that accept no budget, such as Claude Haiku 5.5. enabled or enabled:<budget> (default budget 1024) turns thinking on and spends thinking tokens on every observer request. The server runtime’s claude provider reads the same setting from its environment, and adds an enabled budget to CLAUDE_MEM_SERVER_MAX_OUTPUT_TOKENS so thinking can’t spend the answer’s tokens

If an Anthropic-compatible gateway rejects the thinking parameter with a 400, the worker’s observer drops the parameter for the rest of that session and retries the same batch, so nothing is lost while you change the setting. The server’s provider doesn’t retry; set omit for such a gateway.

​

System Configuration

Setting	Default	Description
CLAUDE_MEM_DATA_DIR	~/.claude-mem	Data directory location
CLAUDE_MEM_LOG_LEVEL	INFO	Log verbosity (DEBUG, INFO, WARN, ERROR, SILENT)
CLAUDE_MEM_FETCH_VERBOSE	(unset / off)	Opt-in worker-IPC fetch() diagnostics (1/true/on/yes). Passes Node/undici { verbose: true } and writes the error cause chain on socket-level hook failures. Default stays off.
CLAUDE_MEM_SESSION_INIT_TIMEOUT_MS	10000 (7000 on Windows)	Total time the UserPromptSubmit hook may spend reaching the worker for each prompt (startup check, session init, semantic context). When it runs out, the prompt goes through without memory for that turn. Accepts 500–14000; it has to stay under Claude Code’s 15 s timeout for that hook. The clock starts after the hook process has loaded, which takes 4–5 s on Windows, so on Windows the default is 7000 and any higher value is cut to 7000. Codex keeps its own bounded worker-startup wait, and its requests stay within this budget. Also read from the environment.
CLAUDE_MEM_HOOK_HANDOFF_TIMEOUT_MS	250	Per-event timeout (ms) for live hook observation, file-edit, and summary delivery to the worker. The hook waits up to this long before it exits, so a larger value adds that much to the hook’s time on a slow worker. When the deadline expires, the hook skips the event and logs it at WARN; nothing is retried or written to a replay spool. Accepts 1–14000 (larger values are cut to 14000, which keeps the hook under Claude Code’s 15 s hook timeout). Also read from the environment.
CLAUDE_MEM_IDLE_EXIT_SEC	0 (off)	Opt-in worker idle exit, in seconds. 0 (the default) never exits, and values from 1 to 59 are raised to 60. Once this long passes with no session activity or running observer, no queued work, no open or recent request (a viewer tab, a memory search, a corpus build) and no AI interaction, the worker stops through the same graceful shutdown as claude-mem stop (telemetry shutdown_reason: idle). The next hook that reads memory, such as session start or your next prompt, starts it again. That first prompt pays a cold start and goes without memory if the boot outlasts the hook’s time budget, and observations captured in between wait in the hook spool until the worker is back. Turn it on only where claude-mem’s hooks run, such as Claude Code and Codex. Leave it off for OpenCode plugin capture and OpenClaw, which never start the worker, and for MCP-only hosts, where the first memory call after each idle exit waits for a worker boot. It stays off with CLAUDE_MEM_WORKER_AUTOSTART=false or while transcript watches are active, since nothing would start the worker again. Cloud sync and transcript capture run only while the worker is up. Also read from the environment.
CLAUDE_MEM_TOOL_USES_SEARCH_ENABLED	false	Local-only, optional FTS5 index of stored raw tool inputs/responses. Restart the worker after changing this setting. Once built, search with deep:true can find raw evidence when observation search succeeds with no matches on its first page. Indexing runs in committed batches after core search is ready. Disabling drops only the derived index and its triggers; raw rows remain. See raw evidence search for scope, costs, and failure semantics.
CLAUDE_MEM_TOOL_USES_RETENTION_DAYS	0 (keep forever)	Opt-in retention for the raw tool input/response index behind get_tool_uses. With a positive number of days, the worker deletes tool_uses rows older than that and linked to an observation that still exists, once at start. Rows with no observation, or whose observation was deleted, are the only copy of that tool I/O and are never deleted. A purged id returns the usual not-found result from get_tool_uses. Freed pages are reused by SQLite; shrinking the file on disk needs a VACUUM. 30 and "30" both work. Anything that is not a whole number of days (empty, negative, abc) keeps everything.
CLAUDE_MEM_LOG_RETENTION_DAYS	30	How many days of daily worker logs (~/.claude-mem/logs/claude-mem-YYYY-MM-DD.log, named by UTC date) to keep. The worker deletes older ones 5 minutes after it starts and then once a day; hooks and the MCP server never do. Today’s and yesterday’s files are always kept, and so is any file written to within the window. Other files in the folder, such as runner-errors.log, are never touched. 0 keeps every log forever, as before. 30 and "30" both work. Anything that is not a whole number of days (empty, negative, abc) also keeps everything.
CLAUDE_MEM_AUTO_UPDATE	true	Whether claude-mem updates itself to the release its owner promotes: one check a day, installed while you are away. false turns it off; only true turns it on (in any case), so any other value leaves it off. This is the reliable off switch, including on managed machines. Read again every hour, so no restart is needed. Off in settings.json or in an environment variable of the same name turns it off; the environment cannot turn it on over a saved false. File/env only — not writable via the viewer HTTP API. See Auto-update.
CLAUDE_MEM_AUTO_UPDATE_PROMOTED_RELEASE_URL	(empty — the built-in release file)	Where the daily check reads the promoted version. Empty means https://raw.githubusercontent.com/thedotmack/claude-mem/main/releases/promoted-release.json, the owner’s release switch. Set it only to test against your own file (for example a local server or a file:// URL). Read from settings.json only: an environment variable of the same name is ignored, so whatever starts the worker cannot point it at another file. Not writable via the viewer HTTP API.
CLAUDE_MEM_PYTHON_VERSION	3.13	Python version for chroma-mcp
CLAUDE_MEM_CHROMA_UVX_PATH	(empty — search uv’s install folders, then PATH)	The uvx that launches chroma-mcp, as the full path to the binary (on Windows, e.g. C:\Users\you\AppData\Local\Programs\Python\Python313\Scripts\uvx.exe) or its folder. Set it when pip install uv put uvx outside uv’s usual folders, or when another tool’s uvx comes first on PATH. An environment variable of the same name overrides settings.json. File/env only — not writable via the viewer HTTP API. Restart the worker after changing it.
CLAUDE_MEM_ONLINE_OPTIN	(unset — ask)	Environment variable only. false skips the installer’s optional email question. It is also skipped without a terminal (agent-run installs), when CI is set, and once an email is saved (CLAUDE_MEM_ONLINE_SIGNUP_EMAIL in settings.json).
CLAUDE_CODE_PATH	(auto-detect)	Path to Claude Code CLI (for Windows). File/env only — not writable via the viewer HTTP API.
CLAUDE_MEM_PROJECT_NAME_SOURCE	path	How a git repository’s project name is derived: path (the repository folder’s name) or git-remote (a stable org/repo slug from the origin remote, which survives renaming the folder and tells same-named repositories apart; every worktree of the repository shares it). Opt-in. Memory stored under the folder name before you switch stays readable. See Project Names.
CLAUDE_MEM_PROJECT_ENVIRONMENTS	[]	Named environments: a JSON array of {"name", "patterns", "inherit?"}. Optional inherit selects which additional project keys remain readable; [] isolates the environment from derived keys. Folders matching an environment’s glob patterns (the same rules as CLAUDE_MEM_EXCLUDED_PROJECTS) share one project named after it. See Project Names.
CLAUDE_MEM_CLAUDE_CONFIG_DIR	(unset — falls through to CLAUDE_CONFIG_DIR/~/.claude)	Override which CLAUDE_CONFIG_DIR profile’s OAuth keychain entry to read, and which CLAUDE_CONFIG_DIR the spawned SDK subprocess sees. For running multiple named Claude Code profiles (e.g. ~/.claude-profiles/<name>, each logged in separately) side by side on one machine. macOS only for the keychain lookup; Windows/Linux credential stores are not profile-aware yet.
CLAUDE_MEM_OBSERVER_CLAUDE_CONFIG_DIR	(unset — transcripts follow the credential profile dir)	Transcript-only CLAUDE_CONFIG_DIR for claude-mem’s internal SDK sessions (observer, knowledge corpus). By default they persist under ~/.claude/projects/, where importers like Codex pick them up as user chats; set this to a dedicated directory (e.g. ~/.claude-mem/observer-claude) to keep them out. Credentials are unaffected — the worker keeps reading your default login and injects a fresh OAuth token at each spawn, so the directory itself never needs to be logged in. Only honored while CLAUDE_MEM_CLAUDE_CONFIG_DIR is unset (an explicit profile keeps its transcripts beside its credentials by design). Two things to know: a token-injected subprocess cannot refresh the token itself — capture pauses with the usual re-login notice if your Claude Code login expires — and sessions recorded before you set this cannot be resumed — a corpus primed before enabling this misses its resume once, and its next query recovers automatically through the existing reprime path into a fresh session here. To carry the old session over instead of starting fresh, move the store first: mkdir -p <dir>/projects && mv ~/.claude/projects/-<munged-home>-claude-mem-observer-sessions <dir>/projects/.

​

Grok Bot Brainbeat Webhook

Optional. Set CLAUDE_MEM_GROK_BOT_WEBHOOK_URL and claude-mem POSTs every observation that matches the Grok Bot awareness triggers (CLAUDE_MEM_GROK_BOT_AWARENESS_TRIGGER_TYPES / CLAUDE_MEM_GROK_BOT_AWARENESS_TRIGGER_CONCEPTS, default types decision,bugfix,security_alert,sensitive) to that URL. It is independent of every Telegram setting.

Setting	Default	Description
CLAUDE_MEM_GROK_BOT_WEBHOOK_URL	—	Receiver for brainbeat POSTs; empty = off. File/env only, masked by GET /api/settings
CLAUDE_MEM_GROK_BOT_WEBHOOK_SECRET	—	Optional shared secret sent as x-claude-mem-shared-secret. File/env only, masked by GET /api/settings

Each matching observation is sent as one JSON POST:

{
  "event": "claude_mem.brainbeat",
  "observation_id": 1234,
  "type": "security_alert",
  "title": "PII exposure in logs",
  "subtitle": "Raw token printed in retry path",
  "project": "payments-service",
  "concepts": ["auth", "logging"],
  "why_fired": {
    "matched_type": true,
    "matched_concepts": ["auth"]
  },
  "timestamp": "2026-09-02T02:56:46.087Z"
}

POSTs are sent concurrently and each times out after 5 seconds. Redirects are refused, so the shared secret and the observation only ever go to the configured URL; put the receiver’s final address in the setting. A failure is logged with the receiver’s origin and a short reason only (never the full URL) and never blocks observation storage or other notifications.

​

Notion Export

Optional. Copies each new observation into a Notion database as it is stored. See Notion Export for setup and the database schema.

Setting	Default	Description
CLAUDE_MEM_NOTION_ENABLED	false	Turn the export on
CLAUDE_MEM_NOTION_TOKEN	—	Notion integration secret. File/env only, masked by GET /api/settings
CLAUDE_MEM_NOTION_DATABASE_ID	—	Target database id or URL
CLAUDE_MEM_NOTION_AUTO_CREATE_PROPERTIES	true	Add missing database properties on first run

​

Near-Duplicate Deduplication

Opt-in (off by default) dedup of observations whose titles describe the same recurring work but are worded slightly differently, so content_hash (byte-identical only) misses them. Two deterministic tiers:

• Tier 0 — exact-normalized-title → safe silent auto-merge: a new observation whose title matches an existing one after lowercasing / whitespace-collapse / punctuation-strip is collapsed onto the existing row and its occurrence_count is bumped (cross-session, within the same project, the same host platform and the same agent scope: main session work never merges into a subagent row, which SessionStart leaves out). Rows stored before an upgrade are re-keyed by POST /api/dedup/scan.
• Tier 1 — IDF-weighted similarity → review-only near-duplicate candidates are recorded in observation_dedup_candidates (never auto-merged), so distinct work that differs only in one rare token (rdlp-api vs rdlp-plugin) is never silently destroyed.

Setting	Default	Description
CLAUDE_MEM_DEDUP_ENABLED	false	Master switch. Off = byte-identical legacy behavior
CLAUDE_MEM_DEDUP_COSINE_THRESHOLD	0.80	Min IDF-weighted cosine for a Tier-1 candidate
CLAUDE_MEM_DEDUP_IDF_VETO_DF	10	A title token in ≤ N project rows is “discriminating” and vetoes a merge
CLAUDE_MEM_DEDUP_MIN_SHARED_TOKENS	2	Require ≥ N shared tokens before scoring (kills sparse-vector noise)
CLAUDE_MEM_DEDUP_MIN_PROJECT_DOCS	10	Cold-start gate: skip Tier-1 below N docs/project (IDF unreliable)
CLAUDE_MEM_DEDUP_MAX_SCAN	2000	Per-insert Tier-1 candidate-scan cap
CLAUDE_MEM_DEDUP_MAX_BACKFILL_ROWS	50000	dedup-scan skips a project larger than this (memory safety)

After enabling on an existing database, run a one-time scan to backfill the IDF model and surface accumulated near-duplicates: POST /api/dedup/scan (worker, localhost-only). Review candidates via GET /api/dedup/candidates?project=<name> (add &status=pending to see only unreviewed ones), and record a verdict with POST /api/dedup/candidates/<id>/resolve and a body of {"status": "distinct"} or {"status": "dismissed"}. A later scan keeps the verdict.

​

Screenshots and Images

claude-mem keeps the screenshots and images that tools return (browser screenshots, a Read of an image file inside the project) and shows them on the request they belong to in My Work, both on this computer and at work.cmem.ai. Keeping images is on by default. Letting the observer model look at them is a separate switch that is off by default: keeping images never sends one to a model.

To stop keeping images, turn off Keep images under Images in the memory viewer’s Settings (/viewer on your worker’s port), or set CLAUDE_MEM_MEDIA_CAPTURE_ENABLED to false. Images already kept stay until their event is deleted. An install whose settings.json still holds the old false default is moved to true once, on the first worker start after the update; a false you set after that is kept.

Setting	Default	Description
CLAUDE_MEM_MEDIA_CAPTURE_ENABLED	true	Convert and retain images from tool results, and show them in My Work (the Keep images switch)
CLAUDE_MEM_MEDIA_INFERENCE_ENABLED	false	Send retained images to the observer model when the endpoint qualifies

What is stored. Only PNG, JPEG and WebP images, at most four per tool event and 3 MiB each, are accepted. Each one is converted to two WebP copies: a full-size viewer copy and a smaller copy (longest edge 1536 px, at most 256 KiB) for the model. Conversion strips EXIF/GPS metadata. The original bytes are not kept: the image body is replaced by a short descriptor before the tool result is written to the database, so the raw base64 never reaches tool_uses, the observer prompt, logs or sync. If the image came from a file, its path is recorded so the viewer can tell you whether that file still exists; the path is shown only when you ask for source details in the image viewer and never appears in feeds, logs or sync.

Where it lives. Converted copies are written under <data dir>/media-v1/<attachment-id>/ (by default ~/.claude-mem/media-v1/), readable only by your user. The worker serves them only to the viewer page on the same loopback port; other origins, LAN clients and proxies are refused.

How long it is kept. Images are kept on this computer until their event is deleted: an image lives as long as an observation or its source tool event still references it. There is no total size cap and no age limit; each image is at most about 3.25 MiB on disk and an event keeps at most four. Deleting an observation, a session or a project removes the references at once; the files are removed by a background cleanup within about 30 seconds (retried with backoff if the disk refuses). Images are never kept for analytics.

Cloud upload. When capture is on and Cloud Sync is configured, each converted image is uploaded privately to your cmem.ai account so your other devices and My Work at work.cmem.ai can show it; they download it on first view. Deleting it locally also deletes the cloud copy. Observation text syncs without the image bytes.

Third-party image inference. When inference is on and the observer endpoint qualifies (OpenRouter directly, or the cmem.ai gateway), the model-sized copy of each image in the current tool event is sent with that one observer request to the model provider behind that endpoint (OpenRouter and the provider it routes to). It is not re-sent in later turns, summaries or context injection. Other providers stay text-only. If the endpoint rejects images, the turn is resent once without them and the images are marked “not inspected”.

Logs and metrics about images contain only attachment IDs, byte sizes, dimensions, the conversion recipe, error codes and timings. They never contain pixels, paths, URLs, captions or your text. The cmem.ai gateway additionally receives an X-Cmem-Correlation header holding a random request ID, the retry attempt number and up to four hashed event IDs, so metered usage can be tied to a request.

​

Model Configuration

Configure which Claude model compresses your observations (only applies when CLAUDE_MEM_PROVIDER=claude).

​

Available Models

Value	Notes
haiku	Default — the newest Haiku, fastest, ideal for compression
sonnet	The newest Sonnet, balanced quality and speed
opus	The newest Opus, highest quality (slowest)

Each alias follows the newest model of its tier, so new releases (usually cheaper or better for the price) reach you without a settings change. A full model ID, such as claude-sonnet-5, pins that one version and never updates. Installs that had the old shipped default claude-haiku-4-5-20251001 saved are moved to haiku automatically, except gateway installs (see Manual Configuration below).

​

Picking via the Installer

npx claude-mem install prompts for the Claude model (when the Claude provider is selected) and persists the choice to ~/.claude-mem/settings.json.

​

Manual Configuration

Edit ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_MODEL": "haiku"
}

haiku moves to each new Haiku release on its own. A full model ID such as claude-haiku-4-5-20251001 pins that one version and never updates, so use one only when you deliberately want to stay on it. Installs that saved the old default, claude-haiku-4-5-20251001, are moved to haiku automatically, except gateway installs (an ANTHROPIC_BASE_URL in ~/.claude-mem/.env, or the auth method set to gateway), which keep their saved model because the gateway decides which model names it accepts.

​

Mode Configuration

Configure the active workflow mode and language.

​

Settings

Setting	Default	Description
CLAUDE_MEM_MODE	code	Defines behavior and language. See Modes & Languages.

​

Examples

Spanish Code Mode:

{
  "CLAUDE_MEM_MODE": "code--es"
}

Email Investigation Mode:

{
  "CLAUDE_MEM_MODE": "email-investigation"
}

​

Project Names

claude-mem files every observation under a project name, and SessionStart injects the memory stored for the current project.

• Inside a git repository the name is the repository root’s folder name, so every subfolder shares it. A git worktree is stored as <repo>/<worktree> (a worktree whose folder has the repository’s own name, like Codex’s ~/.codex/worktrees/<id>/<repo>, is stored as <repo>) and a git submodule as <superproject>/<path>; both also read their parent repository’s memory. Memory a submodule stored under its own folder name before it was grouped this way stays readable from it. When a worktree or submodule checkout is deleted, the worker folds its memory into the parent repository at its next start (merged or not), so nothing is stranded.
• With CLAUDE_MEM_PROJECT_NAME_SOURCE=git-remote a repository that has an origin remote is named by its org/repo slug instead (e.g. thedotmack/claude-mem), so renaming or re-cloning the folder keeps its memory, two repositories with the same folder name stay apart, and every worktree of the repository shares the slug (a submodule, being a repository of its own, is named by its own origin). Memory stored under the folder-based names stays readable, and a deleted worktree’s memory from before the switch is still folded into the repository. Repositories without a usable origin (or with a local one) keep the folder-based name.
• Outside git the name is the current folder’s name. To give a non-git project one name across all of its subfolders, put an empty .claude-mem-project file (or a .claude-mem.json) in its root folder: every folder below it then uses the root folder’s name. Memory stored under a subfolder’s own name before you added the file stays readable from that subfolder. Marker files in your home directory, the system temp directory or Claude’s config directory are ignored, so they can never fold unrelated folders together.
• Named environments (CLAUDE_MEM_PROJECT_ENVIRONMENTS) group several folders, git or not, into one project and win over every rule above. For example, [{"name": "acme", "patterns": ["~/work/acme/**"]}] files everything under ~/work/acme as acme, and SessionStart labels it as an environment. Memory those folders stored under their own names stays readable from them; to fold it into the environment for good, run npx claude-mem project merge <old-name> acme (it runs inside claude-mem’s worker whenever the worker is running). The merge rewrites nothing (rows are marked as merged, the way a worktree folds into its repository) and brings along memory already folded into the old name, such as a merged worktree’s. It reaches your other devices through cloud sync and updates semantic search; if that last step fails, the command says so, and running it again retries it.

​

Choosing an environment’s memory scope

By default, naming an environment retains the folder and git-remote keys it previously read. To keep a business or package inside a larger repository from reading the parent’s entire history, set inherit explicitly:

{
  "CLAUDE_MEM_PROJECT_ENVIRONMENTS": [
    { "name": "business-a", "patterns": ["~/Workspace/business-a/**"], "inherit": [] },
    { "name": "business-b", "patterns": ["~/Workspace/business-b/**"], "inherit": ["shared"] }
  ]
}

• Omitted inherit keeps existing behavior: derived keys and the environment key are readable.
• inherit: [] reads only the environment key and memory explicitly merged or adopted into it.
• inherit: ["shared"] reads the environment and the listed project keys, including their existing merged history, without automatically adding parent, folder, or remote-derived keys. Entries are project names, not environment names to resolve recursively or path patterns.

Writes still use name. This changes the checkout’s default read scope for SessionStart, semantic injection, file context, and MCP queries for that project; it does not move or delete stored history. Ordinary worktrees and submodules with no explicit inheritance configuration keep their existing behavior. Reading a project’s memory does not merge the environment’s history back into that project. Automatic orphan adoption uses recorded folder-derived identity, not the environment’s read scope.

inherit must be an array of non-empty project names. Names are trimmed and deduplicated, and cannot contain commas (the query protocol uses commas to separate projects). An invalid explicit value raises a configuration error rather than reverting to the broader derived scope; correct it before using those hooks.

This setting selects default context, not access permissions. Explicit queries for other projects and CLAUDE_MEM_CONTEXT_PROJECTS=all can still read a broader scope. Previously performed whole-project merges also remain in effect.

Environment patterns and CLAUDE_MEM_EXCLUDED_PROJECTS use the same glob rules. A complete **/ segment matches zero or more directories: ~/work/**/private matches both ~/work/private and ~/work/team/private. Add a trailing /** to match their descendants too.

​

Files and Directories

​

Data Directory Structure

The data directory location depends on the environment:

• Production (installed plugin): ~/.claude-mem/ (always, regardless of CLAUDE_PLUGIN_ROOT)
• Development: Can be overridden with CLAUDE_MEM_DATA_DIR

~/.claude-mem/
├── claude-mem.db           # SQLite database
├── .install-version        # Version marker written by `npx claude-mem install`/`repair`
├── settings.json           # Worker port + provider/model settings
├── media-v1/               # Converted screenshots/images (only when media capture is on)
└── logs/
    ├── worker-out.log      # Worker stdout logs
    └── worker-error.log    # Worker stderr logs

​

Plugin Directory Structure

${CLAUDE_PLUGIN_ROOT}/
├── .claude-plugin/
│   └── plugin.json         # Plugin metadata
├── .mcp.json               # MCP server configuration
├── hooks/
│   └── hooks.json          # Hook configuration
├── scripts/                # Built executables
│   ├── claude-mem-launcher.cjs # Compiled at install into the on-PATH `claude-mem` hook launcher
│   ├── ensure-launcher.cjs # Startup SessionStart self-heal for the launcher
│   ├── version-check.js    # Setup hook (--init / --maintenance): completes missing dependencies, records the install marker
│   ├── worker-service.cjs  # Worker service + hook dispatcher (CJS)
│   └── mcp-server.cjs      # MCP search server (CJS)
└── ui/
    └── viewer.html         # Web viewer UI bundle

​

Plugin Configuration

​

Hooks Configuration

Hooks are registered in plugin/hooks/hooks.json. Each runtime hook is one exec-form entry with no shell, {"command": "claude-mem", "args": ["hook", "claude-code", "<event>"]}. Claude Code finds claude-mem on PATH: a small compiled launcher that npx claude-mem install / update place at ~/.local/bin (POSIX) or %LOCALAPPDATA%\claude-mem\bin (Windows). The launcher runs the single dispatcher, worker-service.cjs hook claude-code <event>, under Bun. The events wired up are:

• Setup → version-check.js (installs missing plugin dependencies, records .install-version). The only bash entry; Claude Code fires it only for claude --init / --maintenance.
• SessionStart → claude-mem start (worker, async), then hook claude-code context (context injection); at startup also node ${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs, which places or refreshes the launcher for marketplace-only installs
• UserPromptSubmit → hook claude-code session-init
• PreToolUse (matcher Read) → hook claude-code file-context (synchronous: adds the file’s observation timeline as context and can block whole-file Reads; see File Read Gate)
• PostToolUse (matcher *) → hook claude-code observation
• Stop → hook claude-code summarize
• SessionEnd → hook claude-code session-end

The exact hooks.json entries are generated by scripts/build-hooks.js and shipped with the plugin; do not hand-edit them in the marketplace copy unless you know what you’re doing. npx claude-mem doctor shows a Hook launcher row for the claude-mem the hooks will run.

​

Turning off the tool hooks

These switches are read from the hook’s environment only, not from ~/.claude-mem/settings.json. Set them under the env block in ~/.claude/settings.json (Claude Code passes that block to every hook) or export them in your shell:

Variable	Effect when set to 1
CLAUDE_MEM_DISABLE_TOOL_HOOKS	PreToolUse (file-context) and PostToolUse (observation) return a no-op right away. SessionStart, UserPromptSubmit and Stop keep working.
CLAUDE_MEM_DISABLE_OBSERVATION	Only PostToolUse observation returns a no-op (tool calls are no longer captured).
CLAUDE_MEM_DISABLE_FILE_CONTEXT	Only PreToolUse file-context returns a no-op: no file history is injected before Read, and the File Read Gate never blocks a Read.

Claude Code still launches each hook. The claude-mem hook launcher checks these switches before resolving the plugin or starting Bun, so a disabled tool hook does not load the worker bundle. The Codex shell hooks check them before starting Node; the Codex Windows launcher still starts Node, then checks the switch before resolving scripts or starting Bun. These switches do not change the feature settings in settings.json.

​

Turning off the end-of-session summary

Variable	Effect when set to 1
CLAUDE_MEM_DISABLE_SUMMARY	The Stop hook (summarize) skips the end-of-session summary and advisor-call capture: no observer-model call and no session_summaries row. SessionStart and UserPromptSubmit keep working, and Kimi’s context refresh after a compaction still happens.

Orchestrators that launch short headless runs (a codex exec review of a staged diff, say) usually set CLAUDE_MEM_DISABLE_OBSERVATION=1 so nothing the run observes is captured. The summary switch completes the picture for those runs: they keep reading claude-mem context at session start, but their Stop no longer writes a summary of an intermediate diff into the project’s recent summaries. Unlike the tool-hook switches, this check runs inside the summarize handler, so the hook process still starts and reads its input before the summary is skipped.

​

Search Configuration

Claude-Mem provides MCP search tools for querying your project history.

No configuration required - MCP tools are automatically available in Claude Code sessions.

Search operations are provided via:

• MCP Server: 3 tools (search, timeline, get_observations) with progressive disclosure
• HTTP API: 10 endpoints on the worker service port (per-user, default 37700 + (uid % 100); see ~/.claude-mem/settings.json)
• Auto-Invocation: Claude recognizes natural language queries about past work

​

Worker Service Management

Worker service is managed by Bun as a background process. The worker auto-starts on first session and runs continuously in the background.

​

Observation TV Remote Access

The worker binds to 127.0.0.1 by default and has no request authentication — the loopback bind is its only defence. CLAUDE_MEM_TV_TOKEN adds a read-only broadcast surface so a second device on your LAN (a phone, an iPad, a spare monitor) can watch Observation TV and do nothing else.

Mint a token:

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

The host setting and the token work as a pair:

CLAUDE_MEM_WORKER_HOST	CLAUDE_MEM_TV_TOKEN	Result
127.0.0.1 (default)	empty	Today. Nothing reachable off-box. Recommended for everyone not using the TV remotely.
127.0.0.1	set	Token is inert — nothing can reach the port anyway. Harmless.
0.0.0.0	empty	Dangerous, and unchanged from today: the full API — settings incl. provider API keys, deletes, import, better-auth — is on the LAN. This is what the Docker setup already tells people to do, so the worker warns rather than refuses to bind.
0.0.0.0	set	The point of the feature. LAN devices reach /tv, /tv.html, /stream, GET /api/observations with the secret, and get 404/403/401 for everything else.

Booting with a non-loopback host and no token logs a SECURITY warning; the worker still binds.

A local port-forward reopens the whole API. The guard exempts loopback by socket peer, so anything that arrives as loopback bypasses it entirely — including ssh -L <port>:127.0.0.1:<port> <box> from another device, or any local forwarding proxy. To the worker that traffic is indistinguishable from the operator’s own browser, so it gets the full API, GET /api/settings and its provider API keys included. This is the one concrete way “the device can do nothing else” stops being true: only forward the port to devices you would hand the machine to.

Docker and bridge networking. With CLAUDE_MEM_WORKER_HOST=0.0.0.0 inside a bridge-network container, requests from the host’s own browser arrive from the bridge gateway address, not 127.0.0.1. Once a token is set, that browser is treated as remote like any other device and must supply ?token= to open the TV — and the React viewer at / is denied outright, exactly as it is for any other remote device.

Open the TV on the second device at http://<lan-ip>:<port>/tv.html?token=<secret>.

The React viewer at / stops working remotely when a token is set. That is intended — the viewer needs the write and settings routes the guard denies. Loopback is never gated, so the viewer keeps working normally on the machine running the worker.

Treat the URL as the secret. The token rides in the query string for /stream because the browser’s EventSource API cannot set request headers. It is not written to the worker log (the request logger records req.path, which excludes the query string), but it will be in the browser’s history on the device you open it on. Authorization: Bearer <token> and X-Api-Key: <token> also work for anything that can set headers.

This is plain HTTP. The token stops an unauthenticated device from reading the stream; it does not encrypt it. Anyone who can sniff your LAN sees observation titles. For a home network that is the accepted tradeoff; for anything else, terminate TLS in front of the worker (out of scope here) — and still never a tunnel to the unmodified worker, which would publish GET /api/settings and its provider API keys to the open internet.

Use the exact paths. The allowlist is exact-match and case-sensitive: /tv.html, /tv, /stream, /api/observations and nothing else. A trailing slash or a different case — /tv/, /API/observations, /api/observations/by-file — returns 404 even with a valid token. That is deliberate fail-closed behavior, not a bug.

The TV’s ?project= and ?source= filters are client-side only. They are display filters, not access control — a token holder still receives every project’s observations.

Accepted risks, stated plainly:

1. GET /api/observations returns full observation bodies — narrative, facts, text, files_read, files_modified — for every project on the box, not just the four fields the TV renders. A token holder can page through the entire memory database with offset.
2. /stream is unfiltered. It carries every observation for every project on the box, plus the project catalog and processing status. There is no per-client filtering.
3. No rate limiting. A token holder can hammer GET /api/observations freely.
4. The token is readable on loopback via GET /api/settings, exactly like your provider API keys are today. It is deliberately not writable through POST /api/settings (that route is unauthenticated), so it can only be set by someone with filesystem or environment access.
5. /stream is not side-effect-free. Every new connection triggers an initial_load broadcast to all connected clients, and the client list is unbounded. A token holder reconnecting in a loop can therefore disturb the operator’s own local viewer. This is pre-existing worker behavior; the token is what newly makes it reachable from the LAN.

​

Manual Configuration

Edit ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_WORKER_HOST": "0.0.0.0",
  "CLAUDE_MEM_TV_TOKEN": "your-minted-token"
}

Then restart the worker:

npm run worker:restart

​

Watching Off-LAN (cmem.ai Pro)

Everything above is the LAN path. Watching from outside your network — on cellular, at a coffee shop, from another house — is a cmem.ai Pro feature: open https://cmem.ai/tv in any browser while signed in to your account. It requires Cloud Sync to be enabled, because the hosted page reads titles your worker has already pushed to your sync hub.

No token, no open port, no inbound connection. This path needs neither CLAUDE_MEM_TV_TOKEN nor a non-loopback CLAUDE_MEM_WORKER_HOST — both belong to the LAN path and have no effect on it, so leave them at their defaults. The box never accepts an inbound connection for the hosted TV; the worker only ever dials out. No tunnel (cloudflared, ngrok, or anything like them) is needed, and none is recommended.

The hosted TV surface shows observation titles and nothing else. It never renders narratives, facts, file lists, snippets or prompt text.

That is not the same as “only titles leave your machine.” The hosted TV is a feature of cloud sync, and cloud sync uploads your observation narratives and your full prompt text to the sync hub under your cmem.ai account. The hosted page is titles-only; the upload standing behind it is not. Don’t enable cloud sync if that content must stay on your machine.

One rendering difference. An observation with no title still appears on the LAN TV, which falls back to the subtitle. It does not appear on the hosted phone TV — that surface receives titles only, so it has no subtitle to fall back to.

​

Folder Context Files

Claude-mem can automatically generate CLAUDE.md files in your project folders with activity timelines. This feature is disabled by default.

Setting	Default	Description
CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED	false	Enable auto-generation of folder CLAUDE.md files

​

Grok Bot live INDEX

The worker writes a growing observation INDEX into each Grok Bot seat’s Memory mid-attach file (agents/<uuid>/memory/log/zz-claude-mem-inject.md). See Grok Bot Integration.

Setting	Default	Description
CLAUDE_MEM_GROK_BOT_INJECT_ENABLED	true	Live-write the INDEX. false disables it. No-op when no Grok Bot seats exist.
CLAUDE_MEM_GROK_BOT_INJECT_AGENT_IDS	*	* / all / empty = every live seat; or a comma-separated UUID list.
CLAUDE_MEM_GROK_BOT_INJECT_FALLBACK	house	house fills thin seat diaries from newest worker observations. off = seat project only.
CLAUDE_MEM_GROK_BOT_INJECT_TIER	episode	Memory rank prefix (episode, plain, note).
CLAUDE_MEM_GROK_BOT_INJECT_WINDOW	80	Newest INDEX rows to keep (max 100).
CLAUDE_MEM_GROK_BOT_INJECT_PLATFORM_SOURCE	—	Optional host filter. Leave empty unless you want grok-only rows.
CLAUDE_MEM_GROK_BOT_INJECT_PROJECTS_BY_AGENT	—	Optional uuid=projA,projB;uuid2=projC override of transcript-watch projects.

See Folder Context Files for full documentation on how this feature works, configuration options, and git integration recommendations.

​

Context Injection Configuration

Claude-Mem injects past observations into each new session, giving Claude awareness of recent work. You can configure exactly what gets injected using the Context Settings Modal.

​

Context Settings Modal

Access the settings modal from the web viewer. The worker prints its URL on startup; the port comes from CLAUDE_MEM_WORKER_PORT.

1. Click the gear icon in the header
2. Adjust settings in the right panel
3. See changes reflected live in the Terminal Preview on the left
4. Click Save to keep your changes

The Terminal Preview shows the selected project and source. Select All sources to preview a combined SessionStart context.

​

Loading Settings

Control how many observations are injected:

Setting	Default	Range	Description
Observations	50	1-200	Total number of recent observations to include
Include all sources at session start	Off	On/Off	Include observations from Claude, Codex, and other harnesses in startup context
Sessions	10	1-50	Number of recent sessions to pull observations from

Considerations:

• Higher values = More context but slower SessionStart and more tokens used
• Lower values = Faster SessionStart but less historical awareness
• Default of 50 observations from 10 sessions balances context richness with performance

​

Filter Settings

Control which observation types and concepts are included:

Types (select any combination):

• bugfix - Bug fixes and error resolutions
• feature - New functionality additions
• refactor - Code restructuring
• discovery - Learnings about how code works
• decision - Architectural or design decisions
• change - General code changes

Concepts (select any combination):

• how-it-works - System behavior explanations
• why-it-exists - Rationale for code/design
• what-changed - Change summaries
• problem-solution - Problem/solution pairs
• gotcha - Edge cases and pitfalls
• pattern - Recurring patterns
• trade-off - Design trade-offs

Use “All” or “None” buttons to quickly select/deselect all options.

​

Display Settings

Control how observations appear in the context:

Full Observations:

Setting	Default	Options	Description
Count	5	0-20	How many observations show expanded details
Field	narrative	narrative, facts	Which field to expand

The most recent N observations (set by Count) show their full narrative or facts. Remaining observations show only title, type, and token counts in a compact table format.

Token Economics (toggles):

Setting	Default	Description
Read cost	true	Show tokens to read each observation
Work investment	true	Show tokens spent creating the observation

Token economics help you understand the value of cached observations vs. re-reading files.

​

Advanced Settings

Setting	Default	Description
Model	sonnet	AI model for generating observations
Worker Port	37700 + (uid % 100)	Port for background worker service (override with CLAUDE_MEM_WORKER_PORT)
MCP search server	true	Enable Model Context Protocol search tools
Include last summary	false	Add previous session’s summary to context
Include last message	false	Add previous session’s final message
Block full-file reads	true	Block whole-file Reads of code files of 32 KB and up that have observation history (File Read Gate)

​

Manual Configuration

Settings are stored in ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "100",
  "CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES": "true",
  "CLAUDE_MEM_CONTEXT_SESSION_COUNT": "20",
  "CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES": "bugfix,decision,discovery",
  "CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS": "how-it-works,gotcha",
  "CLAUDE_MEM_CONTEXT_FULL_COUNT": "10",
  "CLAUDE_MEM_CONTEXT_FULL_FIELD": "narrative",
  "CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS": "true",
  "CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS": "true",
  "CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY": "false",
  "CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE": "false"
}

Note: The Context Settings Modal (in the web viewer) is the recommended way to configure these settings, as it provides live preview of changes.

​

Customization

Settings can be customized in ~/.claude-mem/settings.json.

​

Custom Data Directory

Edit ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_DATA_DIR": "/custom/path"
}

​

Custom Worker Port

Edit ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_WORKER_PORT": "38000"
}

Then restart the worker:

npm run worker:restart

​

Custom Model

Edit ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_MODEL": "opus"
}

Then restart the worker:

export CLAUDE_MEM_MODEL=opus
npm run worker:restart

​

Custom Skip Tools

Control which tools are excluded from observations. Edit ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_SKIP_TOOLS": "ListMcpResourcesTool,SlashCommand,Skill"
}

Default excluded tools:

• ListMcpResourcesTool
• SlashCommand
• Skill
• TodoWrite
• AskUserQuestion

Common customizations:

• Include TodoWrite: Remove from skip list to track task planning
• Include AskUserQuestion: Remove to capture decision-making conversations
• Skip additional tools: Add tool names to reduce observation noise

Changes take effect on the next tool execution (no worker restart needed).

​

Advanced Configuration

​

Hook Timeouts

Hook timeouts are set in plugin/hooks/hooks.json. The current defaults match the shape of the workload at each lifecycle stage:

• Setup (version-check.js, claude --init / --maintenance only): 300s ceiling; fast when the plugin’s dependencies are complete, up to 120s when it has to run bun install
• SessionStart (worker-start + context): 60s
• SessionStart (ensure-launcher, startup only, synchronous): 180s, enough to compile the launcher
• UserPromptSubmit: 15s
• PreToolUse (file-context, Read matcher): 15s, synchronous so the File Read Gate can block a Read; its worker lookup gives up after 3s
• PostToolUse (observation): 120s
• Stop (summary): 120s

npx claude-mem install / npx claude-mem repair install the runtime (Bun, uv, bun install) outside the session lifecycle. The Setup hook only runs bun install when the loaded plugin’s dependencies are missing — typically a plugin-marketplace install or claude plugin update — and writes the .install-version marker once they are complete. Claude Code does not fire Setup on plugin install or update, so run claude --init-only or npx claude-mem install to trigger that repair.

​

Worker Memory Limit

The worker service is managed by Bun and will automatically restart if it encounters issues. Memory usage is typically low (~100-200MB).

​

Logging Verbosity

Enable debug logging:

export DEBUG=claude-mem:*
npm run worker:restart
npm run worker:logs

​

Configuration Best Practices

1. Use defaults: Default configuration works for most use cases
2. Override selectively: Only change what you need
3. Document changes: Keep track of custom configurations
4. Test after changes: Verify worker restarts successfully
5. Monitor logs: Check worker logs after configuration changes

​

Troubleshooting Configuration

​

Configuration Not Applied

1. Restart worker after changes:

   npm run worker:restart
   

2. Verify environment variables:

   echo $CLAUDE_MEM_MODEL
   echo $CLAUDE_MEM_WORKER_PORT
   

3. Check worker logs:

   npm run worker:logs
   

​

Invalid Model Name

If you specify an invalid Claude model name, the worker logs a warning and uses the default. Valid Claude models for CLAUDE_MEM_MODEL:

• haiku (default, the newest Haiku)
• sonnet (the newest Sonnet)
• opus (the newest Opus)
• a full model ID, such as claude-sonnet-5, to pin one version

​

Port Already in Use

The default worker port is 37700 + (uid % 100), so different OS users on the same machine get different ports automatically. If you still hit a collision (e.g. running multiple profiles as the same UID), set a fixed port:

1. Set custom port:

   export CLAUDE_MEM_WORKER_PORT=38000
   

2. Restart worker:

   npm run worker:restart
   

3. Verify new port:

   curl -s http://127.0.0.1:$CLAUDE_MEM_WORKER_PORT/api/health | jq .port
   

​

Next Steps

• Architecture Overview - Understand the system
• Troubleshooting - Common issues
• Development - Building from source