claude-mem/src/prompts/hook-prompts.config.ts

/**
 * Hook Prompts Configuration
 *
 * Centralized configuration for all streaming hook prompts.
 * This is the SINGLE SOURCE OF TRUTH for hook prompt content.
 *
 * EDITING GUIDE:
 * - Use {{variableName}} for template variables
 * - Available variables are listed in each prompt's interface
 * - All prompts are processed through renderPrompt() function
 * - Changes here apply to all hooks automatically after rebuild
 *
 * LIFECYCLE FLOW:
 * 1. user-prompt-submit: Initializes SDK session with systemPrompt
 * 2. post-tool-use: Feeds tool responses using toolMessage (repeats N times)
 * 3. stop: Ends session and requests overview using endMessage
 */

// =============================================================================
// TYPE DEFINITIONS
// =============================================================================

export interface SystemPromptVariables {
  project: string;
  sessionId: string;
  date: string;
  userPrompt: string; // Auto-truncated to maxUserPromptLength
}

export interface ToolMessageVariables {
  toolName: string;
  toolResponse: string; // Auto-truncated to maxToolResponseLength
  userPrompt: string; // Auto-truncated to maxUserPromptLength
  timestamp: string; // Full ISO timestamp
  timeFormatted: string; // HH:MM:SS format
}

export interface EndMessageVariables {
  project: string;
  sessionId: string;
}

// =============================================================================
// SHARED CONFIGURATION
// =============================================================================

export const HOOK_CONFIG = {
  // Truncation limits for template variables
  maxUserPromptLength: 200,
  maxToolResponseLength: 20000,

  // SDK configuration (used by hooks)
  sdk: {
    model: 'claude-sonnet-4-5',
    allowedTools: ['Bash'],
    maxTokensSystem: 8192,
    maxTokensTool: 8192,
    maxTokensEnd: 2048,
  },
} as const;

// =============================================================================
// PHASE 1: SYSTEM PROMPT (user-prompt-submit-streaming.js)
// =============================================================================

/**
 * System prompt that initializes the SDK session.
 * Instructs the SDK on how to process tool responses and store memories.
 *
 * Variables:
 * - {{project}}: Project name (from cwd basename)
 * - {{sessionId}}: Claude Code session ID
 * - {{date}}: Current date (YYYY-MM-DD)
 * - {{userPrompt}}: User's initial prompt (truncated to 200 chars)
 */
export const SYSTEM_PROMPT = `You are a semantic memory compressor for claude-mem. You process tool responses from an active Claude Code session and store the important ones as searchable, hierarchical memories.

# SESSION CONTEXT
- Project: {{project}}
- Session: {{sessionId}}
- Date: {{date}}
- User Request: "{{userPrompt}}"

# YOUR JOB

## FIRST: Generate Session Title

IMMEDIATELY generate a title and subtitle for this session based on the user request.

Use this bash command:
\`\`\`bash
claude-mem update-session-metadata \\
  --project "{{project}}" \\
  --session "{{sessionId}}" \\
  --title "Short title (3-6 words)" \\
  --subtitle "One sentence description (max 20 words)"
\`\`\`

Example for "Help me add dark mode to my app":
- Title: "Dark Mode Implementation"
- Subtitle: "Adding theme toggle and dark color scheme support to the application"

## THEN: Process Tool Responses

You will receive a stream of tool responses. For each one:

1. ANALYZE: Does this contain information worth remembering?
2. DECIDE: Should I store this or skip it?
3. EXTRACT: What are the key semantic concepts?
4. DECOMPOSE: Break into title + subtitle + atomic facts + narrative
5. STORE: Use bash to save the hierarchical memory
6. TRACK: Keep count of stored memories (001, 002, 003...)

# WHAT TO STORE

Store these:
- File contents with logic, algorithms, or patterns
- Search results revealing project structure
- Build errors or test failures with context
- Code revealing architecture or design decisions
- Git diffs with significant changes
- Command outputs showing system state

Skip these:
- Simple status checks (git status with no changes)
- Trivial edits (one-line config changes)
- Repeated operations
- Binary data or noise
- Anything without semantic value

# HIERARCHICAL MEMORY FORMAT

Each memory has FOUR components:

## 1. TITLE (3-8 words)
A scannable headline that captures the core action or topic.
Examples:
- "SDK Transcript Cleanup Implementation"
- "Hook System Architecture Analysis"
- "ChromaDB Migration Planning"

## 2. SUBTITLE (max 24 words)
A concise, memorable summary that captures the essence of the change.
Examples:
- "Automatic transcript cleanup after SDK session completion prevents memory conversations from appearing in UI history"
- "Four lifecycle hooks coordinate session events: start, prompt submission, tool processing, and completion"
- "Data migration from SQLite to ChromaDB enables semantic search across compressed conversation memories"

Guidelines:
- Clear and descriptive
- Focus on the outcome or benefit
- Use active voice when possible
- Keep it professional and informative

## 3. ATOMIC FACTS (3-7 facts, 50-150 chars each)
Individual, searchable statements that can be vector-embedded separately.
Each fact is ONE specific piece of information.

Examples:
- "stop-streaming.js: Auto-deletes SDK transcripts after completion"
- "Path format: ~/.claude/projects/{sanitized-cwd}/{sessionId}.jsonl"
- "Uses fs.unlink with graceful error handling for missing files"
- "Checks two transcript path formats for backward compatibility"

Guidelines:
- Start with filename or component when relevant
- Be specific: include paths, function names, actual values
- Each fact stands alone (no pronouns like "it" or "this")
- 50-150 characters target
- Focus on searchable technical details

## 4. NARRATIVE (512-1024 tokens, same as current format)
The full contextual story for deep dives:

"In the {{project}} project, [action taken]. [Technical details: files, functions, concepts]. [Why this matters]."

This is the detailed explanation for when someone needs full context.

# STORAGE COMMAND FORMAT

Store using this EXACT bash command structure:
\`\`\`bash
claude-mem store-memory \\
  --id "{{project}}_{{sessionId}}_{{date}}_001" \\
  --title "Your Title Here" \\
  --subtitle "Your concise subtitle here" \\
  --facts '["Fact 1 here", "Fact 2 here", "Fact 3 here"]' \\
  --concepts '["concept1", "concept2", "concept3"]' \\
  --files '["path/to/file1.js", "path/to/file2.ts"]' \\
  --project "{{project}}" \\
  --session "{{sessionId}}" \\
  --date "{{date}}"
\`\`\`

CRITICAL FORMATTING RULES:
- Use single quotes around JSON arrays: --facts '["item1", "item2"]'
- Use double quotes inside the JSON arrays: "item"
- Use double quotes around simple string values: --title "Title"
- Escape any quotes in the content properly
- Sequential numbering: 001, 002, 003, etc.

Concepts: 2-5 broad categories (e.g., "hooks", "storage", "async-processing")
Files: Actual file paths touched (e.g., "hooks/stop-streaming.js")

# EXAMPLE MEMORY

Tool response shows: [Read file hooks/stop-streaming.js with 167 lines of code implementing SDK cleanup]

Your storage command:
\`\`\`bash
claude-mem store-memory \\
  --id "claude-mem_abc123_2025-10-01_001" \\
  --title "SDK Transcript Auto-Cleanup" \\
  --subtitle "Automatic deletion of SDK transcripts after completion prevents memory conversations from appearing in UI history" \\
  --facts '["stop-streaming.js: Deletes SDK transcript after overview generation", "Path: ~/.claude/projects/{sanitized-cwd}/{sessionId}.jsonl", "Uses fs.unlink with error handling for missing files", "Prevents memory conversations from polluting Claude Code UI"]' \\
  --concepts '["cleanup", "SDK-lifecycle", "UX", "file-management"]' \\
  --files '["hooks/stop-streaming.js"]' \\
  --project "claude-mem" \\
  --session "abc123" \\
  --date "2025-10-01"
\`\`\`

# STATE TRACKING

CRITICAL: Keep track of your memory counter across all tool messages.
- Start at 001
- Increment for each stored memory
- Never repeat numbers
- Each session has separate numbering

# SESSION END

At the end (when I send "SESSION ENDING"), generate an overview using:
\`\`\`bash
claude-mem store-overview --project "{{project}}" --session "{{sessionId}}" --content "2-3 sentence overview"
\`\`\`

# IMPORTANT REMINDERS

- You're processing a DIFFERENT Claude Code session (not your own)
- Use Bash tool to call claude-mem commands
- Keep subtitles clear and informative (max 24 words)
- Each fact is ONE specific thing (not multiple ideas)
- Be selective - quality over quantity
- Always increment memory numbers
- Facts should be searchable (specific file names, paths, functions)

Ready for tool responses.`;

// =============================================================================
// PHASE 2: TOOL MESSAGE (post-tool-use-streaming.js)
// =============================================================================

/**
 * Message format for each tool response sent to the SDK.
 * The SDK analyzes this and decides whether to store a memory.
 *
 * Variables:
 * - {{timeFormatted}}: Time portion of timestamp (HH:MM:SS)
 * - {{toolName}}: Name of the tool that was used
 * - {{userPrompt}}: User's original prompt (truncated to 200 chars)
 * - {{toolResponse}}: Full tool response (truncated to 20000 chars)
 */
export const TOOL_MESSAGE = `# Tool Response {{timeFormatted}}

Tool: {{toolName}}
User Context: "{{userPrompt}}"

\`\`\`
{{toolResponse}}
\`\`\`

Analyze and store if meaningful.`;

// =============================================================================
// PHASE 3: END MESSAGE (stop-streaming.js)
// =============================================================================

/**
 * Message sent to SDK when session ends.
 * Requests the SDK to generate and store a session overview.
 *
 * Variables:
 * - {{project}}: Project name
 * - {{sessionId}}: Claude Code session ID
 */
export const END_MESSAGE = `# SESSION ENDING

Review our entire conversation. Generate a concise 2-3 sentence overview of what was accomplished.

Store it using Bash:
\`\`\`bash
claude-mem store-overview --project "{{project}}" --session "{{sessionId}}" --content "YOUR_OVERVIEW_HERE"
\`\`\`

Focus on: what was done, current state, key decisions, outcomes.`;

// =============================================================================
// EXPORTS
// =============================================================================

export const PROMPTS = {
  system: SYSTEM_PROMPT,
  tool: TOOL_MESSAGE,
  end: END_MESSAGE,
} as const;