palyrad). It provides a unified interface for persisting orchestrator sessions, event logs, cron jobs, workspace documents, and memory items. The system is built on SQLite and emphasizes auditability through cryptographic hash chaining of events.
JournalStore Architecture
TheJournalStore is the primary handle for database operations. It manages a rusqlite::Connection and provides methods for transactional updates to the underlying schema.
Key Components
- SQLite Backend: Uses a local file (default:
data/journal.sqlite3) with WAL (Write-Ahead Logging) mode for concurrent access crates/palyra-daemon/src/config/schema.rs#34-34. - Hash Chaining: When enabled, every event appended to the journal includes a
parent_hash, creating an immutable audit trail crates/palyra-daemon/src/config/schema.rs#35-35. - ULID Identifiers: All records use Universally Unique Lexicographically Sortable Identifiers (ULIDs) for primary keys to ensure time-based ordering and uniqueness crates/palyra-daemon/src/journal.rs#17-17.
Code Entity Mapping: Persistence Core
The following diagram bridges the high-level persistence concepts to the specific Rust structs and database tables. Sources: crates/palyra-daemon/src/journal.rs#19-71, crates/palyra-daemon/src/config/schema.rs#34-35Schema & Tables
1. Journal Events (journal_events)
The journal_events table stores the “Tape” of an orchestrator run. It captures every message, tool call, and state transition.
- Auditability: Each record contains an
event_hash(SHA-256) which covers the event type, payload, and theparent_hashof the preceding event crates/palyra-daemon/src/journal.rs#16-16. - Redaction: Sensitive keys (e.g.,
api_key,password) are automatically redacted before being committed to the journal crates/palyra-daemon/src/journal.rs#29-45.
2. Orchestrator Sessions (orchestrator_sessions)
Stores the metadata for long-running agent interactions.
- Fields:
session_id,owner_principal,status, andusage_deltacrates/palyra-daemon/src/gateway.rs#67-68. - Lifecycle: Managed via
RunStateMachinewhich transitions sessions betweenRunning,Completed, andFailedcrates/palyra-daemon/src/gateway.rs#77-77.
3. Cron Jobs (cron_jobs)
Handles scheduled tasks and recurring agent runs.
- Schedule Types: Supports
Cron(standard expression),Every(interval), andAt(one-time) crates/palyra-daemon/src/journal.rs#102-108. - Concurrency Policies: Defines behavior when a job triggers while a previous instance is still running:
Forbid,Replace, orQueueOnecrates/palyra-daemon/src/journal.rs#132-136.
4. Workspace Documents (workspace_documents)
Persists the state of the shared file space used by agents during a session.
- Integrity: Includes
scan_workspace_content_for_prompt_injectionto prevent malicious content from being loaded into model context crates/palyra-daemon/src/journal.rs#22-23.
Data Flow: Event Appending
When the Gateway receives a message or an Orchestrator executes a tool, the data flows through theJournalStore to ensure durability before any response is sent.
Sources: crates/palyra-daemon/src/gateway.rs#63-63, crates/palyra-daemon/src/journal.rs#16-17
Memory & Vector Persistence
The journal also handles the persistence of the RAG (Retrieval-Augmented Generation) system.- MemoryItemRecord: Stores text chunks, metadata, and a
vector_embeddingcrates/palyra-daemon/src/journal.rs#64-66. - Embedding Provider: Uses
HashMemoryEmbeddingProviderby default for deterministic testing, but supports pluggable providers for actual vector generation crates/palyra-daemon/src/journal.rs#71-80. - Retention: A background maintenance task (triggered via
Cron) enforcesMemoryRetentionPolicy, purging items based on TTL or capacity limits crates/palyra-daemon/src/journal.rs#56-57.
Migrations & Configuration
The persistence layer includes a migration system to handle schema updates without data loss.- Version Tracking: The
journalschema version is stored within the database itself. - Config Migration: The
palyra-daemonusesparse_document_with_migrationto upgradepalyra.tomlfiles when new mandatory fields are added crates/palyra-daemon/src/config/load.rs#9-11. - Safety: The
JournalStorevalidates the database file path and permissions on startup, ensuring the daemon has write access to its storage root crates/palyra-daemon/src/journal.rs#9-10.