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.

This feature is disabled by default. Enable it in ~/.claude-mem/settings.json.

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:

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

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

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.

Enabling the feature

1. Open your settings file

   Edit ~/.claude-mem/settings.json. The file is created automatically on first run.

2. Add the setting

   {
     "CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED": "true"
   }
   
3. Save the file

   Changes take effect immediately — no worker restart needed.

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

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.

Manually regenerating context

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

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

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

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

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

Gitignore patterns

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

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

# Keep the root CLAUDE.md
!CLAUDE.md

To ignore all CLAUDE.md files everywhere:

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

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.

Configuration

All settings including folder context options

Export and import

Move memory data between machines