> ## Documentation Index
> Fetch the complete documentation index at: https://docs.claude-mem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Folder Context Files

> 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 theme={null}
<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 theme={null}
# 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 theme={null}
{
  "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 theme={null}
# 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 theme={null}
# 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 theme={null}
**/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 theme={null}
# 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 theme={null}
# 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