> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/thedotmack/claude-mem) · [上游 README](https://github.com/thedotmack/claude-mem/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

🇨🇳 中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇵🇹 Português • 🇧🇷 Português • 🇰🇷 한국어 • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇮🇱 עברית • 🇸🇦 العربية • 🇷🇺 Русский • 🇵🇱 Polski • 🇨🇿 Čeština • 🇳🇱 Nederlands • 🇹🇷 Türkçe • 🇺🇦 Українська • 🇻🇳 Tiếng Việt • 🇵🇭 Tagalog • 🇮🇩 Indonesia • 🇹🇭 ไทย • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇷🇴 Română • 🇸🇪 Svenska • 🇮🇹 Italiano • 🇬🇷 Ελληνικά • 🇭🇺 Magyar • 🇫🇮 Suomi • 🇩🇰 Dansk • 🇳🇴 Norsk

为 Claude Code 构建的持久化记忆压缩系统。

快速开始 • 工作原理 • 搜索工具 • 文档 • 配置 • 故障排除 • 许可证

Claude-Mem 通过在会话之间无缝保留上下文，自动捕获工具使用观察记录、生成语义摘要，并使其在后续会话中可用。这样即使会话结束或重新连接，Claude 也能保持对项目知识的连续性。

--- ## 快速开始一条命令即可安装： ```bash npx claude-mem install ``` 或在 OpenCode 中安装： ```bash npx claude-mem install --ide opencode ``` 或在 Antigravity CLI 中安装（[安装指南](https://docs.claude-mem.ai/antigravity-cli/setup)): ```bash npx claude-mem install --ide antigravity ``` 或在 Claude Code 内的插件市场中安装： ```bash /plugin marketplace add thedotmack/claude-mem /plugin install claude-mem ``` 重启 Claude Code。此前会话的上下文将自动出现在新会话中。 > **注意：** Claude-Mem 也发布在 npm 上，但 `npm install -g claude-mem` 仅安装 **SDK/库** — 不会注册插件钩子或设置 worker 服务。请始终通过 `npx claude-mem install` 或上文中的 `/plugin` 命令安装。 ### 🦞 OpenClaw Gateway 一条命令即可在 [OpenClaw](https://openclaw.ai) 网关上将 claude-mem 安装为持久化记忆插件： ```bash curl -fsSL https://install.cmem.ai/openclaw.sh | bash ``` 安装程序会处理依赖项、插件设置、AI 提供商配置、worker 启动，以及可选的实时观察流推送到 Telegram、Discord、Slack 等平台。详见 [OpenClaw 集成指南](https://docs.claude-mem.ai/openclaw-integration)。 **主要特性：** - 🧠 **持久化记忆（Persistent Memory）** - 上下文跨会话保留 - 📊 **渐进式披露（Progressive Disclosure）** - 分层记忆检索，并可见 token 成本 - 🔍 **基于 Skill 的搜索** - 使用 mem-search skill 查询项目历史 - 🖥️ **Web 查看器 UI** - 启动时打印的 worker URL 上可查看实时记忆流 - 💻 **Claude Desktop Skill** - 在 Claude Desktop 对话中搜索记忆 - 🔒 **隐私控制** - 使用 `` 标签排除敏感内容，使其不被存储 - ⚙️ **上下文配置** - 精细控制注入的上下文内容 - 🤖 **自动运行** - 无需人工干预 - 🔗 **引用（Citations）** - 通过 worker API 用 ID 引用过往观察记录，或在 Web 查看器中查看全部 --- ## 文档 📚 **[查看完整文档](https://docs.claude-mem.ai/)** - 在官方网站浏览 ### 入门 - **[安装指南](https://docs.claude-mem.ai/installation)** - 快速入门与高级安装 - **[使用指南](https://docs.claude-mem.ai/usage/getting-started)** - Claude-Mem 如何自动工作 - **[搜索工具](https://docs.claude-mem.ai/usage/search-tools)** - 用自然语言查询项目历史 - **[云同步](https://docs.claude-mem.ai/cloud-sync)** - 将记忆备份到 cmem.ai — 无需守护进程，worker 在写入时同步 ### 最佳实践 - **[Context Engineering](https://docs.claude-mem.ai/context-engineering)** - AI 智能体上下文优化原则 - **[Progressive Disclosure](https://docs.claude-mem.ai/progressive-disclosure)** - Claude-Mem 上下文预载策略背后的理念 ### 架构 - **[Overview](https://docs.claude-mem.ai/architecture/overview)** - 系统组件与数据流 - **[Architecture Evolution](https://docs.claude-mem.ai/architecture-evolution)** - 从 v3 到 v5 的演进历程 - **[Hooks Architecture](https://docs.claude-mem.ai/hooks-architecture)** - Claude-Mem 如何使用生命周期钩子 - **[Hooks Reference](https://docs.claude-mem.ai/architecture/hooks)** - 7 个钩子脚本说明 - **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API 与 Bun 管理 - **[Database](https://docs.claude-mem.ai/architecture/database)** - SQLite schema 与 FTS5 搜索 - **[Search Architecture](https://docs.claude-mem.ai/architecture/search-architecture)** - 基于 Chroma 向量数据库的混合搜索 ### 配置与开发 - **[Configuration](https://docs.claude-mem.ai/configuration)** - 环境变量与设置 - **[Development](https://docs.claude-mem.ai/development)** - 构建、测试与贡献 - **[Release Branches](https://docs.claude-mem.ai/branches)** - stable、core-dev 与 community-edge 分支流程 - **[Troubleshooting](https://docs.claude-mem.ai/troubleshooting)** - 常见问题与解决方案 --- ## 工作原理 **核心组件：** 1. **5 个生命周期钩子（Lifecycle Hooks）** - SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd（6 个钩子脚本） 2. **Smart Install（智能安装）** - 带缓存的依赖检查器（预钩子脚本，非生命周期钩子） 3. **Worker Service（工作服务）** - 由 Bun 管理的本地 HTTP API，提供 Web 查看器 UI 与搜索端点 4. **SQLite 数据库** - 存储会话、观察记录与摘要 5. **mem-search Skill** - 支持渐进式披露（Progressive Disclosure）的自然语言查询 6. **Chroma 向量数据库** - 语义 + 关键词混合搜索，用于智能上下文检索详见 [Architecture Overview](https://docs.claude-mem.ai/architecture/overview)。 --- ## MCP 搜索工具 Claude-Mem 通过 **4 个 MCP 工具**提供智能记忆搜索，遵循省 token 的 **三层工作流模式**： **三层工作流：** 1. **`search`** - 获取带 ID 的紧凑索引（约 50–100 tokens/条结果） 2. **`timeline`** - 获取有趣结果周边的按时间排序的上下文 3. **`get_observations`** - **仅**为已筛选的 ID 拉取完整详情（约 500–1,000 tokens/条结果） **工作原理：** - Claude 使用 MCP 工具搜索你的记忆 - 先用 `search` 获取结果索引 - 使用 `timeline` 查看特定观察记录周边发生了什么 - 使用 `get_observations` 为相关 ID 拉取完整详情 - 先筛选再拉取详情，可节省约 **10 倍 token** **可用的 MCP 工具：** 1. **`search`** - 用全文查询搜索记忆索引，可按类型/日期/项目筛选 2. **`timeline`** - 获取特定观察记录或查询周边的按时间排序的上下文 3. **`get_observations`** - 按 ID 拉取完整观察详情（务必批量传入多个 ID） **使用示例：** ```typescript // Step 1: Search for index search(query="authentication bug", type="bugfix", limit=10) // Step 2: Review index, identify relevant IDs (e.g., #123, #456) // Step 3: Fetch full details get_observations(ids=[123, 456]) ``` 详见 [Search Tools Guide](https://docs.claude-mem.ai/usage/search-tools) 中的详细示例。 --- ## 发布分支稳定版从 `main` 发布，并发布到 npm。`core-dev` 和 `community-edge` 是用于早期可靠性修复与社区集成的源码运行分支。分支流程与非稳定版运行说明见 **[Release Branches](https://docs.claude-mem.ai/branches)**。 --- ## 系统要求 - **Node.js**：20.0.0 或更高版本 - **Claude Code**：支持插件的最新版本 - **Bun**：JavaScript 运行时与进程管理器（缺失时自动安装） - **uv**：用于向量搜索的 Python 包管理器（缺失时自动安装） - **SQLite 3**：持久化存储（已捆绑） --- ### Windows 安装说明若出现如下错误： ```powershell npm : The term 'npm' is not recognized as the name of a cmdlet ``` 请确保已安装 Node.js 与 npm，并已加入 PATH。从 https://nodejs.org 下载最新 Node.js 安装包，安装后重启终端。 --- ## 配置设置在 `~/.claude-mem/settings.json` 中管理（首次运行时会自动创建并填入默认值）。可配置 AI 模型、worker 端口、数据目录、日志级别与上下文注入设置。所有可用设置与示例见 **[Configuration Guide](https://docs.claude-mem.ai/configuration)**。 ### 模式与语言配置 Claude-Mem 通过 `CLAUDE_MEM_MODE` 设置支持多种工作流模式与语言。该选项同时控制： - 工作流行为（例如 code、chill、investigation） - 生成观察记录所使用的语言 #### 如何配置在 `~/.claude-mem/settings.json` 编辑设置文件： ```json { "CLAUDE_MEM_MODE": "code--zh" } ``` 模式定义于 `plugin/modes/`。要在本地查看所有可用模式： ```bash ls ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/ ``` #### 可用模式 | 模式 | 说明 | |------------|-------------------------| | `code` | 默认英文模式 | | `code--zh` | 简体中文模式 | | `code--ja` | 日文模式 | 语言专用模式遵循 `code--[lang]` 命名模式，其中 `[lang]` 为 ISO 639-1 语言代码（例如：中文为 `zh`，日文为 `ja`，西班牙文为 `es`）。 > 注意：`code--zh`（简体中文）已内置——无需额外安装或更新插件。 #### 更改模式后重启 Claude Code 以应用新的模式配置。 --- ## 开发构建说明、测试与贡献流程见 **[Development Guide](https://docs.claude-mem.ai/development)**。 --- ## 故障排除如遇问题，向 Claude 描述问题，故障排除技能会自动诊断并提供修复方案。常见问题与解决方案见 **[Troubleshooting Guide](https://docs.claude-mem.ai/troubleshooting)**。 --- ## 错误报告使用自动生成器创建完整的错误报告： ```bash cd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report ``` ## 贡献欢迎贡献！请： 1. Fork 该仓库 2. 创建功能分支 3. 在修改时附带测试 4. 更新文档 5. 提交 Pull Request Claude-Mem 从三个分支发布：`main`（stable）、`core-dev` 和 `community-edge`。仅 `main` 发布到 npm；其余分支需从源码运行。策略与本地运行说明见 [Release Branches](https://docs.claude-mem.ai/branches)。贡献流程见 [Development Guide](https://docs.claude-mem.ai/development)。 --- ## 许可证 Claude-Mem 采用 Apache License 2.0 许可。我们选择 Apache-2.0，是因为持久的智能体记忆应易于嵌入开发者工具、本地智能体、MCP 服务器、企业系统、机器人技术栈，以及生产级智能体运行时（agent harnesses）。完整条款见 [LICENSE](LICENSE) 文件。许可范围及开源/商业边界见 [docs/license.md](docs/license.md) 与 [docs/ip-boundary.md](docs/ip-boundary.md)。 **关于 Ragtime**：`ragtime/` 目录采用 **Apache License 2.0** 许可。详见 [ragtime/LICENSE](ragtime/LICENSE)。 --- ## 支持 - **文档**：[docs/](docs/) - **Issues**：[GitHub Issues](https://github.com/thedotmack/claude-mem/issues) - **仓库**：[github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) - **官方 X 账号**：[@Claude_Memory](https://x.com/Claude_Memory) - **官方 Discord**：[Join Discord](https://discord.com/invite/J4wttp9vDu) - **作者**：Alex Newman（[@thedotmack](https://github.com/thedotmack)) --- **Built with Claude Agent SDK** | **Works with Claude Code** | **Made with TypeScript** --- ### CMEM 是什么？ CMEM 是由第三方创建的代币，但获得了 Claude-Mem 创作者（Alex Newman，@thedotmack）的官方认可。该代币充当社区增长催化剂，也是将 CMEM 带给最需要的开发者和知识工作者的载体。 Official BASE CA: 0x76b1967eec0ccaeb001bbbb2b40dc4badba31ba3