Database

Snippbot uses SQLite for all persistence. Each subsystem has its own database file to avoid schema conflicts and allow independent migration.

Database files

File	Path	Contents
`main.db`	`~/.snippbot/main.db`	Agents, projects, tasks, chat history
`scheduler.db`	`~/.snippbot/scheduler.db`	Jobs, runs, chains, activity patterns
`workflows.db`	`~/.snippbot/workflows.db`	Workflow definitions, runs, templates
`hooks.db`	`~/.snippbot/hooks.db`	Hooks, deliveries, webhook endpoints
`channels.db`	`~/.snippbot/channels.db`	Platform credentials, bindings, access rules
`skills.db`	`~/.snippbot/skills.db`	Tool registry, MCP server configs
`devices.db`	`~/.snippbot/devices.db`	Device registrations, execution history
`memory_{agent_id}.db`	`~/.snippbot/agents/{id}/`	Episodic memory, knowledge graph

| profile_settings.db | ~/.snippbot/profile_settings.db | User profile (display name, theme, avatar) |

Migrations

Database migrations run automatically on daemon startup. Each database file has a schema_version table tracking the applied migration version.

If a migration fails, the daemon logs the error and exits. To diagnose:

tail -50 ~/.snippbot/logs/daemon.log | grep -i migrat

Pre-upgrade backups are saved automatically to ~/.snippbot/backups/ before each migration.

Key tables

`agents`

The runtime roster of agents. This table is not the canonical agent definition: an agent’s identity (name, handle, bio, expertise) is a synced projection of its workspace IDENTITY.md, refreshed by agent_sync on startup; only the runtime-customization columns (preferred model, avatar, custom system prompt, tool profile) are owned here. The canonical definition lives in the workspace files (IDENTITY.md + companions). A marketplace install also drops an agent.json provenance backlink in the agent’s directory — that file is not a definition source and is not read at runtime.

Column	Type	Description
`id`	TEXT PK	UUID
`name`	TEXT	Display name
`archetype`	TEXT	One of 10 archetypes
`model`	TEXT	LLM model ID
`system_prompt`	TEXT	Custom instructions
`tools_config`	TEXT	JSON — enabled tools
`memory_config`	TEXT	JSON — memory settings
`trust_score`	REAL	0.0–1.0
`created_at`	TEXT	ISO 8601
`updated_at`	TEXT	ISO 8601

`projects`

Column	Type	Description
`id`	TEXT PK	UUID
`name`	TEXT	Project name
`goal`	TEXT	High-level goal
`status`	TEXT	`pending`, `planning`, `in_progress`, `paused`, `completed`, `failed`
`agent_id`	TEXT FK	Assigned agent
`execution_strategy`	TEXT	`sequential`, `parallel`, `dag`
`created_at`	TEXT	ISO 8601

`tasks`

Column	Type	Description
`id`	TEXT PK	UUID
`project_id`	TEXT FK	Parent project
`title`	TEXT	Task title
`description`	TEXT	Detailed description
`status`	TEXT	`pending`, `running`, `completed`, `failed`, `skipped`
`depends_on`	TEXT	JSON array of task IDs
`result`	TEXT	Task output
`error`	TEXT	Error message if failed
`started_at`	TEXT	ISO 8601
`completed_at`	TEXT	ISO 8601

`scheduled_jobs`

Column	Type	Description
`id`	TEXT PK	UUID
`name`	TEXT	Job name
`goal`	TEXT	Agent goal
`agent_id`	TEXT FK	Executing agent
`schedule_config`	TEXT	JSON — type, expression, timezone
`delivery_config`	TEXT	JSON — channel, format
`retry_config`	TEXT	JSON — attempts, strategy
`condition_config`	TEXT	JSON — condition type, expression
`status`	TEXT	`active`, `paused`, `completed`, `failed`
`run_count`	INTEGER	Total runs
`next_run_at`	TEXT	Next scheduled time
`last_run_at`	TEXT	Last execution time

`job_runs`

Column	Type	Description
`id`	TEXT PK	UUID
`job_id`	TEXT FK	Parent job
`status`	TEXT	`running`, `completed`, `failed`, `cancelled`
`trigger_time`	TEXT	When the job was supposed to fire
`started_at`	TEXT	Actual start time
`completed_at`	TEXT	End time
`output`	TEXT	Agent result
`error`	TEXT	Error if failed
`attempt`	INTEGER	Retry attempt number

`channel_credentials`

Column	Type	Description
`platform`	TEXT PK	Platform ID (`slack`, `discord`, etc.)
`encrypted_data`	BLOB	Fernet-encrypted JSON of credentials
`preview`	TEXT	Masked preview for display
`created_at`	TEXT	ISO 8601
`updated_at`	TEXT	ISO 8601

`channel_bindings`

Column	Type	Description
`id`	TEXT PK	UUID
`platform`	TEXT	Platform ID
`channel_id`	TEXT	Platform channel ID
`channel_name`	TEXT	Display name
`agent_id`	TEXT FK	Bound agent
`access_mode`	TEXT	`open`, `allowlist`, `admin_only`
`enabled`	INTEGER	1 = active

`hooks`

Column	Type	Description
`id`	TEXT PK	UUID
`name`	TEXT	Hook name
`event`	TEXT	Event type to subscribe to
`type`	TEXT	`webhook`, `script`, `announcement`, `chain`
`config`	TEXT	JSON — URL, secret, code, etc.
`condition`	TEXT	Optional filter expression
`enabled`	INTEGER	1 = active

`hook_deliveries`

Column	Type	Description
`id`	TEXT PK	UUID
`hook_id`	TEXT FK	Parent hook
`event_type`	TEXT	Event that triggered
`status`	TEXT	`success`, `failed`, `pending`
`attempt`	INTEGER	Attempt number
`response_code`	INTEGER	HTTP status (for webhooks)
`latency_ms`	INTEGER	Round-trip time
`delivered_at`	TEXT	ISO 8601

SQLite pragmas

All databases use these pragmas for performance and safety:

PRAGMA journal_mode = WAL;    -- Write-ahead logging for concurrent reads
PRAGMA synchronous = NORMAL;  -- Balance safety and performance
PRAGMA foreign_keys = ON;     -- Enforce referential integrity
PRAGMA cache_size = -64000;   -- 64 MB cache

Backup and restore

# List backups
snippbot reset --list-backups

# Restore from backup
snippbot reset --restore pre-upgrade-2026-03-01

Automatic backups are created before each migration and can also be scheduled via a cron job pointing to ~/.snippbot/.