Skip to content
BSWEN
Blog

Claude Code Memory System: User vs Project Memory Configuration Guide

Cowrie
Cowrie
Dev @ Bswen

Problem

Every time I start a new Claude Code session, I have to re-explain:

  • My coding style preferences
  • My development environment
  • Project architecture and conventions

This wastes tokens and time. Is there a way to make Claude remember?

The Solution: Memory Files

Claude Code has a memory system using two files:

  1. User Memory (~/.claude/CLAUDE.md) - Global preferences
  2. Project Memory (PROJECT_ROOT/.CLAUDE.md) - Project-specific settings
┌─────────────────────────────────────────────────────────────┐
│  User Memory (~/.claude/CLAUDE.md)                         │
│  ├── Your coding style                                      │
│  ├── Preferred frameworks                                   │
│  ├── Development environment                                │
│  └── Personal preferences                                   │
├─────────────────────────────────────────────────────────────┤
│  Project Memory (PROJECT_ROOT/.CLAUDE.md)                   │
│  ├── Project architecture                                   │
│  ├── Tech stack                                             │
│  ├── Coding conventions                                     │
│  └── Common commands                                        │
└─────────────────────────────────────────────────────────────┘

User Memory Template

Edit ~/.claude/CLAUDE.md for your personal preferences:

~/.claude/CLAUDE.md
# User Preferences


## Programming Languages
- Primary: Python, JavaScript, TypeScript
- Frameworks: React, FastAPI, Express


## Code Style
- Indentation: 4 spaces
- Naming: camelCase (JS), snake_case (Python)
- Functions: Verb-first, descriptive names
- Comments: In English, detailed


## Development Environment
- Editor: VS Code, Cursor
- Terminal: zsh with oh-my-zsh
- Version Control: Git with conventional commits


## Work Habits
- Test-driven development (TDD)
- Code review required
- Documentation first
- Security priority


## Common Tools
- Package managers: npm, pip, poetry
- Databases: PostgreSQL, Redis
- Deployment: Docker, Kubernetes

Project Memory Template

Create .CLAUDE.md in your project root:

PROJECT_ROOT/.CLAUDE.md
# Project Configuration


## Project Info
- Name: E-commerce API
- Stack: Node.js + Express + PostgreSQL + Redis
- Environment: Node 20.x, npm 10.x
- Deployment: Docker + Kubernetes


## Architecture
- Microservices architecture
- API Gateway: Kong
- Authentication: JWT + Redis session
- Database: Master-slave, read-write separation


## Coding Standards
- ESLint + Prettier
- Function naming: camelCase
- File naming: kebab-case
- Commits: Conventional Commits


## Environment Variables
- DATABASE_URL: Database connection
- REDIS_URL: Redis connection
- JWT_SECRET: JWT secret key
- API_PORT: API port (default 3000)


## Common Commands
- Start dev: `npm run dev`
- Run tests: `npm test`
- Build: `npm run build`
- Migrate: `npm run migrate`
- Lint: `npm run lint`


## API Design
- RESTful style
- Unified error handling
- Rate limiting
- Versioning (/api/v1/)


## Security Requirements
- All APIs require authentication
- Sensitive data encrypted
- SQL injection protection
- XSS protection


## Testing Requirements
- Unit test coverage > 80%
- Integration tests required
- E2E tests for critical flows

How to Edit Memory Files

User Memory

Edit user memory
claude
> /edit

Project Memory

Edit project memory
cd your-project
claude
> /edit project

Via Conversation

You can also update memory through conversation:

Update memory via chat
claude "记住我喜欢使用TypeScript而不是JavaScript"
claude "记住这个项目使用PostgreSQL作为主数据库"

Why This Matters

Memory files provide several benefits:

  1. Save tokens - No need to repeat preferences
  2. Consistency - Claude follows your style every time
  3. Efficiency - Faster context setup for each session
  4. Team alignment - Project memory can be shared via git

Common Mistakes

  1. Not creating memory files at all - Missing out on the feature
  2. Putting project info in user memory - Wrong scope
  3. Not updating memory when preferences change - Outdated context

Summary

In this post, I showed how to configure Claude Code’s memory system. The key points are:

  1. Use ~/.claude/CLAUDE.md for global user preferences
  2. Use PROJECT_ROOT/.CLAUDE.md for project-specific settings
  3. Edit with /edit (user) or /edit project (project)
  4. Update memory as your preferences and project evolve

Memory files eliminate the need to re-explain your context every session.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: