wehub/thedotmack--claude-mem
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
main
thedotmack--claude-mem/README.md
T
wehub-resource-sync 2fa6c4b858
CI / typecheck · build · test · bundle-size (push) Has been cancelled
Details
CI / clean-room dependency closure smoke (push) Has been cancelled
Details
CI / server-runtime e2e (docker · pg + valkey) (push) Has been cancelled
Details
Windows / build (push) Has been cancelled
Details
docs: make Chinese README the default
2026-07-13 09:54:40 +00:00

17 KiB
Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。


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 集成指南。

主要特性：

  • 🧠 持久化记忆（Persistent Memory） - 上下文跨会话保留
  • 📊 渐进式披露（Progressive Disclosure） - 分层记忆检索，并可见 token 成本
  • 🔍 基于 Skill 的搜索 - 使用 mem-search skill 查询项目历史
  • 🖥️ Web 查看器 UI - 启动时打印的 worker URL 上可查看实时记忆流
  • 💻 Claude Desktop Skill - 在 Claude Desktop 对话中搜索记忆
  • 🔒 隐私控制 - 使用 <private> 标签排除敏感内容，使其不被存储
  • ⚙️ 上下文配置 - 精细控制注入的上下文内容
  • 🤖 自动运行 - 无需人工干预
  • 🔗 引用（Citations） - 通过 worker API 用 ID 引用过往观察记录，或在 Web 查看器中查看全部

文档

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

入门

  • 安装指南 - 快速入门与高级安装
  • 使用指南 - Claude-Mem 如何自动工作
  • 搜索工具 - 用自然语言查询项目历史
  • 云同步 - 将记忆备份到 cmem.ai — 无需守护进程，worker 在写入时同步

最佳实践

架构

配置与开发

工作原理

核心组件：

  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。

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）

使用示例：

// 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 中的详细示例。

发布分支

稳定版从 main 发布，并发布到 npm。core-dev 和 community-edge 是用于早期可靠性修复与 社区集成的源码运行分支。分支流程与非稳定版运行说明见 Release Branches。

系统要求

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

所有可用设置与示例见 Configuration Guide。

模式与语言配置

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

开发

构建说明、测试与贡献流程见 Development Guide。

故障排除

如遇问题，向 Claude 描述问题，故障排除技能会自动诊断并提供修复方案。

常见问题与解决方案见 Troubleshooting Guide。

错误报告

使用自动生成器创建完整的错误报告：

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。

贡献流程见 Development Guide。

许可证

Claude-Mem 采用 Apache License 2.0 许可。

我们选择 Apache-2.0，是因为持久的智能体记忆应易于嵌入 开发者工具、本地智能体、MCP 服务器、企业系统、机器人技术栈， 以及生产级智能体运行时（agent harnesses）。

完整条款见 LICENSE 文件。许可范围及开源/商业边界见 docs/license.md 与 docs/ip-boundary.md。

关于 Ragtime：ragtime/ 目录采用 Apache License 2.0 许可。详见 ragtime/LICENSE。

支持

Built with Claude Agent SDK | Works with Claude Code | Made with TypeScript

CMEM 是什么？

CMEM 是由第三方创建的代币，但获得了 Claude-Mem 创作者（Alex Newman，@thedotmack）的官方认可。该代币充当社区增长催化剂，也是将 CMEM 带给最需要的开发者和知识工作者的载体。

Official BASE CA: 0x76b1967eec0ccaeb001bbbb2b40dc4badba31ba3

Reference in New Issue View Git Blame Copy Permalink