文件夹上下文文件

概述¶

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

工作原理¶

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

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

生成的内容¶

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

• 供参考的观察 ID
• 工作发生的时间戳
• 类型指示符（错误修复、功能、发现等）
• 描述工作的简短标题
• 估算的 Token 数量

<claude-mem-context>
# Recent Activity

### 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 编写针对特定文件夹的指令
• 包含架构说明或约定

# 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 文件通常包含你手动编写的项目级指令
• 在根目录自动生成可能会覆盖重要的项目文档
• 子文件夹才是文件夹级上下文最有用的地方

配置¶

启用该功能¶

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

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

2. 添加或更新此设置：

{
  "CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED": "true"
}

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

清理模式¶

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

# 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. 保留在标签之外有用户内容的文件

这在以下场景中很有用： - 为 PR 准备分支（移除生成的文件） - 重置文件夹上下文以重新开始 - 在共享代码之前移除上下文

Git 集成¶

应该提交这些文件吗？¶

这是你的选择，取决于你的工作流程。以下是利弊权衡：

Gitignore 模式¶

要从 Git 中排除文件夹 CLAUDE.md 文件：

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

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

或者忽略所有位置的 CLAUDE.md 文件：

**/CLAUDE.md

推荐的工作流程¶

对于独立开发者： - 将其保留在本地（gitignore）以获取个人上下文 - 或者如果你在多台机器上工作，则提交它们

对于团队： - 与你的团队讨论哪种方法最有效 - 如果入职频繁，请考虑提交它们 - 如果你更喜欢干净的差异，请在 PR 之前使用 --clean

在合并 PR 之前：

# 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 文件：

# 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

以下情况很有用： - 从另一台机器导入观察结果 - 数据库恢复 - 希望刷新所有文件夹上下文

Worktree 支持¶

v9.0 新增：claude-mem 现在支持具有统一上下文的 git worktree。

当你在 git worktree 中工作时，会自动从以下两个位置收集上下文： - 父仓库（创建 worktree 的位置） - worktree 目录本身

这意味着，无论你位于哪个 worktree，关于共享代码的观察结果都是可见的，让你全面了解所有相关目录中的近期活动。

工作原理¶

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

技术细节¶

文件格式¶

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

类型指示器¶

原子写入¶

文件通过临时文件 + 重命名模式进行原子写入。这可以防止进程中断时出现部分写入。

性能¶

• 更新异步执行（即发即忘）
• 失败会被记录，但不会阻塞主工作流
• 仅更新有实际文件活动的文件夹
• 去重可防止同一文件夹的冗余更新