Index - claude-mem

Greptile

🇨🇳 中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇵🇹 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 即使在会话结束或重新连接之后，也能保持对项目知识的连续性。

快速开始¶

为 Grok Bot 安装 claude-mem：

npx claude-mem install --ide grok-bot

Grok Bot 没有主机钩子，因此我们会监视聊天日志文件。默认使用 CMEM Pro 托管记忆。本地观察器为可选启用：--provider host。安装此插件不会安装 Cursor。

感知推送试点（LFG + Orifice）： 关键观察（decision、bugfix、security_alert、sensitive）会以带日期的 - YYYY-MM-DD [awareness] … 行形式追加到该机器人的 memory/log/YYYY-MM.md 文件中。Grok Bot 已经会从磁盘重新读取该日志。此操作不会写入 profile.md、用户记忆或项目记忆。可通过 CLAUDE_MEM_GROK_BOT_AWARENESS_ENABLED=false 禁用。

使用单条命令安装：

npx claude-mem install

安装程序会先完成所有设置，然后要求你在浏览器中登录 claude-mem（邮箱魔法链接——无需信用卡）。登录后将为你的账户分配一个记忆密钥，并解锁 claude-mem 观察器的 30 天免费试用：记忆在套餐之外运行，因此你最多可获得套餐用量 100% 的额外空间。免费试用结束后，除非你订阅，否则记忆会自动回退到你的 Anthropic 套餐。登录后，你可以选择你的记忆提供方——claude-mem 观察器、你自己的 OpenRouter 或 Gemini 密钥，或者你的 Anthropic 套餐。

想跳过登录？传入显式的 --provider 标志，设置 CLAUDE_MEM_ONLINE_OPTIN=false，或在 CI/非交互式 shell 中运行——安装程序无需任何账户交互即可完成。

或为 OpenCode 安装：

npx claude-mem install --ide opencode

这适用于 OpenCode 1.3.4 或更高版本，包括 OpenCode 2。安装后请重启 OpenCode。

或为 T3 Code（Codex 和 Claude Code 提供方）安装：

npx claude-mem install --ide t3code

安装程序会发现 T3 Code 已启用的提供方，在其配置的主目录中注册原生 Claude-Mem 插件，并支持 T3 管理的 Codex。重启 T3 Code，在提示时信任提供方的钩子，然后开始新会话。有关自定义服务器设置、状态和移除，请参阅 T3 Code 集成指南。

或为 Antigravity CLI 安装（设置指南）：

npx claude-mem install --ide antigravity

或为 OMP（Oh My Pi）安装：

npx claude-mem install --ide omp

或安装原生 Pi 扩展或 DeepSeek Harness 插件：

npx claude-mem install --ide pi
npx claude-mem install --ide dsh --dsh-profile tui

Pi 和 DeepSeek Harness 使用 worker 运行时。有关捕获、召回和故障排除，请参阅原生 harness 设置。

或从 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 网关¶

使用单条命令将 claude-mem 安装为 OpenClaw 网关上的持久记忆插件：

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

安装程序负责处理依赖项、插件设置、AI 提供方配置、worker 启动，以及可选的实时观察推送，可发送到 Telegram、Discord、Slack 等渠道。详情请参阅 OpenClaw 集成指南。

主要特性：

🧠 持久记忆 - 上下文在会话之间保持
📊 渐进式披露 - 分层记忆检索，附带 Token 成本可见性
🔍 智能搜索（默认） - 使用三步 mem-search 技能查询你的项目历史
🖥️ 本地 My Work - 在启动时打印的 worker URL 上查看实时请求、进度、人工交接和已保存的审查队列。指南。记忆、会话和设置保留在 /viewer。
👥 TeamBrain - My Work 旁边的一个可选共享工作区，包含真实的团队工作列表、成员归属和关联发现。每个人自行选择要分享的内容；个人请求和审查备注保持独立。创建团队。
💻 Claude Desktop 技能 - 从 Claude Desktop 对话中搜索记忆
🔒 隐私控制 - 使用 <private> 标签将敏感内容排除在存储之外
⚙️ 上下文配置 - 对注入哪些上下文进行细粒度控制
🤖 自动运行 - 无需手动干预
🔗 引用 - 通过 worker API 使用 ID 引用过去的观察结果，或在网页查看器中查看全部

文档¶

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

开始使用¶

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

最佳实践¶

上下文工程 - AI 智能体上下文优化原则
渐进式披露 - Claude-Mem 上下文预加载策略背后的设计理念

架构¶

概述 - 系统组件与数据流
架构演进 - 从 v3 到 v5 的演进历程
Hooks 架构 - Claude-Mem 如何使用生命周期 hooks
Hooks 参考 - 每个 hook 条目的详细说明
Worker Service - HTTP API 与 Bun 管理
数据库 - SQLite 架构与 FTS5 搜索
搜索架构 - 使用 Chroma 向量数据库的混合搜索

配置与开发¶

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

工作原理¶

核心组件：

生命周期 Hooks - SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、SessionEnd。每个 hook 都是一条不依赖 shell 的命令 claude-mem hook claude-code <event>，由安装程序放入 PATH 的小型启动器运行
智能安装 - 缓存依赖检查器（claude --init / --maintenance 上的 Setup hook，以及 npx claude-mem install / repair）
Worker Service - 带有 Web 查看器 UI 和搜索端点的本地 HTTP API，由 Bun 管理
SQLite 数据库 - 存储会话、观察记录、摘要
mem-search Skill - 支持渐进式披露的自然语言查询
Chroma 向量数据库 - 混合语义 + 关键词搜索，用于智能上下文检索

有关详细信息，请参阅架构概述。

MCP 搜索工具¶

Claude-Mem 通过 4 个 MCP 工具提供智能记忆搜索，遵循一种节省 token 的 3 层工作流模式：

3 层工作流：

search - 获取带有 ID 的紧凑索引（约 50-100 tokens/结果）
timeline - 获取有趣结果周围的时间顺序上下文
get_observations - 仅获取筛选后 ID 的完整详细信息（约 500-1,000 tokens/结果）

工作原理：

Claude 使用 MCP 工具搜索您的记忆
从 search 开始，获取结果索引
使用 timeline 查看特定观察记录周围发生的事情
使用 get_observations 获取相关 ID 的完整详细信息
通过先筛选再获取详细信息，节省约 10 倍 tokens

可用的 MCP 工具：

search - 使用全文查询搜索记忆索引，可按类型/日期/项目过滤
timeline - 获取特定观察记录或查询周围的时间顺序上下文
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])

有关详细示例，请参阅搜索工具指南。

系统要求¶

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 Code hooks 不需要 Git Bash。每个 hook 直接运行 claude-mem，npx claude-mem install 会将该启动器放置在 %LOCALAPPDATA%\claude-mem\bin\claude-mem.exe，并将该文件夹添加到您的用户 Path。之后请重新启动终端或 IDE，以便 Claude Code 获取新的 Path。如果 hooks 报告 Executable not found in $PATH: "claude-mem"，请运行 npx claude-mem doctor 并参阅故障排查。

配置¶

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

要在 Claude Code 和 Codex 的 SessionStart 上下文中包含来自所有 harness 的观察记录，请在该文件中设置 "CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES": "true"，或在查看器设置中启用在会话开始时包含所有来源。默认值为 "false"，即将启动上下文仅限于当前 harness。观察记录数量限制仍然适用于所选来源。

有关所有可用设置和示例，请参阅配置指南。

模式与语言配置¶

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 描述问题，故障排除技能将自动诊断并提供修复方案。

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

错误报告¶

使用自动化生成器创建全面的错误报告：

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

贡献¶

欢迎贡献！请：

Fork 仓库
创建功能分支
进行更改并编写测试
更新文档
向 main 提交 Pull Request

发布版本从 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 了解详情。

支持¶

文档：docs/
问题：GitHub Issues
仓库：github.com/thedotmack/claude-mem
官方 X 账号：@Claude_Memory
官方 Discord：加入 Discord
作者：Alex Newman (@thedotmack)

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

关于 CMEM？¶

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

官方 BASE CA：0x76b1967eec0ccaeb001bbbb2b40dc4badba31ba3

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/claude-mem