Claude-Mem 文档

为 Claude Code 构建的持久化内存压缩系统

快速开始

在终端中启动新的 Claude Code 会话并输入以下命令：

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

重启 Claude Code。来自先前会话的上下文将自动出现在新会话中。

核心特性

• 🧠 持久化内存 - 上下文跨会话保留
• 📁 文件夹上下文文件 - 在项目文件夹中自动生成带活动时间线的 CLAUDE.md
• 🌐 多语言模式 - 支持28种语言（西班牙语、中文、法语、日语等）
• 🎭 模式系统 - 在不同工作流之间切换（代码、邮件调查、休闲）
• 🔍 MCP搜索工具 - 使用自然语言查询项目历史
• 🌐 Web查看器界面 - 在 http://localhost:37777 实时查看内存流
• 🔒 隐私控制 - 使用 <private> 标签排除敏感内容的存储
• ⚙️ 上下文配置 - 精细控制注入的上下文内容
• 🤖 自动操作 - 无需手动干预
• 📊 FTS5搜索 - 快速全文搜索观察
• 🔗 引用 - 使用ID引用过去的观察

工作原理

核心组件

1. 4个生命周期钩子 - SessionStart、UserPromptSubmit、PostToolUse、Stop
2. 智能安装 - 缓存依赖检查器（预钩子脚本）
3. Worker服务 - 端口37777上的HTTP API，由Bun管理
4. SQLite数据库 - 存储会话、观察、摘要，支持FTS5搜索
5. MCP搜索工具 - 使用自然语言查询历史上下文
6. Web查看器UI - 实时可视化，支持SSE和无限滚动

详见 架构概述。

系统要求

• Node.js: 18.0.0 或更高版本
• Claude Code: 支持插件的最新版本
• Bun: JavaScript运行时和进程管理器（如缺失会自动安装）
• SQLite 3: 用于持久化存储（已内置）

配置

设置在 ~/.claude-mem/settings.json 中管理（首次运行时自动创建默认设置）。可配置AI模型、worker端口、数据目录、日志级别和上下文注入设置。

详见 配置指南。

开发

详见 开发指南 了解构建说明、测试和贡献工作流程。

故障排除

如果遇到问题，向Claude描述问题，troubleshoot技能将自动诊断并提供修复方案。

详见 故障排除指南。

文档目录

入门指南

• 安装指南 - 快速开始与高级安装
• 使用指南 - Claude-Mem如何自动工作
• 搜索工具 - 使用自然语言查询项目历史
• 测试版功能 - 尝试实验性功能，如无尽模式

最佳实践

• 上下文工程 - AI代理上下文优化原则
• 渐进式披露 - Claude-Mem上下文启动策略背后的哲学

架构

• 概述 - 系统组件与数据流
• 架构演进 - 从v3到v5的旅程
• 钩子架构 - Claude-Mem如何使用生命周期钩子
• 钩子参考 - 7个钩子脚本详解
• Worker服务 - HTTP API与Bun管理
• 数据库 - SQLite模式与FTS5搜索
• 搜索架构 - 使用Chroma向量数据库的混合搜索

配置与开发

• 配置 - 环境变量与设置
• 开发 - 构建、测试、贡献
• 故障排除 - 常见问题与解决方案

本文档由AI自动翻译，原文见 Claude-Mem GitHub