memory-init

Memory System Initialization

You are setting up a persistent memory system for this codebase. This memory exists solely for YOU to load and parse across sessions. No human will ever read these files directly.

Step 0: Check for Existing Memory

Before creating anything, check if .claude/mem/ already exists.

If it does:

• Read the existing memory files
• Ask the user: "This project already has Claude memory. Should I: (a) Keep existing memory and update the hooks only (b) Rebuild memory from scratch (existing memory will be backed up to .claude/mem.bak/) (c) Cancel"
• If (a): Skip to Step 2 (hooks), preserve .claude/mem/
• If (b): Copy .claude/mem/ to .claude/mem.bak/, then proceed normally
• If (c): Stop

Step 1: Create Directory Structure

Create the following directories:

• .claude/mem/
• .claude/hooks/

Step 2: Create the Hooks

This system uses 4 hooks for full lifecycle coverage. Create all of them.

Configuration File

Create .claude/hooks/config.sh — a shared config sourced by all hooks. Users edit this one file to tune thresholds:

#!/bin/bash
# Memory system configuration
# Edit these values to tune hook behavior.
# All hooks fall back to defaults if this file is missing.

MEM_MAX_CHARS=8000           # Token budget (~2000 tokens). load-memory.sh warns above this.
CHECKPOINT_FRESHNESS=600     # Seconds. Stop hook skips if session saved within this window.
STOP_TURN_THRESHOLD=25       # Transcript lines. Stop hook only blocks after this many turns.
SAVE_TURN_THRESHOLD=4        # Transcript lines. SessionEnd hook skips trivial sessions below this.
TOOLS_CAP=20                 # Max tool entries logged in session metadata.

2A: SessionStart — Load Memory

Create .claude/hooks/load-memory.sh:

#!/bin/bash
set -euo pipefail

# Load config (optional — defaults used if missing)
HOOKS_DIR="$(cd "$(dirname "$0")" && pwd)"
[[ -f "$HOOKS_DIR/config.sh" ]] && source "$HOOKS_DIR/config.sh"

cd "$(dirname "$0")/../.." || exit 1

MEM_DIR=".claude/mem"
[[ -d "$MEM_DIR" ]] || exit 0

MAX_CHARS="${MEM_MAX_CHARS:-8000}"
TOTAL_CHARS=0

for f in "$MEM_DIR"/*; do
  [[ -f "$f" ]] || continue
  FILE_CHARS=$(wc -c < "$f" | tr -d ' ')
  TOTAL_CHARS=$((TOTAL_CHARS + FILE_CHARS))
done

if [[ "$TOTAL_CHARS" -gt "$MAX_CHARS" ]]; then
  echo "!!! MEMORY EXCEEDS TOKEN BUDGET (${TOTAL_CHARS} chars > ${MAX_CHARS}). Compact your .claude/mem/ files. !!!"
fi

for f in "$MEM_DIR"/*; do
  if [[ -f "$f" ]]; then
    echo "=== $(basename "$f") ==="
    cat "$f"
    echo ""
  fi
done

echo "=== git_state ==="
echo "hash:$(git log -1 --format=%h 2>/dev/null || echo 'not-a-repo')"
echo "branch:$(git branch --show-current 2>/dev/null || echo 'unknown')"