配置¶

设置文件¶

设置存储在 ~/.claude-mem/settings.json 中。首次运行时，该文件将使用默认值自动创建。

核心设置¶

子代理与动态工作流过滤¶

Claude Code 动态工作流 会将单个提示扇出到数十到数百个并行子代理（agent_type: workflow-subagent）。每个子代理的每次工具调用都会触发 PostToolUse 钩子，因此 claude-mem 会为每次调用创建一条由提供商分析的观察记录——单次运行可能产生 成百上千 条低信号观察。这可能会耗尽所配置提供商的免费层配额（HTTP 429），并丢弃该运行的其余部分，包括有价值的主会话工作。

有两项设置可让你在这些观察 进入任何 worker 往返或提供商调用之前 将其过滤掉。两者默认均为关闭，因此现有行为保持不变。

• 丢弃所有子代理噪声（推荐给重度工作流用户）：

{ "CLAUDE_MEM_SKIP_SUBAGENT_OBSERVATIONS": "true" }

这是最稳妥的控制手段——无论类型如何，它都会捕获每个子代理工具调用（同时带有代理 ID 和代理类型的调用）。主会话观察会被保留，包括 claude --agent <type> 主线程以及诸如 Grok Bot 席位等转录监控宿主，后者只携带两者之一。

• 精准丢弃特定代理类型（保留某些子代理，丢弃其他子代理）：

{ "CLAUDE_MEM_SKIP_AGENT_TYPES": "workflow-subagent" }

添加一个逗号分隔的 agent_type 值列表。两项设置以并集方式组合：如果全局开关打开，或 其 agent_type 在列表中，则该子代理观察会被跳过。

子代理 摘要 本来就会自动跳过；这些设置则为 观察 增加了同样的控制。跨会话的持久知识通常来自主会话，因此丢弃短暂的子代理步骤通常会提高信噪比。SessionStart 在默认情况下已经不让子代理行进入注入的上下文（CLAUDE_MEM_CONTEXT_MAIN_AGENT_ONLY）；这些设置则更进一步，完全跳过对它们的捕获，这也能节省观察者提供商的令牌。

Gemini 提供商设置¶

有关详细配置和速率限制信息，请参阅 Gemini 提供商。

Codex 订阅提供商设置¶

以运行 worker 的用户身份执行 codex login，然后使用 npx claude-mem install --provider codex 安装。添加 --model gpt-6-luna 可选择该模型，或在查看器设置中选择 Codex 并输入模型。Codex 使用本地 CLI 订阅登录，不需要 OpenAI API 密钥。

不带 --model 重新安装会保留已保存的 Codex 模型。首次安装时该设置为空，Codex 会选择其默认模型。之后若要恢复默认值，请在查看器中清除 Codex Model 字段。

worker 使用隔离的 codex app-server 会话处理观察记录和摘要。Codex CLI 身份验证必须是基于文件的 ChatGPT 登录；不接受 API 密钥登录。每个请求都使用共享的 CLAUDE_MEM_LLM_TIMEOUT_MS 超时截止时间。有关故障如何暂停和恢复的详细信息，请参阅仓库中的 docs/codex-provider.md。

OpenRouter 提供商设置¶

有关详细配置、免费模型列表和使用指南，请参阅 OpenRouter 提供商。

OpenAI 兼容提供商设置¶

对于 CLAUDE_MEM_PROVIDER=openai-compatible：任何支持 /chat/completions 的端点，无论是托管还是本地均可。

有关预设和配置，请参阅 OpenAI 兼容提供商。

配额回退设置¶

参见 配额回退 了解回退如何开始和结束。

配额防护设置¶

使用订阅身份验证时，一旦某个使用窗口达到其阈值，观察者就会停止。提供程序已拒绝的窗口无论阈值如何都始终会使其停止。五小时窗口在重置后 15 分钟内达到 85% 或更高时也会使其停止，即使低于其阈值。API-key 身份验证从不停止。

阈值是 0 到 1 之间的小数（0.93 = 93%）。超出该范围的值（例如 93）会回退到默认值，并在 worker 日志中发出警告。空白值使用默认值。

观察者预算设置¶

这些设置适用于所有观察者提供程序。观察者的对话按代（generation）运行。当一代达到其预算时，claude-mem 会将其退役，并启动一个以会话自身观察结果为简报的新一代。预算是 CLAUDE_MEM_OBSERVER_MAX_CONVERSATION_CHARS 与观察者模型上下文窗口一半（约每 token 4 个字符）中的较小值。每个工具调用的参数和结果上限为窗口的十分之一，最多 16,000 个字符。

如果提供程序仍以请求超出模型窗口为由拒绝请求，观察者会退役该代，并在新的一代中重试相同的工作，处理方式与它处理 Claude 的“Prompt is too long”的方式相同。

对于这些 HTTP 提供程序，观察者的指令和输出格式作为系统消息发送，用户的请求作为第一条用户消息发送。在输出 token 上限处被截断的回复会以警告形式记录，并指明该上限。

Claude 网关设置¶

网关凭据存放在 ~/.claude-mem/.env 中，而不是 settings.json。

当你希望 CLAUDE_MEM_PROVIDER=claude 通过 LiteLLM 路由，同时保留 Claude Agent SDK worker 路径时，请使用 LiteLLM 网关。

如果 Anthropic 兼容网关以 400 拒绝 thinking 参数，worker 的观察者会在该会话的剩余时间内丢弃该参数并重试同一批次，这样你在更改设置期间不会丢失任何内容。服务器的提供程序不会重试；对于此类网关，请设置 omit。

系统配置¶

Grok Bot Brainbeat Webhook¶

可选。设置 CLAUDE_MEM_GROK_BOT_WEBHOOK_URL 后，claude-mem 会将每条符合 Grok Bot 感知触发器（CLAUDE_MEM_GROK_BOT_AWARENESS_TRIGGER_TYPES / CLAUDE_MEM_GROK_BOT_AWARENESS_TRIGGER_CONCEPTS，默认类型为 decision,bugfix,security_alert,sensitive）的观察记录 POST 到该 URL。它独立于所有 Telegram 设置。

每条匹配的观察记录以一次 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"
}

POST 会并发发送，每个请求在 5 秒后超时。拒绝重定向，因此共享密钥和观察记录只会被发送到配置的 URL；请将接收方的最终地址填入该设置。失败时仅记录接收方的来源和简短原因（绝不会记录完整 URL），并且绝不会阻塞观察记录的存储或其他通知。

Notion 导出¶

可选。每条新观察记录在存储时会被复制到 Notion 数据库中。有关设置和数据库结构，请参阅 Notion 导出。

近似重复去重¶

可选（默认关闭）的去重功能，针对那些标题描述相同重复工作但措辞略有不同的观察记录——仅按字节级相同匹配的 content_hash 会漏掉它们。该功能分为两个确定性的层级：

• 第 0 层 — 规范化标题精确匹配 → 安全静默自动合并：新观察记录的标题经小写化/空白折叠/去标点处理后与已有记录匹配时，会合并到已有行上，并递增其 occurrence_count（跨会话，且需在同一项目、同一主机平台和同一代理作用域内：主会话的工作绝不会合并到子代理行，SessionStart 会将其排除在外）。升级前存储的行会通过 POST /api/dedup/scan 重新建立键。
• 第 1 层 — IDF 加权相似度 → 仅供审核的近似重复候选会记录在 observation_dedup_candidates 中（绝不会自动合并），这样仅在一个稀有 token 上存在差异的不同工作（rdlp-api 与 rdlp-plugin）绝不会被静默销毁。

在现有数据库上启用后，请运行一次性扫描来回填 IDF 模型并呈现累积的近似重复项：POST /api/dedup/scan（worker，仅限 localhost）。通过 GET /api/dedup/candidates?project=<name> 审核候选（添加 &status=pending 可仅查看未审核的候选），并使用 POST /api/dedup/candidates/<id>/resolve 及请求体 {"status": "distinct"} 或 {"status": "dismissed"} 记录判定。后续扫描会保留该判定。

模型配置¶

配置由哪个 Claude 模型来压缩你的观察记录（仅在 CLAUDE_MEM_PROVIDER=claude 时生效）。

可用模型¶

通过安装程序选择¶

npx claude-mem install 会提示选择 Claude 模型（当选中 Claude 提供方时），并将选择持久化到 ~/.claude-mem/settings.json。

手动配置¶

编辑 ~/.claude-mem/settings.json：

{
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}

模式配置¶

配置当前的工作流模式和语言。

设置¶

示例¶

西班牙语代码模式：

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

邮件调查模式：

{
  "CLAUDE_MEM_MODE": "email-investigation"
}

项目名称¶

claude-mem 将每条观察记录按项目名称归档，SessionStart 会注入为当前项目存储的记忆。

• 在 git 仓库内，名称是仓库根目录的文件夹名称，因此每个子文件夹都共用该名称。git worktree 存储为 <repo>/<worktree>（如果一个 worktree 的文件夹与仓库自身同名，例如 Codex 的 ~/.codex/worktrees/<id>/<repo>，则存储为 <repo>），git 子模块存储为 <superproject>/<path>；两者也都会读取其父仓库的记忆。子模块在按这种方式归组之前以其自身文件夹名称存储的记忆，仍可从该子模块中读取。当删除某个 worktree 或子模块检出时，worker 会在下次启动时将其记忆并入父仓库（无论是否已合并），因此不会有任何记忆被遗留。
• 设置 CLAUDE_MEM_PROJECT_NAME_SOURCE=git-remote 后，带有 origin 远程的仓库改用其 org/repo 简称来命名（例如 thedotmack/claude-mem），这样重命名或重新克隆文件夹后仍能保留其记忆，两个同名文件夹的仓库也会彼此区分开，并且该仓库的每个 worktree 都共用这一简称（子模块作为独立仓库，则按其自身的 origin 命名）。以文件夹名称为基础存储的记忆仍然可读，而且切换前被删除的 worktree 的记忆仍会并入仓库。没有可用 origin（或 origin 为本地）的仓库继续使用基于文件夹的名称。
• 在 git 之外，名称就是当前文件夹的名称。若要为某个非 git 项目在所有子文件夹中统一使用一个名称，请在其根文件夹中放置一个空的 .claude-mem-project 文件（或 .claude-mem.json）：其下的所有文件夹随即都使用根文件夹的名称。在添加该文件之前，以子文件夹自身名称存储的记忆仍可从该子文件夹中读取。位于主目录、系统临时目录或 Claude 配置目录中的标记文件会被忽略，因此它们绝不会把无关的文件夹归并到一起。
• 命名环境（CLAUDE_MEM_PROJECT_ENVIRONMENTS）会将多个文件夹（无论是否为 git）归组到同一个项目中，并优先于上述所有规则。例如，[{"name": "acme", "patterns": ["~/work/acme/**"]}] 会把 ~/work/acme 下的所有内容统一记作 acme，SessionStart 也会将其标记为环境。这些文件夹以其自身名称存储的记忆仍可从它们中读取；若要将其永久并入该环境，请运行 npx claude-mem project merge <old-name> acme（只要 worker 正在运行，该命令便会在 claude-mem 的 worker 内执行）。该合并不会重写任何内容（行会被标记为已合并，正如 worktree 并入其仓库的方式），并且会一并带入已经并入旧名称的记忆，例如某个已合并 worktree 的记忆。它会通过云同步到达你的其他设备，并更新语义搜索；如果最后一步失败，命令会明确提示，再次运行即可重试。

环境模式与 CLAUDE_MEM_EXCLUDED_PROJECTS 使用相同的 glob 规则。完整的 **/ 段匹配零个或多个目录：~/work/**/private 同时匹配 ~/work/private 和 ~/work/team/private。在末尾添加 /** 即可同时匹配它们的后代。

文件与目录¶

数据目录结构¶

数据目录的位置取决于环境： - 生产环境（已安装的插件）：~/.claude-mem/（始终如此，无论 CLAUDE_PLUGIN_ROOT 为何） - 开发环境：可使用 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

插件目录结构¶

${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

插件配置¶

Hook 配置¶

Hook 注册在 plugin/hooks/hooks.json 中。每个运行时 hook 都是一条 exec 形式的条目，不使用 shell：{"command": "claude-mem", "args": ["hook", "claude-code", "<event>"]}。Claude Code 会在 PATH 中找到 claude-mem：这是一个小型编译启动器，由 npx claude-mem install / update 放置到 ~/.local/bin（POSIX）或 %LOCALAPPDATA%\claude-mem\bin（Windows）。该启动器在 Bun 下运行单一分发器 worker-service.cjs hook claude-code <event>。接入的事件有：

• Setup → version-check.js（安装缺失的插件依赖，记录 .install-version）。唯一使用 bash 的条目；Claude Code 仅在 claude --init / --maintenance 时触发它。
• SessionStart → claude-mem start（worker，异步），随后执行 hook claude-code context（上下文注入）；启动时还会执行 node ${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs，该脚本会为仅通过 marketplace 安装的情况放置或刷新启动器
• UserPromptSubmit → hook claude-code session-init
• PreToolUse（匹配器 Read）→ hook claude-code file-context（同步：将文件的观察时间线作为上下文添加，并可阻止对整个文件的 Read；请参阅 文件读取门控）
• PostToolUse（匹配器 *）→ hook claude-code observation
• Stop → hook claude-code summarize
• SessionEnd → hook claude-code session-end

确切的 hooks.json 条目由 scripts/build-hooks.js 生成并随插件一起发布；除非你清楚自己在做什么，否则不要在 marketplace 副本中手工编辑它们。npx claude-mem doctor 会针对 hooks 将要运行的 claude-mem 显示一行 Hook 启动器。

关闭工具钩子¶

这些开关只从钩子的环境中读取，而不是从 ~/.claude-mem/settings.json 读取。将它们设置在 ~/.claude/settings.json 的 env 块中（Claude Code 会将该块传递给每个钩子），或者在 shell 中导出它们：

Claude Code 仍然会启动每个钩子。claude-mem 钩子启动器会在解析插件或启动 Bun 之前检查这些开关，因此被禁用的工具钩子不会加载 worker bundle。Codex shell 钩子会在启动 Node 之前检查它们；Codex Windows 启动器仍会先启动 Node，然后在解析脚本或启动 Bun 之前检查开关。这些开关不会改变 settings.json 中的功能设置。

关闭会话结束摘要¶

编排器如果会启动短时无头运行（比如对暂存 diff 执行 codex exec 审查），通常会设置 CLAUDE_MEM_DISABLE_OBSERVATION=1，这样该运行过程中观察到的任何内容都不会被捕获。摘要开关为这些运行补齐了最后一块拼图：它们仍会在会话开始时读取 claude-mem 上下文，但它们的 Stop 不再把中间 diff 的摘要写入项目的近期摘要。与工具钩子开关不同，这项检查在 summarize 处理器内部运行，因此钩子进程仍会启动并读取其输入，然后摘要才会被跳过。

搜索配置¶

Claude-Mem 提供 MCP 搜索工具，用于查询你的项目历史。

无需配置——MCP 工具在 Claude Code 会话中自动可用。

搜索操作可通过以下方式使用：

• MCP Server：3 个工具（search、timeline、get_observations），支持渐进式披露
• HTTP API：worker service 端口上的 10 个端点（按用户计算，默认 37700 + (uid % 100)；参见 ~/.claude-mem/settings.json）
• 自动调用：Claude 能识别关于过往工作的自然语言查询

Worker Service 管理¶

Worker service 由 Bun 作为后台进程管理。worker 会在首次会话时自动启动，并在后台持续运行。

Observation TV 远程访问¶

默认情况下，worker 绑定到 127.0.0.1，并且没有任何请求认证——回环绑定是它唯一的防线。CLAUDE_MEM_TV_TOKEN 增加了一个只读广播通道，因此你局域网上的第二台设备（手机、iPad、备用显示器）可以观看 Observation TV，除此之外什么都做不了。

生成令牌：

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

主机设置和令牌成对配合：

使用非回环主机且未设置令牌启动时，会记录一条 SECURITY 警告；worker 仍会绑定。

本地端口转发会让整个 API 重新暴露。该守卫按 socket 对端来豁免回环，因此任何以回环身份到达的流量都会完全绕过它——包括从另一台设备执行 ssh -L <port>:127.0.0.1:<port> <box>，或任何本地转发代理。对于 worker 来说，这些流量与操作者自己的浏览器流量无法区分，因此它能获得完整 API，包括 GET /api/settings 及其中的 provider API 密钥。这是“该设备无法做任何其他事”这一说法不再成立的唯一切实方式：只把端口转发给你愿意把整台机器交给它的设备。

Docker 与桥接网络。 在桥接网络容器内，如果设置了 CLAUDE_MEM_WORKER_HOST=0.0.0.0，来自宿主机自身浏览器的请求会从桥接网关地址到达，而不是 127.0.0.1。一旦设置了令牌，该浏览器就会像任何其他设备一样被视为远程设备，必须提供 ?token= 才能打开 TV——并且 / 上的 React 查看器会被直接拒绝，与任何其他远程设备完全相同。

在第二台设备上通过 http://<lan-ip>:<port>/tv.html?token=<secret> 打开 TV。

设置令牌后，位于 / 的 React 查看器将无法远程工作。 这是有意为之——查看器需要守卫所拒绝的写入路由和设置路由。回环从不受限制，因此该查看器在运行 worker 的机器上仍可正常工作。

将 URL 视为机密。 令牌随查询字符串附加在 /stream 中，因为浏览器的 EventSource API 无法设置请求头。它不会被写入 worker 日志（请求记录器记录的是 req.path，不包含查询字符串），但它会留在你打开它的设备的浏览器历史记录中。对于任何可以设置请求头的方式，Authorization: Bearer <token> 和 X-Api-Key: <token> 也同样有效。

这是纯 HTTP。 token 可阻止未认证的设备读取流；但它不会加密。任何能嗅探你局域网的人都能看到观察标题。对于家庭网络，这是可接受的权衡；对于其他场景，请在 worker 前端终止 TLS（此处不展开）——并且仍然绝不要对未修改的 worker 使用隧道，否则会把 GET /api/settings 及其供应商 API 密钥发布到公网。

请使用精确路径。 允许列表是精确匹配且区分大小写的：/tv.html、/tv、/stream、/api/observations，仅此而已。尾部斜杠或不同大小写——/tv/、/API/observations、/api/observations/by-file——即使使用有效 token 也会返回 404。这是刻意设计的 fail-closed 行为，而非 bug。

TV 的 ?project= 和 ?source= 过滤器仅限客户端。它们是显示过滤器，不是访问控制——token 持有者仍会收到每个项目的观察记录。

已接受的风险，明确列出：

1. GET /api/observations 返回完整的观察正文 —— narrative、facts、text、files_read、files_modified —— 涵盖机器上的每个项目，而不仅仅是 TV 渲染的四个字段。token 持有者可以使用 offset 翻遍整个记忆数据库。
2. /stream 不过滤。 它承载机器上每个项目的所有观察记录，外加项目目录和处理状态。没有按客户端进行过滤。
3. 没有速率限制。 token 持有者可以随意频繁请求 GET /api/observations。
4. token 可通过 GET /api/settings 在 loopback 上读取，正如你当前的供应商 API 密钥一样。它刻意不能通过 POST /api/settings 写入（该路由未认证），因此只有具备文件系统或环境访问权限的人才能设置它。
5. /stream 并非无副作用。 每次新连接都会触发一次 initial_load 广播，发送给所有已连接的客户端，而且客户端列表无上限。因此，token 持有者循环重连可能会干扰操作者自己的本地查看器。这是 worker 既有的行为；token 只是让它新近可以从局域网访问。

手动配置¶

编辑 ~/.claude-mem/settings.json：

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

然后重启 worker：

npm run worker:restart

在局域网外观看（cmem.ai Pro）¶

以上都是局域网路径。从外部网络观看——在蜂窝网络、咖啡馆、另一处住所——是 cmem.ai Pro 功能：在登录你的账户后，于任意浏览器打开 https://cmem.ai/tv。它要求启用 Cloud Sync，因为托管页面读取的是你的 worker 已经推送到同步中心的标题。

无需 token，无需开放端口，无需入站连接。 此路径既不需要 CLAUDE_MEM_TV_TOKEN，也不需要非 loopback 的 CLAUDE_MEM_WORKER_HOST——两者都属于局域网路径，对它没有影响，因此请保持默认值。机器绝不会为托管 TV 接受入站连接；worker 只会向外拨出。不需要任何隧道（cloudflared、ngrok 或类似工具），也不建议使用任何隧道。

托管 TV 界面只显示观察标题，不显示任何其他内容。 它从不渲染叙事、事实、文件列表、片段或 prompt 文本。

这与“只有标题离开你的机器”不是一回事。 托管 TV 是 cloud sync 的一项功能，而 cloud sync 会将你的观察叙事和完整 prompt 文本上传到你的 cmem.ai 账户下的同步中心。托管页面仅包含标题；其背后的上传并非如此。如果这些内容必须保留在你的机器上，请不要启用 cloud sync。

一个渲染上的差异。 没有标题的观察记录仍会出现在局域网 TV 上，此时会回退到副标题。它不会出现在托管手机 TV 上——该界面只接收标题，因此没有副标题可供回退。

文件夹上下文文件¶

Claude-mem 可以自动在你的项目文件夹中生成带有活动时间线的 CLAUDE.md 文件。此功能默认禁用。

Grok Bot 实时 INDEX¶

worker 会将不断增长的观察 INDEX 写入每个 Grok Bot 席位的 Memory mid-attach 文件（agents/<uuid>/memory/log/zz-claude-mem-inject.md）。参见 Grok Bot 集成。

关于此功能的工作原理、配置选项和 git 集成建议的完整文档，请参见 文件夹上下文文件。

上下文注入配置¶

Claude-Mem 会将过去的观察记录注入每个新会话，让 Claude 了解近期工作。你可以使用上下文设置模态框精确配置要注入的内容。

上下文设置模态框¶

从 Web 查看器访问设置模态框。worker 会在启动时打印其 URL；端口来自 CLAUDE_MEM_WORKER_PORT。

1. 点击页眉中的齿轮图标
2. 在右侧面板中调整设置
3. 在左侧的终端预览中实时查看更改
4. 点击保存以保留更改

终端预览会显示所选项目和来源。选择 所有来源 可预览合并后的 SessionStart 上下文。

加载设置¶

控制注入多少条观察记录：

注意事项： - 值越高 = 上下文越多，但 SessionStart 越慢且消耗更多 Token - 值越低 = SessionStart 更快，但历史感知更弱 - 默认从 10 个会话中提取 50 条观察记录，在上下文丰富度与性能之间取得平衡

筛选设置¶

控制包含哪些观察类型和概念：

类型（可选择任意组合）： - bugfix — Bug 修复与错误解决 - feature — 新增功能 - refactor — 代码重构 - discovery — 对代码运行方式的了解 - decision — 架构或设计决策 - change — 一般代码变更

概念（可选择任意组合）： - how-it-works — 系统行为说明 - why-it-exists — 代码/设计存在的原因 - what-changed — 变更摘要 - problem-solution — 问题/解决方案对 - gotcha — 边界情况与陷阱 - pattern — 反复出现的模式 - trade-off — 设计权衡

使用“全部”或“无”按钮可快速全选/取消全选所有选项。

显示设置¶

控制观察记录在上下文中的显示方式：

完整观察记录： | 设置 | 默认值 | 选项 | 描述 | |---------|---------|---------|-------------| | 数量 | 5 | 0-20 | 显示展开详情的观察记录条数 | | 字段 | narrative | narrative、facts | 展开哪个字段 |

最近的 N 条观察记录（由数量设置）显示完整的叙述或事实。其余观察记录仅以紧凑表格格式显示标题、类型和 Token 数量。

Token 经济性（开关）： | 设置 | 默认值 | 描述 | |---------|---------|-------------| | 读取成本 | true | 显示读取每条观察记录所需的 Token | | 工作投入 | true | 显示创建观察记录所花费的 Token | | 节省量 | true | 显示通过重用上下文节省的 Token 总量 |

Token 经济性帮助您理解缓存观察记录与重新读取文件相比的价值。

高级设置¶

手动配置¶

设置存储于 ~/.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"
}

注意：上下文设置弹窗（位于 Web 查看器中）是配置这些设置的推荐方式，因为它提供变更的实时预览。

自定义¶

可在 ~/.claude-mem/settings.json 中自定义设置。

自定义数据目录¶

编辑 ~/.claude-mem/settings.json：

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

自定义工作端口¶

编辑 ~/.claude-mem/settings.json：

{
  "CLAUDE_MEM_WORKER_PORT": "38000"
}

然后重启 Worker Service：

npm run worker:restart

自定义模型¶

编辑 ~/.claude-mem/settings.json：

{
  "CLAUDE_MEM_MODEL": "opus"
}

然后重启 Worker Service：

export CLAUDE_MEM_MODEL=opus
npm run worker:restart

自定义跳过工具¶

控制哪些工具被排除在观察记录之外。编辑 ~/.claude-mem/settings.json：

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

默认排除的工具： - ListMcpResourcesTool - SlashCommand - Skill - TodoWrite - AskUserQuestion

常见自定义： - 包含 TodoWrite：从跳过列表中移除以跟踪任务规划 - 包含 AskUserQuestion：移除以捕获决策对话 - 跳过更多工具：添加工具名称以减少观察记录噪音

更改将在下一次工具执行时生效（无需重启 Worker Service）。

高级配置¶

Hook 超时¶

Hook 超时设置在 plugin/hooks/hooks.json 中。当前默认值与每个生命周期阶段的工作负载形态相匹配：

• Setup（version-check.js，仅 claude --init / --maintenance）：300 秒上限；插件依赖完整时很快，需要运行 bun install 时最多 120 秒
• SessionStart（worker-start + 上下文）：60 秒
• SessionStart（ensure-launcher，仅启动时，同步）：180 秒，足以编译启动器
• UserPromptSubmit：15 秒
• PreToolUse（file-context，Read 匹配器）：15 秒，同步执行以便文件读取门控能够阻止 Read；其 Worker Service 查找在 3 秒后放弃
• PostToolUse（观察）：120 秒
• Stop（摘要）：120 秒

npx claude-mem install / npx claude-mem repair 在会话生命周期之外安装运行时（Bun、uv、bun install）。Setup Hook 仅在所加载插件的依赖缺失时运行 bun install（通常是插件市场安装或 claude plugin update），并在依赖完成后写入 .install-version 标记。Claude Code 在插件安装或更新时不会触发 Setup，因此请运行 claude --init-only 或 npx claude-mem install 来触发该修复。

Worker 内存限制¶

Worker Service 由 Bun 管理，遇到问题时会自动重启。内存使用量通常较低（约 100-200MB）。

日志详细程度¶

启用调试日志：

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

配置最佳实践¶

1. 使用默认值：默认配置适用于大多数使用场景
2. 有选择地覆盖：只修改你需要的配置
3. 记录变更：跟踪自定义配置
4. 变更后测试：验证 Worker 能成功重启
5. 监控日志：配置更改后检查 Worker 日志

配置故障排查¶

配置未生效¶

1. 更改后重启 Worker：

   npm run worker:restart
   

2. 验证环境变量：

   echo $CLAUDE_MEM_MODEL
   echo $CLAUDE_MEM_WORKER_PORT
   

3. 检查 Worker 日志：

   npm run worker:logs
   

无效的模型名称¶

如果你指定了无效的 Claude 模型名称，Worker 会记录一条警告并使用默认模型。CLAUDE_MEM_MODEL 的有效 Claude 模型：

• claude-haiku-4-5-20251001（默认）
• claude-sonnet-5
• claude-opus-4-8

端口已被占用¶

默认 Worker 端口是 37700 + (uid % 100)，因此同一台机器上的不同操作系统用户会自动获得不同的端口。如果仍然遇到冲突（例如以相同的 UID 运行多个配置文件），请设置固定端口：

1. 设置自定义端口：

   export CLAUDE_MEM_WORKER_PORT=38000
   

2. 重启 Worker：

   npm run worker:restart
   

3. 验证新端口：

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

后续步骤¶

• 架构概述 - 了解系统
• 故障排查 - 常见问题
• 开发 - 从源码构建