Architectural Overview
The primary interface for persistence is theJournalStore struct, which manages a connection to a SQLite database crates/palyra-daemon/src/journal.rs#63-71. It handles the storage of several distinct data domains:
- The Tape: A linear, immutable log of events for every agent run.
- Approvals: A registry of human-in-the-loop tool execution decisions.
- Memory: A vector-capable store for long-term information retrieval.
- Cron & Schedules: Persistence for background routines and their execution history.
- Canvas: State snapshots and patches for the Agent-to-User Interface (A2UI).
Persistence Data Flow
The following diagram illustrates how an event (such as an LLM response or a tool execution) moves from theGatewayRuntimeState into the JournalStore.
Figure 1: Event Persistence Flow
Sources: crates/palyra-daemon/src/gateway.rs#132-146, crates/palyra-daemon/src/journal.rs#63-71
The Tape: Append-Only Event Log
The Tape represents the ground truth of a session. Every interaction—user messages, assistant thoughts, tool calls, and tool outputs—is recorded as aJournalEventRecord.
Hash Chaining and Auditability
To prevent tampering, the Journal Store can be configured with hash chaining enabled crates/palyra-daemon/src/transport/grpc/services/gateway/service.rs#155-158. Each event includes a SHA-256 hash that incorporates the hash of the previous event, creating a verifiable ledger. Key attributes of a Tape event include:event_id: A unique ULID crates/palyra-daemon/src/transport/grpc/services/gateway/service.rs#111-117.actor: Identifies if the event was generated by a User, Assistant, or System crates/palyra-daemon/src/transport/grpc/services/gateway/service.rs#128-130.payload_json: The raw data of the event, which is automatically redacted if it contains sensitive keys likeapi_keyorpasswordcrates/palyra-daemon/src/journal.rs#29-44.
Long-Term Memory and Vector Search
Palyra implements a “Memory” system that allows agents to store and retrieve facts across different sessions. This is implemented via theMemoryItem entities in the JournalStore.
Embedding Providers
The system uses aMemoryEmbeddingProvider trait to generate vector representations of text crates/palyra-daemon/src/journal.rs#64-68.
- Default Provider:
HashMemoryEmbeddingProvidercreates a 64-dimension vector using a deterministic hashing algorithm crates/palyra-daemon/src/journal.rs#71-79. - Search: Memory retrieval uses a combination of SQLite
FTS5for keyword matching and cosine similarity (or Euclidean distance) on vector embeddings for semantic retrieval.
| Component | Implementation | File Reference |
|---|---|---|
| Search Request | MemorySearchRequest | crates/palyra-daemon/src/gateway.rs#66 |
| Search Logic | JournalStore::search_memory | crates/palyra-daemon/src/journal.rs#64-67 |
| Retention | MemoryRetentionPolicy | crates/palyra-daemon/src/gateway.rs#66 |
Approvals and Governance
TheJournalStore persists ApprovalRecord entities, which track the lifecycle of sensitive tool executions.
Figure 2: Approval State Persistence
Sources: crates/palyra-daemon/src/transport/grpc/services/gateway/service.rs#36-41, crates/palyra-daemon/src/gateway.rs#57-59
Full-Text Search (FTS5)
The Journal Store utilizes SQLite’sFTS5 extension to provide high-performance search across sessions and memory items. This allows the Web Console to filter the “Session Catalog” by keywords crates/palyra-daemon/src/transport/http/handlers/console/sessions.rs#144-156.
- Session Indexing: Metadata such as session titles and last intents are indexed.
- Memory Indexing: The content of memory items is indexed alongside their vector embeddings.
Technical Constraints and Limits
To ensure system stability and performance, the Journal Store enforces several hard limits:| Limit | Value | Code Reference |
|---|---|---|
| Write Latency Budget | 25ms | crates/palyra-daemon/src/gateway.rs#92 |
| Max Recent Events | 100 | crates/palyra-daemon/src/gateway.rs#89 |
| Max Memory Item Size | 16 KB | crates/palyra-daemon/src/gateway.rs#118 |
| Max Memory Tokens | 2,048 | crates/palyra-daemon/src/gateway.rs#119 |
| Max Canvas Snapshots | 10,000 | crates/palyra-daemon/src/gateway.rs#139 |