Claude-Mem：为 Claude Code 打造的智能记忆插件

xyaioo
3 阅读7分钟

一个让 AI 编程助手拥有持久记忆的强大工具

项目介绍

Claude-Mem 是一款专为 Claude Code 设计的智能记忆插件，它能够自动捕获编码会话中的所有操作记录，通过 AI 智能压缩，并在未来的会话中注入相关上下文。这款插件解决了 AI 编程助手最棘手的问题之一——上下文连续性。

在传统的 Claude Code 使用中，每次开启新会话，AI 都需要重新了解项目背景，这不仅浪费时间，还容易导致信息丢失。Claude-Mem 通过一套精密的记忆系统，让 Claude 能够“记住”之前的对话和操作，实现真正的智能辅助编程。

核心功能

1. 自动上下文捕获

  • 通过 5 个生命周期钩子（SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd）自动记录会话

  • 智能依赖检查器确保环境配置正确

2. 智能压缩与存储

  • 使用 SQLite 数据库存储会话、观察和摘要

  • 集成 Chroma 向量数据库，支持语义 + 关键词混合搜索

  • 将工具输出压缩为约 500 令牌的观察记录

3. 强大的搜索能力

  • 提供 10 种搜索端点，包括全文搜索、概念标签、文件引用、类型过滤等

  • 自然语言查询支持，支持渐进式信息展示

  • 相比传统 MCP 方式可节省约 2,250 个令牌

4. Web 可视化界面

  • 内置 HTTP API 服务（默认端口 37777）

  • 提供直观的 Web 查看器界面

  • 支持在浏览器中浏览和管理记忆

5. Endless Mode（实验性功能）

  • 突破传统 Claude Code 会话限制（约 50 次工具使用后上下文超限）

  • 通过实时转录转换，将工具输出压缩为观察记录

  • 理论上可实现无限长的会话（实测完成 600+ 文件的完整重构）

适合什么人使用

1. 专业开发者

对于需要处理大型项目、长期维护代码库的专业开发者，Claude-Mem 能够：

  • 保持项目知识的连续性，避免每次会话重复解释项目背景

  • 自动记录重要的代码决策和技术方案

  • 快速检索历史问题和解决方案

2. 全栈工程师

全栈项目通常涉及多个技术栈和复杂的依赖关系，Claude-Mem 可以帮助：

  • 追踪跨组件的修改和影响

  • 维护技术决策的完整历史

  • 在切换项目时快速恢复上下文

3. AI 辅助编程的重度用户

如果你每天都在使用 Claude Code 进行开发工作：

  • 显著提升工作效率，减少重复沟通

  • 建立个人编码知识库

  • 实现真正的“个性化”AI 助手

4. 团队协作开发者

在团队环境中，Claude-Mem 可以：

  • 作为项目知识沉淀的工具

  • 帮助新成员快速了解项目历史

  • 记录代码审查和重构决策

5. 需要处理遗留代码的工程师

当面对复杂的历史代码库时：

  • 记录对代码的理解和分析

  • 追踪重构过程中的决策

  • 保存重要的发现和修复方案

安装教程

前置要求

  • Node.js >= 18.0.0

  • Bun 运行时（用于 Worker 服务）

  • Python 3.13（用于 Chroma MCP 集成）

  • Claude Code 已安装并配置

安装步骤

步骤 1：安装 Bun

如果你还没有安装 Bun，可以通过以下命令安装：

# macOS / Linux
curl -fsSL https://bun.sh/install | bash

# Windows (需要 PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

步骤 2：安装 Claude-Mem 插件

在终端中执行以下命令：

# 进入 Claude Code 的 hooks 目录（如果不存在则创建）
mkdir -p ~/.claude/hooks

# 克隆 claude-mem 仓库
cd ~/.claude/hooks
git clone https://github.com/thedotmack/claude-mem.git

# 进入项目目录
cd claude-mem

# 安装依赖
bun install

# 运行安装脚本
bun run install

步骤 3：配置环境

安装脚本会自动创建默认配置文件 ~/.claude-mem/settings.json。你可以根据需要编辑该文件：

{
  "CLAUDE_MEM_MODEL": "claude-sonnet-4-5",
  "CLAUDE_MEM_WORKER_PORT": 37777,
  "CLAUDE_MEM_WORKER_HOST": "127.0.0.1",
  "CLAUDE_MEM_DATA_DIR": "~/.claude-mem",
  "CLAUDE_MEM_LOG_LEVEL": "INFO",
  "CLAUDE_MEM_PYTHON_VERSION": "3.13",
  "CLAUDE_CODE_PATH": "/usr/local/bin/claude",
  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": 50
}

配置项说明：

配置项默认值说明
CLAUDE_MEM_MODELclaude-sonnet-4-5用于生成观察记录的 AI 模型
CLAUDE_MEM_WORKER_PORT37777Worker 服务端口号
CLAUDE_MEM_WORKER_HOST127.0.0.1Worker 绑定地址（设置为 0.0.0.0 允许远程访问）
CLAUDE_MEM_DATA_DIR~/.claude-mem数据存储目录
CLAUDE_MEM_LOG_LEVELINFO日志级别（DEBUG/INFO/WARN/ERROR/SILENT）
CLAUDE_MEM_CONTEXT_OBSERVATIONS50会话开始时注入的观察记录数量

步骤 4：重启 Claude Code

# 完全退出 Claude Code
claude exit

# 重新启动
claude

重启后，Claude-Mem 会自动加载并开始工作。

使用教程

基础使用

1. 验证安装

启动 Claude Code 后，你应该会看到类似以下的输出，表明 Claude-Mem 已成功加载：

[Claude-Mem] Worker service started on port 37777
[Claude-Mem] Previous session context loaded: 15 observations

2. 访问 Web 界面

打开浏览器，访问 http://localhost:37777，你可以：

  • 查看所有会话历史

  • 搜索过去的观察记录

  • 管理记忆数据

  • 切换 Beta 版本（体验 Endless Mode）

3. 自然语言搜索

Claude-Mem 最强大的功能是自然语言搜索。你可以直接向 Claude 提问关于之前工作的问题：

"我们昨天是怎么解决那个数据库连接问题的？"
"上周重构认证模块时做了什么决定？"
"帮我找到关于 API 速率限制的所有相关代码"

Claude 会自动调用 mem-search 技能，从记忆中检索相关信息。

高级功能

1. 启用 Endless Mode（实验性）

如果你需要处理超大规模项目，可以启用 Endless Mode：

# 1. 打开 Web 界面
open http://localhost:37777

# 2. 点击右上角的设置图标（齿轮图标）
# 3. 在 "Version Channel" 部分，点击 "Try Beta (Endless Mode)"
# 4. 等待 Worker 服务重启

注意事项：

  • Endless Mode 会显著增加延迟（每个工具操作需要 60-90 秒生成观察记录）

  • 这是实验性功能，可能不稳定

  • 切换版本时记忆数据会被保留

2. 隐私管理

Claude-Mem 提供双重隐私标签系统：

  • 隐私标签（Privacy Tags）：在数据收集阶段标记敏感信息，确保它们不会被存储

  • 分类标签（Classification Tags）：在检索阶段过滤和分类记忆

配置隐私设置：

# 编辑设置文件
nano ~/.claude-mem/settings.json

3. 使用搜索工具

Claude-Mem 提供 10 种搜索操作：

搜索类型用途
观察记录搜索全文搜索所有观察记录
会话搜索搜索会话摘要
提示词搜索搜索原始用户请求
概念搜索按概念标签查找（discovery、problem-solution、pattern 等）
文件搜索查找引用特定文件的观察记录
类型搜索按类型查找（decision、bugfix、feature、refactor、discovery、change）
最近上下文获取项目的近期会话上下文
时间线获取特定时间点周围的统一时间线
查询时间线搜索观察记录并获取最佳匹配项的时间线上下文
API 帮助获取搜索 API 文档

故障排除

常见问题及解决方案

1. Worker 服务无法启动

# 检查端口占用
lsof -i :37777

# 杀死占用进程
kill -9 <pid>

# 手动启动 Worker
cd ~/.claude/hooks/claude-mem
bun run worker
</pid>

2. 上下文未正确注入

# 检查数据库状态
ls -la ~/.claude-mem/

# 查看日志
tail -f ~/.claude-mem/logs/claude-mem.log

3. 搜索无结果

  • 确认会话已正确结束（使用 exit 命令而非强制关闭）

  • 检查 CLAUDE_MEM_CONTEXT_OBSERVATIONS 设置

  • 手动触发搜索：在 Claude Code 中输入 /mem-search <查询内容>

生成错误报告

如果遇到问题，可以使用内置的错误报告工具：

# 在 Claude Code 中执行
/mem-bug-report

这将生成一份包含系统信息、配置和日志的综合报告，方便提交 Issue。

总结

Claude-Mem 是 Claude Code 生态系统中一款革命性的插件，它通过智能记忆系统解决了 AI 编程助手的上下文连续性问题。无论你是独立开发者还是团队成员，这款工具都能显著提升你的编程效率。

项目当前已获得超过 55,000 个 Star 和近 3,000 个 Fork，日均新增 Star 超过 4,000 个，足以证明其受欢迎程度。随着 Endless Mode 等实验性功能的不断完善，Claude-Mem 有望成为 AI 辅助编程领域的标杆工具。

avatar
文章
阅读
粉丝