How the SessionStart Hook Enables Memory Persistence in Claude Code

The SessionStart hook is a Bash script that automatically scans for recent session files and learned skills, then reports them to Claude via stderr so the model can load previous context into new sessions.

The everything-claude-code repository implements a robust memory persistence system for Claude Code through event-driven hooks. At the heart of this system is the SessionStart hook—located at ~/.claude/hooks/memory-persistence/session-start.sh—which bridges the gap between separate Claude sessions by surfacing historical context when a new session begins.

How the SessionStart Hook Works

The hook operates through three coordinated mechanisms that execute automatically whenever Claude launches.

Scanning for Recent Session Files

The script searches ~/.claude/sessions for .tmp files modified within the last 7 days using:

find ~/.claude/sessions -name "*.tmp" -mtime -7

When matches exist, it identifies the most recent file:

ls -t ~/.claude/sessions/*.tmp 2>/dev/null | head -1

The hook outputs diagnostic messages to stderr:

[SessionStart] Found 3 recent session(s)
[SessionStart] Latest: /home/user/.claude/sessions/2026-01-20-feature-auth.tmp

Claude captures these messages and can embed the referenced file's contents—containing task lists, notes, and state from the previous session—directly into the new session's prompt.

Detecting Learned Skills

The hook also checks ~/.claude/skills/learned for Markdown skill files:

ls ~/.claude/skills/learned/*.md 2>/dev/null | wc -l

It reports the count:

[SessionStart] 5 learned skill(s) available in /home/user/.claude/skills/learned

These learned skills represent custom knowledge saved from earlier sessions, allowing Claude to reuse domain-specific expertise without retraining.

Hook Registration in Claude Configuration

The hook is registered in ~/.claude/settings.json under the SessionStart event:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/memory-persistence/session-start.sh"
          }
        ]
      }
    ]
  }
}

The "matcher": "*" wildcard ensures the hook runs on every session start. The type: "command" directive executes the Bash script, whose stderr output Claude processes to reconstruct context.

Session File Format and Content Recovery

Session files are created by the complementary SessionEnd hook (session-end.sh). A typical file contains structured Markdown:

# Session: 2026-01-20

**Date:** 2026-01-20
**Started:** 14:02
**Last Updated:** 14:35

---

## Current State

[Session context goes here]

### Completed

- [x] Task A

### In Progress

- [ ] Task B

### Notes for Next Session

- Remember to review the API design.

### Context to Load

relevant files

When the SessionStart hook locates this file, Claude ingests the "Context to Load" section to resume work precisely where the previous session ended.

Key Implementation Files

File	Purpose
hooks/memory-persistence/session-start.sh	Scans for recent sessions and skills; outputs discovery messages to stderr.
hooks/memory-persistence/session-end.sh	Creates or updates daily session logs with context, tasks, and notes.
hooks/memory-persistence/pre-compact.sh	(Optional) Prepares context before compact operations.
hooks/hooks.json	Central registry of all hook definitions.

According to the WorldFlowAI/everything-claude-code source code, this architecture achieves memory persistence without manual intervention by combining filesystem scanning with Claude's event hook system.

Configuration and Customization

To enable SessionStart memory persistence in your environment:

1. Copy the hook scripts to ~/.claude/hooks/memory-persistence/
2. Add the hook definition to ~/.claude/settings.json (see registration example above)
3. Ensure the session directory exists: mkdir -p ~/.claude/sessions ~/.claude/skills/learned

The 7-day lookback window and stderr output method are hardcoded in session-start.sh and can be modified by editing the find command's -mtime parameter or the output redirection logic.

Summary

• SessionStart hook (session-start.sh) runs automatically when Claude launches via "matcher": "*" configuration
• Recent session discovery uses find with -mtime -7 to locate relevant .tmp files within ~/.claude/sessions
• Skill detection counts *.md files in ~/.claude/skills/learned for reusable knowledge assets
• Stderr communication allows Claude to capture and process hook output for prompt injection
• Session-end pairing ensures context is saved by session-end.sh before the start hook can retrieve it

Frequently Asked Questions

Where does the SessionStart hook look for previous sessions?

The hook searches ~/.claude/sessions for files matching *.tmp with modification times within the last 7 days. It uses find with -mtime -7 and ls -t to identify the most recently updated session file, which typically contains the previous interaction's state, task lists, and notes.

How does Claude receive information from the SessionStart hook?

The hook writes diagnostic messages to stderr using shell commands like echo >&2. Claude's hook system captures this stderr output and makes it available to the model. The hook specifically avoids stdout to prevent interfering with normal command output channels.

What is the relationship between SessionStart and SessionEnd hooks?

SessionEnd (session-end.sh) creates and updates daily session logs in ~/.claude/sessions/ with context, completed tasks, and notes for the next session. SessionStart subsequently reads these files to restore context. This pairing creates a complete persistence cycle: SessionEnd saves state when exiting, SessionStart loads state when beginning.

Can I adjust how far back the SessionStart hook searches for sessions?

Yes. In hooks/memory-persistence/session-start.sh, modify the -mtime -7 parameter in the find command. Change 7 to your preferred number of days—-mtime -30 for 30 days, for example. Be aware that longer lookback periods may surface outdated context that could confuse Claude about current priorities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}