claude-mem/README.zh.md at 25684ea8f7bccac1866864d596605d415531a3ed

Files

T

Alex Newman 25684ea8f7 Add Chinese translation for README and implement README translation script

- Created README.zh.md for Chinese localization of the project.
- Developed a README translation script to support multiple languages using Claude Agent SDK.
- Implemented CLI and programmatic usage for the translation tool.
- Added examples for integrating the translation tool into build scripts and CI/CD pipelines.
- Enhanced error handling and logging for translation processes.
- Included support for various languages and output customization options.

2025-12-12 00:58:36 -05:00

16 KiB

Raw Blame History

为 Claude Code 构建的持久化内存压缩系统。

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

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

快速开始

在终端中启动新的 Claude Code 会话并输入以下命令:

> /plugin marketplace add thedotmack/claude-mem

> /plugin install claude-mem

重启 Claude Code。之前会话的上下文将自动出现在新会话中。

核心功能:

🧠 持久化内存 - 上下文在会话间保持
📊 渐进式披露 - 分层内存检索,可见令牌成本
🔍 基于技能的搜索 - 使用 mem-search 技能查询项目历史(节省约 2,250 个令牌)
🖥️ Web 查看器界面 - 在 http://localhost:37777 实时查看内存流
💻 Claude Desktop 技能 - 从 Claude Desktop 对话中搜索内存
🔒 隐私控制 - 使用 <private> 标签排除敏感内容存储
⚙️ 上下文配置 - 精细控制注入的上下文内容
🤖 自动运行 - 无需手动干预
🔗 引用 - 使用 claude-mem:// URI 引用过去的决策
🧪 Beta 频道 - 通过版本切换尝试实验性功能,如无尽模式

文档

📚 查看完整文档 - 在 GitHub 上浏览 markdown 文档

💻 本地预览: 在本地运行 Mintlify 文档:

cd docs
npx mintlify dev

入门指南

安装指南 - 快速开始与高级安装
使用指南 - Claude-Mem 如何自动工作
搜索工具 - 使用自然语言查询项目历史
Beta 功能 - 尝试实验性功能,如无尽模式

最佳实践

上下文工程 - AI 代理上下文优化原则
渐进式披露 - Claude-Mem 上下文预备策略背后的哲学

架构

概述 - 系统组件与数据流
架构演进 - 从 v3 到 v5 的发展历程
钩子架构 - Claude-Mem 如何使用生命周期钩子
钩子参考 - 7 个钩子脚本详解
Worker 服务 - HTTP API 与 PM2 管理
数据库 - SQLite 架构与 FTS5 搜索
搜索架构 - 使用 Chroma 向量数据库的混合搜索

配置与开发

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

工作原理

┌─────────────────────────────────────────────────────────────┐
│ 会话开始 → 注入最近的观察作为上下文                         │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 用户提示 → 创建会话,保存用户提示                            │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 工具执行 → 捕获观察(Read、Write 等)                         │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ Worker 处理 → 通过 Claude Agent SDK 提取学习内容            │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 会话结束 → 生成摘要,为下一个会话做好准备                    │
└─────────────────────────────────────────────────────────────┘

核心组件:

5 个生命周期钩子 - SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd(6 个钩子脚本)
智能安装 - 缓存依赖检查器(预钩子脚本,非生命周期钩子)
Worker 服务 - 端口 37777 上的 HTTP API,带有 Web 查看器界面和 10 个搜索端点,由 PM2 管理
SQLite 数据库 - 存储会话、观察、摘要,支持 FTS5 全文搜索
mem-search 技能 - 自然语言查询,支持渐进式披露(相比 MCP 节省约 2,250 个令牌)
Chroma 向量数据库 - 混合语义 + 关键词搜索,实现智能上下文检索

详见架构概述。

mem-search 技能

Claude-Mem 通过 mem-search 技能提供智能搜索,当您询问过去的工作时会自动调用:

工作原理:

只需自然提问:"上个会话我们做了什么?" 或 "我们之前修复过这个 bug 吗?"
Claude 自动调用 mem-search 技能查找相关上下文
相比 MCP 方法,每次会话开始节省约 2,250 个令牌

可用搜索操作:

搜索观察 - 跨观察的全文搜索
搜索会话 - 跨会话摘要的全文搜索
搜索提示 - 搜索原始用户请求
按概念搜索 - 按概念标签查找(discovery、problem-solution、pattern 等)
按文件搜索 - 查找引用特定文件的观察
按类型搜索 - 按类型查找(decision、bugfix、feature、refactor、discovery、change)
最近上下文 - 获取项目的最近会话上下文
时间线 - 获取特定时间点周围的统一上下文时间线
按查询的时间线 - 搜索观察并获取最佳匹配周围的时间线上下文
API 帮助 - 获取搜索 API 文档

自然语言查询示例:

"上个会话我们修复了哪些 bug?"
"我们是如何实现身份验证的?"
"对 worker-service.ts 做了哪些更改?"
"显示这个项目的最近工作"
"添加查看器界面时发生了什么?"

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

Beta 功能与无尽模式

Claude-Mem 提供带有实验性功能的 beta 频道。直接从 Web 查看器界面在稳定版和 beta 版之间切换。

如何尝试 Beta

打开 http://localhost:37777
点击设置(齿轮图标)
在 版本频道 中,点击 "Try Beta (Endless Mode)"
等待 worker 重启

切换版本时您的内存数据会被保留。

无尽模式(Beta)

旗舰 beta 功能是 无尽模式 - 一种仿生内存架构,可显著延长会话时长:

问题: 标准 Claude Code 会话在约 50 次工具使用后达到上下文限制。每个工具添加 1-10k+ 令牌,Claude 在每次响应时都会重新合成所有先前的输出(O(N²) 复杂度)。

解决方案: 无尽模式将工具输出压缩为约 500 令牌的观察,并实时转换记录:

工作内存(上下文):     压缩的观察(每个约 500 令牌)
归档内存(磁盘):       保留完整工具输出供调用

预期结果:

上下文窗口中约 95% 的令牌减少
在上下文耗尽前约 20 倍的工具使用次数
线性 O(N) 扩展而非二次 O(N²)
保留完整记录以实现完美回忆

注意事项: 增加延迟(每个工具 60-90 秒用于生成观察),仍处于实验阶段。

详见Beta 功能文档。

新功能

v6.4.9 - 上下文配置设置:

11 个新设置,用于精细控制上下文注入
配置令牌经济性显示、按类型/概念过滤观察
控制观察数量和要显示的字段

v6.4.0 - 双标签隐私系统:

<private> 标签用于用户控制的隐私 - 包裹敏感内容以排除存储
系统级 <claude-mem-context> 标签防止递归观察存储
边缘处理确保私密内容永不到达数据库

v6.3.0 - 版本频道:

从 Web 查看器界面在稳定版和 beta 版之间切换
无需手动 git 操作即可尝试实验性功能,如无尽模式

先前亮点:

v6.0.0: 重大会话管理与记录处理改进
v5.5.0: mem-search 技能增强,100% 有效率
v5.4.0: 基于技能的搜索架构(每次会话节省约 2,250 令牌)
v5.1.0: 基于 Web 的查看器界面,实时更新
v5.0.0: 使用 Chroma 向量数据库的混合搜索

完整版本历史见 CHANGELOG.md。

系统要求

Node.js: 18.0.0 或更高版本
Claude Code: 支持插件的最新版本
PM2: 进程管理器(已捆绑 - 无需全局安装)
SQLite 3: 用于持久化存储(已捆绑)

核心优势

渐进式披露上下文

分层内存检索镜像人类内存模式
第 1 层(索引): 在会话开始时查看存在哪些观察及其令牌成本
第 2 层(详情): 通过 MCP 搜索按需获取完整叙述
第 3 层(完美回忆): 访问源代码和原始记录
智能决策: 令牌计数帮助 Claude 在获取详情或读取代码之间做出选择
类型指示器: 视觉提示(🔴 关键、🟤 决策、🔵 信息)突出显示观察重要性

自动内存

Claude 启动时自动注入上下文
无需手动命令或配置
在后台透明工作

完整历史搜索

跨所有会话和观察搜索
FTS5 全文搜索实现快速查询
引用链接回特定观察

结构化观察

AI 驱动的学习内容提取
按类型分类(decision、bugfix、feature 等)
标记概念和文件引用

多提示会话

会话跨越多个用户提示
上下文在 /clear 命令间保留
跟踪整个对话线程

配置

设置在 ~/.claude-mem/settings.json 中管理。文件在首次运行时自动创建,包含默认值。

可用设置:

设置	默认值	描述
`CLAUDE_MEM_MODEL`	`claude-haiku-4-5`	用于观察的 AI 模型
`CLAUDE_MEM_WORKER_PORT`	`37777`	Worker 服务端口
`CLAUDE_MEM_DATA_DIR`	`~/.claude-mem`	数据目录位置
`CLAUDE_MEM_LOG_LEVEL`	`INFO`	日志详细程度(DEBUG、INFO、WARN、ERROR、SILENT)
`CLAUDE_MEM_PYTHON_VERSION`	`3.13`	chroma-mcp 的 Python 版本
`CLAUDE_CODE_PATH`	(自动检测)	Claude 可执行文件路径
`CLAUDE_MEM_CONTEXT_OBSERVATIONS`	`50`	SessionStart 时注入的观察数量

设置管理:

# 通过 CLI 助手编辑设置
./claude-mem-settings.sh

# 或直接编辑
nano ~/.claude-mem/settings.json

# 查看当前设置
curl http://localhost:37777/api/settings

设置文件格式:

{
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5",
  "CLAUDE_MEM_WORKER_PORT": "37777",
  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "50"
}

详见配置指南。

开发

# 克隆并构建
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
npm install
npm run build

# 运行测试
npm test

# 启动 worker
npm run worker:start

# 查看日志
npm run worker:logs

详细说明见开发指南。

故障排除

快速诊断:

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

常见问题:

Worker 无法启动 → npm run worker:restart
没有上下文出现 → npm run test:context
数据库问题 → sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
搜索不工作 → 检查 FTS5 表是否存在

完整解决方案见故障排除指南。

贡献

欢迎贡献!请:

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

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

许可证

本项目采用 GNU Affero 通用公共许可证 v3.0 (AGPL-3.0) 授权。

完整详情见 LICENSE 文件。

这意味着什么:

您可以自由使用、修改和分发本软件
如果您修改并部署在网络服务器上,必须提供源代码
衍生作品也必须采用 AGPL-3.0 许可
本软件不提供任何担保

支持

文档: docs/
问题: GitHub Issues
仓库: github.com/thedotmack/claude-mem
作者: Alex Newman (@thedotmack)

使用 Claude Agent SDK 构建 | 由 Claude Code 驱动 | 使用 TypeScript 制作

16 KiB Raw Blame History