RepoThread Logo
RepoThread
价格

快速上手

相关源文件

本页面内容基于以下源文件生成：

Claude-Mem 是一个为 Claude Code 提供持久化记忆能力的插件系统，通过自动捕获工具使用观察、生成语义摘要，使 Claude 能够在会话之间保持上下文连续性。本文档将介绍如何快速安装和配置该系统。

系统要求

在安装 Claude-Mem 之前，需要确保系统满足以下要求：

组件版本要求说明
Node.js18.0.0 或更高版本核心运行时环境
Claude Code最新版本（支持插件）目标集成平台
BunJavaScript 运行时自动安装（如缺失）
uvPython 包管理器用于向量搜索，自动安装（如缺失）
SQLite 3持久化存储已捆绑在项目中

安装脚本会在启动时检查 Node.js 版本，如果版本低于 18 将直接报错退出（install/public/install.sh:19-28）。完整的系统要求列表可在 README 中找到（README.md:263-270）。

安装方式

Claude-Mem 提供多种安装方式，根据使用场景选择最适合的方案：

方式一：Claude Code 插件安装（推荐）

在 Claude Code 终端会话中执行以下命令：

bash
1/plugin marketplace add thedotmack/claude-mem
2/plugin install claude-mem

安装完成后重启 Claude Code，之前会话的上下文将自动出现在新会话中（README.md:130-141）。

注意：Claude-Mem 也发布在 npm 上，但 npm install -g claude-mem 仅安装 SDK/库，不会注册插件钩子或设置 worker 服务。作为插件使用时，必须通过上述 /plugin 命令安装。

方式二：OpenClaw Gateway 一键安装

对于 OpenClaw 网关用户，可使用单行命令完成安装：

bash
1curl -fsSL https://install.cmem.ai/openclaw.sh | bash

该安装器会自动处理依赖、插件设置、AI 提供商配置、worker 启动，以及可选的实时观察推送到 Telegram、Discord、Slack 等平台（README.md:142-150）。

方式三：交互式安装器

通过通用安装脚本启动交互式安装流程：

bash
1curl -fsSL https://install.cmem.ai | bash

该脚本首先检查 Node.js 环境，然后下载并执行安装器（install/public/install.sh:1-30）。安装器需要交互式终端，不支持非 TTY 环境运行（installer/src/index.ts:13-16）。

安装器流程

交互式安装器提供完整的引导式安装体验，流程如下：

正在加载图表渲染器...

安装器首先显示欢迎界面并检测现有安装，根据检测结果提供不同的安装模式选项（installer/src/steps/welcome.ts:8-43）：

模式适用场景说明
Fresh Install首次安装推荐选项，完整安装
Upgrade已有安装更新到最新版本
Configure仅配置修改设置而不重新安装
Fresh Install（强制）已有安装从头重新安装

主流程依次执行依赖检查、IDE 选择、提供商配置、设置配置、安装和 worker 启动（installer/src/index.ts:19-42）。如果选择"仅配置"模式，则跳过安装和 worker 启动步骤。

核心功能

Claude-Mem 提供以下核心功能（README.md:152-164）：

功能说明
持久化记忆上下文在会话间保留
渐进式披露分层记忆检索，显示 token 成本
技能搜索使用 mem-search 技能查询项目历史
Web 查看器实时记忆流，访问地址 http://localhost:37777
隐私控制使用 <private> 标签排除敏感内容
引用系统通过 ID 引用历史观察记录

MCP 搜索工具

Claude-Mem 通过 4 个 MCP 工具提供智能记忆搜索，采用高效的三层工作流模式（README.md:218-238）：

  1. search - 获取紧凑索引（约 50-100 tokens/结果）
  2. timeline - 获取特定观察周围的时序上下文
  3. get_observations - 仅获取筛选后 ID 的完整详情（约 500-1000 tokens/结果）

这种工作流通过先筛选再获取详情的方式，可节省约 10 倍的 token 消耗。

运行验证

安装完成后，可通过以下方式验证系统正常运行：

检查 Worker 服务

Worker 服务默认运行在端口 37777，可通过访问 Web 查看器确认：

bash
1# 检查服务状态
2curl http://localhost:37777
3
4# 或在浏览器中打开
5open http://localhost:37777

Web 查看器提供实时记忆流界面，可查看所有观察记录（README.md:157）。

验证插件注册

安装器会将插件注册到 Claude 的插件系统中（installer/src/steps/install.ts:47-75）。检查以下路径确认安装成功：

  • 插件目录：~/.claude/plugins/marketplaces/thedotmack/
  • 设置文件：~/.claude-mem/settings.json

测试记忆功能

在新的 Claude Code 会话中，之前会话的上下文应自动加载。可使用 MCP 搜索工具测试记忆检索：

typescript
1// 搜索记忆索引
2search(query="previous work", limit=10)
3
4// 获取特定观察详情
5get_observations(ids=[123, 456])

常见问题与排错

问题 1：Node.js 版本不兼容

症状：安装脚本报错 "Node.js >= 18 required"

解决方案：升级 Node.js 到 18.0.0 或更高版本。安装脚本会检查版本并拒绝继续（install/public/install.sh:24-28）。

问题 2：非交互式终端错误

症状：安装器报错 "This installer requires an interactive terminal"

解决方案：安装器需要 TTY 终端运行（installer/src/index.ts:13-16）。直接在终端中运行 npx claude-mem-installer，而非通过管道或脚本执行。

问题 3：Worker 服务无法启动

症状：无法访问 http://localhost:37777

解决方案：

  1. 检查端口 37777 是否被占用
  2. 确认 Bun 运行时已正确安装（Worker 服务由 Bun 管理）
  3. 查看安装器完成摘要中的配置信息

问题 4：插件未生效

症状：重启 Claude Code 后上下文未自动加载

解决方案：

  1. 确认使用 /plugin 命令安装，而非 npm install -g（README.md:140）
  2. 检查 ~/.claude/settings.json 中 enabledPlugins 是否包含 claude-mem@thedotmack
  3. 重新运行安装器选择"Upgrade"模式

问题 5：检测到现有安装但无法升级

症状：安装器检测到现有安装但升级失败

解决方案：安装器通过检查 ~/.claude-mem/settings.json 和插件目录判断是否已安装（installer/src/steps/welcome.ts:14-17）。如需完全重新安装，选择"Fresh Install"模式。

下一步建议

安装完成后，建议阅读以下文档以充分利用 Claude-Mem：

  1. 使用指南 - 了解 Claude-Mem 如何自动工作
  2. 搜索工具 - 使用自然语言查询项目历史
  3. 配置 - 环境变量和高级设置
  4. 架构概览 - 系统组件和数据流

如需尝试实验性功能（如 Endless Mode），可在 Web 查看器的设置中切换到 Beta 频道（README.md:257-259）。