Feature Request: Proactive, Self-Improving `CLAUDE.md` Based on Session Activity

Title: Feature Request: Proactive, Self-Improving CLAUDE.md Based on Session Activity

Labels: enhancement, feature-request, agent-behavior, memory

Is your feature request related to a problem? Please describe.

The CLAUDE.md memory system is a powerful feature for providing persistent, project-specific context to the agent. However, its effectiveness depends entirely on manual curation by the user. The current methods (/memory, the # shortcut) are reactive and require the user to recognize that a piece of information is valuable, know what kind of information is most effective, and remember to add it.

This creates several problems:

• Cognitive Load: It places the entire burden of maintaining and optimizing the agent's context on the user.
• Learning Curve: New users or teams may not know how to build an effective memory file, leading to a suboptimal experience and a slower onboarding process.
• Stale Context: As projects and team conventions evolve, manually maintained CLAUDE.md files can easily become outdated.

A truly agentic coding assistant should not only consume context but also actively help build and refine it over time, making it more of a proactive partner than a passive tool.

Describe the solution you'd like

I propose a feature where Claude Code proactively identifies patterns during a session and suggests additions or modifications to the relevant CLAUDE.md file (project or user). When a recurring pattern is detected, Claude would offer a non-intrusive prompt to the user to save this learned knowledge for future sessions.

This could be triggered by several scenarios:

1. Command Repetition:

• Detection: The user or Claude repeatedly executes the same complex or specific shell command (e.g., npm run test:e2e -- --watch --coverage).
• Proactive Suggestion:

> "I've noticed we're using npm run test:e2e -- --watch --coverage frequently. Would you like me to add it as a common command to CLAUDE.md?"

2. Consistent File Access Patterns:

• Detection: When working on a specific feature (e.g., "authentication"), the agent consistently reads or edits the same set of files together (e.g., auth.service.ts, auth.controller.ts, user.model.ts).
• Proactive Suggestion:

> "When working on authentication, it seems we always reference a core set of files. Should I create a 'Core Authentication Files' section in CLAUDE.md with references to them?"
This could leverage the @-mention file import syntax.

3. Correction-Based Learning:

• Detection: The user repeatedly corrects Claude's output on a specific coding style, pattern, or convention.
• Proactive Suggestion:

> "You've corrected me to use named exports instead of default exports multiple times now. To improve my accuracy, should I add 'Always use named exports' to the style guide in CLAUDE.md?"

4. Successful Complex Workflows:

• Detection: After a complex, multi-step task is successfully completed (e.g., creating a new component, adding a Storybook file, and writing tests).
• Proactive Suggestion:

> "We just successfully completed the workflow for creating a new component. Would you like me to document these steps in CLAUDE.md for future reference?"

The user interaction for these suggestions should be simple, such as a [Yes], [No], [Edit], or [Remind me later] prompt, allowing the user to easily accept, reject, or refine the suggestion before it's saved.

Describe alternatives you've considered

The current alternative is the status quo: 100% manual maintenance via direct file editing, /memory, or the # shortcut. While these tools are functional, they are reactive and fail to leverage the agent's unique ability to observe and learn from user interactions. This proposal seeks to augment these existing tools with a proactive, intelligent layer.

Additional context

Implementing this feature would significantly enhance the agentic nature of Claude Code and provide several key benefits:

• Reduces Manual Effort: Lowers the cognitive load on developers to maintain context files.
• Improves Onboarding: Helps new users and teams build a rich, useful CLAUDE.md file organically as they work.
• Dynamic and Adaptive Memory: The context file would evolve naturally alongside the project, ensuring it stays relevant and optimized.
• Surfaces Implicit Knowledge: Automatically captures and documents unwritten team conventions and best practices, making them explicit and discoverable.