Skip to content

README.zh.md

Latest commit

 

History

History
428 lines (313 loc) · 15.9 KB

README.zh.md

File metadata and controls

428 lines (313 loc) · 15.9 KB
Raw

🌐 这是自动翻译。欢迎社区修正!


Claude-Mem
Vercel OSS Program

🇨🇳 中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇵🇹 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 构建的持久化内存压缩系统。

License Version Node Mentioned in Awesome Claude Code

thedotmack/claude-mem | Trendshift


Claude-Mem Preview Star History Chart

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

Claude-Mem 通过自动捕获工具使用观察、生成语义摘要并使其可用于未来会话,无缝保留跨会话的上下文。这使 Claude 能够在会话结束或重新连接后,依然保持对项目知识的连续性。

快速开始

使用一条命令即可安装:

npx claude-mem install

或为 OpenCode 安装:

npx claude-mem install --ide opencode

或为 Antigravity CLI 安装(设置指南):

npx claude-mem install --ide antigravity

或在 Claude Code 内部从插件市场安装:

/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 网关上将 claude-mem 安装为持久化内存插件:

curl -fsSL https://install.cmem.ai/openclaw.sh | bash

该安装程序会处理依赖项、插件设置、AI 提供商配置、worker 启动,以及可选的向 Telegram、Discord、Slack 等平台的实时观察推送。详情请参阅 OpenClaw 集成指南。

核心特性:

  • 🧠 持久化内存 - 上下文跨会话保留
  • 📊 渐进式披露 - 分层内存检索,具有令牌成本可见性
  • 🔍 基于技能的搜索 - 使用 mem-search 技能查询项目历史
  • 🖥️ Web 查看器界面 - 在启动时打印的 worker URL 上实时查看内存流
  • 💻 Claude Desktop 技能 - 从 Claude Desktop 对话中搜索内存
  • 🔒 隐私控制 - 使用 <private> 标签排除敏感内容的存储
  • ⚙️ 上下文配置 - 精细控制注入的上下文内容
  • 🤖 自动操作 - 无需手动干预
  • 🔗 引用 - 通过 worker API 使用 ID 引用过去的观察,或在 Web 查看器中查看全部

文档

📚 查看完整文档 - 在官方网站浏览

入门指南

最佳实践

架构

配置与开发

工作原理

核心组件:

  1. 5 个生命周期钩子 - SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd(6 个钩子脚本)
  2. 智能安装 - 缓存依赖检查器(预钩子脚本,不是生命周期钩子)
  3. Worker 服务 - 本地 HTTP API,带有 Web 查看器界面和搜索端点,由 Bun 管理
  4. SQLite 数据库 - 存储会话、观察、摘要
  5. mem-search 技能 - 具有渐进式披露的自然语言查询
  6. Chroma 向量数据库 - 混合语义 + 关键词搜索,实现智能上下文检索

详见架构概述。

MCP 搜索工具

Claude-Mem 通过 4 个 MCP 工具提供智能内存搜索,遵循一种省令牌的三层工作流模式:

三层工作流:

  1. search - 获取带有 ID 的紧凑索引(约 50-100 个令牌/结果)
  2. timeline - 获取感兴趣结果周围的时间顺序上下文
  3. get_observations - 仅为筛选出的 ID 获取完整详情(约 500-1,000 个令牌/结果)

工作方式:

  • Claude 使用 MCP 工具搜索您的内存
  • 首先使用 search 获取结果索引
  • 使用 timeline 查看特定观察周围发生的情况
  • 使用 get_observations 为相关 ID 获取完整详情
  • 通过在获取详情前进行筛选,节省约 10 倍的令牌

可用的 MCP 工具:

  1. search - 使用全文查询搜索内存索引,按类型/日期/项目筛选
  2. timeline - 获取特定观察或查询周围的时间顺序上下文
  3. get_observations - 按 ID 获取完整观察详情(始终批量处理多个 ID)

使用示例:

// 步骤 1:搜索索引
search(query="authentication bug", type="bugfix", limit=10)

// 步骤 2:查看索引,识别相关 ID(例如 #123、#456)

// 步骤 3:获取完整详情
get_observations(ids=[123, 456])

详见搜索工具指南的详细示例。

发布分支

稳定版发布自 main 分支,并发布到 npm。core-dev 和 community-edge 是用于早期可靠性修复和社区集成的源码运行分支。请参阅 发布分支 了解分支流程和非稳定版运行说明。

系统要求

  • Node.js: 20.0.0 或更高版本
  • Claude Code: 支持插件的最新版本
  • Bun: JavaScript 运行时和进程管理器(如缺失会自动安装)
  • uv: 用于向量搜索的 Python 包管理器(如缺失会自动安装)
  • SQLite 3: 用于持久化存储(已内置)

Windows 设置说明

如果您看到类似以下的错误:

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 端口、数据目录、日志级别和上下文注入设置。

详见 配置指南 了解所有可用设置和示例。

模式与语言配置

Claude-Mem 通过 CLAUDE_MEM_MODE 设置支持多种工作流模式和语言。

此选项同时控制:

  • 工作流行为(例如 code、chill、investigation)
  • 生成观察时所使用的语言

配置方法

编辑位于 ~/.claude-mem/settings.json 的设置文件:

{
  "CLAUDE_MEM_MODE": "code--zh"
}

模式定义在 plugin/modes/ 中。要在本地查看所有可用模式:

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 以应用新的模式配置。

开发

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

故障排除

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

详见 故障排除指南 了解常见问题和解决方案。

Bug 报告

使用自动生成器创建全面的 bug 报告:

cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report

贡献

欢迎贡献!请:

  1. Fork 仓库
  2. 创建功能分支
  3. 进行更改并添加测试
  4. 更新文档
  5. 提交 Pull Request

Claude-Mem 从三个分支发布:main(稳定版)、core-dev 和 community-edge。只有 main 会发布到 npm;其他分支从源码运行。请参阅 发布分支 了解相关策略和本地运行说明。

详见开发指南了解贡献工作流程。

许可证

Claude-Mem 根据 Apache License 2.0 授权。

我们选择 Apache-2.0 是因为持久化的代理内存应该易于嵌入到 开发者工具、本地代理、MCP 服务器、企业系统、机器人技术栈, 以及生产环境的代理运行框架中。

完整详情请参阅 LICENSE 文件。授权范围及开源/商业边界 请参阅 docs/license.md 和 docs/ip-boundary.md。

关于 Ragtime 的说明:ragtime/ 目录根据 Apache License 2.0 授权。详情请参阅 ragtime/LICENSE。

支持

使用 Claude Agent SDK 构建 | 兼容 Claude Code | 使用 TypeScript 制作

CMEM 是什么?

CMEM 是由第三方创建、但获得 Claude-Mem 创建者(Alex Newman,@thedotmack)正式认可的代币。该代币作为社区增长的催化剂,以及将 CMEM 带给最需要它的开发者和知识工作者的载体。

官方 BASE 合约地址:0x76b1967eec0ccaeb001bbbb2b40dc4badba31ba3