Pre-Session Memory Hook

Automatically retrieves relevant long-term memory context when a new Claude Code session starts. Analyzes the current project context and injects relevant prior work, decisions, and patterns.

Trigger

This hook is triggered at session start and:

1. Detects current project from working directory
2. Retrieves recent activity for the project
3. Surfaces relevant decisions, patterns, and work status
4. Injects summary context (500-2000 tokens based on activity)

Configuration

Enable/Disable

# Enable (default)
export CODITECT_MEMORY_HOOK=enabled

# Disable
export CODITECT_MEMORY_HOOK=disabled

Budget Control

# Minimal (500 tokens) - quick sessions
export CODITECT_MEMORY_BUDGET=minimal

# Standard (2000 tokens) - default
export CODITECT_MEMORY_BUDGET=standard

# Comprehensive (5000 tokens) - deep work
export CODITECT_MEMORY_BUDGET=comprehensive

Auto-Detection Settings

# Project detection from git
export CODITECT_MEMORY_PROJECT_DETECT=git

# Always use specific project
export CODITECT_MEMORY_PROJECT=myproject

# Disable project filtering
export CODITECT_MEMORY_PROJECT_DETECT=none

Hook Implementation

#!/usr/bin/env python3
"""Pre-session memory hook for CODITECT."""

import os
import subprocess
import sys
from pathlib import Path

def get_project_name():
    """Detect project name from git or directory."""
    try:
        result = subprocess.run(
            ['git', 'rev-parse', '--show-toplevel'],
            capture_output=True, text=True
        )
        if result.returncode == 0:
            return Path(result.stdout.strip()).name
    except Exception:
        pass
    return Path.cwd().name

def retrieve_memory_context(project: str, budget: int = 2000):
    """Retrieve memory context for project."""
    script = Path(__file__).parent.parent / 'scripts' / 'memory-retrieval.py'

    cmd = [
        sys.executable, str(script),
        '--status',
        '--budget', str(budget)
    ]

    result = subprocess.run(cmd, capture_output=True, text=True)
    return result.stdout

def main():
    # Check if hook is enabled
    if os.environ.get('CODITECT_MEMORY_HOOK') == 'disabled':
        return

    # Get budget
    budget_map = {
        'minimal': 500,
        'standard': 2000,
        'comprehensive': 5000
    }
    budget = budget_map.get(
        os.environ.get('CODITECT_MEMORY_BUDGET', 'standard'),
        2000
    )

    # Get project
    project = os.environ.get('CODITECT_MEMORY_PROJECT') or get_project_name()

    # Retrieve and print context
    context = retrieve_memory_context(project, budget)
    if context.strip():
        print("\n--- Prior Session Context ---")
        print(context)
        print("--- End Context ---\n")

if __name__ == '__main__':
    main()

Integration

Claude Code Hooks (settings.json)

{
  "hooks": {
    "session_start": [
      {
        "name": "pre-session-memory",
        "script": "hooks/pre-session-memory.py",
        "timeout": 5000,
        "enabled": true
      }
    ]
  }
}

Manual Invocation

# Run manually at any time
python3 hooks/pre-session-memory.py

# Or use the command
/recall --status

What Gets Retrieved

Always Retrieved (High Priority)

• Blockers: Any blocked items that need attention
• Work-in-progress: Active tasks from recent sessions
• Recent errors: Unresolved issues from last session

Conditionally Retrieved (Based on Budget)

• Decisions: Recent architectural/technology decisions
• Patterns: Relevant code patterns for current project
• Completed work: Recently finished items for reference

Example Output

--- Prior Session Context ---

## Work Status Summary

**Work Status:**
- [IN_PROGRESS] API authentication refactor - 60%
- [BLOCKED] Payment integration - awaiting Stripe keys
- [COMPLETED] Database migration v2 (yesterday)

**Recent Decisions:**
1. Use JWT with refresh tokens (ADR-005)
2. Repository pattern for data access

**Active Blockers:**
- Payment integration blocked on external API keys

---
*Token count: ~450 / 500 budget*

--- End Context ---

Customization

Custom Retrieval Logic

Create hooks/pre-session-memory-custom.py to override default behavior:

from hooks.pre_session_memory import retrieve_memory_context

def custom_retrieval(project, budget):
    # Add custom logic
    context = retrieve_memory_context(project, budget)

    # Add project-specific context
    if project == 'myproject':
        context += "\n**Project Note:** Remember to run tests before commit."

    return context

Per-Project Configuration

Create .coditect/memory-config.json in project root:

{
  "memory_hook": {
    "enabled": true,
    "budget": "standard",
    "focus": ["decisions", "blockers"],
    "exclude": ["patterns"]
  }
}

Troubleshooting

Hook Not Running

1. Check hook is enabled: echo $CODITECT_MEMORY_HOOK
2. Verify databases exist (ADR-118): ls ~/PROJECTS/.coditect-data/context-storage/org.db ~/PROJECTS/.coditect-data/context-storage/sessions.db
3. Run manually: python3 hooks/pre-session-memory.py

Empty Context

1. Run /cx to extract messages first
2. Check database has content: /cxq --stats
3. Verify project detection: git rev-parse --show-toplevel

Too Much Context

1. Reduce budget: export CODITECT_MEMORY_BUDGET=minimal
2. Focus on specific types: modify hook config
3. Use /recall --status for minimal output

Related Components

• Agent: memory-context-agent
• Skill: skills/memory-retrieval/SKILL.md
• Command: /recall
• Script: scripts/memory-retrieval.py

---

Version: 1.0.0 Last Updated: 2025-12-12