配置

设置文件

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

核心设置

设置	默认值	描述
`CLAUDE_MEM_MODEL`	`sonnet`	用于处理观测的AI模型（使用Claude时）
`CLAUDE_MEM_PROVIDER`	`claude`	AI 提供商: `claude`, `gemini` 或 `openrouter`
`CLAUDE_MEM_MODE`	`code`	活跃模式配置文件（例如，`code--es`、`email-investigation`）
`CLAUDE_MEM_CONTEXT_OBSERVATIONS`	`50`	要注入的观测次数
`CLAUDE_MEM_WORKER_PORT`	`37777`	Worker 服务端口
`CLAUDE_MEM_WORKER_HOST`	`127.0.0.1`	Worker 服务主机地址
`CLAUDE_MEM_SKIP_TOOLS`	`ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion`	用逗号分隔的要从观测中排除的工具

Gemini提供者设置

设置	默认值	描述
`CLAUDE_MEM_GEMINI_API_KEY`	—	Gemini API 密钥 (获取免费密钥)
`CLAUDE_MEM_GEMINI_MODEL`	`gemini-2.5-flash-lite`	Gemini模型: `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-flash-preview`

有关详细配置和免费套餐信息，请参阅 Gemini Provider。

OpenRouter 提供商设置

设置	默认值	描述
`CLAUDE_MEM_OPENROUTER_API_KEY`	—	OpenRouter API 密钥 (获取密钥)
`CLAUDE_MEM_OPENROUTER_MODEL`	`xiaomi/mimo-v2-flash:free`	模型标识符（支持100个模型）
`CLAUDE_MEM_OPENROUTER_MAX_CONTEXT_MESSAGES`	`20`	对话历史中的最大消息数
`CLAUDE_MEM_OPENROUTER_MAX_TOKENS`	`100000`	token 预算安全限额
`CLAUDE_MEM_OPENROUTER_SITE_URL`	—	可选：分析的 URL
`CLAUDE_MEM_OPENROUTER_APP_NAME`	`claude-mem`	可选：用于分析的应用名称

有关详细配置、免费模型列表和使用指南，请参见 OpenRouter Provider。

系统配置

设置	默认值	描述
`CLAUDE_MEM_DATA_DIR`	`~/.claude-mem`	数据目录位置
`CLAUDE_MEM_LOG_LEVEL`	`INFO`	日志详细级别（DEBUG, INFO, WARN, ERROR, SILENT）
`CLAUDE_MEM_PYTHON_VERSION`	`3.13`	用于 chroma-mcp 的 Python 版本
`CLAUDE_CODE_PATH`	(自动检测)	Claude Code CLI 的路径（适用于 Windows）

模型配置

配置哪个 AI 模型处理您的观察结果。

可用型号

简称模型名称会自动转发到最新版本：

haiku - 快速、经济高效
sonnet - 平衡（默认）
opus - 最有能力

使用交互式脚本

bash

./claude-mem-settings.sh

此脚本管理 ~/.claude-mem/settings.json 中的设置。

手动配置

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

json

{
  "CLAUDE_MEM_MODEL": "sonnet"
}

模式配置

配置活动工作流模式和语言。

设置

设置	默认	描述
`CLAUDE_MEM_MODE`	`code`	定义行为和语言。见 Modes & Languages。

例子

西班牙代码模式：

json

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

电子邮件调查模式：

json

{
  "CLAUDE_MEM_MODE": "email-investigation"
}

文件和目录

数据目录结构

数据目录的位置取决于环境：

生产（已安装插件）：~/.claude-mem/（始终如此，无论 CLAUDE_PLUGIN_ROOT）
开发：可以被 CLAUDE_MEM_DATA_DIR 覆盖

~/.claude-mem/
├── claude-mem.db           # SQLite database
├── .install-version        # Cached version for smart installer
├── worker.port             # Current worker port file
└── 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
│   ├── smart-install.js    # Smart installer script
│   ├── 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/hooks/hooks.json：

json

{
  "description": "Claude-mem memory system hooks",
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/smart-install.js && node ${CLAUDE_PLUGIN_ROOT}/scripts/context-hook.js",
        "timeout": 120
      }]
    }],
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/new-hook.js",
        "timeout": 120
      }]
    }],
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/save-hook.js",
        "timeout": 120
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/summary-hook.js",
        "timeout": 120
      }]
    }]
  }
}

搜索配置

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

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

搜索操作通过以下方式提供：

MCP 服务器：3 个工具（搜索、时间线、获取观测）与逐步揭示
HTTP API：worker 服务端口 37777 上的 10 个端点
自动调用：Claude 能理解关于过去工作的自然语言查询

版本频道

Claude-Mem 支持通过网页查看器界面在稳定版和测试版之间切换。

正在访问版本频道

在 http://localhost:37777 打开查看器
点击设置齿轮图标
找到 版本通道 部分

切换版本

尝试测试版：点击“尝试测试版（无尽模式）”以切换到带有实验性功能的测试版分支
切换到稳定版：点击“切换到稳定版”以返回生产版本
检查更新：拉取您当前分支的最新更改

切换版本时您的记忆数据会被保留。只有插件代码会发生变化。

无尽模式是实验性的，比标准模式慢。详细信息和重要限制请参见 Beta Features。

Worker 服务管理

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

文件夹上下文文件

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

设置	默认	描述
`CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED`	`false`	启用文件夹 CLAUDE.md 自动生成

有关此功能如何工作、配置选项以及 Git 集成建议的完整文档，请参见 Folder Context Files。

上下文注入配置

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

上下文设置模态窗口

从网页查看器在 http://localhost:37777: 访问设置模态

点击标题栏中的齿轮图标
在右侧面板中调整设置
在左侧的 终端预览 中实时查看更改
设置会在更改时自动保存

终端预览准确显示了将在所选项目的下一次 Claude Code会话开始时注入的内容。

正在加载设置

控制注入的观察次数：

设置	默认	范围	描述
观察	50	1-200	要包含的近期观察总数
会话	10	1-50	从中获取观察结果的最近会话数量

注意事项：

更高的数值 = 更多的上下文，但会导致 SessionStart 更慢并使用更多的 token
较低的值 = 更快的会话启动，但历史意识较少
来自10个会话的50个观察的默认值在上下文丰富性与性能之间取得平衡

过滤器设置

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

类型（可选择任意组合）：

bugfix - 错误修复与问题解决
feature - 新功能添加
refactor - 代码重构
discovery - 关于代码工作原理的学习
decision - 建筑或设计决策
change - 一般代码更改

概念（可选择任意组合）：

how-it-works - 系统行为解释
why-it-exists - 代码/设计的理由
what-changed - 更改摘要
problem-solution - 问题/解决方案对
gotcha - 边缘情况和陷阱
pattern - 循环模式
trade-off - 设计权衡

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

显示设置

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

完整观察：

设置	默认	选项	描述
计数	5	0-20	有多少观察显示了详细信息
字段	叙述	叙述，事实	要扩展的字段

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

token经济学（切换）：

设置	默认	描述
读取成本	true	显示读取每个观测的 token
工作投入	true	显示创建观察时消耗的token
储蓄	true	显示通过重用上下文节省的总token数

token经济学帮助你理解缓存观察值与重新读取文件的价值。

高级设置

设置	默认	描述
模型	诗体	用于生成观察的人工智能模型
工作端口	37777	后台Worker 服务端口
MCP 搜索服务器	true	启用模型上下文协议搜索工具
包含上次总结	否	将上次会话的总结添加到上下文中
包含最后一条消息	否	添加上次会话的最后一条消息

手动配置

设置存储在 ~/.claude-mem/settings.json 中：

json

{
  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "100",
  "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"
}

注意：上下文设置模态窗口（位于 http://localhost:37777）是配置这些设置的推荐方式，因为它提供更改的实时预览。

自定义

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

自定义数据目录

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

json

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

自定义工作端口

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

json

{
  "CLAUDE_MEM_WORKER_PORT": "38000"
}

然后重新启动 Worker 进程：

bash

npm run worker:restart

自定义模型

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

json

{
  "CLAUDE_MEM_MODEL": "opus"
}

然后重新启动 Worker 进程：

bash


npm run worker:restart

自定义跳过工具

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

json

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

默认排除的工具：

ListMcpResourcesTool
SlashCommand
Skill
TodoWrite
AskUserQuestion

常见自定义：

包含 TodoWrite：从跳过列表中移除以跟踪任务计划
包括 AskUserQuestion：删除以捕捉决策对话
跳过额外工具：添加工具名称以减少观察噪音

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

高级配置

钩子超时

修改 plugin/hooks/hooks.json 中的超时设置：

json

{
  "timeout": 120  // Default: 120 seconds
}

推荐值：

会话开始：120秒（需要时间进行智能安装检查和上下文检索）
用户提示提交：60秒
工具使用后：120秒（可以处理许多观察）
停止：60秒
会话结束：60秒

注意：使用智能安装缓存（v5.0.3）时，除非需要安装依赖项，否则 SessionStart 通常非常快（10 毫秒）。

工作进程内存限制

该 Worker 服务由 Bun 管理，如果遇到问题，它会自动重启。内存使用通常很低（约 100-200MB）。

日志详细程度

启用调试日志：

bash


npm run worker:restart
npm run worker:logs

配置最佳实践

使用默认设置：默认配置适用于大多数使用场景
选择性覆盖：只更改你需要的内容
文档更改：跟踪自定义配置
更改后的测试：验证Worker 进程是否成功重启
监控日志：在配置更改后检查工作节点日志

故障排除配置

配置未应用

在更改后重启工作进程：
bash
```
npm run worker:restart
```

验证环境变量：

bash

echo $CLAUDE_MEM_MODEL
echo $CLAUDE_MEM_WORKER_PORT

检查工作日志：
bash
```
npm run worker:logs
```

无效的模型名称

如果您指定了一个无效的模型名称，Worker 进程将回退到 sonnet 并记录一条警告。

有效的速记模型（更新至最新版本）：

俳句
十四行诗
作品

端口已被占用

如果端口 37777 已经被使用：

设置自定义端口：
bash
重启Worker 进程：
bash
```
npm run worker:restart
```
验证新端口：
bash
```
cat ~/.claude-mem/worker.port
```

下一步

Architecture Overview - 了解系统
Troubleshooting - 常见问题
Development - 从源代码构建

配置 ​

设置文件 ​

核心设置 ​

Gemini提供者设置 ​

OpenRouter 提供商设置 ​

系统配置 ​

模型配置 ​

可用型号 ​

使用交互式脚本 ​

手动配置 ​

模式配置 ​

设置 ​

例子 ​

文件和目录 ​

数据目录结构 ​

插件目录结构 ​

插件配置 ​

钩子配置 ​

搜索配置 ​

版本频道 ​

正在访问版本频道 ​

切换版本 ​

Worker 服务管理 ​

文件夹上下文文件 ​

上下文注入配置 ​

上下文设置模态窗口 ​

正在加载设置 ​

过滤器设置 ​

显示设置 ​

高级设置 ​

手动配置 ​

自定义 ​

自定义数据目录 ​

自定义工作端口 ​

自定义模型 ​

自定义跳过工具 ​

高级配置 ​

钩子超时 ​

工作进程内存限制 ​

日志详细程度 ​

配置最佳实践 ​

故障排除配置 ​

配置未应用 ​

无效的模型名称 ​

端口已被占用 ​

下一步 ​

配置

设置文件

核心设置

Gemini提供者设置

OpenRouter 提供商设置

系统配置

模型配置

可用型号

使用交互式脚本

手动配置

模式配置

设置

例子

文件和目录

数据目录结构

插件目录结构

插件配置

钩子配置

搜索配置

版本频道

正在访问版本频道

切换版本

Worker 服务管理

文件夹上下文文件

上下文注入配置

上下文设置模态窗口

正在加载设置

过滤器设置

显示设置

高级设置

手动配置

自定义

自定义数据目录

自定义工作端口

自定义模型

自定义跳过工具

高级配置

钩子超时

工作进程内存限制

日志详细程度

配置最佳实践

故障排除配置

配置未应用

无效的模型名称

端口已被占用

下一步