claude-memory

Claude Diary

A long-term memory plugin for Claude Code that learns from your activity over time and continuously improves Claude's understanding of your preferences, patterns, and workflows.

• Diary: Generate a diary entry for any Claude Code session
• Reflection: Performs reflection across multiple diary entries
• Memory: Reflection updates your CLAUDE.md with observed patterns and preferences

Read more: Blog post

Quickstart

1. Clone this repository:

git clone https://github.com/rlancemartin/claude-diary claude-diary
cd claude-diary

2. Install commands:

cp commands/*.md ~/.claude/commands/

3. Install PreCompact hook (for auto-diary generation):

mkdir -p ~/.claude/hooks
cp hooks/pre-compact.sh ~/.claude/hooks/pre-compact.sh
chmod +x ~/.claude/hooks/pre-compact.sh

4. Configure the hook in settings:

   Add the following to ~/.claude/settings.json (global) or .claude/settings.local.json (project-specific):

   {
     "hooks": {
       "PreCompact": [
         {
           "matcher": "auto",
           "hooks": [
             {
               "type": "command",
               "command": "bash ~/.claude/hooks/pre-compact.sh"
             }
           ]
         }
       ]
     }
   }
   

   Alternatively, use the interactive command:

   /hooks
   

   Then select PreCompact event, auto matcher, and enter bash ~/.claude/hooks/pre-compact.sh as the command.

5. Use the system:

   • Run /diary after important sessions (or let the PreCompact hook auto-generate)
   • After any collection of diary entries, run /reflect to analyze patterns
   • CLAUDE.md automatically updated with learnings

Overview

CLAUDE.md files serve as long-term memory for Claude Code. But, they are typically updated manually (e.g., via the # shortcut or /memory command). This plugin aims to automates the process of updating CLAUDE.md with the learnings from your activity over time. It is inspired by an interview between Dan Shipper and Cat Wu / Boris Cherny from the Claude Code team, which mentions that some Anthropic employees have started generating diary entries for Claude sessions and performing reflection over them. The approach follows that general flow, and also borrows ideas from the Generative Agents paper, which introduces a memory architecture with three key components:

1. Observations: Raw experiences recorded in natural language (like our diary entries)
2. Reflection: Higher-level insights and patterns (like our /reflect command)
3. Retrieval: Accessing memories to inform behavior (like reading CLAUDE.md into each session)

Diary Entries

The /diary command creates diary entries from the current session. It uses a context-first approach, reflecting on the conversation already in Claude Code's context, but can also parse JSONL transcripts, which are logged for each session to the project directory. See diary.md for details. The diary command can be run in two ways:

1. Automatic: PreCompact hook runs before conversation compacts (long sessions, 200+ messages). This could be customized to run at different points using different Claude Code hooks.
2. Manual: Run /diary anytime to capture important context in the current session

How the Diary Command Works

The command instructs Claude to create diary entries by reflecting on the conversation history in context (user messages, tool invocations, files modified, errors, solutions). It then instructs Claude to write the diary entry to a file in the ~/.claude/memory/diary/ directory as a markdown file with sections for task summary, work done, design decisions, user preferences, code review feedback, challenges, solutions, and code patterns. It instructs Claude to be factual and specific, capture the "why" behind decisions, document ALL user preferences (especially commits/PRs/linting/testing), include failures as learning. The output location is ~/.claude/memory/diary/YYYY-MM-DD-session-N.md.

Reflection

The /reflect command analyzes diary entries to identify patterns and automatically updates CLAUDE.md. See reflect.md for details. The reflect command can be run in manually in any session; run /reflect anytime you have accumulated diary entries and want to update CLAUDE.md with new learnings.

How the Reflect Command Works