Struct DbStore 

pub struct DbStore { /* private fields */ }

Implementations

impl DbStore

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 DbStore

pub async fn record_admission_training( &self, input: AdmissionTrainingInput<'_>, ) -> Result<i64, MemoryError>

Record a message in the RL admission training data.

Called for BOTH admitted and rejected messages so the model sees both classes. message_id is None for rejected messages (never persisted to messages table). features_json is the JSON-serialized feature vector used for training.

Errors

Returns an error if the database insert fails.

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

Mark training records as recalled for the given message IDs.

Called after batch_increment_access_count() in SemanticMemory::recall(). Sets was_recalled = 1 and updates updated_at for all matching records.

Errors

Returns an error if the database update fails.

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

Count total training records (admitted + rejected).

Errors

Returns an error if the database query fails.

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

Get a batch of training records for model training.

Returns up to limit records ordered by creation time (oldest first).

Errors

Returns an error if the database query fails.

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

Delete old training records, keeping the most recent keep_recent.

Called after each retraining cycle to prevent unbounded table growth.

Errors

Returns an error if the database delete fails.

pub async fn save_rl_weights( &self, weights_json: &str, sample_count: i64, ) -> Result<(), MemoryError>

Save trained RL model weights to SQLite for persistence across restarts.

Uses a fixed id = 1 row (INSERT OR REPLACE) so the table never grows beyond one row — avoiding unbounded growth from repeated retrain cycles.

Errors

Returns an error if the database upsert fails.

pub async fn load_rl_weights( &self, ) -> Result<Option<(String, i64)>, MemoryError>

Load the latest RL model weights from SQLite.

Returns None if no weights have been saved yet.

Errors

Returns an error if the database query fails.

impl DbStore

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, category: &str, ) -> Result<i64, MemoryError>

Log a compression failure pair.

Both compressed_context and failure_reason are truncated to 4096 chars. category should be one of: tool_output, assistant_reasoning, user_context, unknown. 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 get_unused_failure_pairs_by_category( &self, category: &str, limit: usize, ) -> Result<Vec<CompressionFailurePair>, MemoryError>

Get unused failure pairs for a specific category (oldest first), up to limit.

Used by the categorized ACON updater to run per-category update cycles.

Errors

Returns an error if the database query fails.

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

Count unused failure pairs for a specific category.

Errors

Returns an error if the database query fails.

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

Load the latest compression guidelines for a specific category.

When conversation_id is Some, prefers conversation-specific rows. Returns (0, "") if no guidelines exist for this category.

Errors

Returns an error if the database query fails.

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

Save a new version of compression guidelines for a specific category.

Errors

Returns an error if the database insert 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 DbStore

pub async fn record_compression_training( &self, conversation_id: ConversationId, compression_ratio: f32, message_count: i64, avg_message_length: f32, tool_output_fraction: f32, probe_score: f32, ) -> Result<i64, MemoryError>

Record a compression probe result for predictor training.

Errors

Returns an error if the database insert fails.

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

Count total compression training records.

Errors

Returns an error if the query fails.

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

Get the most recent limit training records for model training (sliding window).

Errors

Returns an error if the query fails.

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

Trim compression training records, keeping the most recent keep_recent.

Errors

Returns an error if the delete fails.

pub async fn save_compression_predictor_weights( &self, weights_json: &str, ) -> Result<(), MemoryError>

Save compression predictor weights (singleton row, id = 1).

Errors

Returns an error if the upsert fails.

pub async fn load_compression_predictor_weights( &self, ) -> Result<Option<String>, MemoryError>

Load compression predictor weights.

Returns None if no weights have been saved yet.

Errors

Returns an error if the query fails.

impl DbStore

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 DbStore

pub async fn insert_experiment_result( &self, result: &NewExperimentResult<'_>, ) -> Result<i64, MemoryError>

Insert an experiment result and return the new row ID.

Errors

Returns an error if the insert fails.

pub async fn list_experiment_results( &self, session_id: Option<&str>, limit: u32, ) -> Result<Vec<ExperimentResultRow>, MemoryError>

List experiment results, optionally filtered by session_id, newest first.

Errors

Returns an error if the query fails.

pub async fn best_experiment_result( &self, parameter: Option<&str>, ) -> Result<Option<ExperimentResultRow>, MemoryError>

Get the best accepted result (highest delta), optionally filtered by parameter.

Errors

Returns an error if the query fails.

pub async fn experiment_results_since( &self, since: &str, ) -> Result<Vec<ExperimentResultRow>, MemoryError>

Get all results since a given ISO-8601 timestamp (YYYY-MM-DD HH:MM:SS or YYYY-MM-DDTHH:MM:SS).

Errors

Returns MemoryError::Other if since does not match the expected timestamp format. Returns an error if the query fails.

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

Get a summary for a specific session.

Errors

Returns an error if the query fails.

impl DbStore

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 DbStore

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

Fetch semantic-tier messages not yet assigned to any scene.

Returns (message_id, content) pairs ordered by id ASC.

Errors

Returns an error if the SQLite query fails.

pub async fn insert_mem_scene( &self, label: &str, profile: &str, member_ids: &[MessageId], ) -> Result<MemSceneId, MemoryError>

Insert a new MemScene and link member messages to it.

Returns the new scene’s ID.

Errors

Returns an error if the SQLite insert fails.

pub async fn list_mem_scenes(&self) -> Result<Vec<MemScene>, MemoryError>

List all MemScenes ordered by creation time descending.

Errors

Returns an error if the SQLite query fails.

pub async fn scene_member_ids( &self, scene_id: MemSceneId, ) -> Result<Vec<MessageId>, MemoryError>

Fetch member message IDs for a given scene.

Errors

Returns an error if the SQLite query fails.

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

Delete all MemScenes and their memberships (reset for re-clustering).

Errors

Returns an error if the SQLite delete fails.

impl DbStore

pub async fn insert_tree_leaf( &self, content: &str, token_count: i64, ) -> Result<i64, MemoryError>

Insert a leaf node (level 0) into the memory tree.

Returns the id of the new row.

Errors

Returns an error if the query fails.

pub async fn insert_tree_node( &self, level: i64, parent_id: Option<i64>, content: &str, source_ids: &str, token_count: i64, ) -> Result<i64, MemoryError>

Insert a consolidated node at a given level.

Returns the id of the new row.

Errors

Returns an error if the query fails.

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

Load unconsolidated leaf nodes (level 0 without a parent).

Errors

Returns an error if the query fails.

pub async fn load_tree_level( &self, level: i64, limit: usize, ) -> Result<Vec<MemoryTreeRow>, MemoryError>

Load all nodes at a given level (for consolidation of higher levels).

Errors

Returns an error if the query fails.

pub async fn traverse_tree_up( &self, leaf_id: i64, max_level: i64, ) -> Result<Vec<MemoryTreeRow>, MemoryError>

Traverse from a leaf up to max_level, returning all ancestor nodes.

The result is ordered from leaf (level 0) to root (highest level).

Errors

Returns an error if the query fails.

pub async fn mark_nodes_consolidated( &self, child_ids: &[i64], parent_id: i64, ) -> Result<(), MemoryError>

Mark child nodes as consolidated by setting their parent_id.

This runs inside a single transaction to prevent partial state. Per-cluster transactions (critic S2 fix): call this once per cluster, not once per full sweep.

Errors

Returns an error if the query fails.

pub async fn consolidate_cluster( &self, level: i64, summary: &str, source_ids_json: &str, token_count: i64, child_ids: &[i64], ) -> Result<i64, MemoryError>

Insert a parent node and mark its children as consolidated in one transaction.

Both the INSERT of the parent and the UPDATE of all children happen inside a single BEGIN … COMMIT. A crash between the two operations therefore leaves no orphaned parent.

Errors

Returns an error if any query inside the transaction fails (the transaction is rolled back).

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

Increment the total consolidation counter in memory_tree_meta.

Errors

Returns an error if the query fails.

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

Count total nodes in the memory tree.

Errors

Returns an error if the query fails.

impl DbStore

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_category( &self, conversation_id: ConversationId, role: &str, content: &str, category: Option<&str>, ) -> Result<MessageId, MemoryError>

Save a message with an optional category tag.

The category column is NULL when None — existing rows are unaffected.

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 apply_tool_pair_summaries( &self, conversation_id: ConversationId, hide_ids: &[i64], summaries: &[String], ) -> Result<(), MemoryError>

Atomically hide tool_use/tool_result message pairs and insert summary messages.

Within a single transaction:

1. Sets agent_visible=0, compacted_at=<now> for each ID in hide_ids.
2. Inserts each text in summaries as a new agent-only assistant message.

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_unembedded_messages(&self) -> Result<usize, MemoryError>

Count messages that have no embedding yet.

Errors

Returns an error if the query fails.

pub fn stream_unembedded_messages( &self, limit: i64, ) -> impl Stream<Item = Result<(MessageId, ConversationId, String, String), MemoryError>> + '_

Stream message IDs and content for messages without embeddings, one row at a time.

Executes the same query as Self::unembedded_message_ids but returns a streaming cursor instead of loading all rows into a Vec. The SQLite read transaction is held for the duration of iteration; callers must not write to embeddings_metadata while the stream is live (use a separate async task for writes).

Errors

Yields a MemoryError if the query or row decoding 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 = CURRENT_TIMESTAMP for the given IDs.

Skips the update when ids is empty.

Errors

Returns an error if the update fails.

pub async fn find_promotion_candidates( &self, min_sessions: u32, batch_size: usize, ) -> Result<Vec<PromotionCandidate>, MemoryError>

Return episodic messages with session_count >= min_sessions, ordered by session count descending then importance score descending.

Errors

Returns an error if the query fails.

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

Count messages per tier (episodic, semantic) that are not deleted.

Returns (episodic_count, semantic_count).

Errors

Returns an error if the query fails.

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

Count semantic facts (tier=‘semantic’, not deleted).

Errors

Returns an error if the query fails.

pub async fn promote_to_semantic( &self, conversation_id: ConversationId, merged_content: &str, original_ids: &[MessageId], ) -> Result<MessageId, MemoryError>

Promote a set of episodic messages to semantic tier in a single transaction.

Within one transaction:

1. Inserts a new message with tier='semantic' and promotion_timestamp=unixepoch().
2. Soft-deletes the original episodic messages and marks them qdrant_cleaned=0 so the eviction sweep picks up their Qdrant vectors.

Returns the MessageId of the new semantic message.

Errors

Returns an error if the transaction fails.

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

Manually promote a set of messages to semantic tier without merging.

Sets tier='semantic' and promotion_timestamp=unixepoch() for the given IDs. Does NOT soft-delete the originals — use this for direct user-requested promotion.

Errors

Returns an error if the update fails.

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

Increment session_count for all episodic messages in a conversation.

Called when a session restores an existing conversation to mark that messages were accessed in a new session. Only episodic (non-deleted) messages are updated.

Errors

Returns an error if the database update fails.

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

Fetch the tier string for each of the given message IDs.

Messages not found or already deleted are omitted from the result.

Errors

Returns an error if the query fails.

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

Return all conversation IDs that have at least one non-consolidated original message.

Used by the consolidation sweep to find conversations that need processing.

Errors

Returns an error if the database query fails.

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

Fetch a batch of non-consolidated original messages for the consolidation sweep.

Returns (id, content) pairs for messages that have not yet been processed by the consolidation loop (consolidated = 0) and are not soft-deleted.

Errors

Returns an error if the database query fails.

pub async fn find_consolidated_for_source( &self, source_id: MessageId, ) -> Result<Option<MessageId>, MemoryError>

Look up which consolidated entry (if any) covers the given original message.

Returns the consolidated_id of the first consolidation product that lists source_id in its sources, or None if no consolidated entry covers it.

Errors

Returns an error if the database query fails.

pub async fn apply_consolidation_merge( &self, conversation_id: ConversationId, role: &str, merged_content: &str, source_ids: &[MessageId], confidence: f32, confidence_threshold: f32, ) -> Result<bool, MemoryError>

Insert a consolidated message and record its source linkage in a single transaction.

Atomically:

1. Inserts the consolidated message with consolidated = 1 and the given confidence.
2. Inserts rows into memory_consolidation_sources for each source ID.
3. Marks each source message’s consolidated = 1 so future sweeps skip them.

If confidence < confidence_threshold the operation is skipped and false is returned.

Errors

Returns an error if any database operation fails. The transaction is rolled back automatically on failure so no partial state is written.

pub async fn apply_consolidation_update( &self, target_id: MessageId, new_content: &str, additional_source_ids: &[MessageId], confidence: f32, confidence_threshold: f32, ) -> Result<bool, MemoryError>

Update an existing consolidated message in-place with new content.

Atomically:

1. Updates content and consolidation_confidence on target_id.
2. Inserts rows into memory_consolidation_sources linking target_id → each source.
3. Marks each source message’s consolidated = 1.

If confidence < confidence_threshold the operation is skipped and false is returned.

Errors

Returns an error if any database operation fails.

pub async fn set_importance_score( &self, id: MessageId, score: f64, ) -> Result<(), MemoryError>

Set importance_score for a single message by ID.

Used in tests and by forgetting sweep helpers.

Errors

Returns an error if the update fails.

pub async fn get_importance_score( &self, id: MessageId, ) -> Result<Option<f64>, MemoryError>

Get importance_score for a single message by ID.

Returns None if the message does not exist or is deleted.

Errors

Returns an error if the query fails.

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

Increment access_count and update last_accessed for a batch of messages.

Alias used in forgetting tests; forwards to increment_access_counts.

Errors

Returns an error if the update fails.

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

Mark a set of messages as consolidated (consolidated = 1).

Used in tests to simulate the state after consolidation.

Errors

Returns an error if the update fails.

pub async fn run_forgetting_sweep_tx( &self, config: &ForgettingConfig, ) -> Result<ForgettingResult, MemoryError>

Execute the three-phase forgetting sweep (SleepGate) inside a single transaction.

Phase 1 — Downscale all active non-consolidated importance scores by decay_rate. Phase 2 — Undo the decay for messages accessed within replay_window_hours or with access_count >= replay_min_access_count (undo current sweep’s decay only). Phase 3 — Soft-delete messages below forgetting_floor that are not protected by recent access (protect_recent_hours) or high access count (protect_min_access_count). Uses batch_size as a row-count cap.

All phases commit atomically: concurrent readers see either the pre-sweep or post-sweep state, never an intermediate.

Errors

Returns an error if any database operation fails.

impl DbStore

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 save_archive( &self, conversation_id: i64, content: &[u8], ) -> Result<String, MemoryError>

Save a Memex compaction-time archive, returning the generated UUID.

Archives use archive_type = 'archive' and are excluded from the short-lived cleanup_overflow() job. They persist as long as the conversation exists.

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 execution-time overflow entries (archive_type = 'overflow') older than max_age_secs seconds. Compaction-time archives (archive_type = 'archive') are intentionally excluded — they persist for the lifetime of the conversation.

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 DbStore

pub async fn upsert_persona_fact( &self, category: &str, content: &str, confidence: f64, source_conversation_id: Option<i64>, supersedes_id: Option<i64>, ) -> Result<i64, MemoryError>

Upsert a persona fact.

On exact-content conflict within the same category: increments evidence_count and updates confidence and updated_at.

When supersedes_id is provided, the referenced older fact is logically replaced — it will be excluded from context assembly via the NOT IN filter.

Errors

Returns an error if the query fails.

pub async fn load_persona_facts( &self, min_confidence: f64, ) -> Result<Vec<PersonaFactRow>, MemoryError>

Load all persona facts above min_confidence, excluding superseded facts.

Results are ordered by confidence DESC so the most reliable facts come first.

Errors

Returns an error if the query fails.

pub async fn delete_persona_fact(&self, id: i64) -> Result<bool, MemoryError>

Delete a persona fact by id (for user-initiated corrections).

Returns true if a row was deleted, false if the id was not found.

Errors

Returns an error if the query fails.

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

Count total persona facts (for metrics/TUI).

Errors

Returns an error if the query fails.

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

Read the last extracted message id from the persona_meta singleton.

Errors

Returns an error if the query fails.

pub async fn set_persona_last_extracted_message_id( &self, message_id: i64, ) -> Result<(), MemoryError>

Update the last extracted message id in the persona_meta singleton.

Errors

Returns an error if the query fails.

impl DbStore

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 DbStore

pub async fn save_session_digest( &self, conversation_id: ConversationId, digest: &str, token_count: i64, ) -> Result<(), MemoryError>

Upsert a session digest for conversation_id.

Uses INSERT ... ON CONFLICT ... DO UPDATE to preserve the original created_at and avoid resetting the auto-incremented id on updates.

Errors

Returns an error if the database write fails.

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

Load the session digest for conversation_id, if it exists.

Errors

Returns an error if the database query fails.

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

Delete the session digest for conversation_id.

Errors

Returns an error if the database write fails.

impl DbStore

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 distinct_session_count( &self, skill_name: &str, ) -> Result<i64, MemoryError>

Count the number of distinct conversation sessions in which a skill produced an outcome.

Uses COUNT(DISTINCT conversation_id) from skill_outcomes. Rows where conversation_id IS NULL are excluded (legacy rows without session tracking).

Errors

Returns an error if the query 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.

pub async fn insert_tool_usage_log( &self, tool_sequence: &str, sequence_hash: &str, context_hash: &str, outcome: &str, conversation_id: Option<ConversationId>, ) -> Result<(), MemoryError>

Insert a tool usage log entry.

tool_sequence must be a normalized compact JSON array (see stem::normalize_tool_sequence). sequence_hash is the 16-char blake3 hex of tool_sequence.

Errors

Returns MemoryError on insert failure.

pub async fn find_recurring_patterns( &self, min_count: u32, window_days: u32, ) -> Result<Vec<(String, String, u32, u32)>, MemoryError>

Find tool sequences that have been seen at least min_count times within the last window_days days.

Returns (tool_sequence, sequence_hash, occurrence_count, success_count) tuples.

Errors

Returns MemoryError on query failure.

pub async fn prune_tool_usage_log( &self, retention_days: u32, ) -> Result<u64, MemoryError>

Delete skill_usage_log rows older than retention_days days.

Errors

Returns MemoryError on delete failure.

pub async fn insert_skill_heuristic( &self, skill_name: Option<&str>, heuristic_text: &str, confidence: f64, ) -> Result<i64, MemoryError>

Insert a new heuristic (no dedup — caller must check first).

Errors

Returns MemoryError on insert failure.

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

Increment use_count and update updated_at for an existing heuristic by ID.

Errors

Returns MemoryError on update failure.

pub async fn load_skill_heuristics( &self, skill_name: &str, min_confidence: f64, limit: u32, ) -> Result<Vec<(i64, String, f64, i64)>, MemoryError>

Load heuristics for a given skill (exact match + NULL/general), ordered by confidence DESC.

Returns (id, heuristic_text, confidence, use_count) tuples. At most limit rows are returned.

Errors

Returns MemoryError on query failure.

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

Load all heuristics for a skill (for dedup checks), without confidence filter.

Returns (id, heuristic_text) tuples.

Errors

Returns MemoryError on query failure.

pub async fn find_step_corrections( &self, skill_name: &str, failure_kind: &str, error_context: &str, tool_name: &str, limit: u32, ) -> Result<Vec<(i64, String)>, MemoryError>

Find matching step corrections for a tool failure.

Returns (id, hint) pairs ordered by success_count DESC, use_count DESC. Uses INSTR instead of LIKE to avoid wildcard injection from error_context.

Errors

Returns MemoryError on query failure.

pub async fn insert_step_correction( &self, skill_name: &str, failure_kind: &str, error_substring: &str, tool_name: &str, hint: &str, ) -> Result<(), MemoryError>

Insert a new step correction (from ARISE trace analysis).

Duplicate (skill_name, failure_kind, error_substring, tool_name) tuples are silently ignored (handled by ON CONFLICT IGNORE in the schema).

Errors

Returns MemoryError on query failure.

pub async fn record_correction_usage( &self, correction_id: i64, was_successful: bool, ) -> Result<(), MemoryError>

Increment use_count and optionally success_count for a step correction.

Errors

Returns MemoryError on query failure.

pub async fn load_routing_head_weights( &self, ) -> Result<Option<(i64, Vec<u8>, f64, i64)>, MemoryError>

Load routing head weights blob from the singleton row.

Returns (embed_dim, weights_bytes, baseline, update_count) or None if not yet trained.

Errors

Returns MemoryError on query failure.

pub async fn save_routing_head_weights( &self, embed_dim: i64, weights: &[u8], baseline: f64, update_count: i64, ) -> Result<(), MemoryError>

Persist routing head weights (upsert singleton row).

Errors

Returns MemoryError on query failure.

impl DbStore

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 DbStore

pub async fn insert_trajectory_entry( &self, entry: NewTrajectoryEntry<'_>, ) -> Result<i64, MemoryError>

Insert a trajectory entry.

Returns the id of the inserted row.

Errors

Returns an error if the query fails.

pub async fn load_trajectory_entries( &self, kind: Option<&str>, limit: usize, ) -> Result<Vec<TrajectoryEntryRow>, MemoryError>

Load trajectory entries, optionally filtered by kind.

Results are ordered by confidence DESC, then created_at DESC.

Errors

Returns an error if the query fails.

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

Count total trajectory entries (for metrics/TUI).

Errors

Returns an error if the query fails.

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

Read the last extracted message id for a given conversation from trajectory_meta.

Returns 0 if no row exists for the conversation yet.

Errors

Returns an error if the query fails.

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

Upsert the last extracted message id for a given conversation in trajectory_meta.

Errors

Returns an error if the query fails.

impl DbStore

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 upsert_skill_trust_with_git_hash( &self, skill_name: &str, trust_level: &str, source_kind: SourceKind, source_url: Option<&str>, source_path: Option<&str>, blake3_hash: &str, git_hash: Option<&str>, ) -> Result<(), MemoryError>

Upsert trust metadata for a skill, including an optional upstream git hash.

git_hash is the upstream commit hash from the x-git-hash SKILL.md frontmatter field. It tracks the upstream commit at install time and is stored separately from blake3_hash (which tracks content integrity).

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 DbStore

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

Open (or create) the database and run migrations.

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 database with a configurable connection pool size.

Errors

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

pub fn pool(&self) -> &DbPool

Expose the underlying pool for shared access by other stores.

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

Run all migrations on the given pool.

Errors

Returns an error if any migration fails.

Trait Implementations

impl Clone for DbStore

fn clone(&self) -> DbStore

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DbStore

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

Formats the value using the given formatter.