thedotmack--claude-mem/docs/public/usage/folder-context.mdx

---
title: "Folder Context Files"
description: "Automatic per-folder CLAUDE.md files that provide directory-level context to Claude"
---

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

<Info>
This feature is **disabled by default**. Enable it via settings if you want automatic folder-level context generation.
</Info>

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

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

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

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

<Note>
Git submodules (which have a `.git` *file* instead of directory) are correctly detected and **not** excluded, so they receive auto-generated context.
</Note>

## 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:**
```json
{
  "CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED": "true"
}
```

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

| Value | Behavior |
|-------|----------|
| `"false"` (default) | Folder CLAUDE.md generation disabled |
| `"true"` | Auto-generate folder CLAUDE.md files |

<Tip>
If the settings file doesn't exist, create it with just the settings you want to change. Claude-mem will use defaults for any missing settings.
</Tip>

## Cleanup Mode

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

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

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

<Tabs>
  <Tab title="Commit Them">
    **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
  </Tab>
  <Tab title="Gitignore Them">
    **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
  </Tab>
</Tabs>

### Gitignore Pattern

To exclude folder CLAUDE.md files from git:

```gitignore
# 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:
```gitignore
**/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:**
```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"
```

## Regenerating Context

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

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

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

<Note>
No configuration needed - worktree detection is automatic. If you're not using worktrees, this feature has no effect.
</Note>

## Technical Details

### File Format

Generated content uses a consistent markdown table format:

| Column | Description |
|--------|-------------|
| ID | Observation ID (e.g., `#1234`) or session ID (`#S123`) |
| Time | 12-hour format with AM/PM, ditto marks (`"`) for repeated times |
| T | Type emoji indicator |
| Title | Brief description of the observation |
| Read | Estimated token count (e.g., `~250`) |

### Type Indicators

| Emoji | Type |
|-------|------|
| 🔴 | Bug fix |
| 🟣 | Feature |
| 🔄 | Refactor |
| ✅ | Change |
| 🔵 | Discovery |
| ⚖️ | Decision |
| 🎯 | Session |
| 💬 | Prompt |

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