Automation Hooks

Use automation hooks to preserve session context, capture durable outcomes, and reload only the memories that should survive into the next session.

What Are Automation Hooks?

When your LLM's context window fills up, it performs a "compaction" - summarizing the conversation to free up space. Without hooks, you lose important context like what files were accessed, what decisions were made, and what the current task is.

Automation hooks let you save, review, and restore context automatically:

Supported Hooks

Canonical Event Ingestion

Hook adapters and local compatibility CLIs can now forward normalized lifecycle events into Snipara over the automation API. This is the preferred way to get closer to local-memory products without moving review or durable memory policy out of Snipara.

snipara-companion emit-event --event-type tool_call --payload '{"hook":"pre-tool","tool":"Read"}'

POST /api/projects/{project}/automation/events

{
  "events": [
    {
      "type": "tool_call",
      "client": "snipara-companion",
      "workspace": "/workspace/app",
      "session_id": "sess_123",
      "agent_id": "local-agent",
      "timestamp": "2026-04-16T18:00:00.000Z",
      "privacy_level": "standard",
      "payload": {
        "hook": "pre-tool",
        "tool": "Read"
      }
    }
  ]
}

Current compatibility mapping:

• pre-tool forwards a canonical tool_call event
• post-tool forwards a canonical tool_result event
• session-end forwards a canonical session_end event

Inspecting Local Edge Events

Event forwarding is only half of the loop. The local companion can also read back recently ingested automation events so users can verify what their edge adapters actually sent.

snipara-companion events recent --limit 20

snipara-companion events recent --session-id sess_123

This is useful when debugging hook capture, checking which commands/files were forwarded, and confirming that the Snipara Sandbox edge is feeding the hosted automation layer correctly.

Supported AI Clients

Hook compatibility is agent-specific. Claude Code is the verified full-hook baseline. Codex, Cursor, Gemini CLI, and legacy Windsurf have compatible native or adapter-backed bundles where their clients expose useful lifecycle hooks. VS Code, ChatGPT, Continue, and custom MCP clients stay MCP-first unless their compatibility contract allows installation.

Select hook behavior in Snipara project settings, then install the compatible selected bundle locally with npx -y snipara-companion@latest automations install. Unsupported hook options are disabled instead of being written as broken local scripts.

Quick Setup (Claude Code)

Step 1: Generate Configuration

Go to your project's Automation page in the Snipara dashboard and enable the desired options:

• Preserve on Compaction: Save context when Claude compacts
• Restore on Session Start: Restore context after compaction
• Auto-Inject Context: Sync context to Snipara cloud

Download or copy the generated configuration files.

Step 2: Add Files to Your Project

Copy the generated files to your project root:

mkdir -p .claude/hooks

chmod +x .claude/hooks/*.sh

Step 3: Configuration Structure

Your Claude MCP server belongs in .mcp.json. Your .claude/settings.json should contain hooks only:

{

  "hooks": {

    "PreCompact": [{

      "matcher": "auto",

      "hooks": [{ "type": "command", "command": ".claude/hooks/context-checkpoint.sh" }]

    }],

    "SessionStart": [{

      "matcher": "compact",

      "hooks": [{ "type": "command", "command": ".claude/hooks/session-restore.sh" }]

    }]

  }

}

Hook Scripts

PreCompact Hook (context-checkpoint.sh)

This script runs before compaction and saves the session context:

#!/bin/bash

# Pre-Compaction Hook for Context Preservation

set -e

PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"

CHECKPOINT_FILE="$PROJECT_DIR/.claude/.session-context"

# Read context from stdin (Claude passes session summary)

CONTEXT=$(cat)

if [ -n "$CONTEXT" ]; then

  mkdir -p "$(dirname "$CHECKPOINT_FILE")"

  echo "$CONTEXT" > "$CHECKPOINT_FILE"

  echo "PreCompact: Checkpoint saved"

fi

SessionStart Hook (session-restore.sh)

This script runs after compaction and restores the saved context:

#!/bin/bash

# Session Restore Hook for Context Restoration

set -e

PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"

CHECKPOINT_FILE="$PROJECT_DIR/.claude/.session-context"

if [ -f "$CHECKPOINT_FILE" ]; then

  CONTEXT=$(cat "$CHECKPOINT_FILE")

  if [ -n "$CONTEXT" ]; then

    # Output JSON for Claude to inject as context

    jq -n --arg content "$CONTEXT" '{

      hookSpecificOutput: {

        hookEventName: "SessionStart",

        additionalContext: $content

      }

    }'

  fi

fi

Memory Capture & Review

Memory capture turns hook output into durable project memory. Instead of only saving raw context, hooks can store decisions, learnings, preferences, and workflow changes that are later recalled semantically.

Memory Types

Auto-Save on Commit

Automatically capture durable outcomes when a git commit is made. This ensures the work is preserved even if you close the session before compaction or handoff.

Hook Configuration:

{

  "hooks": {

    "PostToolUse": [{

      "matcher": "Bash",

      "hooks": [{

        "type": "command",

        "command": ".claude/hooks/commit-memory.sh",

        "timeout": 15

      }]

    }]

  }

}

Enable in your dashboard: Project → Automation → Memory Injection → Save Memory on Commit

Review Modes

Transcript Import Bootstrap

Use Import Transcript on the Memory page to paste a task transcript, retrospective, or handoff summary. Snipara previews durable candidates, classifies them, and imports them into the inbox for review.

• Extracts decisions, learnings, preferences, todos, and longer context fragments
• Deduplicates repeated lines before import
• Imports previewed candidates as pending review so they do not leak into recall early

Cloud Sync (Optional)

When Auto-Inject Context is enabled, the PreCompact hook syncs context to Snipara cloud, enabling cross-session persistence:

POST /api/projects/{project}/automation/inject
Content-Type: application/json
X-API-Key: snp-...

{
  "context": "Session context to store",
  "sessionId": "default",
  "append": false,
  "source": "hook"
}

The context can be retrieved later:

GET /api/projects/{project}/automation/inject?sessionId=default
X-API-Key: snp-...

Response:
{
  "success": true,
  "data": {
    "id": "ctx_123",
    "sessionId": "default",
    "context": "Stored context...",
    "updatedAt": "2025-01-20T..."
  }
}

Testing Your Setup

Test Local Checkpoint

echo '{"test": "context data"}' | bash .claude/hooks/context-checkpoint.sh

PreCompact: Context checkpoint saved (25 bytes)

Test Local Restore

bash .claude/hooks/session-restore.sh

{

  "hookSpecificOutput": {

    "hookEventName": "SessionStart",

    "additionalContext": "{\"test\": \"context data\"}"

  }

}

Test Cloud API

curl -s -X POST "https://www.snipara.com/api/projects/your-project/automation/inject" \

  -H "X-API-Key: snp-your-key" \

  -H "Content-Type: application/json" \

  -d '{"context": "Test context", "source": "manual"}'

Troubleshooting

Failure Modes & Recovery

Hooks are designed to fail gracefully. Here's what happens in common failure scenarios:

Manual Injection Fallback

If hooks aren't working, you can inject context manually via MCP tools:

snipara_inject({ context: "Working on auth refactor. Key files: auth.ts, middleware.ts" })

MCP Alternative

For clients without hook support, you can use MCP tools to manage context manually:

snipara_inject("Working on auth refactor")

snipara_context()

Next Steps