# How the SessionStart Hook Enables Memory Persistence in Claude Code

> Discover how the SessionStart hook enables memory persistence in Claude Code. Learn how Bash scripts load previous context into new sessions for seamless AI interaction.

- Repository: [WorldFlowAI/everything-claude-code](https://github.com/WorldFlowAI/everything-claude-code)
- Tags: internals
- Published: 2026-09-07

---

**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:

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

```

When matches exist, it identifies the most recent file:

```bash
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:

```bash
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:

```json
{
  "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`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/session-end.sh)). A typical file contains structured Markdown:

```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`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/hooks/memory-persistence/session-start.sh) | Scans for recent sessions and skills; outputs discovery messages to stderr. |
| [`hooks/memory-persistence/session-end.sh`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/hooks/memory-persistence/session-end.sh) | Creates or updates daily session logs with context, tasks, and notes. |
| [`hooks/memory-persistence/pre-compact.sh`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/hooks/memory-persistence/pre-compact.sh) | (Optional) Prepares context before compact operations. |
| [`hooks/hooks.json`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/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`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/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`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/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`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/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`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/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`](https://github.com/WorldFlowAI/everything-claude-code/blob/main/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.