memory

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

1. Access stored memories. On session start, locate and read the memory file at .claude/memories/project_memory.json using the Read tool. Parse the JSON structure containing timestamped memory entries. See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full retrieval workflow.
2. 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.
3. 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.
4. 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 /remember command or through automatic capture of conversation signals.
5. 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.
6. 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 /memories command

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 automatically

Manual 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 memory

Tool 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 automatically

Resources

• ${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