Memory Persistence

Memory Persistence

Session lifecycle hooks that maintain context and knowledge across Claude Code sessions.

What This Does

Captures session metadata and context:

• Session Start: Initialize session directory, record metadata
• Session End: Generate summary, prepare for next session
• Session Logging: Track session activity for pattern extraction

Architecture

Session Start → Initialize → Capture Metadata
     │
     │ (work session)
     │
     ▼
Session End → Generate Summary → Extract Patterns
     │
     ▼
~/.claude/sessions/<session-id>/
├── start.jsonl    # Session start metadata
├── end.jsonl      # Session end metadata
├── session.log    # Activity log
└── summary.md     # Human-readable summary

Session Structure

Each session creates a directory in ~/.claude/sessions/:

~/.claude/sessions/
├── 20250127-143022-12345/
│   ├── start.jsonl    # {"timestamp":"...","event":"session_start",...}
│   ├── end.jsonl      # {"timestamp":"...","event":"session_end",...}
│   ├── session.log    # Activity log
│   └── summary.md     # Session summary
├── 20250127-154530-12346/
│   ├── ...

Hooks Configuration

Configure in .claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/scripts/session-start.sh",
            "description": "Initialize session logging"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/scripts/session-end.sh",
            "description": "Finalize session summary"
          }
        ]
      }
    ]
  }
}

Session Metadata

Session Start Records:

• Timestamp
• Session ID (YYYYMMDD-HHMMSS-PID)
• Working directory
• Git branch
• Environment variables

Session End Records:

• Timestamp
• Session duration (calculated)
• Working directory
• Final state

Integration with Handoff

Memory persistence integrates with the /handoff command:

Session End → Handoff Generation:

1. Session ends (hook triggers)
2. Summary generated automatically
3. Handoff document created with session context
4. Next session loads handoff for continuity

Handoff Document Structure:

goal: [What was being worked on]
now: [Current state]
context:
  session_id: [Previous session ID]
  session_summary: [Link to session summary]
  files_modified: [List of files changed]
next_steps: [What to do next]

Cross-Platform Compatibility

Hooks use POSIX-compliant bash for cross-platform support:

• macOS: Works natively
• Linux: Works natively
• Windows: Works via Git Bash or WSL

Session Management

View Sessions:

# List all sessions
ls ~/.claude/sessions/

# View recent sessions
ls -lt ~/.claude/sessions/ | head -10

# Count total sessions
ls ~/.claude/sessions/ | wc -l

Clean Old Sessions:

# Remove sessions older than 30 days
find ~/.claude/sessions/ -type d -mtime +30 -exec rm -rf {} \;

Archive Important Sessions:

# Archive specific session
cp -r ~/.claude/sessions/20250127-143022-12345 ~/archive/sessions/

Best Practices

1. Review session summaries - Check summary.md before starting new session
2. Extract patterns - Use /learn to capture valuable patterns from sessions
3. Archive key sessions - Save important sessions for future reference
4. Clean periodically - Remove old sessions to manage disk space
5. Integrate with handoff - Use handoff for session continuity

Privacy Considerations

• Local storage only - Sessions stored on your machine
• No cloud sync - Session data never uploaded
• No conversation content - Only metadata and summaries
• User control - You decide when to archive or delete

Integration with Seed System

Handoff Command

Session hooks integrate with /handoff:

• Session end → Generate handoff document automatically
• Next session → Load previous handoff for continuity
• Seamless transition between sessions

Related Skills

• handoff - Session continuity and context transfer
• filesystem-context - Persistent storage patterns

Key Principle

Session lifecycle hooks maintain context continuity across sessions, enable pattern extraction, and integrate with handoff for seamless workflow transitions.

Genetic Code

This component carries essential Seed System principles for context: fork isolation:

Delta Standard: Good Component = Expert Knowledge − What Claude Already Knows

Recognition Questions:

• "Would Claude know this without being told?" → Delete (zero delta)
• "Can this work standalone?" → Fix if no (non-self-sufficient)
• "Did I read the actual file, or just see it in grep?" → Verify before claiming