State Persistence

Sheriff maintains persistent state to track your progress across sessions, context compaction, and agent switches.

Storage Location

State is stored in the .sheriff/ directory (relative to the working directory):

.sheriff/
├── sheriff.mv.db        # H2 database with issues and progress
├── sheriff.log          # Application logs
└── sheriff.*.log.gz     # Rotated log archives

What’s Persisted

Issue Data

All issues from the loaded SARIF file
Fingerprints (unique identifiers)
Locations, messages, severities
Code snippets

Progress State

Which issues are marked fixed (F)
Which issues are marked skipped (S)
Which issues are still pending (P)

Session Metadata

Loaded SARIF filename
Content hash for change detection
Timestamp of last load

Persistence Behavior

Context Compaction

When your AI agent’s context compacts (truncates old messages), your progress is safe:

Agent context compacts
Agent calls sheriff load target="same.sarif"
Sheriff detects same content hash
Previous progress is restored
Agent continues where it left off

Session Restart

When you restart Claude Code or your MCP client:

Sheriff server restarts
Agent calls sheriff load target="same.sarif"
Previous progress is restored
Agent continues from last checkpoint

Agent Switch

When switching between AI agents:

First agent makes progress
Session ends
Second agent starts, calls sheriff load
First agent’s progress is preserved
Second agent continues

Content Hash Detection

Sheriff uses content hashing to detect SARIF changes:

qodana.sarif.json → SHA-256 hash → matches stored hash?
  ↓                                    ↓
Same content                      Different content
  ↓                                    ↓
Restore progress                  Clear old, start fresh

SARIF Reload

When a new SARIF file is loaded (different content):

Prior progress counts are captured for the response
Issues and progress tables are cleared
New issues are loaded from the updated SARIF

Database Schema

Sheriff uses H2 embedded database with three tables:

Meta Table

Key-value store for session metadata and internal state (SARIF path, content hash, timestamps, schema version).

Column	Type	Description
`key`	VARCHAR(255)	Primary key
`value`	VARCHAR(4096)	Metadata value

Issues Table

Column	Type	Description
`fp`	VARCHAR(64)	Primary key (fingerprint)
`rule`	VARCHAR(255) NOT NULL	Rule that flagged issue
`file`	VARCHAR(4096) NOT NULL	Source file path
`line`	INT	Line number
`col`	INT	Column number
`msg`	TEXT	Issue description
`sev`	CHAR(1)	Severity: `H`/`M`/`L`
`snip`	TEXT	Code snippet
`ctx`	TEXT	Context lines

Progress Table

Column	Type	Description
`fp`	VARCHAR(64)	Primary key (fingerprint)
`status`	CHAR(1) NOT NULL	`F` (fixed), `S` (skipped)
`ts`	TIMESTAMP DEFAULT CURRENT_TIMESTAMP	When the status was set
`note`	TEXT	Optional note

Indexes

Index	Table	Column
`idx_issues_rule`	issues	rule
`idx_issues_file`	issues	file
`idx_issues_sev`	issues	sev
`idx_progress_status`	progress	status

Troubleshooting

Corrupted State

If state becomes corrupted:

rm -rf .sheriff/

Then reload the SARIF file to start fresh.

Wrong Progress Restored

If wrong progress is restored (from old session):

Check that SARIF content hasn’t changed
If it has, the old progress won’t apply
Delete .sheriff/ and reload

Database Locked

If you see “database locked” errors:

Check for other Sheriff processes
Kill any zombie Java processes holding the file lock
If needed, delete .sheriff/ and reload