Automation Hooks

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

Hosted Core + Thin Edge Runtime

Snipara keeps the durable logic hosted. Hooks, local scripts, and compatibility CLIs form a thin edge runtime that captures local lifecycle signals and forwards them to the hosted automation layer.

The edge can observe, normalize, inject, and forward.
The hosted core keeps review queues, memory policy, recall, and orchestration.
This keeps automation inspectable instead of burying business rules in shell hooks.

All Plans

Automation hooks are available on all plans, including Free.

Agents Starter+ Unlocks Reviewable Memory

Memory capture, transcript import, and inbox review policies are part of Snipara Agents. Use them when hooks should produce durable memory instead of only local checkpoints.

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:

┌─────────────────────────────────────────────────────────────┐
│  AUTOMATION FLOW                                             │
│                                                             │
│  1. SessionStart restores checkpoint + approved memory      │
│  2. PreToolUse / PostToolUse keep context in sync           │
│  3. Commit hook captures durable outcomes from work         │
│  4. Project policy decides AUTO vs INBOX review             │
│  5. Import Transcript can bootstrap historical context      │
│  6. Future sessions recall only approved durable memory     │
└─────────────────────────────────────────────────────────────┘

Supported Hooks

PreCompact

Triggered before context compaction. Receives session summary via stdin. Use this to save important context that should survive the compaction.

context-checkpoint.sh

SessionStart

Triggered when starting a session after compaction or resume. Output is injected as additional context for the LLM.

session-restore.sh

PostToolUse

Triggered after a tool completes. Use with Bash matcher to save context on git commits.

commit-memory.sh

Agents Starter+

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.

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

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

{
  "events": [
    {
      "type": "tool_call",
      "client": "rlm-hook",
      "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

Supported AI Clients

Client	Config File	PreCompact	SessionStart	Notes
Claude Code	`.claude/settings.json`	Full	Full	Best support
Cursor	`.cursor/mcp.json`	Full	Full	v1.7+ required
Continue	`.continue/config.json`	Via MCP	Via MCP	Use rlm_inject
Windsurf	`.windsurf/mcp.json`	-	-	No hook support
Gemini	`.gemini/settings.json`	Via MCP	Via MCP	Use rlm_inject
VS Code Copilot	`.vscode/mcp.json`	-	-	No hook support yet

Quick Setup (Claude Code)

Required Dependencies:

bash (v4+) - Pre-installed on macOS/Linux
jq - JSON processor: brew install jq (macOS) or apt install jq (Linux)

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/settings.json should look like this:

  "mcpServers": {

    "your-project": {

      "transport": "http",

      "url": "https://api.snipara.com/mcp/your-project",

      "headers": { "X-API-Key": "rlm_..." }

},

  "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

Agents Starter+ Required: Memory Injection requires the Agents Starter+ subscription ($15/month).

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 CAPTURE FLOW                                         │
│                                                             │
│  SessionStart:                                              │
│  1. Hook fetches project memory policy                      │
│  2. Calls rlm_session_memories / rlm_recall                 │
│  3. Injects approved durable memory                         │
│                                                             │
│  During Session / Commit:                                   │
│  4. Hooks call rlm_remember_if_novel or                     │
│     rlm_end_of_task_commit                                  │
│  5. AUTO policy approves immediately                        │
│  6. INBOX policy routes captures to pending review          │
│                                                             │
│  Bootstrap:                                                 │
│  7. Import Transcript previews candidates before import     │
└─────────────────────────────────────────────────────────────┘

Memory Types

Type	Use Case
`FACT`	Project-specific knowledge
`DECISION`	Architectural or implementation choices
`LEARNING`	Discovered patterns or behaviors
`PREFERENCE`	User preferences
`TODO`	Task items and reminders
`CONTEXT`	Session context (auto-saved by hooks)

Auto-Save on Commit

CLI Only: PostToolUse hooks currently work in the Claude Code CLI, not the VSCode extension. Use the CLI (claude command) to enable this feature.

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.

┌─────────────────────────────────────────────────────────────┐
│  COMMIT CAPTURE FLOW                                        │
│                                                             │
│  1. User runs: git commit -m "feat: add auth"               │
│  2. Claude Code executes the Bash tool                      │
│  3. PostToolUse hook triggers for Bash tool                 │
│  4. Hook checks if command contains "git commit"            │
│  5. Hook calls rlm_end_of_task_commit or                    │
│     rlm_remember_if_novel via MCP                           │
│  6. Project policy routes write to AUTO or INBOX            │
│  7. Next session recalls only approved durable memory       │
└─────────────────────────────────────────────────────────────┘

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

Mode	Behavior	Best For
`AUTO`	Automated memory writes are approved immediately and can be recalled later.	Trusted automation with low review overhead
`INBOX`	Automated writes land as `PENDING` and stay out of recall/session bootstrap until approved.	Teams that want human review before memories become durable

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: rlm_...

{
  "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: rlm_...

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: rlm_your_key" \

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

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

Troubleshooting

Issue	Cause	Solution
"Invalid API key"	API key not found	Regenerate key from dashboard
"API key does not match project"	Key belongs to different project	Use correct key for project
"Project not found"	Invalid slug/ID in URL	Verify project slug in dashboard
Hook not triggering	Scripts not executable	`chmod +x .claude/hooks/*.sh`
Empty context restored	Checkpoint file missing	Check `.claude/.session-context` exists
jq not found	jq not installed	Install jq: `brew install jq`

Failure Modes & Recovery

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

Scenario	Behavior	Recovery
jq not installed	SessionStart outputs raw text instead of JSON	Install jq or use rlm_inject fallback
Cloud sync fails	Local checkpoint still saved	Context persists locally; cloud sync retries next compaction
Hook script errors	LLM continues without restored context	Run scripts manually to debug: `bash .claude/hooks/session-restore.sh`
Permission denied	Hook fails silently	Run `chmod +x .claude/hooks/*.sh`

Manual Injection Fallback

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

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

rlm_inject

Inject context into the current session. Use this before compaction to save important context.

rlm_inject("Working on auth refactor")

rlm_context

View current session context. Check what context is currently stored.

rlm_context()

Next Steps

GitHub Auto-Sync

Keep documentation automatically synced with your repository.

Shared Context

Share coding standards across your team.

Integration Guide

Complete setup guide for all supported AI clients.

Configure Automation

Go to your dashboard to generate hook configurations.