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

# Folder context files

> Auto-generated CLAUDE.md files that give Claude directory-level awareness of recent activity in each project folder.

Claude Mem can automatically generate `CLAUDE.md` files in your project folders. Each file contains a timeline of recent activity in that directory, giving Claude immediate awareness of what work has been done and where — without needing to search for it.

<Info>
  This feature is **disabled by default**. Enable it in `~/.claude-mem/settings.json`.
</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 the touched files
2. Queries recent observations relevant to each folder
3. Generates a formatted activity timeline
4. Writes it to `CLAUDE.md` in that folder, inside `<claude-mem-context>` tags

Files are written atomically using a temp file and rename pattern, so partial writes cannot occur if the process is interrupted. Updates happen asynchronously and do not block the main workflow.

## What gets generated

Each folder's `CLAUDE.md` contains a "Recent Activity" section with a markdown table:

```markdown theme={null}
<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>
```

### Table column reference

| Column    | Description                                                      |
| --------- | ---------------------------------------------------------------- |
| **ID**    | Observation ID (e.g. `#1234`) or session ID (e.g. `#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 to read the full observation (e.g. `~250`) |

### Type indicators

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

## Preserving your own content

The auto-generated section is wrapped in `<claude-mem-context>` tags. **Any content you write outside these tags is preserved** when the file is regenerated.

```markdown theme={null}
# Authentication module

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

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

## Manual notes

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

You can add folder-specific instructions for Claude, architectural notes, or naming conventions — they will never be overwritten.

## Project root exclusion

The **project root** (folders containing a `.git` directory) is **excluded** from auto-generation. Root `CLAUDE.md` files typically contain project-wide instructions you've written manually, and auto-generating at the root risks overwriting important documentation.

Subfolders are where folder-level context is most useful.

<Note>
  Git submodules — which have a `.git` *file* rather than a directory — are correctly detected and are **not** excluded. They receive auto-generated context like any other subfolder.
</Note>

## Enabling the feature

<Steps>
  <Step title="Open your settings file">
    Edit `~/.claude-mem/settings.json`. The file is created automatically on first run.
  </Step>

  <Step title="Add the setting">
    ```json theme={null}
    {
      "CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED": "true"
    }
    ```
  </Step>

  <Step title="Save the file">
    Changes take effect immediately — no worker restart needed.
  </Step>
</Steps>

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

<Tip>
  If the settings file doesn't exist yet, create it with only the settings you want to change. Claude Mem uses defaults for any missing settings.
</Tip>

## Manually regenerating context

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

```bash theme={null}
# Preview what would be regenerated (dry run)
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, recovering from a database issue, or wanting to refresh all folder context from scratch.

## Cleaning up generated files

The regenerate script includes a `--clean` mode to strip auto-generated content:

```bash theme={null}
# Preview what would be cleaned (dry run)
bun scripts/regenerate-claude-md.ts --clean --dry-run

# Remove auto-generated sections from all CLAUDE.md files
bun scripts/regenerate-claude-md.ts --clean
```

Cleanup behavior:

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 content outside the generated tags

This is useful for preparing a clean branch before opening a PR, resetting folder context, or removing generated files before sharing code.

## Git integration

Whether to commit these files is your choice. Consider 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 recent changes
    * Creates a historical record of work patterns in the repo

    **Cons:**

    * Adds frequently-changing files to your repository
    * Can 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 members don't share folder context
    * Context is lost when switching machines
    * New contributors don't benefit from existing context
  </Tab>
</Tabs>

### Gitignore patterns

To exclude subfolder `CLAUDE.md` files while keeping your root file:

```gitignore theme={null}
# Ignore auto-generated folder context files
**/CLAUDE.md

# Keep the root CLAUDE.md
!CLAUDE.md
```

To ignore all `CLAUDE.md` files everywhere:

```gitignore theme={null}
**/CLAUDE.md
```

### Recommended workflows

**Solo developers:** Keep files local (gitignore) for personal context, or commit them if you work across multiple machines.

**Teams:** Discuss which approach works for your workflow. Committing is most valuable when onboarding is frequent.

**Before merging PRs:** Use cleanup to remove generated files from the diff:

```bash theme={null}
bun scripts/regenerate-claude-md.ts --clean
git add -A
git commit -m "chore: remove generated CLAUDE.md files"
```

## Worktree support

When you're working in a git worktree, context is automatically gathered from both the parent repository and the worktree directory. Observations about shared code remain visible regardless of which worktree you're in.

Claude Mem detects worktrees automatically. No configuration is needed, and the feature has no effect if you're not using worktrees.

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration">
    All settings including folder context options
  </Card>

  <Card title="Export and import" icon="arrow-right-arrow-left" href="/usage/export-import">
    Move memory data between machines
  </Card>
</CardGroup>