Memory
Overview
Memory provides persistent context across Claude Code sessions by storing and retrieving project decisions, user preferences, and coding conventions from a local JSON file. When a new session starts, stored memories load automatically so previously established patterns carry forward without re-explanation.
Prerequisites
- Project memory file at
.claude/memories/project_memory.json(created automatically on first memory save) - Read and Write permissions for the
.claude/memories/directory - Claude Never Forgets plugin installed (
/plugin install yldrmahmet/claude-never-forgets)
Instructions
- Access stored memories. On session start, locate and read the memory file at
.claude/memories/project_memory.jsonusing the Read tool. Parse the JSON structure containing timestamped memory entries. See${CLAUDE_SKILL_DIR}/references/implementation.mdfor the full retrieval workflow. - Match memories to current context. Scan memory entries for keywords and topics relevant to the current task. Extract applicable decisions (e.g., "use pnpm instead of npm"), architectural patterns, library choices, and coding style preferences.
- Apply memories silently. Incorporate remembered preferences into responses and tool usage without announcing them. When a memory dictates a package manager, testing framework, or naming convention, follow it automatically.
- Store new memories. When significant decisions occur -- library selections, architectural choices, user-stated preferences, or tool rejections -- write them to the memory file with a timestamp. Add entries via the
/remembercommand or through automatic capture of conversation signals. - Resolve conflicts. When a stored memory contradicts a current explicit request, prioritize the current request. Flag the conflict if appropriate and update the memory entry to reflect the new decision. Remove outdated memories that no longer apply.
- Handle cleanup. When memory entries exceed 10, consolidate by removing noise (greetings, acknowledgments) and preserving high-value entries (preferences, decisions, corrections). The cleanup threshold is configurable in
hooks/stop_cleanup.py.
Output
- Automatic loading of stored memories at session start
- Silent application of remembered preferences to tool usage and responses
- New memory entries written with timestamps for significant decisions
- Consolidated memory file after cleanup (preserves important entries, removes noise)
- Explicit memory listing via
/memoriescommand
Error Handling
| Error | Cause | Solution |
|---|---|---|
| Memory file not found | First session or file deleted | Initialize a new memory file at .claude/memories/project_memory.json with an empty JSON structure |
| Conflicting memories | Multiple entries contradict each other | Apply the most recent memory; suggest cleanup via /forget to remove outdated entries |
| Invalid memory format | File corrupted or manually edited with syntax errors | Back up the existing file, recreate with valid JSON structure, restore recoverable entries |
| Permission denied | File or directory lacks read/write permissions | Check file permissions on .claude/memories/; request necessary access or use an alternative storage location |
Examples
Automatic preference recall across sessions:
Session 1:
User: "Always use Vitest instead of Jest for this project"
→ Stored to project_memory.json
Session 2:
User: "Add tests for the auth module"
→ Memory loaded: "use Vitest instead of Jest"
→ Test files created with Vitest syntax automaticallyManual memory management:
/remember "This project uses Tailwind CSS v4 with the Vite plugin"
/remember "Deploy to Cloudflare Workers, not Vercel"
/memories # Lists all stored memories with timestamps
/forget "Vercel" # Removes the Vercel-related memoryTool rejection captured as correction:
set -euo pipefail
User declines a suggested `npm install` action
→ Memory stored: "User prefers pnpm over npm"
→ Future sessions use pnpm automaticallyResources
${CLAUDE_SKILL_DIR}/references/implementation.md-- Step-by-step guide for accessing, applying, updating, and resolving memory conflicts${CLAUDE_SKILL_DIR}/references/errors.md-- Detailed error scenarios with recovery procedures/remember [text]-- Add a new memory entry manually/forget [text]-- Remove a matching memory from storage/memories-- Display all currently stored memories with timestamps