Struct StateStore 

pub struct StateStore { /* private fields */ }

Persistent storage for conversation threads, messages, checkpoints, and jobs.

Backed by a SQLite database and an append-only JSONL session index file. The database schema is automatically initialized and migrated on open.

Implementations

impl StateStore

pub fn open(path: Option<PathBuf>) -> Result<Self>

Open (or create) a state store at the given database path.

If path is None, the default location (~/.deepseek/state.db) is used. The database schema is created automatically if it does not exist.

pub fn db_path(&self) -> &Path

Returns the filesystem path of the underlying SQLite database.

pub fn upsert_thread(&self, thread: &ThreadMetadata) -> Result<()>

Insert or update thread metadata.

This does not update current_leaf_id; use append_message or set_current_leaf_id for that.

pub fn get_thread(&self, id: &str) -> Result<Option<ThreadMetadata>>

Retrieve a single thread by its ID.

Returns None if no thread with the given ID exists.

pub fn list_threads( &self, filters: ThreadListFilters, ) -> Result<Vec<ThreadMetadata>>

List threads ordered by most recently updated.

Use ThreadListFilters to control whether archived threads are included and the maximum number of results returned.

pub fn mark_archived(&self, id: &str) -> Result<()>

Archive a thread, setting its status to ThreadStatus::Archived and recording the current timestamp.

pub fn mark_unarchived(&self, id: &str) -> Result<()>

Unarchive a thread, removing the archived flag and clearing archived_at.

pub fn delete_thread(&self, id: &str) -> Result<()>

Permanently delete a thread and all of its associated data (messages, checkpoints, dynamic tools) via cascading foreign keys.

pub fn set_thread_memory_mode(&self, id: &str, mode: Option<&str>) -> Result<()>

Set the memory mode for a thread.

Pass None to clear the memory mode.

pub fn get_thread_memory_mode(&self, id: &str) -> Result<Option<String>>

Get the memory mode configured for a thread.

Returns None if the thread does not exist or has no memory mode set.

pub fn list_leaf_messages(&self, thread_id: &str) -> Result<Vec<MessageRecord>>

List all leaf messages in a thread.

A leaf message is one that has no other message referencing it as a parent. In a branching conversation tree, there may be multiple leaf messages.

pub fn set_current_leaf_id( &self, thread_id: &str, current_leaf_id: &str, ) -> Result<()>

Update the current leaf message pointer for a thread.

This controls which branch of the conversation tree is considered active when listing messages via list_messages.

pub fn persist_dynamic_tools( &self, thread_id: &str, tools: &[DynamicToolRecord], ) -> Result<()>

Replace the dynamic tools for a thread.

All existing dynamic tools for the thread are deleted and replaced with the provided list. The operation is performed within a transaction.

pub fn get_dynamic_tools( &self, thread_id: &str, ) -> Result<Vec<DynamicToolRecord>>

Retrieve all dynamic tools registered for a thread, ordered by position.

pub fn append_message( &self, thread_id: &str, role: &str, content: &str, item: Option<Value>, ) -> Result<i64>

Append a new message to a thread.

The message is linked to the thread’s current leaf as its parent, and the thread’s current_leaf_id is updated to the new message. Returns the ID of the newly created message.

pub fn list_messages( &self, thread_id: &str, limit: Option<usize>, ) -> Result<Vec<MessageRecord>>

List messages in the current conversation branch, walking backwards from the thread’s current_leaf_id.

Messages are returned in chronological order (oldest first). The limit parameter caps how many ancestor messages are traversed; it defaults to 500.

pub fn fork_at_message( &self, message_id: &str, role: &str, content: &str, item: Option<Value>, ) -> Result<i64>

Fork the conversation at a specific message.

Creates a new message whose parent is message_id and updates the thread’s current_leaf_id to the new message. Returns the ID of the new message. This enables branching conversations from any point in the history.

pub fn clear_messages(&self, thread_id: &str) -> Result<usize>

Delete all messages belonging to a thread and reset its current_leaf_id.

Returns the number of messages deleted.

pub fn save_checkpoint( &self, thread_id: &str, checkpoint_id: &str, state: &Value, ) -> Result<()>

Save (or update) a named checkpoint for a thread.

If a checkpoint with the same thread_id and checkpoint_id already exists, its state and timestamp are overwritten.

pub fn load_checkpoint( &self, thread_id: &str, checkpoint_id: Option<&str>, ) -> Result<Option<CheckpointRecord>>

Load a checkpoint for a thread.

If checkpoint_id is provided, loads that specific checkpoint. Otherwise, loads the most recently created checkpoint for the thread. Returns None if no matching checkpoint exists.

pub fn list_checkpoints( &self, thread_id: &str, limit: Option<usize>, ) -> Result<Vec<CheckpointRecord>>

List checkpoints for a thread, ordered by creation time (newest first).

The limit parameter caps the number of results and defaults to 100.

pub fn delete_checkpoint( &self, thread_id: &str, checkpoint_id: &str, ) -> Result<()>

Delete a specific checkpoint from a thread.

pub fn upsert_job(&self, job: &JobStateRecord) -> Result<()>

Insert or update a background job record.

pub fn get_job(&self, id: &str) -> Result<Option<JobStateRecord>>

Retrieve a single job by its ID.

Returns None if no job with the given ID exists.

pub fn list_jobs(&self, limit: Option<usize>) -> Result<Vec<JobStateRecord>>

List jobs ordered by most recently updated.

The limit parameter caps the number of results and defaults to 100.

pub fn delete_job(&self, id: &str) -> Result<()>

Permanently delete a job record.

pub fn find_rollout_path_by_id(&self, id: &str) -> Result<Option<PathBuf>>

Look up the rollout file path for a thread by its ID.

pub fn append_thread_name( &self, thread_id: &str, thread_name: Option<String>, updated_at: i64, rollout_path: Option<PathBuf>, ) -> Result<()>

Append an entry to the JSONL session index file.

The session index is an append-only log that maps thread IDs to their names, update timestamps, and rollout paths. It is used for fast name-based lookups without opening the SQLite database.

pub fn find_thread_name_by_id(&self, thread_id: &str) -> Result<Option<String>>

Find the display name for a thread by its ID, using the session index.

Returns None if the thread is not in the index or has no name.

pub fn find_thread_names_by_ids( &self, ids: &[String], ) -> Result<HashMap<String, Option<String>>>

Look up display names for multiple thread IDs at once.

Returns a map from thread ID to its name (which may be None).

pub fn find_thread_path_by_name_str( &self, name: &str, ) -> Result<Option<PathBuf>>

Find the rollout path for a thread by its display name (case-insensitive).

If multiple threads share the same name, the most recently updated one is returned. Returns None if no matching thread is found.

Trait Implementations

impl Clone for StateStore

fn clone(&self) -> StateStore

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StateStore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.