claw-core 0.1.1

//! Memory record store for claw-core.
//!
//! The `memories` table is the primary store for persistent AI agent memories.
//! Records are classified by [`MemoryType`], can carry arbitrary tags for
//! keyword search, and optionally expire after a configurable TTL.

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use sqlx::SqlitePool;
use uuid::Uuid;

use crate::error::{ClawError, ClawResult};

// ── ListOptions ──────────────────────────────────────────────────────────────

/// Options controlling pagination for list queries.
///
/// Use with [`crate::ClawEngine::list_memories_paginated`] and
/// [`crate::ClawEngine::list_sessions_paginated`].
///
/// # Example
///
/// ```rust
/// use claw_core::ListOptions;
/// // First page — 50 results.
/// let opts = ListOptions { limit: 50, cursor: None };
/// // Subsequent page — pass the cursor returned from the previous call.
/// let opts2 = ListOptions { limit: 50, cursor: Some("some-uuid".to_string()) };
/// ```
#[derive(Debug, Clone, Default)]
pub struct ListOptions {
    /// Maximum number of items to return. `0` is treated as "no limit".
    pub limit: usize,
    /// Opaque cursor returned by the previous call.  `None` starts from the
    /// beginning.  The cursor value is the `id` of the last record on the
    /// previous page.
    pub cursor: Option<String>,
}

/// The logical classification of a memory record.
///
/// # Example
///
/// ```rust
/// use claw_core::MemoryType;
/// let mt = MemoryType::Semantic;
/// assert_eq!(mt.as_str(), "semantic");
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum MemoryType {
    /// Factual world knowledge (e.g. "Paris is the capital of France").
    Semantic,
    /// Event-based memories tied to specific experiences.
    Episodic,
    /// Short-lived working memory for active reasoning.
    Working,
    /// Skill or procedure memory.
    Procedural,
}

impl MemoryType {
    /// Return the string representation stored in the database.
    pub fn as_str(&self) -> &'static str {
        match self {
            MemoryType::Semantic => "semantic",
            MemoryType::Episodic => "episodic",
            MemoryType::Working => "working",
            MemoryType::Procedural => "procedural",
        }
    }
}

impl std::fmt::Display for MemoryType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

impl std::str::FromStr for MemoryType {
    type Err = ClawError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "semantic" => Ok(MemoryType::Semantic),
            "episodic" => Ok(MemoryType::Episodic),
            "working" => Ok(MemoryType::Working),
            "procedural" => Ok(MemoryType::Procedural),
            other => Err(ClawError::InvalidInput(format!(
                "unknown memory type: {other}"
            ))),
        }
    }
}

/// A persistent memory record stored in the `memories` table.
///
/// Create new records with [`MemoryRecord::new`], which auto-generates a UUID
/// and timestamps. Persist them with [`crate::ClawEngine::insert_memory`].
///
/// # Example
///
/// ```rust
/// use claw_core::{MemoryRecord, MemoryType};
/// let r = MemoryRecord::new(
///     "Paris is the capital of France",
///     MemoryType::Semantic,
///     vec!["geography".to_string()],
///     None,
/// );
/// assert_eq!(r.memory_type, MemoryType::Semantic);
/// ```
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MemoryRecord {
    /// Unique record identifier.
    pub id: Uuid,
    /// Natural-language content of the memory.
    pub content: String,
    /// The logical type of this memory.
    pub memory_type: MemoryType,
    /// Searchable tags attached to this record.
    pub tags: Vec<String>,
    /// Optional TTL in seconds from `created_at`. `None` means no expiry.
    pub ttl_seconds: Option<u64>,
    /// Timestamp when this record was first created.
    pub created_at: DateTime<Utc>,
    /// Timestamp when this record was last modified.
    pub updated_at: DateTime<Utc>,
}

impl MemoryRecord {
    /// Create a new [`MemoryRecord`] with a freshly generated UUID and current
    /// UTC timestamps.
    ///
    /// # Example
    ///
    /// ```rust
    /// use claw_core::{MemoryRecord, MemoryType};
    /// let r = MemoryRecord::new("hello", MemoryType::Working, vec![], None);
    /// assert_eq!(r.content, "hello");
    /// assert!(r.ttl_seconds.is_none());
    /// ```
    pub fn new(
        content: impl Into<String>,
        memory_type: MemoryType,
        tags: Vec<String>,
        ttl_seconds: Option<u64>,
    ) -> Self {
        let now = Utc::now();
        MemoryRecord {
            id: Uuid::new_v4(),
            content: content.into(),
            memory_type,
            tags,
            ttl_seconds,
            created_at: now,
            updated_at: now,
        }
    }
}

/// Data-access object for the `memories` and `memories_fts` tables.
///
/// Obtain an instance via [`MemoryStore::new`], passing a shared [`SqlitePool`].
#[derive(Debug)]
pub struct MemoryStore<'a> {
    pool: &'a SqlitePool,
}

impl<'a> MemoryStore<'a> {
    /// Create a new [`MemoryStore`] bound to `pool`.
    pub fn new(pool: &'a SqlitePool) -> Self {
        MemoryStore { pool }
    }

    /// Insert a new [`MemoryRecord`] into the database.
    ///
    /// Both the `memories` table and the `memories_fts` FTS5 index are updated
    /// together.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the SQL execution or serialization fails.
    pub async fn insert(&self, record: &MemoryRecord) -> ClawResult<()> {
        let tags = serde_json::to_string(&record.tags)?;
        sqlx::query(
            "INSERT INTO memories \
             (id, content, memory_type, tags, ttl_seconds, created_at, updated_at) \
             VALUES (?, ?, ?, ?, ?, ?, ?)",
        )
        .bind(record.id.to_string())
        .bind(&record.content)
        .bind(record.memory_type.as_str())
        .bind(&tags)
        .bind(record.ttl_seconds.map(|s| s as i64))
        .bind(record.created_at.to_rfc3339())
        .bind(record.updated_at.to_rfc3339())
        .execute(self.pool)
        .await?;

        sqlx::query("INSERT INTO memories_fts(id, content) VALUES (?, ?)")
            .bind(record.id.to_string())
            .bind(&record.content)
            .execute(self.pool)
            .await?;

        // Populate the normalised tag index (migration 0003).
        for tag in &record.tags {
            sqlx::query("INSERT OR IGNORE INTO memory_tags(memory_id, tag) VALUES (?, ?)")
                .bind(record.id.to_string())
                .bind(tag)
                .execute(self.pool)
                .await?;
        }

        Ok(())
    }

    /// Fetch a [`MemoryRecord`] by its `id`.
    ///
    /// # Errors
    ///
    /// Returns [`ClawError::NotFound`] if no record with the given `id` exists.
    pub async fn get(&self, id: Uuid) -> ClawResult<MemoryRecord> {
        let row =
            sqlx::query_as::<_, (String, String, String, String, Option<i64>, String, String)>(
                "SELECT id, content, memory_type, tags, ttl_seconds, created_at, updated_at \
             FROM memories WHERE id = ?",
            )
            .bind(id.to_string())
            .fetch_optional(self.pool)
            .await?;

        let row = row.ok_or_else(|| ClawError::NotFound {
            entity: "MemoryRecord".to_string(),
            id: id.to_string(),
        })?;

        Self::row_to_record(row)
    }

    /// Update the `content` and `updated_at` of a [`MemoryRecord`].
    ///
    /// # Errors
    ///
    /// Returns [`ClawError::NotFound`] if no record with the given `id` exists.
    pub async fn update_content(
        &self,
        id: Uuid,
        content: &str,
        updated_at: DateTime<Utc>,
    ) -> ClawResult<()> {
        let affected = sqlx::query("UPDATE memories SET content = ?, updated_at = ? WHERE id = ?")
            .bind(content)
            .bind(updated_at.to_rfc3339())
            .bind(id.to_string())
            .execute(self.pool)
            .await?
            .rows_affected();

        if affected == 0 {
            return Err(ClawError::NotFound {
                entity: "MemoryRecord".to_string(),
                id: id.to_string(),
            });
        }

        sqlx::query("UPDATE memories_fts SET content = ? WHERE id = ?")
            .bind(content)
            .bind(id.to_string())
            .execute(self.pool)
            .await?;

        Ok(())
    }

    /// Delete a [`MemoryRecord`] by its `id`.
    ///
    /// # Errors
    ///
    /// Returns [`ClawError::NotFound`] if no record with the given `id` exists.
    pub async fn delete(&self, id: Uuid) -> ClawResult<()> {
        let affected = sqlx::query("DELETE FROM memories WHERE id = ?")
            .bind(id.to_string())
            .execute(self.pool)
            .await?
            .rows_affected();

        if affected == 0 {
            return Err(ClawError::NotFound {
                entity: "MemoryRecord".to_string(),
                id: id.to_string(),
            });
        }

        sqlx::query("DELETE FROM memory_tags WHERE memory_id = ?")
            .bind(id.to_string())
            .execute(self.pool)
            .await?;

        sqlx::query("DELETE FROM memories_fts WHERE id = ?")
            .bind(id.to_string())
            .execute(self.pool)
            .await?;

        Ok(())
    }

    /// List all [`MemoryRecord`]s, optionally filtered by [`MemoryType`].
    ///
    /// Results are ordered by `created_at` ascending.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the query fails.
    pub async fn list(&self, type_filter: Option<&MemoryType>) -> ClawResult<Vec<MemoryRecord>> {
        #[allow(clippy::type_complexity)]
        let rows: Vec<(String, String, String, String, Option<i64>, String, String)> =
            match type_filter {
                Some(mt) => sqlx::query_as(
                    "SELECT id, content, memory_type, tags, ttl_seconds, created_at, updated_at \
                     FROM memories WHERE memory_type = ? ORDER BY created_at ASC",
                )
                .bind(mt.as_str())
                .fetch_all(self.pool)
                .await?,
                None => sqlx::query_as(
                    "SELECT id, content, memory_type, tags, ttl_seconds, created_at, updated_at \
                     FROM memories ORDER BY created_at ASC",
                )
                .fetch_all(self.pool)
                .await?,
            };

        rows.into_iter().map(Self::row_to_record).collect()
    }

    /// Search for records whose tag list contains `tag`.
    ///
    /// Uses the normalised `memory_tags` index (O(log n)) rather than a
    /// full-table LIKE scan.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the query fails.
    pub async fn search_by_tag(&self, tag: &str) -> ClawResult<Vec<MemoryRecord>> {
        #[allow(clippy::type_complexity)]
        let rows: Vec<(String, String, String, String, Option<i64>, String, String)> =
            sqlx::query_as(
                "SELECT m.id, m.content, m.memory_type, m.tags, m.ttl_seconds, \
                        m.created_at, m.updated_at \
                 FROM memories m \
                 JOIN memory_tags mt ON mt.memory_id = m.id \
                 WHERE mt.tag = ? \
                 ORDER BY m.created_at ASC",
            )
            .bind(tag)
            .fetch_all(self.pool)
            .await?;

        rows.into_iter().map(Self::row_to_record).collect()
    }

    /// List memories with keyset pagination.
    ///
    /// Returns up to `opts.limit` records (or all if `limit == 0`) plus an
    /// optional cursor for the next page.  The cursor is the `id` of the last
    /// returned record; pass it back as `opts.cursor` to continue iterating.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the query fails.
    pub async fn list_paginated(
        &self,
        type_filter: Option<&MemoryType>,
        opts: &ListOptions,
    ) -> ClawResult<(Vec<MemoryRecord>, Option<String>)> {
        let limit = if opts.limit == 0 {
            i64::MAX
        } else {
            opts.limit as i64
        };
        // Fetch one extra row to detect whether a next page exists.
        let fetch = limit.saturating_add(1);

        #[allow(clippy::type_complexity)]
        let rows: Vec<(String, String, String, String, Option<i64>, String, String)> =
            match (&opts.cursor, type_filter) {
                (None, None) => {
                    sqlx::query_as(
                        "SELECT id, content, memory_type, tags, ttl_seconds, \
                            created_at, updated_at \
                     FROM memories \
                     ORDER BY created_at ASC, id ASC \
                     LIMIT ?",
                    )
                    .bind(fetch)
                    .fetch_all(self.pool)
                    .await?
                }
                (None, Some(mt)) => {
                    sqlx::query_as(
                        "SELECT id, content, memory_type, tags, ttl_seconds, \
                            created_at, updated_at \
                     FROM memories \
                     WHERE memory_type = ? \
                     ORDER BY created_at ASC, id ASC \
                     LIMIT ?",
                    )
                    .bind(mt.as_str())
                    .bind(fetch)
                    .fetch_all(self.pool)
                    .await?
                }
                (Some(cursor), None) => {
                    sqlx::query_as(
                        "SELECT id, content, memory_type, tags, ttl_seconds, \
                            created_at, updated_at \
                     FROM memories \
                     WHERE (created_at, id) > \
                         (SELECT created_at, id FROM memories WHERE id = ?) \
                     ORDER BY created_at ASC, id ASC \
                     LIMIT ?",
                    )
                    .bind(cursor)
                    .bind(fetch)
                    .fetch_all(self.pool)
                    .await?
                }
                (Some(cursor), Some(mt)) => {
                    sqlx::query_as(
                        "SELECT id, content, memory_type, tags, ttl_seconds, \
                            created_at, updated_at \
                     FROM memories \
                     WHERE memory_type = ? \
                       AND (created_at, id) > \
                           (SELECT created_at, id FROM memories WHERE id = ?) \
                     ORDER BY created_at ASC, id ASC \
                     LIMIT ?",
                    )
                    .bind(mt.as_str())
                    .bind(cursor)
                    .bind(fetch)
                    .fetch_all(self.pool)
                    .await?
                }
            };

        let has_more = rows.len() as i64 > limit;
        let page = if has_more {
            &rows[..limit as usize]
        } else {
            rows.as_slice()
        };

        let records: Vec<MemoryRecord> = page
            .iter()
            .cloned()
            .map(Self::row_to_record)
            .collect::<ClawResult<_>>()?;
        let next_cursor = if has_more {
            records.last().map(|r| r.id.to_string())
        } else {
            None
        };
        Ok((records, next_cursor))
    }

    /// Full-text search over the `memories_fts` index.
    ///
    /// The `query` follows FTS5 query syntax.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if the query fails.
    pub async fn fts_search(&self, query: &str) -> ClawResult<Vec<MemoryRecord>> {
        let ids: Vec<(String,)> =
            sqlx::query_as("SELECT id FROM memories_fts WHERE content MATCH ? ORDER BY rank")
                .bind(query)
                .fetch_all(self.pool)
                .await?;

        let mut records = Vec::with_capacity(ids.len());
        for (id_str,) in ids {
            #[allow(clippy::type_complexity)]
            let row: Option<(
                String,
                String,
                String,
                String,
                Option<i64>,
                String,
                String,
            )> = sqlx::query_as(
                "SELECT id, content, memory_type, tags, ttl_seconds, created_at, updated_at \
                     FROM memories WHERE id = ?",
            )
            .bind(&id_str)
            .fetch_optional(self.pool)
            .await?;
            if let Some(r) = row {
                records.push(Self::row_to_record(r)?);
            }
        }
        Ok(records)
    }

    /// Delete all records whose TTL has expired.
    ///
    /// Returns the number of records deleted.
    ///
    /// # Errors
    ///
    /// Returns a [`ClawError`] if any deletion fails.
    pub async fn expire_ttl(&self) -> ClawResult<u64> {
        let rows: Vec<(String, Option<i64>, String)> = sqlx::query_as(
            "SELECT id, ttl_seconds, created_at FROM memories WHERE ttl_seconds IS NOT NULL",
        )
        .fetch_all(self.pool)
        .await?;

        let now = Utc::now();
        let mut deleted = 0u64;

        for (id_str, ttl_secs, created_at_str) in rows {
            if let Some(ttl) = ttl_secs {
                let created_at = DateTime::parse_from_rfc3339(&created_at_str)
                    .map_err(|e| ClawError::Store(e.to_string()))?
                    .with_timezone(&Utc);
                let expiry = created_at + chrono::Duration::seconds(ttl);
                if now >= expiry {
                    sqlx::query("DELETE FROM memories WHERE id = ?")
                        .bind(&id_str)
                        .execute(self.pool)
                        .await?;
                    sqlx::query("DELETE FROM memories_fts WHERE id = ?")
                        .bind(&id_str)
                        .execute(self.pool)
                        .await?;
                    deleted += 1;
                }
            }
        }

        Ok(deleted)
    }

    fn row_to_record(
        row: (String, String, String, String, Option<i64>, String, String),
    ) -> ClawResult<MemoryRecord> {
        let (id_str, content, memory_type_str, tags_str, ttl_secs, created_at_str, updated_at_str) =
            row;
        Ok(MemoryRecord {
            id: Uuid::parse_str(&id_str).map_err(|e| ClawError::Store(e.to_string()))?,
            content,
            memory_type: memory_type_str.parse()?,
            tags: serde_json::from_str(&tags_str)?,
            ttl_seconds: ttl_secs.map(|s| s as u64),
            created_at: DateTime::parse_from_rfc3339(&created_at_str)
                .map_err(|e| ClawError::Store(e.to_string()))?
                .with_timezone(&Utc),
            updated_at: DateTime::parse_from_rfc3339(&updated_at_str)
                .map_err(|e| ClawError::Store(e.to_string()))?
                .with_timezone(&Utc),
        })
    }
}