Never lose context between Claude Code sessions again.
A complete memory system for Claude Code that maintains context across sessions through intelligent file tracking, automated logging, and structured documentation.
Every time you start a new Claude Code session:
- ❌ You lose all context from previous conversations
- ❌ You have to re-explain your project architecture
- ❌ Claude doesn't remember what you decided or discovered
- ❌ You waste 10-15 minutes getting back up to speed
This gets worse as projects grow and sessions multiply.
A markdown-based memory system that:
- ✅ Automatically tracks every file modification via hooks
- ✅ Maintains session state in human-readable files
- ✅ Documents decisions with Architectural Decision Records (ADRs)
- ✅ Tracks multi-day features with phase-based progress
- ✅ Works universally with any tech stack (React, Python, WordPress, etc.)
- ✅ No dependencies - pure bash scripts + markdown
# Clone this repo
git clone https://github.com/yourusername/claude-memory-template.git
cd claude-memory-template
# Install to your project
./install.sh /path/to/your/project
# Done! 🎉# 1. Navigate to your project
cd /path/to/your/project
# 2. Edit NOW.md with your session goal
nano .claude/NOW.md
# 3. Start Claude Code and say:
"Read .claude/NOW.md and tell me what we're working on"That's it! Claude now has full context and will remember everything.
┌─────────────────────────────────────┐
│ ## ✅ COMPLETED │
│ - [14:23] Created auth-service.ts │ ← Automatic
│ - [14:25] Modified database.ts │ ← Automatic
│ - ✅ JWT authentication working │ ← Manual
│ │
│ ## 🔍 DISCOVERED │
│ - Need Redis for refresh tokens │
│ - Rate limiting requires middleware │
│ │
│ ## ⏭️ NEXT │
│ 1. Implement token refresh logic │
│ 2. Add rate limiting middleware │
└─────────────────────────────────────┘
PostToolUse hooks automatically log to NOW.md:
- [14:23] Created auth.ts
- [14:25] Modified database.js
- [14:28] Ran npm test| File | Purpose | Lifespan | Auto-Updated? |
|---|---|---|---|
| NOW.md | Current session state | 1 session | ✅ Yes |
| PROGRESS.md | Multi-day features | Weeks/months | ❌ Manual |
| DECISIONS.md | Architectural decisions | Permanent | ❌ Manual |
5-minute window prevents spam from rapid file saves.
Works with any tech stack:
- ✅ JavaScript/TypeScript (React, Node.js, Next.js)
- ✅ Python (Django, Flask, FastAPI)
- ✅ PHP (WordPress, Laravel)
- ✅ Ruby, Go, Rust, Java, etc.
Everything is plain text markdown:
- Track in version control
- Review in pull requests
- Share with team members
- No binary formats or databases
- Pure bash scripts
- Standard markdown files
- No plugins to install
- No API keys needed
- Works offline
Quick workflow shortcuts via Claude Code slash commands:
/memory-start → Start session (read NOW.md)
/memory-checkpoint → Update progress
/memory-end → Wrap up session
/feature-start → Plan new feature
/doc-decision → Add ADR
/debug-blocker → Document blocker
/context-full → Load complete context
/commit-prep → Pre-commit checklist
Type / in Claude Code to see all available commands!
- README.md - Comprehensive guide with examples
- QUICKSTART.md - Get running in 5 minutes
- prompts.md - Copy-paste command reference
┌─────────────┐
│ NEW SESSION │
└──────┬──────┘
│
▼
┌─────────────────────────┐
│ 1. Claude reads │ ◄─── Automatic
│ CLAUDE.md │ (project instructions)
└──────┬──────────────────┘
│
▼
┌─────────────────────────┐
│ 2. Claude reads │ ◄─── Automatic
│ NOW.md │ (session context)
└──────┬──────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 3. During work: │
│ Write/Edit → Hook → NOW.md │ ◄─── Automatic logging
│ │
│ Checkpoint → Manual update │ ◄─── Manual insights
└──────┬──────────────────────────────┘
│
▼
┌─────────────────────────┐
│ 4. Session end: │
│ • Summary │
│ • Archive NOW.md │
│ • Prepare next │
└─────────────────────────┘
✅ File creations (Write tool) ✅ File edits (Edit tool) ✅ Bash commands (Bash tool) ✅ Notebook edits (NotebookEdit tool)
✨ Important discoveries ✨ Architectural decisions ✨ Blockers and solutions ✨ Feature progress milestones
Session Start:
/memory-start
"Let's implement JWT authentication"
During Work (automatic):
## ✅ COMPLETED
- [10:15] Created auth-service.ts
- [10:22] Modified user-model.ts
- [10:25] Ran npm testCheckpoint (manual):
/memory-checkpoint
(Claude adds:)
- ✅ COMPLETED: JWT token generation working
- 🔍 DISCOVERED: Need Redis for refresh tokens
- ⏭️ NEXT: Implement token refresh endpoint
Session End:
/memory-end
→ NOW.md archived to archive/NOW-20251027-1015.md
Session Start:
/memory-start
Claude responds:
"I see from NOW.md that yesterday you implemented JWT authentication and discovered the need for Redis for refresh tokens. The next step is to implement the token refresh endpoint. Let's continue from there."
No re-explaining needed! 🎉
| Feature | Claude Memory System | claude-mem |
|---|---|---|
| Storage | Markdown files | Database/compressed |
| Readability | Human-readable | AI-compressed |
| Git Integration | Native | Limited |
| Installation | Copy template | Plugin install |
| Customization | Full control | Plugin-defined |
| Privacy | 100% local | 100% local |
| Dependencies | None (bash + md) | Plugin system |
Use claude-mem if: You want automatic, plugin-based compression Use this system if: You want human-readable, git-friendly files with full control
Both are excellent - choose what fits your workflow!
your-project/
├── .claude/
│ ├── NOW.md # Current session state
│ ├── DECISIONS.md # ADRs (Architectural Decision Records)
│ ├── PROGRESS.md # Multi-day feature tracking
│ ├── prompts.md # Optional: Command reference
│ ├── scripts/
│ │ ├── memory-checkpoint # Auto-logging script
│ │ └── lib/
│ │ └── memory-utils.sh # Bash utilities
│ ├── templates/
│ │ └── session.template.md # NOW.md template
│ ├── archive/ # Old NOW.md files
│ └── settings.json # Hook configuration
│
├── CLAUDE.md # Claude Code instructions
└── [your project files]
Edit CLAUDE.md with your project specifics:
- Project overview
- Tech stack
- Architecture details
- Coding conventions
Edit .claude/settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "YourTool",
"hooks": [{
"type": "command",
"command": "./.claude/scripts/your-custom-script"
}]
}
]
}
}-
Always start with NOW.md
"Read .claude/NOW.md for context" -
Checkpoint every 30-60 minutes
"Update NOW.md with progress" -
Document important decisions
"Add to DECISIONS.md: Why we chose PostgreSQL" -
Track multi-day features in PROGRESS.md
"Update PROGRESS.md: User Auth - Phase 1 complete" -
End sessions clearly
"Session end: summarize progress"
- ✅ All data stays 100% local on your machine
- ✅ No cloud storage, no API calls, no telemetry
- ✅ Add
.claude/to.gitignoreif handling sensitive data - ✅ Scripts run with user permissions only
- ✅ Hooks use
|| trueto never break your workflow
Contributions welcome! Here are some ideas:
- VSCode extension for NOW.md sidebar
- GitHub Action to include NOW.md in PR descriptions
- Slack/Discord integration for team notifications
- Web dashboard for visualizing session history
- Support for additional hooks (GitCommit, Deploy, etc.)
See CONTRIBUTING.md for guidelines.
MIT License - see LICENSE file for details.
- Inspired by the challenges of maintaining context in AI-assisted development
- Built for the Claude Code community
- Special thanks to everyone who provided feedback during development
- Documentation: Full README and QUICKSTART in repo
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Claude Code: https://claude.ai/code
If this helped you, please star the repo! It helps others discover it.
Ready to never lose context again?
./install.sh /path/to/your/projectQuestions? Open an issue or discussion - happy to help! 🚀