claude-mem 中文文档

Appearance

概览 ​

Claude-mem 会在您的项目文件夹中自动生成 CLAUDE.md 文件，以便为 Claude 提供目录级的上下文。这些文件包含每个文件夹中最近活动的摘要，帮助 Claude 了解已完成的工作及其位置。

此功能默认禁用。如果您希望自动生成文件夹级别的上下文，请通过设置启用它。

运作方式 ​

当你在一个项目中使用 Claude Code 时，claude-mem 会跟踪哪些文件被读取和修改。在每次观察保存后，它会自动：

  1. 从被触碰的文件中识别唯一的文件夹路径
  2. 查询与每个文件夹相关的近期观察
  3. 生成格式化的活动时间表
  4. 将其写入该文件夹中的 CLAUDE.md（位于 <claude-mem-context> 标签内）

生成的内容 ​

每个文件夹的 CLAUDE.md 包含一个“最近活动”部分，显示：

  • 用于参考的观察ID
  • 工作发生的时间戳
  • 类型指示器（错误修复、功能、发现等）
  • 描述工作的简短标题
  • 估计的token数量
markdown
<claude-mem-context>
# Recent Activity

<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->

### Jan 4, 2026

| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #1234 | 4:30 PM | 🔵 | Implemented user authentication | ~250 |
| #1235 | " | 🔴 | Fixed login redirect bug | ~180 |
</claude-mem-context>

用户内容保留 ​

自动生成的内容被包裹在 <claude-mem-context> 标签中。你在这些标签之外写的任何内容在文件重新生成时都会被保留。这意味着你可以：

  • 在生成的部分上方或下方添加你自己的文档
  • 为 Claude 撰写针对特定文件夹的说明
  • 包括建筑说明或惯例
markdown
# Authentication Module

This folder contains all authentication-related code.
Follow the established patterns for new auth providers.

<claude-mem-context>
... auto-generated content ...
</claude-mem-context>

## Manual Notes

- OAuth providers go in /providers/
- Session handling uses Redis

项目根目录排除 ​

项目根目录（包含 .git 目录的文件夹）不包含在自动生成中。这是故意的：

  • 根 CLAUDE.md 文件通常包含你手动编写的项目范围指令
  • 在根目录自动生成可能会覆盖重要的项目文档
  • 子文件夹是文件夹级上下文最有用的地方

Git 子模块（具有 .git 文件 而不是目录）能够被正确检测并且不会被排除，因此它们会接收自动生成的上下文。

配置 ​

启用该功能 ​

要启用文件夹 CLAUDE.md 的生成，请编辑您的设置文件：

1. 打开 ~/.claude-mem/settings.json

2. 添加或更新此设置：

json
{
  "CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED": "true"
}

3. 保存文件 - 更改会立即生效（无需重启）

值行为
"false"（默认）文件夹 CLAUDE.md 生成已禁用
"true"自动生成文件夹 CLAUDE.md 文件

如果设置文件不存在，只创建包含你想更改的设置的文件。Claude-mem 会对任何缺失的设置使用默认值。

清理模式 ​

再生脚本包含一个 --clean 模式，用于删除自动生成的内容：

bash
# Preview what would be cleaned (dry run)
bun scripts/regenerate-claude-md.ts --clean --dry-run

# Actually clean files
bun scripts/regenerate-claude-md.ts --clean

清理的作用:

  1. 递归查找所有 CLAUDE.md 文件
  2. 剥离 <claude-mem-context>...</claude-mem-context> 段
  3. 删除在剥离后变为空的文件
  4. 保留 标签外有用户内容的文件

这对于以下情况很有用：

  • 为拉取请求准备分支（移除生成的文件）
  • 正在重置文件夹上下文以重新开始
  • 在共享代码之前删除上下文

Git 集成 ​

你应该提交这些文件吗？ ​

这是根据你的工作流程你的选择。以下是权衡利弊：

**Pros:**
- Team members see folder-level context and recent activity
- New contributors can understand what happened where
- Code reviewers get additional context about changes
- Historical record of work patterns in the repo

**Cons:**
- Adds files to your repository
- Files change frequently during development
- May create noise in diffs and commit history
- Different team members may generate different content


**Pros:**
- Clean repository without generated files
- No commit noise from auto-generated content
- Each developer has their own local context
- Simpler git history

**Cons:**
- Team doesn't share folder context
- Context is lost when switching machines
- New team members don't benefit from existing context

Git 忽略模式 ​

要从 git 中排除 CLAUDE.md 文件夹:

gitignore
# Ignore auto-generated folder context files
**/CLAUDE.md

# But keep the root CLAUDE.md if you want
!CLAUDE.md

或者忽略所有地方的 CLAUDE.md 文件：

gitignore
**/CLAUDE.md

推荐工作流程 ​

适合独立开发者：

  • 保持本地（gitignore）以用于个人上下文
  • 或者如果你在多台机器上工作，就提交它们

适用于团队：

  • 与你的团队讨论哪种方法最有效
  • 如果入职频繁，考虑提交它们
  • 如果你希望差异清晰，请在 PR 之前使用 --clean

在合并拉取请求之前：

bash
# Clean up generated files before merge
bun scripts/regenerate-claude-md.ts --clean
git add -A
git commit -m "chore: clean up generated CLAUDE.md files"

重新生成上下文 ​

要从数据库手动重新生成所有文件夹的 CLAUDE.md 文件：

bash
# Preview what would be regenerated
bun scripts/regenerate-claude-md.ts --dry-run

# Regenerate all folders
bun scripts/regenerate-claude-md.ts

# Regenerate for a specific project only
bun scripts/regenerate-claude-md.ts --project=my-project

这在以下情况下很有用：

  • 从另一台机器导入观测数据
  • 数据库恢复
  • 想要刷新所有文件夹的上下文

工作树支持 ​

v9.0 新功能：Claude-mem 现在支持带有统一上下文的 git 工作树。

当你在 git worktree 中工作时，上下文会自动从两者收集：

  • 父仓库（工作树创建的地方）
  • 工作树目录本身

这意味着对共享代码的观察是可见的，无论你在哪个工作树中，都能让你全面了解所有相关目录的最近活动情况。

运作方式 ​

  1. 在生成上下文时，claude-mem 会检测你的项目是否是工作树
  2. 它会自动识别父仓库
  3. 时间线查询包括两个位置
  4. 结果按时间顺序交错排列

无需配置——工作树检测是自动的。如果你不使用工作树，这个功能不会有任何效果。

技术细节 ​

文件格式 ​

生成的内容使用一致的 Markdown 表格格式：

列描述
ID观测 ID（例如，#1234）或会话 ID（#S123）
时间12小时制，带AM/PM，重复时间使用引号(")
T类型表情符号指示器
标题观察的简要描述
阅读预计标记数（例如，~250）

类型指示器 ​

表情符号类型
🔴修复漏洞
🟣功能
🔄重构
✅变化
🔵发现
⚖️决策
🎯会话
💬提示

原子写入 ​

文件使用临时文件 + 重命名模式进行原子写入。如果进程被中断，这可以防止部分写入。

性能 ​

  • 更新是异步发生的（即发即忘）
  • 失败会被记录，但不会阻塞主要工作流程
  • 只有有实际文件活动的文件夹会被更新
  • 去重可以防止对同一文件夹的重复更新