Struct SqliteStore 

pub struct SqliteStore { /* private fields */ }

Implementations

impl SqliteStore

pub async fn create_acp_session( &self, session_id: &str, ) -> Result<(), MemoryError>

Create a new ACP session record.

Errors

Returns an error if the database write fails.

pub async fn save_acp_event( &self, session_id: &str, event_type: &str, payload: &str, ) -> Result<(), MemoryError>

Persist a single ACP session event.

Errors

Returns an error if the database write fails.

pub async fn load_acp_events( &self, session_id: &str, ) -> Result<Vec<AcpSessionEvent>, MemoryError>

Load all events for an ACP session in insertion order.

Errors

Returns an error if the database query fails.

pub async fn delete_acp_session( &self, session_id: &str, ) -> Result<(), MemoryError>

Delete an ACP session and its events (cascade).

Errors

Returns an error if the database write fails.

pub async fn list_acp_sessions( &self, limit: usize, ) -> Result<Vec<AcpSessionInfo>, MemoryError>

List ACP sessions ordered by last activity descending.

Includes title, updated_at, and message count per session. Pass limit = 0 for unlimited results.

Errors

Returns an error if the database query fails.

pub async fn get_acp_session_info( &self, session_id: &str, ) -> Result<Option<AcpSessionInfo>, MemoryError>

Fetch metadata for a single ACP session.

Returns None if the session does not exist.

Errors

Returns an error if the database query fails.

pub async fn import_acp_events( &self, session_id: &str, events: &[(&str, &str)], ) -> Result<(), MemoryError>

Insert multiple events for a session inside a single transaction.

Atomically writes all events or none. More efficient than individual inserts for bulk import use cases.

Errors

Returns an error if the transaction or any insert fails.

pub async fn update_session_title( &self, session_id: &str, title: &str, ) -> Result<(), MemoryError>

Update the title of an ACP session.

Errors

Returns an error if the database write fails.

pub async fn acp_session_exists( &self, session_id: &str, ) -> Result<bool, MemoryError>

Check whether an ACP session record exists.

Errors

Returns an error if the database query fails.

pub async fn create_acp_session_with_conversation( &self, session_id: &str, conversation_id: ConversationId, ) -> Result<(), MemoryError>

Create a new ACP session record with an associated conversation.

Errors

Returns an error if the database write fails.

pub async fn get_acp_session_conversation_id( &self, session_id: &str, ) -> Result<Option<ConversationId>, MemoryError>

Get the conversation ID associated with an ACP session.

Returns None if the session has no conversation mapping (legacy session).

Errors

Returns an error if the database query fails.

pub async fn set_acp_session_conversation_id( &self, session_id: &str, conversation_id: ConversationId, ) -> Result<(), MemoryError>

Update the conversation mapping for an ACP session.

Errors

Returns an error if the database write fails.

pub async fn copy_conversation( &self, source: ConversationId, target: ConversationId, ) -> Result<(), MemoryError>

Copy all messages from one conversation to another, preserving order.

Summaries are intentionally NOT copied: their first_message_id/last_message_id reference message IDs from the source conversation which differ from the new IDs assigned to the copied messages, making the compaction cursor incorrect. The forked session inherits the full message history and builds its own compaction state from scratch. Other per-conversation state also excluded: embeddings (re-indexed on demand), deferred tool summaries (treated as fresh context budget).

Errors

Returns an error if the database write fails.

impl SqliteStore

pub async fn load_compression_guidelines( &self, conversation_id: Option<ConversationId>, ) -> Result<(i64, String), MemoryError>

Load the latest active compression guidelines.

When conversation_id is Some, returns conversation-specific guidelines preferred over global (NULL) ones. When None, returns only global guidelines.

Returns (version, guidelines_text). Returns (0, "") if no guidelines exist yet.

Errors

Returns an error if the database query fails.

pub async fn load_compression_guidelines_meta( &self, conversation_id: Option<ConversationId>, ) -> Result<(i64, String), MemoryError>

Load only the version and creation timestamp of the latest active compression guidelines.

Same scoping rules as [load_compression_guidelines]: conversation-specific rows are preferred over global ones. Returns (0, "") if no guidelines exist yet.

Use this in hot paths where the full text is not needed (e.g. metrics sync).

Errors

Returns an error if the database query fails.

pub async fn save_compression_guidelines( &self, guidelines: &str, token_count: i64, conversation_id: Option<ConversationId>, ) -> Result<i64, MemoryError>

Save a new version of the compression guidelines.

When conversation_id is Some, the guidelines are scoped to that conversation. When None, the guidelines are global (apply as fallback for all conversations).

Inserts a new row; older versions are retained for audit. Returns the new version number.

Note: version numbers are globally sequential across all conversation scopes — they are not per-conversation counters. The UNIQUE(version) constraint from migration 033 is preserved.

Errors

Returns an error if the database insert fails (including FK violation if conversation_id does not reference a valid conversation row).

pub async fn log_compression_failure( &self, conversation_id: ConversationId, compressed_context: &str, failure_reason: &str, ) -> Result<i64, MemoryError>

Log a compression failure pair.

Both compressed_context and failure_reason are truncated to 4096 chars. Returns the inserted row id.

Errors

Returns an error if the database insert fails.

pub async fn get_unused_failure_pairs( &self, limit: usize, ) -> Result<Vec<CompressionFailurePair>, MemoryError>

Get unused failure pairs (oldest first), up to limit.

Errors

Returns an error if the database query fails.

pub async fn mark_failure_pairs_used( &self, ids: &[i64], ) -> Result<(), MemoryError>

Mark failure pairs as consumed by the updater.

Errors

Returns an error if the database update fails.

pub async fn count_unused_failure_pairs(&self) -> Result<i64, MemoryError>

Count unused failure pairs.

Errors

Returns an error if the database query fails.

pub async fn cleanup_old_failure_pairs( &self, keep_recent: usize, ) -> Result<(), MemoryError>

Delete old used failure pairs, keeping the most recent keep_recent unused pairs.

Removes all rows where used_in_update = 1. Unused rows are managed by the max_stored_pairs enforcement below: if there are more than keep_recent unused pairs, the oldest excess rows are deleted.

Errors

Returns an error if the database query fails.

impl SqliteStore

pub async fn store_user_correction( &self, session_id: Option<i64>, original_output: &str, correction_text: &str, skill_name: Option<&str>, correction_kind: &str, ) -> Result<i64, MemoryError>

Store a user correction and return the new row ID.

Errors

Returns an error if the insert fails.

pub async fn load_corrections_for_skill( &self, skill_name: &str, limit: u32, ) -> Result<Vec<UserCorrectionRow>, MemoryError>

Load corrections for a specific skill, newest first.

Errors

Returns an error if the query fails.

pub async fn load_recent_corrections( &self, limit: u32, ) -> Result<Vec<UserCorrectionRow>, MemoryError>

Load the most recent corrections across all skills.

Errors

Returns an error if the query fails.

pub async fn load_corrections_for_id( &self, id: i64, ) -> Result<Vec<UserCorrectionRow>, MemoryError>

Load a correction by ID (used by vector retrieval path).

Errors

Returns an error if the query fails.

impl SqliteStore

pub async fn load_input_history( &self, limit: i64, ) -> Result<Vec<String>, MemoryError>

Load the most recent input history entries, ordered chronologically.

Errors

Returns an error if the query fails.

pub async fn save_input_entry(&self, text: &str) -> Result<(), MemoryError>

Persist a new input history entry.

Errors

Returns an error if the insert fails.

pub async fn clear_input_history(&self) -> Result<(), MemoryError>

Delete all input history entries.

Errors

Returns an error if the delete fails.

impl SqliteStore

pub async fn create_conversation(&self) -> Result<ConversationId, MemoryError>

Create a new conversation and return its ID.

Errors

Returns an error if the insert fails.

pub async fn save_message( &self, conversation_id: ConversationId, role: &str, content: &str, ) -> Result<MessageId, MemoryError>

Save a message to the given conversation and return the message ID.

Errors

Returns an error if the insert fails.

pub async fn save_message_with_parts( &self, conversation_id: ConversationId, role: &str, content: &str, parts_json: &str, ) -> Result<MessageId, MemoryError>

Save a message with structured parts JSON.

Errors

Returns an error if the insert fails.

pub async fn save_message_with_metadata( &self, conversation_id: ConversationId, role: &str, content: &str, parts_json: &str, agent_visible: bool, user_visible: bool, ) -> Result<MessageId, MemoryError>

Save a message with visibility metadata.

Errors

Returns an error if the insert fails.

pub async fn load_history( &self, conversation_id: ConversationId, limit: u32, ) -> Result<Vec<Message>, MemoryError>

Load the most recent messages for a conversation, up to limit.

Errors

Returns an error if the query fails.

pub async fn load_history_filtered( &self, conversation_id: ConversationId, limit: u32, agent_visible: Option<bool>, user_visible: Option<bool>, ) -> Result<Vec<Message>, MemoryError>

Load messages filtered by visibility flags.

Pass Some(true) to filter by a flag, None to skip filtering.

Errors

Returns an error if the query fails.

pub async fn replace_conversation( &self, conversation_id: ConversationId, compacted_range: RangeInclusive<MessageId>, summary_role: &str, summary_content: &str, ) -> Result<MessageId, MemoryError>

Atomically mark a range of messages as user-only and insert a summary as agent-only.

Within a single transaction:

1. Updates agent_visible=0, compacted_at=now for messages in compacted_range.
2. Inserts summary_content with agent_visible=1, user_visible=0.

Returns the MessageId of the inserted summary.

Errors

Returns an error if the transaction fails.

pub async fn oldest_message_ids( &self, conversation_id: ConversationId, n: u32, ) -> Result<Vec<MessageId>, MemoryError>

Return the IDs of the N oldest messages in a conversation (ascending order).

Errors

Returns an error if the query fails.

pub async fn latest_conversation_id( &self, ) -> Result<Option<ConversationId>, MemoryError>

Return the ID of the most recent conversation, if any.

Errors

Returns an error if the query fails.

pub async fn message_by_id( &self, message_id: MessageId, ) -> Result<Option<Message>, MemoryError>

Fetch a single message by its ID.

Errors

Returns an error if the query fails.

pub async fn messages_by_ids( &self, ids: &[MessageId], ) -> Result<Vec<(MessageId, Message)>, MemoryError>

Fetch messages by a list of IDs in a single query.

Errors

Returns an error if the query fails.

pub async fn unembedded_message_ids( &self, limit: Option<usize>, ) -> Result<Vec<(MessageId, ConversationId, String, String)>, MemoryError>

Return message IDs and content for messages without embeddings.

Errors

Returns an error if the query fails.

pub async fn count_messages( &self, conversation_id: ConversationId, ) -> Result<i64, MemoryError>

Count the number of messages in a conversation.

Errors

Returns an error if the query fails.

pub async fn count_messages_after( &self, conversation_id: ConversationId, after_id: MessageId, ) -> Result<i64, MemoryError>

Count messages in a conversation with id greater than after_id.

Errors

Returns an error if the query fails.

pub async fn keyword_search( &self, query: &str, limit: usize, conversation_id: Option<ConversationId>, ) -> Result<Vec<(MessageId, f64)>, MemoryError>

Full-text keyword search over messages using FTS5.

Returns message IDs with BM25 relevance scores (lower = more relevant, negated to positive for consistency with vector scores).

Errors

Returns an error if the query fails.

pub async fn keyword_search_with_time_range( &self, query: &str, limit: usize, conversation_id: Option<ConversationId>, after: Option<&str>, before: Option<&str>, ) -> Result<Vec<(MessageId, f64)>, MemoryError>

Full-text keyword search over messages using FTS5, filtered by a created_at time range.

Used by the Episodic recall path to combine keyword matching with temporal filtering. Temporal keywords are stripped from query by the caller before this method is invoked (see strip_temporal_keywords) to prevent BM25 score distortion.

after and before are SQLite datetime strings in YYYY-MM-DD HH:MM:SS format (UTC). None means “no bound” on that side.

Errors

Returns an error if the query fails.

pub async fn message_timestamps( &self, ids: &[MessageId], ) -> Result<HashMap<MessageId, i64>, MemoryError>

Fetch creation timestamps (Unix epoch seconds) for the given message IDs.

Messages without a created_at column fall back to 0.

Errors

Returns an error if the query fails.

pub async fn load_messages_range( &self, conversation_id: ConversationId, after_message_id: MessageId, limit: usize, ) -> Result<Vec<(MessageId, String, String)>, MemoryError>

Load a range of messages after a given message ID.

Errors

Returns an error if the query fails.

pub async fn get_eviction_candidates( &self, ) -> Result<Vec<EvictionEntry>, MemoryError>

Return all non-deleted message IDs with their eviction metadata.

Errors

Returns an error if the query fails.

pub async fn soft_delete_messages( &self, ids: &[MessageId], ) -> Result<(), MemoryError>

Soft-delete a set of messages by marking deleted_at.

Soft-deleted messages are excluded from all history queries.

Errors

Returns an error if the update fails.

pub async fn get_soft_deleted_message_ids( &self, ) -> Result<Vec<MessageId>, MemoryError>

Return IDs of soft-deleted messages that have not yet been cleaned from Qdrant.

Errors

Returns an error if the query fails.

pub async fn mark_qdrant_cleaned( &self, ids: &[MessageId], ) -> Result<(), MemoryError>

Mark a set of soft-deleted messages as Qdrant-cleaned.

Errors

Returns an error if the update fails.

pub async fn fetch_importance_scores( &self, ids: &[MessageId], ) -> Result<HashMap<MessageId, f64>, MemoryError>

Fetch importance_score values for the given message IDs.

Messages missing from the table fall back to 0.5 (neutral) and are omitted from the map.

Errors

Returns an error if the query fails.

pub async fn increment_access_counts( &self, ids: &[MessageId], ) -> Result<(), MemoryError>

Increment access_count and set last_accessed = datetime('now') for the given IDs.

Skips the update when ids is empty.

Errors

Returns an error if the update fails.

impl SqliteStore

pub async fn save_overflow( &self, conversation_id: i64, content: &[u8], ) -> Result<String, MemoryError>

Save overflow content associated with a conversation, returning the generated UUID.

Errors

Returns an error if the database insert fails.

pub async fn load_overflow( &self, id: &str, conversation_id: i64, ) -> Result<Option<Vec<u8>>, MemoryError>

Load overflow content by UUID, scoped to the given conversation. Returns None if the entry does not exist or belongs to a different conversation.

Errors

Returns an error if the database query fails.

pub async fn cleanup_overflow( &self, max_age_secs: u64, ) -> Result<u64, MemoryError>

Delete overflow entries older than max_age_secs seconds. Returns the number of deleted rows.

Errors

Returns an error if the database delete fails.

pub async fn overflow_size( &self, conversation_id: i64, ) -> Result<u64, MemoryError>

Return total overflow bytes stored for a conversation.

Errors

Returns an error if the database query fails.

impl SqliteStore

pub async fn upsert_learned_preference( &self, key: &str, value: &str, confidence: f64, evidence_count: i64, ) -> Result<(), MemoryError>

Insert or update a learned preference.

When a key already exists, the value and metadata are updated and updated_at is refreshed. evidence_count is set to the provided value (caller is responsible for accumulation logic).

Keys longer than 128 bytes or values longer than 256 bytes are silently truncated at a UTF-8 character boundary before storage.

Errors

Returns an error if the query fails.

pub async fn load_learned_preferences( &self, ) -> Result<Vec<LearnedPreferenceRow>, MemoryError>

Load all learned preferences, ordered by confidence descending.

Errors

Returns an error if the query fails.

pub async fn load_corrections_after( &self, after_id: i64, limit: u32, ) -> Result<Vec<UserCorrectionRow>, MemoryError>

Load corrections with id > after_id, ordered by id ascending.

Used by the learning engine to process only new corrections since the last analysis run (watermark-based incremental scan).

Errors

Returns an error if the query fails.

impl SqliteStore

pub async fn record_skill_usage( &self, skill_names: &[&str], ) -> Result<(), MemoryError>

Record usage of skills (UPSERT: increment count and update timestamp).

Errors

Returns an error if the database operation fails.

pub async fn load_skill_usage(&self) -> Result<Vec<SkillUsageRow>, MemoryError>

Load all skill usage statistics.

Errors

Returns an error if the query fails.

pub async fn record_skill_outcome( &self, skill_name: &str, version_id: Option<i64>, conversation_id: Option<ConversationId>, outcome: &str, error_context: Option<&str>, outcome_detail: Option<&str>, ) -> Result<(), MemoryError>

Record a skill outcome event.

Errors

Returns an error if the insert fails.

pub async fn record_skill_outcomes_batch( &self, skill_names: &[String], conversation_id: Option<ConversationId>, outcome: &str, error_context: Option<&str>, outcome_detail: Option<&str>, ) -> Result<(), MemoryError>

Record outcomes for multiple skills in a single transaction.

Errors

Returns an error if any insert fails (whole batch is rolled back).

pub async fn skill_metrics( &self, skill_name: &str, ) -> Result<Option<SkillMetricsRow>, MemoryError>

Load metrics for a skill (latest version group).

Errors

Returns an error if the query fails.

pub async fn load_skill_outcome_stats( &self, ) -> Result<Vec<SkillMetricsRow>, MemoryError>

Load all skill outcome stats grouped by skill name.

Errors

Returns an error if the query fails.

pub async fn save_skill_version( &self, skill_name: &str, version: i64, body: &str, description: &str, source: &str, error_context: Option<&str>, predecessor_id: Option<i64>, ) -> Result<i64, MemoryError>

Save a new skill version and return its ID.

Errors

Returns an error if the insert fails.

pub async fn active_skill_version( &self, skill_name: &str, ) -> Result<Option<SkillVersionRow>, MemoryError>

Load the active version for a skill.

Errors

Returns an error if the query fails.

pub async fn activate_skill_version( &self, skill_name: &str, version_id: i64, ) -> Result<(), MemoryError>

Activate a specific version (deactivates others for the same skill).

Errors

Returns an error if the update fails.

pub async fn next_skill_version( &self, skill_name: &str, ) -> Result<i64, MemoryError>

Get the next version number for a skill.

Errors

Returns an error if the query fails.

pub async fn last_improvement_time( &self, skill_name: &str, ) -> Result<Option<String>, MemoryError>

Get the latest auto-generated version’s created_at for cooldown check.

Errors

Returns an error if the query fails.

pub async fn ensure_skill_version_exists( &self, skill_name: &str, body: &str, description: &str, ) -> Result<(), MemoryError>

Ensure a base (v1 manual) version exists for a skill. Idempotent.

Errors

Returns an error if the DB operation fails.

pub async fn load_skill_versions( &self, skill_name: &str, ) -> Result<Vec<SkillVersionRow>, MemoryError>

Load all versions for a skill, ordered by version number.

Errors

Returns an error if the query fails.

pub async fn count_auto_versions( &self, skill_name: &str, ) -> Result<i64, MemoryError>

Count auto-generated versions for a skill.

Errors

Returns an error if the query fails.

pub async fn prune_skill_versions( &self, skill_name: &str, max_versions: u32, ) -> Result<u32, MemoryError>

Delete oldest non-active auto versions exceeding max limit. Returns the number of pruned versions.

Errors

Returns an error if the delete fails.

pub async fn predecessor_version( &self, version_id: i64, ) -> Result<Option<SkillVersionRow>, MemoryError>

Get the predecessor version for rollback.

Errors

Returns an error if the query fails.

pub async fn list_active_auto_versions( &self, ) -> Result<Vec<String>, MemoryError>

Return the skill names for all currently active auto-generated versions.

Used to check rollback eligibility at the start of each agent turn.

Errors

Returns MemoryError on SQLite query failure.

impl SqliteStore

pub async fn save_summary( &self, conversation_id: ConversationId, content: &str, first_message_id: Option<MessageId>, last_message_id: Option<MessageId>, token_estimate: i64, ) -> Result<i64, MemoryError>

Save a summary and return its ID.

first_message_id and last_message_id are None for session-level summaries (e.g. shutdown summaries) that do not correspond to a specific message range.

Errors

Returns an error if the insert fails.

pub async fn load_summaries( &self, conversation_id: ConversationId, ) -> Result<Vec<(i64, ConversationId, String, Option<MessageId>, Option<MessageId>, i64)>, MemoryError>

Load all summaries for a conversation.

first_message_id and last_message_id are None for session-level summaries.

Errors

Returns an error if the query fails.

pub async fn latest_summary_last_message_id( &self, conversation_id: ConversationId, ) -> Result<Option<MessageId>, MemoryError>

Get the last message ID covered by the most recent summary.

Returns None if no summaries exist or the most recent is a session-level summary (shutdown summary) with no tracked message range.

Errors

Returns an error if the query fails.

impl SqliteStore

pub async fn upsert_skill_trust( &self, skill_name: &str, trust_level: &str, source_kind: SourceKind, source_url: Option<&str>, source_path: Option<&str>, blake3_hash: &str, ) -> Result<(), MemoryError>

Upsert trust metadata for a skill.

Errors

Returns an error if the database operation fails.

pub async fn load_skill_trust( &self, skill_name: &str, ) -> Result<Option<SkillTrustRow>, MemoryError>

Load trust metadata for a single skill.

Errors

Returns an error if the query fails.

pub async fn load_all_skill_trust( &self, ) -> Result<Vec<SkillTrustRow>, MemoryError>

Load all skill trust entries.

Errors

Returns an error if the query fails.

pub async fn set_skill_trust_level( &self, skill_name: &str, trust_level: &str, ) -> Result<bool, MemoryError>

Update only the trust level for a skill.

Errors

Returns an error if the skill does not exist or the update fails.

pub async fn delete_skill_trust( &self, skill_name: &str, ) -> Result<bool, MemoryError>

Delete trust entry for a skill.

Errors

Returns an error if the delete fails.

pub async fn update_skill_hash( &self, skill_name: &str, blake3_hash: &str, ) -> Result<bool, MemoryError>

Update the blake3 hash for a skill.

Errors

Returns an error if the update fails.

impl SqliteStore

pub async fn new(path: &str) -> Result<Self, MemoryError>

Open (or create) the SQLite database and run migrations.

Enables foreign key constraints at connection level so that ON DELETE CASCADE and other FK rules are enforced.

Errors

Returns an error if the database cannot be opened or migrations fail.

pub async fn with_pool_size( path: &str, pool_size: u32, ) -> Result<Self, MemoryError>

Open (or create) the SQLite database with a configurable connection pool size.

Errors

Returns an error if the database cannot be opened or migrations fail.

pub fn pool(&self) -> &SqlitePool

Expose the underlying pool for shared access by other stores.

pub async fn run_migrations(pool: &SqlitePool) -> Result<(), MemoryError>

Run all migrations on the given pool.

Errors

Returns an error if any migration fails.

Trait Implementations

impl Clone for SqliteStore

fn clone(&self) -> SqliteStore

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SqliteStore

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

Formats the value using the given formatter.