ceylon_next/memory/

mod.rs

//! Memory system for storing and retrieving agent conversation history.
//!
//! This module provides types and traits for implementing memory storage,
//! allowing agents to maintain context across multiple conversations.
//!
//! # Available Backends
//!
//! - [`InMemoryStore`] - Fast, volatile storage for development and testing
//! - [`SqliteStore`] - Persistent storage using SQLite database
//! - [`FileStore`] - File-based storage with JSON or MessagePack formats
//!
//! # Vector Memory & Semantic Search
//!
//! The [`vector`] module provides semantic search capabilities using vector embeddings:
//!
//! - **Local Vector Store** - In-memory vector storage with cosine similarity search
//! - **Embedding Providers** - OpenAI, Ollama, Hugging Face, and custom embedding models
//! - **Caching Layer** - Efficient embedding caching to reduce API costs
//! - **Semantic Search** - Find similar memories based on meaning, not just keywords
//!
//! Enable vector memory features in `Cargo.toml`:
//! ```toml
//! [dependencies]
//! ceylon = { version = "*", features = ["vector-openai"] }       # For OpenAI embeddings
//! ceylon = { version = "*", features = ["vector-ollama"] }       # For Ollama embeddings
//! ceylon = { version = "*", features = ["vector-huggingface"] }  # For Hugging Face embeddings
//! ceylon = { version = "*", features = ["full-vector"] }         # For all vector features
//! ```
//!
//! See the [`vector`] module documentation for detailed examples.
//!
//! # Migration Utilities
//!
//! - [`migrate_memory`] - Migrate data between different backends
//! - [`export_to_json`] / [`import_from_json`] - JSON backup/restore
//! - [`export_to_msgpack`] / [`import_from_msgpack`] - MessagePack backup/restore

use crate::llm::types::Message;
use async_trait::async_trait;
use serde::{Deserialize, Serialize};

// ============================================
// Core Types
// ============================================

/// A stored conversation between an agent and user.
///
/// Each memory entry represents a complete task execution, including
/// all messages exchanged between the user and agent.
///
/// # Examples
///
/// ```rust
/// use ceylon_next::memory::MemoryEntry;
/// use ceylon_next::llm::types::Message;
///
/// let messages = vec![
///     Message {
///         role: "user".to_string(),
///         content: "Hello!".to_string(),
///     },
///     Message {
///         role: "assistant".to_string(),
///         content: "Hi there!".to_string(),
///     },
/// ];
///
/// let entry = MemoryEntry::new(
///     "agent-123".to_string(),
///     "task-456".to_string(),
///     messages,
/// );
/// ```
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MemoryEntry {
    /// Unique identifier for this memory entry
    pub id: String,
    /// ID of the agent that created this memory
    pub agent_id: String,
    /// ID of the task this memory is associated with
    pub task_id: String,
    /// The conversation messages
    pub messages: Vec<Message>,
    /// Unix timestamp when this memory was created
    pub created_at: u64,
}

impl MemoryEntry {
    /// Creates a new memory entry.
    ///
    /// # Arguments
    ///
    /// * `agent_id` - The ID of the agent that created this memory
    /// * `task_id` - The ID of the task this memory is associated with
    /// * `messages` - The conversation messages to store
    pub fn new(agent_id: String, task_id: String, messages: Vec<Message>) -> Self {
        Self {
            id: uuid::Uuid::new_v4().to_string(),
            agent_id,
            task_id,
            messages,
            created_at: Self::current_timestamp(),
        }
    }

    fn current_timestamp() -> u64 {
        std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap()
            .as_secs()
    }
}

// ============================================
// Memory Trait
// ============================================

/// Trait for implementing memory storage backends.
///
/// The `Memory` trait defines the interface for storing and retrieving
/// agent conversation history. Implementations can use different storage
/// backends like in-memory, SQLite, file-based, etc.
///
/// # Examples
///
/// ```rust,no_run
/// use ceylon_next::memory::{Memory, MemoryEntry, InMemoryStore};
/// use std::sync::Arc;
///
/// #[tokio::main]
/// async fn main() {
///     let memory: Arc<dyn Memory> = Arc::new(InMemoryStore::new());
///
///     // Store a conversation
///     // let entry = MemoryEntry::new(...);
///     // memory.store(entry).await.unwrap();
/// }
/// ```
#[async_trait]
pub trait Memory: Send + Sync {
    /// Stores a conversation in memory.
    async fn store(&self, entry: MemoryEntry) -> Result<String, String>;

    /// Retrieves a specific conversation by ID.
    async fn get(&self, id: &str) -> Result<Option<MemoryEntry>, String>;

    /// Retrieves all conversations for an agent.
    async fn get_agent_history(&self, agent_id: &str) -> Result<Vec<MemoryEntry>, String>;

    /// Retrieves the most recent N conversations for an agent.
    async fn get_recent(&self, agent_id: &str, limit: usize) -> Result<Vec<MemoryEntry>, String>;

    /// Searches conversations for a query string.
    async fn search(&self, agent_id: &str, query: &str) -> Result<Vec<MemoryEntry>, String>;

    /// Clears all memory for an agent.
    async fn clear_agent_memory(&self, agent_id: &str) -> Result<(), String>;
}

// ============================================
// Module Declarations
// ============================================

mod in_memory;
mod sqlite;
mod file_store;
mod migration;

#[cfg(feature = "vector")]
pub mod vector;

pub mod advanced;

#[cfg(test)]
mod tests;

// ============================================
// Public Exports
// ============================================

pub use in_memory::InMemoryStore;
pub use sqlite::SqliteStore;
pub use file_store::{FileStore, StorageFormat};
pub use migration::{
    migrate_memory,
    export_to_json,
    import_from_json,
    export_to_msgpack,
    import_from_msgpack,
};