prompting

>Memory Files for Long Projects

memoryproject-managementcontext
Source:▶Claude SDK: 24-Hour Coding Agent|@Cole Medin

Ever started a coding session by staring at your project for 10 minutes, trying to remember where you left off? Or worse, rebuilt something you already decided against two weeks ago? You're not alone. Long projects suffer from context loss between sessions, and without a system to track decisions and progress, you'll waste hours rediscovering what you already knew.

The solution is surprisingly simple: create a memory.md file that serves as your project's brain. This single file tracks your current status, past decisions, and future plans. When you reference it in your CLAUDE.md file, Claude instantly knows your project's full context every time you start a new conversation.

Setting Up Your Memory File

Create a memory.md file in your project root with four core sections. Each section serves a specific purpose in maintaining project continuity.

# Project Memory

## Current Status
**Active Sprint:** User Authentication (Week 2)
**Last Session:** 2024-01-15 - Fixed password reset flow
**Next Priority:** Add OAuth providers (Google, GitHub)

## Recent Decisions
- **2024-01-15:** Switched from bcrypt to Argon2 for password hashing (better security)
- **2024-01-12:** Using Prisma ORM instead of raw SQL (team familiarity)
- **2024-01-10:** Decided against microservices architecture (premature optimization)

## Active Tasks
- [x] Basic email/password authentication
- [x] Password reset via email
- [ ] Add OAuth providers (Google, GitHub) - IN PROGRESS
- [ ] Implement role-based permissions
- [ ] Add rate limiting to auth endpoints

## Known Issues & Blockers
- OAuth redirect URLs need HTTPS (staging environment pending)
- Client hasn't provided Google OAuth credentials yet
- Rate limiting library has TypeScript compatibility issues

The beauty of this structure is that it gives you—and Claude—immediate context. You can jump back into any project and know exactly where things stand.

Integrating with Your CLAUDE.md File

Your CLAUDE.md file should explicitly reference the memory file so Claude always has access to current project state. Here's how to structure that reference:

# Project Context for Claude

## Project Overview
E-commerce platform built with Next.js, Prisma, and PostgreSQL.

## Current Status
Always check `memory.md` for the latest project status, recent decisions, and active tasks before making suggestions or writing code.

## Development Guidelines
- Use TypeScript for all new code
- Follow ESLint configuration in project root
- Write tests for all business logic
- Update memory.md when making architectural decisions

## File Structure

src/ components/ # Reusable UI components pages/ # Next.js pages and API routes lib/ # Utilities and configurations types/ # TypeScript type definitions memory.md # Project status and decisions (CHECK THIS FIRST)

This setup ensures Claude always starts by understanding your project's current state before suggesting code changes or architectural decisions.

Maintaining Your Memory File

The key to an effective memory file is keeping it current without it becoming a burden. Update it at natural breakpoints in your development process.

End of each session: Add a one-line status update and mark completed tasks:

## Current Status
**Active Sprint:** User Authentication (Week 2)
**Last Session:** 2024-01-16 - Completed Google OAuth integration, started GitHub OAuth
**Next Priority:** Finish GitHub OAuth, then move to user profiles

When making decisions: Document the choice and reasoning:

## Recent Decisions
- **2024-01-16:** Using NextAuth.js for OAuth (handles edge cases we'd miss)
  - Considered: Custom implementation, Auth0, Firebase Auth
  - Reason: Best Next.js integration, active community, handles token refresh

When hitting blockers: Record the issue and any workarounds:

## Known Issues & Blockers
- GitHub OAuth scope permissions need admin approval (requested via IT ticket #1234)
- Temporary workaround: Using personal GitHub app for development

Advanced Memory Patterns

As your project grows, enhance your memory file with additional sections that match your workflow.

Architecture decisions deserve their own space:

## Architecture Log
### Database Schema v2 (2024-01-16)
Added `user_profiles` table with foreign key to `users`. Considered embedding profile data in users table but separated for flexibility and future audit requirements.

### API Design (2024-01-14) 
RESTful endpoints for auth, GraphQL for complex user data queries. Hybrid approach chosen after performance testing showed GraphQL overhead acceptable for complex queries but unnecessary for simple CRUD.

Performance benchmarks help track improvements:

## Performance Baseline
- **2024-01-15:** Auth flow: 245ms average (login + token verification)
- **2024-01-12:** Database queries: 12ms average (user lookup)
- **Target:** Sub-200ms auth flow, sub-10ms queries

Dependencies and version notes prevent compatibility issues:

## Dependencies & Versions
- Node.js 18.17+ required (uses fetch API)
- Next.js 14.0.3 (stable, avoid 14.1.x - known hydration issues)
- Prisma 5.7.1 (migration issue in 5.8.x, stay pinned)

Pro Tips for Memory File Success

Keep it scannable. Use consistent formatting and clear headers. When you're debugging at 2 AM, you need to find information fast.

Date everything. Timestamps help you understand the evolution of decisions and identify when problems were introduced.

Link to external resources: Include URLs to documentation, Stack Overflow threads, or GitHub issues that informed your decisions.

## Recent Decisions
- **2024-01-16:** Switched to server-side session handling
  - Reference: https://nextjs.org/docs/authentication#session-management
  - Solves: Client-side token exposure, automatic refresh handling

Version your memory file. For major project phases, create dated snapshots:

cp memory.md memory-v1.0-launch.md

Common Pitfalls to Avoid

Don't let your memory file become a novel. Keep entries concise but informative. "Fixed auth bug" isn't helpful—"Fixed auth bug: JWT tokens weren't refreshing due to incorrect expiry validation" tells the real story.

Avoid duplicating information that lives elsewhere. Don't copy your entire README into the memory file. Instead, reference it and focus on current state and decisions.

Don't abandon the file during crunch time. That's exactly when you need it most. A quick "Working on critical bug fix, will update memory after deployment" is better than silence.

What's Next

Once you have a solid memory system, consider expanding into related organizational patterns. Look into implementing a decisions.md file for architectural decision records (ADRs), or create project-specific prompt templates that automatically include memory context. You might also explore tools like Linear or Notion that can automatically sync with your memory file for team projects.

The memory file is your foundation for maintaining context across long development cycles. Master this pattern, and you'll never lose your place in a project again.

←cd ~/tips