Skip to main content

​
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.
This feature is disabled by default. Enable it via settings if you want automatic folder-level context generation.

​
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

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

​
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
Git submodules (which have a .git file instead of directory) are correctly detected and not excluded, so they receive auto-generated context.

​
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)
ValueBehavior
"false" (default)Folder CLAUDE.md generation disabled
"true"Auto-generate folder CLAUDE.md files
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.

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

​
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
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
No configuration needed - worktree detection is automatic. If you’re not using worktrees, this feature has no effect.

​
Technical Details

​
File Format

Generated content uses a consistent markdown table format:
ColumnDescription
IDObservation ID (e.g., #1234) or session ID (#S123)
Time12-hour format with AM/PM, ditto marks (") for repeated times
TType emoji indicator
TitleBrief description of the observation
ReadEstimated token count (e.g., ~250)

​
Type Indicators

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