How to Structure the ~/.claude/ Directory for Persistent Memory

Mar 12, 2026

The Problem

I kept losing context between Claude Code sessions. Every time I started a new conversation, I had to re-explain my project architecture, coding preferences, and workflows. Claude had no memory of what we worked on yesterday.

The Solution

I set up a structured ~/.claude/ directory that acts as Claude’s persistent memory. Here’s the layout that works:

~/.claude/
├── CLAUDE.md          # Main configuration file
├── knowledge/         # Reference files Claude reads on demand
├── rules/             # Behavioral rules that load automatically
├── skills/            # Slash-command workflows
├── scripts/           # Hooks and automation
└── state/             # Session logs and task tracking

Each directory has a specific purpose. Let me show you how I set them up.

Creating the Structure

First, I created the directories:

mkdir -p ~/.claude/{knowledge,rules,skills,scripts,state}

The CLAUDE.md File

The CLAUDE.md file is the central configuration. I treat it as the real configuration, not the IDE choice. Here’s a basic example:

# Claude Configuration

## Project Context
- Architecture: Microservices with Flask backend
- Frontend: Alpine.js + Tailwind CSS
- Database: PostgreSQL with SQLAlchemy

## Behavioral Rules
- Always run tests before committing
- Use conventional commit messages
- Never commit directly to main branch

## Knowledge Sources
- Reference knowledge/architecture.md for system design
- Check knowledge/api-patterns.md for API conventions

This file loads automatically when Claude starts a session.

The knowledge/ Directory

I put reference files here that Claude reads when it needs context:

Project architecture documentation
User preferences and coding standards
Research notes and technical references
API documentation and design patterns

Claude reads from knowledge/ when it needs context. I don’t need to repeat myself every session.

The rules/ Directory

Rules load automatically and define how Claude should behave. Here’s my git workflow rule:

# Git Workflow

## Commit Message Format
&lt;type&gt;: &lt;description&gt;

Types: feat, fix, refactor, docs, test, chore

## Branch Naming
feature/&lt;ticket-id&gt;-&lt;description&gt;
bugfix/&lt;ticket-id&gt;-&lt;description&gt;

Rules ensure consistent behavior across all sessions without me having to specify them each time.

The skills/ Directory

Skills are slash-command workflows for recurring tasks. Instead of explaining the same task repeatedly, I define it once as a skill and invoke it with a simple command.

Common skills I use:

Automated code review workflows
Testing and deployment procedures
Documentation generation tasks
Common refactoring patterns

The scripts/ Directory

Hooks and automation go here:

Guard hooks that block dangerous commands
Pre-commit validation scripts
Activity monitors and logging
Custom automation workflows

These run automatically at specific points in the workflow.

The state/ Directory

This is where Claude writes as it works. I use it for:

Session logs for continuity
Task backlog management
Progress tracking files

Here’s how I track current tasks:

# Current Task: Authentication System

## Scope
- Implement JWT-based auth
- Add rate limiting
- Create user management endpoints

## Out of Scope
- OAuth integration
- Password reset flow

## Progress
- [x] JWT implementation
- [ ] Rate limiting
- [ ] User endpoints

Per-task markdown files defining scope keep Claude from going on cleanup tangents.

Why This Structure Works

The separation of concerns is clear:

knowledge/ for reading context
state/ for writing progress
rules/ for automatic behavior constraints
skills/ for reusable workflows
scripts/ for automation

Claude reads from knowledge/ when it needs context and writes to state/ as it works. This creates persistent memory without me repeating myself.

Common Mistakes I Avoided

Treating ~/.claude/ as a dumping ground - Without organization, Claude can’t find what it needs
Overloading CLAUDE.md with too many instructions - I keep it focused on essential context
Not using state/ for session continuity - This defeats the purpose of persistent memory
Ignoring skills/ for recurring tasks - I was re-explaining the same workflows repeatedly
Forgetting per-task scope files - Claude would go on tangents without clear boundaries

Getting Started

If you want to set this up, start with the five core directories:

mkdir -p ~/.claude/{knowledge,rules,skills,scripts,state}

Then create a basic CLAUDE.md with your project context. Add rules as you notice patterns in your workflows. Create skills for tasks you repeat often. Let state accumulate naturally as you work.

The structure transforms Claude from a stateless assistant into a persistent partner with memory, preferences, and workflows.

Summary

In this post, I showed how to structure the ~/.claude/ directory for persistent memory. The key point is that a clear separation between knowledge, rules, skills, scripts, and state gives Claude context that persists across sessions.

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:

👨‍💻 Reddit Discussion: Claude Code setup

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