[FEATURE] Project-Local Conversation History Storage

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Summary

Allow Claude Code to store conversation history within project directories instead of exclusively in the centralized ~/.claude/ directory.

## Related Issues
This addresses #1516 (conversation history lost when moving directories) but proposes a specific architectural approach, hence filed as a separate
issue. This approach provides additional benefits beyond directory portability that #1516 doesn't address.

## Current Behavior

• All conversation histories are stored in ~/.claude/projects/
• Directory names are encoded (e.g., /mypath/my_project/ becomes -mypath-my-project)
• When renaming/moving projects, the ~/.claude/projects/ subdirectory must be manually renamed to maintain /resume functionality

## Proposed Enhancement
Add a configuration option to store conversation history locally within each project directory, such as:

• .claude/history/ within the project root
• Or a .claude-history file/directory

## Benefits

1. Portability: Project history travels with the project when moved/renamed (addressing #1516)
2. Version Control: Teams could optionally commit conversation context
3. Self-Contained Projects: All project-related data stays together
4. Simplified Project Management: No need to manage separate ~/.claude mappings
5. Collaboration: Conversation context can be shared between team members
6. Context Preservation: Important AI interactions can be stored alongside code documentation

## Use Case
Developers working on multiple projects often reorganize directory structures. Having conversation history tied to the project directory would
eliminate the need to manually update ~/.claude/projects/ mappings and make projects more portable across machines. Additionally, teams could
share conversation context through version control, preserving important architectural discussions and decision rationale.

## Backward Compatibility

• Default to current global storage behavior
• Provide migration tool to move existing histories to local storage
• Support both modes simultaneously for gradual migration

Proposed Solution

Suggested Implementation

• Add a setting in ~/.claude/settings.json like "historyStorage": "local" | "global"
• When set to "local", Claude Code would:
• Check for .claude/ or .claude-history in the project root
• Create and use local storage if enabled
• Fall back to global storage if local not available

Alternative Solutions

you could work around this with symlinks:

1. Move conversation to project:

mv ~/.claude/projects/-Users-jsd--vibe-claude-talk /Users/jsd/@vibe/claude/talk/.claude-history

1. Create symlink back:

ln -s /Users/jsd/@vibe/claude/talk/.claude-history ~/.claude/projects/-Users-jsd--vibe-claude-talk

This way the history physically lives in your project but Claude Code can still find it. You'd need to manage these symlinks when moving/renaming projects.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

A team is building a complex authentication system. The lead developer uses Claude Code to architect the initial implementation, discussing security
trade-offs and design decisions.

### Step-by-Step Workflow

1. Initial Development (Week 1)

• Developer A starts in /projects/auth-prototype/
• Has extensive Claude conversation about JWT vs session tokens, discussing security implications
• Claude helps implement OAuth2 flow with detailed explanations about PKCE
• Conversation saved locally in /projects/auth-prototype/.claude/history/

1. Project Reorganization (Week 2)

• Team decides to move project: /projects/auth-prototype/ → /products/identity/auth-service/
• With local storage: Just mv the directory - conversation history moves with it
• Current behavior: Would need to manually rename ~/.claude/projects/-projects-auth-prototype to

~/.claude/projects/-products-identity-auth-service

1. Team Collaboration (Week 3)

• Developer B joins the project, struggles with the OAuth implementation
• Developer A commits .claude/history/ to a feature branch
• Developer B pulls the branch, runs /resume, and can see the entire conversation about why PKCE was chosen, what security concerns were

addressed

• Developer B asks Claude: "Can you explain the PKCE implementation decisions from our previous conversation?"
• Claude has full context and explains the team's specific requirements

1. Production Issue (Month 3)

• Security audit finds a potential issue
• Team runs /resume to review the original security discussion with Claude
• They find Claude had actually warned about this edge case, but it was overlooked
• The conversation history serves as documentation of the design process

1. Knowledge Transfer (Month 6)

• Developer A leaves the company
• New developer C joins
• The .claude/history/ in the repo contains invaluable context about:
• Why certain libraries were chosen over others
• What security vulnerabilities were considered
• What refactoring attempts were made and why they failed
• Developer C can continue conversations with full historical context

### Why This Matters
Without local storage, the conversation history would be lost during the directory move, unavailable to team members, and gone when Developer A's
machine is wiped. With local storage, the AI conversation becomes part of the project's knowledge base, similar to how commit messages and PR
discussions preserve development context.

## Suggested Implementation

• Add a setting in ~/.claude/settings.json like "historyStorage": "local" | "global"
• When set to "local", Claude Code would:
• Check for .claude/ or .claude-history in the project root
• Create and use local storage if enabled
• Fall back to global storage if local not available

## Use Case
Developers working on multiple projects often reorganize directory structures. Having conversation history tied to the project directory would
eliminate the need to manually update ~/.claude/projects/ mappings and make projects more portable across machines. Additionally, teams could
share conversation context through version control, preserving important architectural discussions and decision rationale.

## Backward Compatibility

• Default to current global storage behavior
• Provide migration tool to move existing histories to local storage
• Support both modes simultaneously for gradual migration

Additional Context

_No response_