Configuration

Settings File

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

Core Settings

Setting	Default	Description
`CLAUDE_MEM_MODEL`	`claude-haiku-4-5-20251001`	Claude model used to compress observations (when using the Claude provider)
`CLAUDE_MEM_PROVIDER`	`claude`	AI provider: `claude`, `codex`, `gemini`, `openrouter`, or `openai-compatible`
`CLAUDE_MEM_CLAUDE_AUTH_METHOD`	`subscription`	Claude provider auth mode: `subscription`, `api-key`, or `gateway`
`CLAUDE_MEM_LLM_TIMEOUT_MS`	`180000`	Per-request deadline (ms, 500–300000) for the Gemini and OpenRouter / OpenAI-compatible observer, including the cmem.ai gateway. It exists to catch a hung request; a slow backend just needs a higher value. 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_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_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_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_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_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`, 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.

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)
`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
`CLAUDE_MEM_OPENAI_COMPAT_BASE_URL`	—	OpenAI-compatible base URL. Overrides the preset’s
`CLAUDE_MEM_OPENAI_COMPAT_MODEL`	—	Model id, sent as-is. Empty = the preset’s default model
`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.

Quota Fallback Settings

Setting	Default	Description
`CLAUDE_MEM_QUOTA_FALLBACK_PROVIDER`	— (off)	Where observer work goes while the selected provider’s quota breaker holds (a spent allowance, or rate limits that outlast their retries): `claude`, `gemini`, `openrouter`, or `openai-compatible`. Empty = off
`CLAUDE_MEM_QUOTA_FALLBACK_MODEL`	—	Claude model for a Claude fallback run. Empty = `CLAUDE_MEM_MODEL` and tier routing. Ignored for other fallbacks

See Quota Fallback for how the fallback starts and ends.

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_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`

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.

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

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

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_PYTHON_VERSION`	`3.13`	Python version for chroma-mcp
`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"}`. 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.

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.

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>.

Model Configuration

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

Available Models

Value	Notes
`claude-haiku-4-5-20251001`	Default — fastest, ideal for compression
`claude-sonnet-5`	Balanced quality and speed
`claude-opus-4-8`	Highest quality (slowest)

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": "claude-haiku-4-5-20251001"
}

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.

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
└── 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
│   ├── version-check.js    # Setup hook: completes missing dependencies, records the install marker
│   ├── context-hook.js     # Context injection hook
│   ├── new-hook.js         # Session creation hook
│   ├── save-hook.js        # Observation capture hook
│   ├── summary-hook.js     # Summary generation hook
│   ├── worker-service.cjs  # Worker service (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. The current shape uses a single dispatcher (worker-service.cjs hook claude-code <event>) launched through bun-runner.js, plus a fast Setup-phase version-check.js. The events wired up are:

Setup → version-check.js (installs missing plugin dependencies, records .install-version)
SessionStart → start the worker, then hook claude-code context (context injection)
UserPromptSubmit → hook claude-code session-init
PreToolUse (matcher Read) → hook claude-code file-context
PostToolUse (matcher *) → hook claude-code observation
Stop → hook claude-code summarize

The exact hooks.json entries are written by the installer; do not hand-edit them in the marketplace copy unless you know what you’re doing.

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`).

Claude Code still launches each hook, so these switches turn off claude-mem’s per-tool work, not the hook process itself.

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:

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.
/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.
No rate limiting. A token holder can hammer GET /api/observations freely.
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.
/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. Access the settings modal from the web viewer. The worker prints its URL on startup; the port comes from CLAUDE_MEM_WORKER_PORT.

Click the gear icon in the header
Adjust settings in the right panel
See changes reflected live in the Terminal Preview on the left
Settings auto-save as you change them

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
Savings	true	Show total tokens saved by reusing context

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

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_SAVINGS_AMOUNT": "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 written into plugin/hooks/hooks.json by the installer. The current defaults match the shape of the workload at each lifecycle stage:

Setup (version-check.js): 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
UserPromptSubmit: 60s
PreToolUse (file-context, Read matcher): 60s
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.

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

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

Troubleshooting Configuration

Configuration Not Applied

Restart worker after changes:
npm run worker:restart

Verify environment variables:

echo $CLAUDE_MEM_MODEL
echo $CLAUDE_MEM_WORKER_PORT

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:

claude-haiku-4-5-20251001 (default)
claude-sonnet-5
claude-opus-4-8

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:

Set custom port:
export CLAUDE_MEM_WORKER_PORT=38000
Restart worker:
npm run worker:restart

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

​Configuration

​Settings File

​Core Settings

​Subagent & Dynamic Workflow filtering

​Gemini Provider Settings

​Codex Subscription Provider Settings

​OpenRouter Provider Settings

​OpenAI-Compatible Provider Settings

​Quota Fallback Settings

​Observer Budget Settings

​Claude Gateway Settings

​System Configuration

​Grok Bot Brainbeat Webhook

​Near-Duplicate Deduplication

​Model Configuration

​Available Models

​Picking via the Installer

​Manual Configuration

​Mode Configuration

​Settings

​Examples

​Project Names

​Files and Directories

​Data Directory Structure

​Plugin Directory Structure

​Plugin Configuration

​Hooks Configuration

​Turning off the tool hooks

​Search Configuration

​Worker Service Management

​Observation TV Remote Access

​Manual Configuration

​Watching Off-LAN (cmem.ai Pro)

​Folder Context Files

​Grok Bot live INDEX

​Context Injection Configuration

​Context Settings Modal

​Loading Settings

​Filter Settings

​Display Settings

​Advanced Settings

​Manual Configuration

​Customization

​Custom Data Directory

​Custom Worker Port

​Custom Model

​Custom Skip Tools

​Advanced Configuration

​Hook Timeouts

​Worker Memory Limit

​Logging Verbosity

​Configuration Best Practices

​Troubleshooting Configuration

​Configuration Not Applied

​Invalid Model Name

​Port Already in Use

​Next Steps

Configuration

Settings File

Core Settings

Subagent & Dynamic Workflow filtering

Gemini Provider Settings

Codex Subscription Provider Settings

OpenRouter Provider Settings

OpenAI-Compatible Provider Settings

Quota Fallback Settings

Observer Budget Settings

Claude Gateway Settings

System Configuration

Grok Bot Brainbeat Webhook

Near-Duplicate Deduplication

Model Configuration

Available Models

Picking via the Installer

Manual Configuration

Mode Configuration

Settings

Examples

Project Names

Files and Directories

Data Directory Structure

Plugin Directory Structure

Plugin Configuration

Hooks Configuration

Turning off the tool hooks

Search Configuration

Worker Service Management

Observation TV Remote Access

Manual Configuration

Watching Off-LAN (cmem.ai Pro)

Folder Context Files

Grok Bot live INDEX

Context Injection Configuration

Context Settings Modal

Loading Settings

Filter Settings

Display Settings

Advanced Settings

Manual Configuration

Customization

Custom Data Directory

Custom Worker Port

Custom Model

Custom Skip Tools

Advanced Configuration

Hook Timeouts

Worker Memory Limit

Logging Verbosity

Configuration Best Practices

Troubleshooting Configuration

Configuration Not Applied

Invalid Model Name

Port Already in Use

Next Steps