佛系程序员_ Token 省钱神器：Claude-Mem

学习笔记

发布日期: 2026-04-17 17:13:12

喜欢量: 9 个

阅读次数: 52

Token 省钱神器：Claude-Mem 持久记忆系统完整部署手册

# Token 省钱神器：Claude-Mem 持久记忆系统完整部署手册

> **跨平台部署指南 (Windows 11 / Ubuntu / macOS)**
>
> 支持 Cursor、OpenCode、OpenClaw 三大主流 AI IDE，让你的编码助手跨越会话边界，智能压缩历史记忆，节省 50-70% token 消耗。

---

## 核心价值一句话

**Claude-Mem = 持久记忆 + 智能压缩 + 跨会话检索 = 省钱 + 高效 + 不遗忘**

---

> **版本**: Claude-Mem v12.1.6 | **更新日期**: 2026-04-17

---

## 目录

- [简介](#简介)
- [Token 效率](#token-效率)
- [环境准备](#环境准备)
  - [Windows 11 安装详解](#windows-11-安装详解)
  - [Ubuntu 安装详解](#ubuntu-安装详解)
  - [macOS 安装详解](#macos-安装详解)
- [Cursor 安装指南](#cursor-安装指南)
- [OpenCode 安装指南](#opencode-安装指南)
- [OpenClaw 安装指南](#openclaw-安装指南)
- [验证与测试](#验证与测试)
- [常见问题](#常见问题)
- [参考资源](#参考资源)

---

## 简介

### 什么是 Claude-Mem？

Claude-Mem 是一个为 AI 编码助手提供持久记忆能力的插件系统。它能够：

- **自动捕获**：记录每次工具调用、文件编辑、对话内容
- **智能压缩**：使用 AI 将观察数据压缩存储，节省 token
- **上下文注入**：在新会话中自动注入相关历史记忆
- **跨会话检索**：通过自然语言搜索历史编码记录

### 支持的 IDE

从 v10.7.0 版本开始，Claude-Mem 官方支持以下 IDE：

| IDE | 支持方式 | 安装难度 | 配置文件 |
|-----|----------|----------|----------|
| Claude Code | 原生插件 | ⭐ 最简单 | 自动配置 |
| **Cursor** | Hooks | ⭐ 最简单 | 自动配置 |
| Gemini CLI | Hooks + AGENTS.md | ⭐⭐ 中等 | 自动配置 |
| **OpenCode** | MCP + AGENTS.md | ⭐⭐⭐ 需手动 | 需编辑 opencode.json |
| **OpenClaw** | Plugin | ⭐⭐ 中等 | Gateway 配置 |
| Windsurf | Hooks + Registry | ⭐⭐ 中等 | 自动配置 |
| Codex CLI | Transcript watcher | ⭐⭐⭐ 较复杂 | 自动配置 |

**推荐优先级**：
- 已有 Cursor → 直接使用 `claude-mem install`（自动检测）
- 已有 OpenCode → 参考本文档手动配置 MCP
- 已有 OpenClaw → 参考 Gateway 配置章节

---

## Token 效率

Claude-Mem 通过多种机制减少 token 消耗，避免上下文膨胀。

### 压缩机制

**1. AI 智能压缩**

每次工具调用和对话内容被捕获后，使用 LLM（Claude Haiku 或 GPT-4o-mini）生成压缩摘要。原始详细记录存储在数据库，但注入上下文时只使用压缩版本。

| 原始内容 | 压缩后 | 压缩比 |
|----------|--------|--------|
| 完整工具调用日志（含参数、返回值） | 关键操作摘要 | 约 5-10x |
| 多轮对话原文 | 核心结论提取 | 约 3-5x |

**注意**：压缩效果取决于内容类型。代码编辑操作的压缩比较高，调试过程的压缩比相对较低。

**2. Markdown 格式优化**

v10.6.1 版本引入了 Markdown 输出压缩，将表格格式转换为紧凑的扁平行格式：

| 格式 | 压缩比 | 示例 |
|------|--------|------|
| 表格 → 扁平行 | 约 53% | `| A | B |` → `A: value, B: value` |

数据来源：[v10.6.1 Release Notes](https://github.com/thedotmack/claude-mem/releases/tag/v10.6.1)

**3. 文件读取门控**

v12.0.0 引入了智能文件读取决策机制。当文件已有历史观察时，系统会阻止重复读取并提示查看时间线：

```
[Decision Gate] File X has prior observations. View timeline instead of re-reading.
```

这减少了不必要的重复文件读取，节省了每次读取的 token 开销。

### 实际节省估算

以下是基于官方文档和社区反馈的合理估算：

| 场景 | 传统方式 | Claude-Mem | 节省 |
|------|----------|------------|------|
| 跨会话恢复上下文 | 手动复制粘贴历史对话 | 自动注入压缩摘要 | 50-70% |
| 重复讨论同一文件 | 每次重新读取文件内容 | 决策门控 + 时间线查询 | 30-50% |
| 查找历史决策 | 重新阅读整个对话历史 | 自然语言搜索压缩记忆 | 60-80% |

**重要说明**：

- 以上数据来自 Claude-Mem 官方文档和社区报告，实际效果因使用场景而异
- "10x token efficiency" 来自社区描述，但更保守的估计是 3-5x 的综合效率提升
- 压缩过程本身消耗少量 token（使用 Haiku 调用），但整体上节省更多

### Token 消耗对比示例

假设一个典型开发会话：

| 操作 | 无记忆系统 | 有 Claude-Mem |
|------|-----------|---------------|
| 新会话启动（恢复上下文） | 0 tokens | 约 200-500 tokens（注入摘要） |
| 第 5 次询问同一文件 | 每次 500-2000 tokens | 决策门控 + 200 tokens（时间线） |
| 查找 3 天前的决策 | 无法实现，需重新讨论 | 约 100 tokens（搜索查询） |

**总结**：Claude-Mem 的价值在于跨会话记忆，而非单次会话节省。长期使用的项目，累积节省效果更明显。

---

## 环境准备

### 必需组件

| 组件 | 最低版本 | 验证命令 |
|------|----------|----------|
| Node.js | 18.x | `node --version` |
| npm | 9.x | `npm --version` |
| Bun | 1.x | `bun --version` |

---

### Windows 11 安装详解

#### 步骤 1：安装 Node.js

**方法 A：官方安装器（推荐）**

1. 访问 https://nodejs.org/
2. 下载 LTS 版本（当前 v20.x 或更高）
3. 运行安装器，勾选 "Add to PATH"
4. 验证：

```powershell
node --version
npm --version
```

**方法 B：使用 winget**

```powershell
winget install OpenJS.NodeJS.LTS
```

**方法 C：使用 Chocolatey**

```powershell
choco install nodejs-lts
```

#### 步骤 2：安装 Bun

```powershell
# 通过 npm 安装（最可靠）
npm install -g bun

# 验证
bun --version
```

**常见问题：Bun 路径问题**

Windows 下 Bun 可能安装到非标准路径。查找实际位置：

```powershell
where.exe bun
# 通常输出：
# C:\Users\<用户>\AppData\Roaming\npm\bun.cmd
# C:\Users\<用户>\AppData\Roaming\npm\bun
```

如果 `bun` 命令不工作，使用完整路径：

```powershell
$bunExe = "$env:APPDATA\npm\node_modules\bun\bin\bun.exe"
& $bunExe --version
```

#### 步骤 3：设置 Claude-Mem 目录

```powershell
# 创建必要的目录（如果不存在）
$claudeDir = "$env:USERPROFILE\.claude"
$claudeMemDir = "$env:USERPROFILE\.claude-mem"
$opencodeDir = "$env:USERPROFILE\.config\opencode"

if (-not (Test-Path $claudeDir)) { New-Item -Path $claudeDir -ItemType Directory }
if (-not (Test-Path $claudeMemDir)) { New-Item -Path $claudeMemDir -ItemType Directory }
if (-not (Test-Path $opencodeDir)) { New-Item -Path $opencodeDir -ItemType Directory }
```

#### 步骤 4：Windows 防火墙配置

Claude-Mem Worker 监听端口 37777，需要防火墙放行：

```powershell
# 添加防火墙规则（管理员权限）
New-NetFirewallRule -DisplayName "Claude-Mem Worker" -Direction Inbound -LocalPort 37777 -Protocol TCP -Action Allow
New-NetFirewallRule -DisplayName "Claude-Mem Worker" -Direction Outbound -LocalPort 37777 -Protocol TCP -Action Allow
```

#### 步骤 5：创建开机自启动任务

```powershell
# 创建计划任务（管理员权限）
$action = New-ScheduledTaskAction -Execute "$env:APPDATA\npm\node_modules\bun\bin\bun.exe" -Argument "`"$env:USERPROFILE\.claude\plugins\cache\thedotmack\claude-mem\12.1.6\scripts\worker-wrapper.cjs`" start"
$trigger = New-ScheduledTaskTrigger -AtStartup
$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -DontStopOnIdleEnd
Register-ScheduledTask -TaskName "ClaudeMemWorker" -Action $action -Trigger $trigger -Settings $settings -User "$env:USERNAME"
```

---

### Ubuntu 安装详解

#### 步骤 1：安装 Node.js

**方法 A：使用 NodeSource（推荐）**

```bash
# 安装 Node.js 20.x LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证
node --version
npm --version
```

**方法 B：使用 apt（版本可能较旧）**

```bash
sudo apt update
sudo apt install nodejs npm

# 可能需要升级
sudo npm install -g n
sudo n lts
```

**方法 C：使用 snap**

```bash
sudo snap install node --classic
```

#### 步骤 2：安装 Bun

```bash
# 官方安装脚本
curl -fsSL https://bun.sh/install | bash

# 重新加载 shell 配置
source ~/.bashrc
# 或 ~/.zshrc 如果使用 zsh

# 验证
bun --version
```

**如果 Bun 未添加到 PATH**：

```bash
# 手动添加到 PATH
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

# 添加到 shell 配置文件
echo 'export BUN_INSTALL="$HOME/.bun"' >> ~/.bashrc
echo 'export PATH="$BUN_INSTALL/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

#### 步骤 3：设置目录权限

```bash
# 创建必要的目录
mkdir -p ~/.claude
mkdir -p ~/.claude-mem
mkdir -p ~/.config/opencode

# Claude-Mem 数据库目录权限
chmod 700 ~/.claude-mem
```

#### 步骤 4：系统服务配置（systemd）

创建 systemd 服务文件，实现开机自启动：

```bash
sudo nano /etc/systemd/system/claude-mem.service
```

内容：

```ini
[Unit]
Description=Claude-Mem Worker Service
After=network.target

[Service]
Type=simple
User=<你的用户名>
WorkingDirectory=/home/<你的用户名>
ExecStart=/home/<你的用户名>/.bun/bin/bun /home/<你的用户名>/.claude/plugins/cache/thedotmack/claude-mem/12.1.6/scripts/worker-wrapper.cjs start
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
```

**注意**：将 `<你的用户名>` 替换为实际用户名，`12.1.6` 替换为实际版本。

启用服务：

```bash
# 重载 systemd
sudo systemctl daemon-reload

# 启用开机自启
sudo systemctl enable claude-mem

# 立即启动
sudo systemctl start claude-mem

# 查看状态
sudo systemctl status claude-mem

# 查看日志
journalctl -u claude-mem -f
```

#### 步骤 5：防火墙配置（ufw）

```bash
# 如果使用 ufw 防火墙
sudo ufw allow 37777/tcp
sudo ufw reload

# 验证规则
sudo ufw status
```

---

### macOS 安装详解

#### 步骤 1：安装 Node.js

```bash
# 使用 Homebrew（推荐）
brew install node

# 验证
node --version
npm --version
```

#### 步骤 2：安装 Bun

```bash
# 官方安装
curl -fsSL https://bun.sh/install | bash

# 或使用 Homebrew
brew install bun

# 验证
bun --version
```

#### 步骤 3：launchd 自启动配置

创建 LaunchAgent：

```bash
nano ~/Library/LaunchAgents/com.claude-mem.worker.plist
```

内容：

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.claude-mem.worker</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/<你的用户名>/.bun/bin/bun</string>
        <string>/Users/<你的用户名>/.claude/plugins/cache/thedotmack/claude-mem/12.1.6/scripts/worker-wrapper.cjs</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/claude-mem.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/claude-mem-error.log</string>
</dict>
</plist>
```

加载服务：

```bash
launchctl load ~/Library/LaunchAgents/com.claude-mem.worker.plist
launchctl start com.claude-mem.worker
```

---

### 环境验证汇总

| 平台 | Node.js 验证 | Bun 验证 | Claude-Mem 验证 |
|------|--------------|----------|-----------------|
| Windows 11 | `node --version` | `bun --version` 或 `where.exe bun` | `claude-mem --version` |
| Ubuntu | `node --version` | `bun --version` 或 `$BUN_INSTALL/bin/bun --version` | `claude-mem --version` |
| macOS | `node --version` | `bun --version` | `claude-mem --version` |

---

## Cursor 安装指南

Cursor 是一款基于 VS Code 的 AI 编码 IDE，Claude-Mem 通过 Hooks 机制为其提供持久记忆支持。

### Cursor 特点

| 特性 | 说明 |
|------|------|
| **集成方式** | Claude-Mem Hooks（自动配置） |
| **配置文件** | `.cursorrules` + AGENTS.md |
| **支持版本** | Cursor 0.40+ |
| **安装难度** | ⭐ 简单（一行命令） |

### 步骤 1：确认 Cursor 已安装

确保 Cursor IDE 已安装并正常运行：

- 下载地址：https://cursor.sh/
- 支持平台：Windows、macOS、Linux
- 版本要求：0.40 或更高版本

### 步骤 2：安装 Claude-Mem CLI

```bash
# macOS/Linux
npm install -g claude-mem@latest

# Windows PowerShell
npm install -g claude-mem@latest
```

验证安装：

```bash
claude-mem --version
# 输出: 12.1.6
```

### 步骤 3：运行安装器

Claude-Mem 安装器会自动检测 Cursor 并配置 Hooks：

```bash
# 自动检测所有已安装的 IDE（包括 Cursor）
claude-mem install

# 或指定安装到 Cursor
claude-mem install --ide cursor --yes
```

**输出示例**：

```
claude-mem install
  Version: 12.1.6
  Platform: darwin (x64)
  Detecting installed IDEs...
  Found: cursor, claude-code
  
  Installing for Cursor...
  Creating .cursor/hooks...
  Hook: pre_tool_use → OK
  Hook: post_tool_use → OK
  AGENTS.md injection → OK
  
  Cursor integration complete!
```

### 步骤 4：验证 Hooks 配置

Claude-Mem 会在 Cursor 配置目录创建以下文件：

| 文件 | 位置 | 作用 |
|------|------|------|
| `.cursorrules` | 项目根目录 | Cursor 规则配置 |
| `hooks.json` | `~/.cursor/hooks/` | Claude-Mem 钩子定义 |
| `AGENTS.md` | 项目根目录 | 记忆上下文注入 |

检查 Hooks 是否正确安装：

```bash
# macOS/Linux
ls -la ~/.cursor/hooks/
cat ~/.cursor/hooks/hooks.json

# Windows PowerShell
Get-ChildItem "$env:APPDATA\Cursor\hooks"
Get-Content "$env:APPDATA\Cursor\hooks\hooks.json"
```

### 步骤 5：启动 Worker 服务

Cursor 需要后台 Worker 服务运行：

```bash
# macOS/Linux
bun ~/.claude/plugins/cache/thedotmack/claude-mem/VERSION/scripts/worker-wrapper.cjs start &

# Windows PowerShell（后台启动）
Start-Process -FilePath "$env:APPDATA\npm\node_modules\bun\bin\bun.exe" -ArgumentList "$env:USERPROFILE\.claude\plugins\cache\thedotmack\claude-mem\VERSION\scripts\worker-wrapper.cjs", "start" -WindowStyle Hidden
```

### Cursor 工作原理

```
┌─────────────────────────────────────────────────────────────┐
│                      Cursor IDE                              │
│                                                             │
│  用户操作 ──▶ Claude-Mem Hook ──▶ Worker API ──▶ 记忆存储    │
│                                                             │
│                      ▲                                      │
│                      │                                      │
│              AGENTS.md 注入                                 │
│              （压缩记忆摘要）                                │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**Hooks 触发时机**：

| Hook | 触发时机 | 作用 |
|------|----------|------|
| `pre_tool_use` | AI 调用工具前 | 检查文件读取门控 |
| `post_tool_use` | AI 调用工具后 | 记录操作到记忆库 |
| `session_start` | 新会话开始时 | 注入历史记忆上下文 |

### 项目级配置

在项目根目录创建 `.cursorrules` 文件，启用 Claude-Mem：

```cursorrules
# Claude-Mem Integration
# 记忆系统会自动注入历史上下文

## 规则
- 参考历史编码决策
- 查找相似问题解决方案
- 保持代码风格一致性
```

### Cursor 与 Claude Code 共享记忆

Claude-Mem 默认为不同 IDE 创建独立的记忆存储。如需共享记忆：

**方法 1：使用同一项目名称**

```bash
# 在两个 IDE 中使用相同的项目名
claude-mem config set project "my-shared-project"
```

**方法 2：手动配置数据库路径**

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

```json
{
  "database": {
    "path": "~/.claude-mem/shared-memories.db"
  },
  "projects": {
    "default": "shared-project"
  }
}
```

### Cursor 常见问题

**Q: Hooks 未生效，记忆不保存**

检查项：
1. Worker 服务是否运行（`curl http://localhost:37777/health`）
2. `hooks.json` 文件是否存在
3. Cursor 版本是否 >= 0.40

**Q: 记忆搜索无结果**

确保：
1. 至少完成过一个完整会话
2. Worker 正常运行并保存了观察
3. 使用正确的项目名称搜索

**Q: 与 Claude Code 记忆隔离**

默认情况下，Cursor 和 Claude Code 使用独立记忆库。如需共享，参见上文配置方法。

---

## OpenCode 安装指南

### 步骤 1：全局安装 Claude-Mem

```powershell
npm install -g claude-mem@latest
```

验证安装：

```powershell
claude-mem --version
# 输出: 12.1.6
```

### 步骤 2：运行安装器

```powershell
claude-mem install --ide opencode --yes
```

安装器会执行以下操作：

1. 复制插件文件到 Claude 插件目录
2. 缓存插件版本
3. 注册到 marketplace
4. 安装依赖（可能需要手动确认）

**输出示例**：

```
claude-mem install
  Version: 12.1.6
  Platform: win32 (x64)
  Copying to marketplace directory...
  Plugin files copied OK
  Caching v12.1.6...
  Plugin cached (v12.1.6) OK
  Marketplace registered OK
  Plugin registered OK
  Plugin enabled OK
```

```
error: install script from "tree-sitter-kotlin" exited with 1
⚠️  Bun install failed, falling back to npm...
   (This can happen with npm alias packages like *-cjs)
	 
Installing Claude-Mem for OpenCode...

Plugin installed to: C:\Users\Administrator\.config\opencode\plugins\claude-mem.js
[SETTINGS] Created settings file with defaults: C:\Users\Administrator\.claude-mem\settings.json
  Placeholder context created (worker not running)

Installation complete!

Plugin installed to: C:\Users\Administrator\.config\opencode\plugins\claude-mem.js
Context file: C:\Users\Administrator\.config\opencode\AGENTS.md

Next steps:
  1. Start claude-mem worker: npx claude-mem start
  2. Restart OpenCode to load the plugin
  3. Memory capture is automatic from then on

|
*  OpenCode: plugin installed.
|
o  Installation Complete -------------------------------------------------------+
|                                                                               |
|  Version:     12.1.6                                                          |
|  Plugin dir:  C:\Users\Administrator\.claude\plugins\marketplaces\thedotmack  |
|  IDEs:        opencode                                                        |
|                                                                               |
+-------------------------------------------------------------------------------+
|
o  Next Steps --------------------------------------------------------+
|                                                                     |
|  Open Claude Code and start a conversation -- memory is automatic!  |
|  View your memories: http://localhost:37777                         |
|  Search past work: use /mem-search in Claude Code                   |
|  Start worker: npx claude-mem start                                 |
|                                                                     |
+---------------------------------------------------------------------+
|
—  claude-mem installed successfully!
```
### 步骤 3：配置 OpenCode MCP

手动添加 MCP 服务器配置。

编辑文件：`~/.config/opencode/opencode.json`（Windows: `C:\Users\<用户名>\.config\opencode\opencode.json`）

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    // 你的其他插件...
  ],
  "mcp": {
    "claude-mem": {
      "type": "local",
      "command": [
        "node",
        "C:\\Users\\Administrator\\.claude\\plugins\\cache\\thedotmack\\claude-mem\\12.1.6\\scripts\\mcp-server.cjs"
      ],
      "enabled": true
    }
    // 你的其他 MCP 服务器...
  }
}
```

**注意**：将路径中的 `Administrator` 替换为你的用户名，`12.1.6` 替换为实际安装版本。

### 步骤 4：启动 Worker 服务

Claude-Mem 需要后台 Worker 服务来处理记忆存储和检索。

**Windows PowerShell**：

```powershell
# 方法 1：使用 Bun 直接启动（推荐）
$bunPath = "$env:APPDATA\npm\node_modules\bun\bin\bun.exe"
$workerPath = "$env:USERPROFILE\.claude\plugins\cache\thedotmack\claude-mem\12.1.6\scripts\worker-wrapper.cjs"
Start-Process -FilePath $bunPath -ArgumentList $workerPath, "start" -WindowStyle Hidden
```

```
$bunPath="E:\yiyi\npm-global\node_modules\bun\bin\bun.exe"
```

**macOS/Linux**：

```bash
# 方法 2：使用 npx（如果 PATH 正常）
npx claude-mem start

# 方法 3：直接使用 Bun
bun ~/.claude/plugins/cache/thedotmack/claude-mem/12.1.6/scripts/worker-wrapper.cjs start &
```

### 步骤 5：创建启动脚本（可选）

为方便每次开机后启动，创建 PowerShell 脚本：

保存为：`C:\Users\<用户名>\claude-mem-start.ps1`

```powershell
# Claude-Mem Worker Startup Script
$bunPath = "$env:APPDATA\npm\node_modules\bun\bin\bun.exe"
$workerPath = "$env:USERPROFILE\.claude\plugins\cache\thedotmack\claude-mem\12.1.6\scripts\worker-wrapper.cjs"

# Check if already running
$running = Get-Process -Name bun -ErrorAction SilentlyContinue
if ($running) {
    Write-Host "Worker already running (PID: $($running.Id))" -ForegroundColor Green
    exit 0
}

# Start worker
Write-Host "Starting Claude-Mem worker..." -ForegroundColor Yellow
Start-Process -FilePath $bunPath -ArgumentList $workerPath, "start" -WindowStyle Hidden

# Wait and verify
Start-Sleep -Seconds 5
try {
    $health = Invoke-WebRequest -Uri "http://localhost:37777/health" -UseBasicParsing -TimeoutSec 5
    Write-Host "Worker started successfully!" -ForegroundColor Green
    Write-Host "Web UI: http://localhost:37777" -ForegroundColor Cyan
} catch {
    Write-Host "Worker startup failed. Check logs." -ForegroundColor Red
}
```

---

## OpenClaw 安装指南

OpenClaw 是一个 AI Agent Gateway 平台，Claude-Mem 通过插件方式为其提供持久记忆。

### 步骤 1：安装 Claude-Mem CLI

```bash
npm install -g claude-mem@latest
```

### 步骤 2：配置 OpenClaw Gateway

在 OpenClaw Gateway 配置文件中添加 Claude-Mem 插件：

```json
{
  "plugins": {
    "claude-mem": {
      "enabled": true,
      "config": {
        "project": "my-project",
        "syncMemoryFile": true,
        "observationFeed": {
          "enabled": true,
          "port": 37777
        }
      }
    }
  }
}
```

### 步骤 3：配置选项说明

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `project` | 项目名称，用于区分不同项目的记忆 | 必填 |
| `syncMemoryFile` | 是否同步 MEMORY.md 到工作区 | `true` |
| `observationFeed.enabled` | 启用 SSE 观察流 | `true` |
| `observationFeed.port` | Worker 服务端口 | `37777` |
| `syncMemoryFileExclude` | 排除特定 Agent ID 的上下文注入 | `[]` |

### 步骤 4：启动 Claude-Mem Worker

OpenClaw 需要同一机器上运行 Worker 服务：

```bash
claude-mem start
# 或
bun ~/.claude/plugins/cache/thedotmack/claude-mem/VERSION/scripts/worker-wrapper.cjs start
```

### OpenClaw 特殊功能

1. **系统提示注入**：v10.6.0+ 版本不再写入 MEMORY.md，而是通过 `before_prompt_build` 钩子将观察时间线注入 Agent 的系统提示。

2. **多 Agent 支持**：可以为不同 Agent 配置不同的记忆隔离。

3. **实时观察流**：通过 SSE 实时推送观察数据到连接的客户端。

---

## 验证与测试

### Worker 健康检查

```bash
# HTTP 请求验证
curl http://localhost:37777/health
# 或 PowerShell
Invoke-WebRequest -Uri "http://localhost:37777/health" -UseBasicParsing

# 应返回
{"status":"ok","timestamp":1234567890000}
```

### 统计信息查看

```bash
curl http://localhost:37777/api/stats
# 或 PowerShell
Invoke-WebRequest -Uri "http://localhost:37777/api/stats" -UseBasicParsing

# 返回示例
{
  "worker": {
    "version": "12.1.6",
    "uptime": 1234,
    "activeSessions": 0,
    "sseClients": 0,
    "port": 37777
  },
  "database": {
    "path": "/path/to/claude-mem.db",
    "size": 4096,
    "observations": 0,
    "sessions": 0,
    "summaries": 0
  }
}
```

### Web UI 访问

浏览器打开：`http://localhost:37777`

功能：
- 查看所有记忆条目
- 搜索历史观察
- 查看会话时间线
- 手动添加记忆

### MCP 工具测试

重启 OpenCode 后，在会话中使用：

```typescript
// 搜索记忆
claude-mem_search({ query: "authentication implementation", limit: 10 })

// 查看时间线
claude-mem_timeline({ anchor: 12345, depthBefore: 3, depthAfter: 3 })

// 获取详细观察
claude-mem_get_observations({ ids: [12345, 12346] })
```

---

## 常见问题

### Q1: Worker 启动失败 "spawn bun ENOENT"

**原因**：Bun 可执行文件路径不在系统 PATH 中。

**解决方案**：

```powershell
# 查找 Bun 实际位置
where.exe bun
# 通常在: C:\Users\<用户>\AppData\Roaming\npm\bun.cmd

# 直接使用 Bun exe 启动
$bunExe = "$env:APPDATA\npm\node_modules\bun\bin\bun.exe"
& $bunExe "$env:USERPROFILE\.claude\plugins\cache\thedotmack\claude-mem\VERSION\scripts\worker-wrapper.cjs" start
```

### Q2: OpenCode 无法识别 MCP 工具

**检查项**：

1. 确认 `opencode.json` 配置正确
2. 确认 MCP 服务器脚本路径正确
3. 确认 Worker 服务正在运行
4. 重启 OpenCode

### Q3: 记忆不保存或搜索无结果

**检查项**：

1. Worker 是否正在运行（检查进程）
2. 健康检查是否返回 OK
3. 数据库文件是否存在（`~/.claude-mem/claude-mem.db`）

### Q4: 如何跨 Claude Code 和 OpenCode 共享记忆？

使用社区插件 `opencode-claude-mem`：

```bash
git clone https://github.com/synapz-org/opencode-claude-mem.git
cd opencode-claude-mem
./install.sh
```

此方案让两个 IDE 共享同一 Claude-Mem 数据库。

### Q5: Windows 路径问题

**注意事项**：

- JSON 配置中使用双反斜杠 `\\` 或正斜杠 `/`
- PowerShell 脚本中使用 `$env:USERPROFILE` 变量
- 版本号需要根据实际安装更新

---

## 参考资源

### 官方资源

| 资源 | 链接 |
|------|------|
| Claude-Mem GitHub | https://github.com/thedotmack/claude-mem |
| Claude-Mem Releases | https://github.com/thedotmack/claude-mem/releases |
| Claude-Mem CHANGELOG | https://github.com/thedotmack/claude-mem/blob/main/CHANGELOG.md |

### OpenCode 资源

| 资源 | 链接 |
|------|------|
| OpenCode 官网 | https://opencode.ai |
| OpenCode 文档 - MCP | https://opencode.ai/docs/mcp-servers |
| OpenCode 文档 - Plugins | https://opencode.ai/docs/plugins |

### OpenClaw 资源

| 资源 | 链接 |
|------|------|
| OpenClaw 文档 | 参考 Claude-Mem CHANGELOG 中的 OpenClaw 章节 |

### 社区插件

| 插件 | 链接 | 说明 |
|------|------|------|
| opencode-claude-mem | https://github.com/synapz-org/opencode-claude-mem | 跨 IDE 共享记忆 |
| claude-mem-opencode | https://libraries.io/npm/claude-mem-opencode | npm 包集成 |
| opencode-mem | https://github.com/tickernelz/opencode-mem | 独立记忆系统 |

---

## 附录：完整配置示例

### OpenCode 配置文件示例

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "oh-my-openagent",
    "superpowers@git+https://github.com/obra/superpowers.git"
  ],
  "mcp": {
    "docfork": {
      "type": "remote",
      "url": "https://mcp.docfork.com/mcp",
      "enabled": true
    },
    "opencode-mcp": {
      "type": "local",
      "command": ["npx", "-y", "opencode-mcp"],
      "enabled": true
    },
    "claude-mem": {
      "type": "local",
      "command": [
        "node",
        "C:\\Users\\Administrator\\.claude\\plugins\\cache\\thedotmack\\claude-mem\\12.1.6\\scripts\\mcp-server.cjs"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw Gateway 配置示例

```json
{
  "plugins": {
    "claude-mem": {
      "enabled": true,
      "config": {
        "project": "production-agents",
        "syncMemoryFile": true,
        "syncMemoryFileExclude": ["debugger", "snarf"],
        "observationFeed": {
          "enabled": true,
          "port": 37777
        }
      }
    }
  }
}
```

---

## 版本历史

| 版本 | 日期 | 重要变更 |
|------|------|----------|
| v12.1.6 | 2026-04-17 | 当前最新版本，修复 observation 保存问题 |
| v12.1.5 | 2026-04-15 | 强制更新以修复 --setting-sources 问题 |
| v12.0.0 | 2026-04-07 | 智能文件读取门控、平台隔离 |
| v11.0.0 | 2026-04-05 | 安装器回归修复 |
| v10.7.0 | 2026-04-04 | 首次正式支持 OpenCode |
| v10.0.0 | 2026-02-11 | 首次正式支持 OpenClaw |

---

> **作者**: AI Assistant
> **生成日期**: 2026-04-17
> **适用版本**: Claude-Mem v12.1.6, OpenCode v1.x, OpenClaw Gateway

yyii

https://amtb.info/show/Mzcz

本博客所有文章除特別声明外,转载请注明来源佛系程序员 !