Folder Context Files

Overview

Claude-mem automatically generates CLAUDE.md files in your project folders to provide Claude with directory-level context. These files contain a summary of recent activity in each folder, helping Claude understand what work has been done and where.

How It Works

When you work with Claude Code in a project, claude-mem tracks which files are read and modified. After each observation is saved, it automatically:

1. Identifies unique folder paths from touched files
2. Queries recent observations relevant to each folder
3. Generates a formatted timeline of activity
4. Writes it to CLAUDE.md in that folder (inside <claude-mem-context> tags)

What Gets Generated

Each folder's CLAUDE.md contains a "Recent Activity" section showing:

• Observation IDs for reference
• Timestamps of when work occurred
• Type indicators (bug fixes, features, discoveries, etc.)
• Brief titles describing the work
• Estimated token counts

<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>

User Content Preservation

The auto-generated content is wrapped in <claude-mem-context> tags. Any content you write outside these tags is preserved when the file is regenerated. This means you can:

• Add your own documentation above or below the generated section
• Write folder-specific instructions for Claude
• Include architectural notes or conventions

# 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

Project Root Exclusion

The project root (folders containing a .git directory) is excluded from auto-generation. This is intentional:

• Root CLAUDE.md files typically contain project-wide instructions you've written manually
• Auto-generating at the root could overwrite important project documentation
• Subfolders are where folder-level context is most useful

Configuration

Enabling the Feature

To enable folder CLAUDE.md generation, edit your settings file:

1. Open ~/.claude-mem/settings.json

2. Add or update this setting:

{
  "CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED": "true"
}

3. Save the file - changes take effect immediately (no restart needed)

Cleanup Mode

The regenerate script includes a --clean mode for removing auto-generated content:

# 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

What cleanup does:

1. Finds all CLAUDE.md files recursively
2. Strips <claude-mem-context>...</claude-mem-context> sections
3. Deletes files that become empty after stripping
4. Preserves files that have user content outside the tags

This is useful for:

• Preparing a branch for PR (removing generated files)
• Resetting folder context to start fresh
• Removing context before sharing code

Git Integration

Should You Commit These Files?

This is your choice based on your workflow. Here are the trade-offs:

**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

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

Gitignore Pattern

To exclude folder CLAUDE.md files from git:

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

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

Or to ignore all CLAUDE.md files everywhere:

**/CLAUDE.md

Recommended Workflows

For Solo Developers:

• Keep them local (gitignore) for personal context
• Or commit them if you work across multiple machines

For Teams:

• Discuss with your team which approach works best
• Consider committing them if onboarding is frequent
• Use --clean before PRs if you prefer clean diffs

Before Merging PRs:

# 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"

Regenerating Context

To manually regenerate all folder CLAUDE.md files from the database:

# 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

This is useful after:

• Importing observations from another machine
• Database recovery
• Wanting to refresh all folder context

Worktree Support

New in v9.0: Claude-mem now supports git worktrees with unified context.

When you're working in a git worktree, context is automatically gathered from both:

• The parent repository (where the worktree was created)
• The worktree directory itself

This means observations about shared code are visible regardless of which worktree you're in, giving you a complete picture of recent activity across all related directories.

How It Works

1. When generating context, claude-mem detects if your project is a worktree
2. It identifies the parent repository automatically
3. Timeline queries include both locations
4. Results are interleaved chronologically

Technical Details

File Format

Generated content uses a consistent markdown table format:

Type Indicators

Atomic Writes

Files are written atomically using a temp file + rename pattern. This prevents partial writes if the process is interrupted.

Performance

• Updates happen asynchronously (fire-and-forget)
• Failures are logged but don't block the main workflow
• Only folders with actual file activity are updated
• Deduplication prevents redundant updates for the same folder