第 2 期：安装 Claude-Mem — 从零到跑通的完整指南

本期场景：你决定给博客项目装上 Claude-Mem。安装很简单，但「装好了」和「真的能用」之间，差的是验证。

2.1 前置条件检查清单

开始安装前，请逐项确认：

# ✅ 检查 Node.js 版本（需要 ≥ 18）
node -v
# 期望输出: v18.x.x 或更高

# ✅ 检查 Claude Code 是否安装
claude --version
# 期望输出: claude-code/x.x.x

# ✅ 以下两个会自动安装，无需手动处理
# Bun — JavaScript 运行时（Worker 用它跑）
# uv — Python 包管理器（向量搜索用它装依赖）

⚠️ Windows 用户注意：如果终端提示 npm: The term 'npm' is not recognized，说明 Node.js 未加入系统 PATH。请从 nodejs.org 重新安装并勾选"Add to PATH"选项。

2.2 安装方式一（推荐）：命令行安装

在任意终端中运行：

npx claude-mem install

这条命令会自动完成以下所有操作：

graph TD
    A["npx claude-mem install"] --> B["注册 Hook 脚本到
~/.claude/plugins/"]
    B --> C{"Bun 已安装？"}
    C -->|否| D["自动安装 Bun"]
    C -->|是| E["跳过"]
    D --> F{"uv 已安装？"}
    E --> F
    F -->|否| G["自动安装 uv"]
    F -->|是| H["跳过"]
    G --> I["创建 ~/.claude-mem/ 目录"]
    H --> I
    I --> J["生成 settings.json
(默认配置)"]
    J --> K["启动 Worker Service
(port 37777)"]
    K --> L["✅ 安装完成"]

    style A fill:#6366f1,color:#fff
    style L fill:#10b981,color:#fff

2.3 安装方式二：Plugin Marketplace

如果你更喜欢在 Claude Code 内部操作：

# 在 Claude Code 会话中输入：
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

两种安装方式的效果完全相同。

2.4 ⚠️ 这个命令是错的！

# ❌ 千万不要这样装
npm install -g claude-mem

为什么？因为 npm install 只会安装 Claude-Mem 的 SDK 代码库，但不会：

• ❌ 注册生命周期钩子（没有钩子 = 无法自动捕获）
• ❌ 启动 Worker 服务（没有 Worker = 数据无处可存）
• ❌ 创建配置目录和数据库

记住：永远用 npx claude-mem install。

2.5 验证安装的 5 步检查

安装完成后，必须重启 Claude Code。然后逐步验证：

第 1 步：重启 Claude Code

# 完全退出 Claude Code，然后重新打开
# 如果是终端版本：
claude

第 2 步：打开 Web UI

在浏览器中访问：

http://localhost:37777

你应该看到一个实时记忆流界面。如果页面打不开，说明 Worker 没有启动。

第 3 步：Health Check

curl http://localhost:37777/api/health

期望返回：

{"status":"ok"}

第 4 步：检查数据库文件

ls -la ~/.claude-mem/claude-mem.db

应该能看到一个 SQLite 数据库文件。

第 5 步：检查配置文件

cat ~/.claude-mem/settings.json

应该能看到类似这样的默认配置：

{
  "CLAUDE_MEM_MODE": "code",
  "WORKER_PORT": 37777,
  "LOG_LEVEL": "info"
}

5 步全部通过？恭喜你，Claude-Mem 已经在正常运行了！ 🎉

2.6 首次使用：让 Claude-Mem 开始记录

现在，让我们在博客项目中开启第一个有记忆的会话：

# 进入你的博客项目目录
cd ~/my-blog

# 启动 Claude Code
claude

然后正常地让 Claude 帮你工作。比如：

你：帮我初始化一个 Next.js 项目，我要做一个个人技术博客。

Claude 会开始执行各种操作（创建文件、安装依赖、修改配置）。在这个过程中，打开另一个浏览器标签页访问 http://localhost:37777，你会看到：

• 🟢 实时的 Observation 条目不断出现
• 每条 Observation 都有标题、类型标签和时间戳
• 操作细节被自动压缩成简洁的笔记

这就是 Claude-Mem 在工作的样子。你什么都不需要做，它完全自动。

2.7 如果安装失败了怎么办？

实操练习

1. ✅ 运行 npx claude-mem install
2. ✅ 重启 Claude Code
3. ✅ 通过 5 步检查验证安装
4. ✅ 在博客项目中开启一个会话，观察 Web UI 中出现的 Observations
5. ✅ 截图 Web UI 首页（作为安装成功的证据）

下期预告

安装已经搞定了。下一期，我们打开 Claude-Mem 的"大脑"，看看它到底把你的开发记录存成了什么样子。为什么同时需要 SQLite 和 ChromaDB 两个数据库？Observation 长什么样？我们会直接用 SQL 查询给你看。

➡️ 第 3 期：解剖 Claude-Mem 的"大脑" — 数据存储架构全解