Automation Hooks

Use automation hooks to preserve session context, capture reviewable outcome candidates, 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"
      }
    }
  ]
}

Canonical events are dual-written behind this contract: a short-term checkpoint receipt is kept for compatibility, while a dedicated execution trace store preserves the durable runtime history used by replay and historical reads.

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.

Execution Memory Snapshot

Raw events are only one part of coding-agent continuity. Snipara also exposes an execution memory snapshot that groups canonical events, manual checkpoints, and session context by session so dashboard users can resume work, inspect historical cutoffs, and avoid replaying a full transcript.

GET /api/projects/{project}/automation/execution-memory?limit=6&eventLimit=8&before=2026-05-25T09:00:00.000Z

This surface is intentionally operational. It helps with handoff, stuck-debugging, and return-to-work context. Reviewed memory remains the place for durable decisions, learnings, and preferences.

The payload stays stable while the backend evolves: time-travel and replay now come from a long-retention execution trace store, not only from short-lived checkpoint rows.

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 reviewable outcome candidates when a git commit is made. The capture produces review-pending candidates first, so work is preserved without making it durable until policy or a reviewer approves it.

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 Journal Checkpoint 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.

To resolve review-pending candidates locally, use snipara-companion Decision Requests: workflow decisions lists pending questions, workflow decide records the reviewer receipt, and memory reviews --emit-decisions emits Decision Requests from hosted memory review candidates.

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

The automation/inject route is an authenticated hook API documented for agent integrations. Treat the project id, API key, and session id as scoped credentials; do not expose them in public logs or client-side code.

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