Claude-Mem：开源 Claude Code 持久化记忆插件，跨会话上下文延续与智能检索工具

一、Claude-Mem是什么

Claude-Mem是一款基于TypeScript编写的开源Claude Code插件，本质是一个持久化记忆压缩系统。该工具通过在Claude Code会话中植入钩子脚本，自动捕获、压缩、存储会话中的上下文信息，并在新会话中根据需求渐进式注入记忆内容，实现Claude Code跨会话的知识连续性。同时，Claude-Mem还提供了记忆检索、隐私控制、Web可视化等功能，让开发者对会话记忆拥有全面的管理与使用权限，大幅提升Claude Code的使用效率与开发体验。

简单来说，Claude-Mem就像是Claude Code的“长期记忆大脑”，它能记住开发者之前说过的项目细节、写过的代码逻辑、遇到的调试问题，让开发者在任何时候回到Claude Code会话，都能直接基于历史记忆继续开发，无需重复“自我介绍”项目背景。

二、功能特色

Claude-Mem的功能围绕“记忆持久化、检索智能化、使用便捷化”三大核心目标设计，涵盖从记忆捕获到应用的全流程，其核心特色可分为以下10个维度：

1. 全自动会话记忆持久化

这是Claude-Mem最核心的功能。无需开发者手动干预，工具通过内置的钩子脚本，在Claude Code会话过程中自动捕获上下文信息，包括项目需求描述、代码片段、调试对话、决策结论等内容，并将其压缩后存储到本地数据库中。当开发者重启Claude Code或开启新会话时，工具会自动加载历史记忆，实现上下文的无缝衔接，彻底解决“重启会话即失忆”的问题。

2. 渐进式记忆披露与令牌成本可控

AI模型的上下文窗口存在令牌限制，若一次性注入全部历史记忆，不仅会占用大量令牌资源，还可能导致核心信息被稀释。Claude-Mem创新性地采用渐进式披露机制，根据当前会话的需求，分层级、分优先级检索并注入记忆内容，确保关键信息优先展示。同时，工具提供令牌成本可见性，开发者可以清晰看到每一次记忆注入所消耗的令牌数量，从而精准控制上下文成本，避免资源浪费。官方数据显示，通过该机制，平均可节省约2250个令牌的使用量。

3. 基于技能的记忆搜索功能

Claude-Mem内置mem-search技能，开发者在Claude Code会话中可直接通过指令调用该技能，实现对历史记忆的精准检索。例如，当开发者需要查找某段代码的调试记录时，只需输入相关关键词，工具就会从数据库中提取对应的记忆片段并展示，无需翻阅冗长的历史会话记录。这种基于技能的搜索方式，大幅提升了记忆检索的效率与准确性。

4. 可视化Web查看器UI

为了让开发者更直观地管理会话记忆，Claude-Mem提供了一个Web查看器界面，启动工具后，开发者只需在浏览器中访问http://localhost:37777，即可查看实时更新的记忆流。界面中会清晰展示记忆的捕获时间、内容摘要、令牌消耗等信息，开发者还可以对记忆片段进行筛选、删除等操作，实现对记忆的可视化管理。

5. 支持Claude桌面技能扩展

除了在Claude Code终端会话中使用，Claude-Mem还支持Claude桌面端的技能扩展。开发者在Claude桌面会话中，同样可以调用记忆搜索技能，检索跨终端的历史记忆内容，实现终端与桌面端的记忆互通，满足不同使用场景下的记忆需求。

6. 精细化隐私控制机制

在开发过程中，会话内容可能包含敏感信息（如API密钥、商业机密、私人代码逻辑等），Claude-Mem考虑到这一点，提供了隐私标签控制功能。开发者只需在会话中，将敏感内容包裹在<private>标签内，工具就会自动跳过该部分内容的存储，确保敏感信息不会被持久化到数据库中，从源头保障数据隐私安全。

7. 灵活的上下文配置功能

不同的开发场景对记忆内容的需求不同，例如调试场景需要详细的错误记录，而功能开发场景需要项目架构描述。Claude-Mem支持精细的上下文配置，开发者可以通过配置文件，自定义记忆注入的范围、优先级与格式，例如指定只注入近3次会话的记忆、只保留与当前项目相关的内容等，让记忆内容更贴合实际开发需求。

8. 记忆引用与URI链接功能

Claude-Mem支持通过claude-mem://格式的URI链接，直接引用历史会话中的决策或代码片段。例如，当开发者需要参考之前确定的项目架构方案时，可以输入claude-mem://[记忆ID]，工具会自动提取对应的记忆内容并展示，实现历史决策与当前开发的无缝衔接，提升开发决策的一致性。

9. 测试版通道与实验性功能支持

为了满足开发者对新功能的探索需求，Claude-Mem提供了测试版通道，开发者可以手动切换到测试版本，体验最新的实验性功能，例如Endless Mode（无限记忆模式）。该模式可以突破常规记忆存储的限制，实现更长时间跨度的会话记忆持久化，适合大型项目的长期开发场景。

10. 零门槛自动操作，无需手动配置

Claude-Mem遵循“开箱即用”的设计原则，开发者安装插件后，无需进行复杂的手动配置，工具会自动完成钩子脚本注入、数据库初始化、记忆捕获与加载等操作。整个过程对开发者透明，不会干扰正常的开发流程，真正实现“无感使用”。

三、技术细节

Claude-Mem的技术架构围绕“轻量化、高性能、易扩展”的原则设计，底层由钩子架构、工作服务、数据库存储、混合搜索四大核心模块组成，各模块协同工作，支撑起整个记忆管理系统的运行。

1. 技术栈基础信息

Claude-Mem的核心技术栈如下表所示，整体采用轻量化、跨平台的技术选型，确保工具的兼容性与运行效率：

2. 核心架构模块解析

（1）钩子架构：会话交互的“桥梁”

钩子架构是Claude-Mem与Claude Code交互的核心，工具内置了7种钩子脚本，分别对应Claude Code会话的不同生命周期阶段，包括会话启动钩子、消息接收钩子、消息发送钩子、记忆注入钩子、搜索触发钩子、隐私过滤钩子、会话结束钩子。

以“消息接收钩子”为例，当开发者向Claude Code发送一条消息时，该钩子会自动触发，捕获消息内容，并将其传递给记忆处理模块；“隐私过滤钩子”则会在记忆存储前，检测内容中是否包含<private>标签，过滤掉敏感信息。通过这7种钩子的协同工作，Claude-Mem实现了对Claude Code会话全流程的监控与干预，确保记忆的精准捕获与处理。

（2）工作服务：系统运行的“中枢”

Claude-Mem的工作服务基于Bun构建，主要负责三大核心任务：一是提供HTTP API服务，支撑Web查看器的可视化功能；二是管理数据库的读写操作，实现记忆的存储、检索与更新；三是协调各个钩子脚本的运行，确保记忆捕获、处理、注入的流程顺畅。

工作服务采用模块化设计，各个功能模块之间低耦合，开发者可以根据需求，对某一模块进行修改或扩展，例如替换数据库类型、新增钩子脚本等，提升了工具的可扩展性。

（3）数据库存储：记忆的“仓库”

Claude-Mem采用混合存储架构，将SQLite与Chroma向量数据库结合，分别负责不同类型的记忆存储：

• SQLite + FTS5：负责存储记忆的元数据（如捕获时间、会话ID、令牌消耗）与结构化内容（如代码片段、决策结论），并通过FTS5引擎实现全文检索。SQLite的轻量化特性，使得工具无需依赖外部服务端，所有数据均存储在本地，保障了数据的安全性与访问速度。

• Chroma向量数据库：负责存储记忆内容的向量表示，支持语义化搜索。当开发者输入自然语言关键词进行检索时，工具会将关键词转化为向量，与数据库中的记忆向量进行相似度匹配，从而找到语义相关的记忆片段，提升检索的精准度。

（4）混合搜索架构：记忆检索的“引擎”

Claude-Mem的搜索功能基于全文搜索+向量搜索的混合架构实现，兼顾检索的效率与准确性：

1. 全文搜索：基于SQLite的FTS5引擎，通过关键词匹配快速筛选出包含目标信息的记忆片段，适用于精准的关键词检索场景（如搜索某段代码的函数名）。

2. 向量搜索：基于Chroma向量数据库，通过语义相似度匹配检索记忆片段，适用于模糊的自然语言检索场景（如搜索“如何解决XX代码的报错问题”）。

工具会根据开发者的检索指令类型，自动选择合适的搜索方式，或结合两种方式进行混合检索，确保在最短时间内找到最相关的记忆内容。

3. 核心工作流程

Claude-Mem的整体工作流程可以分为记忆捕获→记忆处理→记忆存储→记忆检索→记忆注入五个阶段，具体流程如下：

1. 记忆捕获：会话启动后，钩子脚本监控Claude Code的消息收发行为，捕获会话中的上下文内容；

2. 记忆处理：隐私过滤钩子过滤敏感内容，压缩模块对记忆内容进行轻量化压缩，降低存储与令牌消耗；

3. 记忆存储：处理后的记忆内容被分为结构化数据与向量数据，分别存储到SQLite与Chroma数据库中；

4. 记忆检索：新会话启动或开发者调用mem-search技能时，混合搜索引擎根据需求检索相关记忆片段；

5. 记忆注入：检索到的记忆片段通过渐进式披露机制，按优先级注入到Claude Code的上下文窗口中，供AI模型参考。

四、应用场景

Claude-Mem的核心价值在于提升Claude Code的跨会话使用效率，其应用场景覆盖了个人开发、团队协作、大型项目维护等多个维度，具体包括以下6类场景：

1. 个人长期项目开发

对于需要长期维护的个人项目（如开源工具、个人网站、客户端应用），开发者往往需要多次切换开发场景（如白天写业务逻辑、晚上调试BUG）。使用Claude-Mem后，每次回到Claude Code会话，工具都会自动加载之前的项目记忆，包括项目架构、代码逻辑、未解决的问题等，开发者无需重复描述项目背景，直接基于历史记忆继续开发，大幅节省沟通成本。

2. 复杂代码调试场景

代码调试是一个需要持续追溯的过程，开发者可能需要在多次会话中尝试不同的调试方案。Claude-Mem可以记录每一次的调试步骤、错误信息、解决方案，当开发者遇到类似问题时，只需调用记忆搜索技能，就能快速找到之前的调试记录，避免重复踩坑。例如，当开发者遇到“TypeError: Cannot read property 'xxx' of undefined”报错时，检索历史记忆就能找到之前解决同类报错的方法。

3. 团队协作开发场景

在团队协作中，多名开发者可能会共用同一个Claude Code实例，或需要基于前人的开发成果继续工作。Claude-Mem可以存储团队成员的会话记忆，新成员加入后，通过检索历史记忆，就能快速了解项目的开发进度、代码规范、决策过程，无需向老成员反复询问，提升团队协作的效率。同时，隐私控制功能可以确保团队的敏感信息不被泄露。

4. 技术学习与实验场景

对于正在学习编程的开发者来说，Claude Code是一个重要的学习工具，开发者可能会在会话中记录大量的技术知识点、代码示例、学习笔记。Claude-Mem可以持久化这些学习记忆，开发者在后续学习中，随时可以检索之前的笔记，巩固知识点。例如，当学习React Hooks时，开发者可以检索之前记录的useState、useEffect的使用方法，加深理解。

5. 大型项目架构设计场景

大型项目的架构设计需要经过多次讨论与修改，每一次的决策过程都需要被记录下来。Claude-Mem可以存储架构设计的每一个版本、讨论的关键点、修改的原因，当开发者需要调整架构时，通过引用历史记忆中的决策记录，就能确保架构设计的一致性，避免出现前后矛盾的情况。

6. 实验性功能探索场景

对于喜欢尝试新技术的开发者来说，Claude-Mem的测试版通道提供了探索实验性功能的机会。例如，Endless Mode可以支持无限时间跨度的记忆存储，适合开发者进行长期的技术实验，记录每一次的实验过程与结果，为后续的技术研究提供参考。

五、使用方法

Claude-Mem的使用流程非常简单，分为插件安装、功能使用、高级配置三个阶段，全程无需复杂的命令行操作，适合不同技术水平的开发者。

1. 前置条件

在安装Claude-Mem之前，需要确保满足以下前置条件：

• 已安装Claude Code终端或桌面客户端；

• 已安装Node.js 18.0.0或更高版本；

• 网络环境正常，能够访问GitHub仓库。

2. 插件安装步骤

Claude-Mem作为Claude Code的插件，支持通过插件市场一键安装，具体步骤如下：

1. 打开Claude Code终端会话：启动Claude Code，进入终端交互界面；

2. 添加插件仓库：在终端中输入以下命令，将Claude-Mem的仓库添加到插件市场：

   > /plugin marketplace add thedotmack/claude-mem

3. 安装插件：输入以下命令，安装Claude-Mem插件：

   > /plugin install claude-mem

4. 重启Claude Code：安装完成后，重启Claude Code客户端，插件即可生效。

重启后，Claude-Mem会自动初始化数据库、注入钩子脚本，开发者无需进行额外配置，即可开始使用记忆持久化功能。

3. 核心功能使用方法

（1）自动记忆持久化与注入

插件生效后，所有会话内容都会被自动捕获并存储，无需手动操作。当开发者开启新会话时，工具会自动检索相关记忆，并渐进式注入到上下文窗口中。开发者可以直接在新会话中，继续之前的话题，例如：

上一次我们讨论的XX函数的优化方案，现在可以具体实现了吗？

Claude Code会基于历史记忆，给出对应的回答。

（2）调用mem-search技能检索记忆

当需要主动检索历史记忆时，可以在终端中输入以下指令，调用mem-search技能：

> /skill mem-search [检索关键词]

例如，检索与“用户登录功能”相关的记忆：

> /skill mem-search 用户登录功能

工具会返回所有相关的记忆片段，并标注记忆的捕获时间与会话ID。

（3）访问Web查看器管理记忆

启动Claude Code后，Claude-Mem会自动启动Web服务，开发者只需在浏览器中输入http://localhost:37777，即可进入Web查看器界面。在界面中，开发者可以：

• 查看所有记忆片段的列表，包括内容摘要、捕获时间、令牌消耗；

• 通过关键词筛选记忆片段；

• 删除不需要的记忆内容；

• 查看记忆的详细信息。

（4）使用隐私标签保护敏感信息

在会话中，将敏感内容包裹在<private>标签内，即可避免该内容被存储。例如：

这个项目的API密钥是1234567890abcdef，请帮我实现接口调用功能。

工具会自动跳过<private>标签内的内容，不会将其持久化到数据库中。

（5）切换测试版通道体验实验性功能

若需要体验实验性功能（如Endless Mode），可以在终端中输入以下命令，切换到测试版通道：

> /plugin config claude-mem channel beta

切换后重启Claude Code，即可启用实验性功能。若需要切回稳定版，输入以下命令：

> /plugin config claude-mem channel stable

4. 高级配置（可选）

对于有个性化需求的开发者，可以通过修改Claude-Mem的配置文件，调整记忆注入的范围、优先级等参数。配置文件的路径为：

~/.claude/plugins/claude-mem/config.json

常见的配置项包括：

• maxMemoryCount：最大记忆存储数量，默认值为100；

• tokenLimit：单次记忆注入的最大令牌数，默认值为2000；

• searchMode：默认搜索模式，可选值为fulltext（全文搜索）、vector（向量搜索）、hybrid（混合搜索）。

修改配置文件后，重启Claude Code即可生效。

六、常见问题解答（FAQ）

1. Claude-Mem支持Claude Code的所有版本吗？

答：Claude-Mem基于Claude Agent SDK开发，支持所有兼容该SDK的Claude Code版本，包括终端版与桌面版。若遇到兼容性问题，建议将Claude Code升级到最新版本。

2. 记忆数据存储在本地还是云端？

答：所有记忆数据均存储在本地的SQLite与Chroma数据库中，工具不会将数据上传到云端，开发者无需担心数据泄露问题。

3. 如何清理不需要的记忆内容？

答：有两种清理方式：一是通过Web查看器界面，手动删除指定的记忆片段；二是删除本地数据库文件，路径为~/.claude/plugins/claude-mem/data，删除后所有记忆内容将被清空。

4. 为什么有时候记忆注入会失败？

答：记忆注入失败可能有以下原因：① 会话的令牌窗口已满，无法注入新内容；② 检索不到与当前会话相关的记忆；③ 插件未正确安装或启动。可以通过查看Web查看器的日志，排查具体原因。

5. Claude-Mem会影响Claude Code的运行速度吗？

答：不会。Claude-Mem的钩子脚本与工作服务均采用轻量化设计，对系统资源的占用极低，不会影响Claude Code的正常运行速度。

6. 可以在团队中共享记忆数据吗？

答：Claude-Mem的记忆数据默认存储在本地，若需要团队共享，可以将数据库文件（~/.claude/plugins/claude-mem/data）共享给团队成员，成员将文件放入对应的目录，即可加载共享的记忆内容。

7. 插件支持自定义钩子脚本吗？

答：支持。Claude-Mem的钩子架构采用模块化设计，开发者可以在~/.claude/plugins/claude-mem/hooks目录下，新增自定义钩子脚本，实现个性化的记忆捕获与处理功能。

七、相关链接

1. GitHub仓库地址：https://github.com/thedotmack/claude-mem

2. Claude Agent SDK文档：https://docs.anthropic.com/claude/docs/agent-sdk

八、总结

Claude-Mem是一款专为Claude Code打造的开源持久化记忆压缩系统，它通过创新的钩子架构、混合搜索技术与轻量化存储方案，完美解决了AI代码助手跨会话上下文丢失的核心痛点，实现了会话记忆的自动捕获、持久化存储、精准检索与渐进式注入。该工具不仅提供了开箱即用的功能体验，还支持隐私控制、Web可视化、技能扩展等个性化功能，同时兼顾了令牌成本控制与数据安全，适用于个人长期开发、团队协作、代码调试、技术学习等多种场景。作为一款遵循AGPL 3.0协议的开源工具，Claude-Mem的代码开源透明，支持开发者根据需求进行二次开发与功能扩展，为提升Claude Code的使用效率与开发体验提供了强有力的支持，是广大开发者不可或缺的Claude Code辅助工具。