Struct FileStore 

pub struct FileStore { /* private fields */ }

A file-based implementation of the Memory trait.

This provides persistent storage of conversation history using files. Supports both JSON (human-readable) and MessagePack (compact binary) formats.

Examples

use ceylon_next::memory::{FileStore, StorageFormat};
use std::sync::Arc;

#[tokio::main]
async fn main() {
    // JSON format
    let memory = Arc::new(
        FileStore::new("memory.json", StorageFormat::Json).await.unwrap()
    );

    // MessagePack format
    let memory_mp = Arc::new(
        FileStore::new("memory.msgpack", StorageFormat::MessagePack).await.unwrap()
    );
}

Implementations

impl FileStore

pub async fn new<P: Into<PathBuf>>( file_path: P, format: StorageFormat, ) -> Result<Self, String>

Creates a new file-based store with the given file path and format.

Arguments

• file_path - Path to the storage file
• format - Serialization format (JSON or MessagePack)

Examples

use ceylon_next::memory::{FileStore, StorageFormat};

#[tokio::main]
async fn main() {
    let store = FileStore::new("memory.json", StorageFormat::Json).await.unwrap();
}

Examples found in repository

examples/11_persistent_memory.rs (line 64)

async fn main() {
    println!("🤖 Ceylon Agent - Persistent Memory Example\n");

    // ============================================
    // Part 1: SQLite Backend
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📦 Part 1: SQLite Backend");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    let sqlite_path = "agent_memory.db";
    let sqlite_store = SqliteStore::new(sqlite_path).await
        .expect("Failed to create SQLite store");

    let mut agent = Agent::new("PersistentAssistant", "ollama::gemma3:latest");
    agent.with_memory(Arc::new(sqlite_store))
         .with_system_prompt("You are a helpful assistant with persistent memory across sessions.");

    println!("✅ Created agent with SQLite backend at {}\n", sqlite_path);

    // Run some tasks to populate memory
    let tasks = vec![
        "My name is Alice and I love programming in Rust",
        "What programming language do I like?",
    ];

    for prompt in tasks {
        println!("📋 Task: {}", prompt);
        let mut task = TaskRequest::new(prompt);
        task.with_priority(5);

        let response = agent.run(task).await;
        if let OutputData::Text(_) = response.result() {
            println!("✓ Task completed\n");
        }
    }

    println!("📊 SQLite database now contains conversation history");
    println!("   This data persists even after the program exits!\n");

    // ============================================
    // Part 2: File-based Backend (JSON)
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📄 Part 2: File-based Backend (JSON)");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    let json_path = "agent_memory.json";
    let file_store = FileStore::new(json_path, StorageFormat::Json).await
        .expect("Failed to create File store");

    let mut agent2 = Agent::new("FileAssistant", "ollama::gemma3:latest");
    agent2.with_memory(Arc::new(file_store))
          .with_system_prompt("You are a helpful assistant storing memories in JSON files.");

    println!("✅ Created agent with JSON file backend at {}\n", json_path);

    let task = TaskRequest::new("Remember: My favorite color is blue");
    let response = agent2.run(task).await;

    if let OutputData::Text(_) = response.result() {
        println!("✓ Memory saved to JSON file");
        println!("   You can open {} to view the human-readable data!\n", json_path);
    }

    // ============================================
    // Part 3: MessagePack Backend
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📦 Part 3: MessagePack Backend (Compact Binary)");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    let msgpack_path = "agent_memory.msgpack";
    let msgpack_store = FileStore::new(msgpack_path, StorageFormat::MessagePack).await
        .expect("Failed to create MessagePack store");

    let mut agent3 = Agent::new("BinaryAssistant", "ollama::gemma3:latest");
    agent3.with_memory(Arc::new(msgpack_store))
          .with_system_prompt("You are a helpful assistant using compact binary storage.");

    println!("✅ Created agent with MessagePack backend at {}\n", msgpack_path);

    let task = TaskRequest::new("Store this efficiently: The quick brown fox jumps over the lazy dog");
    let response = agent3.run(task).await;

    if let OutputData::Text(_) = response.result() {
        println!("✓ Memory saved to MessagePack file");
        println!("   Binary format is more compact than JSON!\n");
    }

    // ============================================
    // Part 4: Memory Migration
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("🔄 Part 4: Memory Migration Between Backends");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    // Create source and destination stores
    let source_db = SqliteStore::new("source.db").await.unwrap();

    // Create an agent with source backend and add some data
    let mut temp_agent = Agent::new("MigrationAgent", "ollama::gemma3:latest");
    temp_agent.with_memory(Arc::new(source_db));

    let task = TaskRequest::new("Migration test: This data will be migrated!");
    temp_agent.run(task).await;

    // Note: You would normally track your agent IDs. For this demo, we'll use
    // a known pattern - the agent creates entries with its own ID
    println!("💡 Tip: To migrate data, you need to know the agent's ID");
    println!("   In production, track agent IDs when creating agents\n");

    println!("✓ Migration between backends is available via migrate_memory()\n");
    println!("   Example: migrate_memory(&source, &target, \"agent-id\").await\n");

    // ============================================
    // Part 5: Export/Import Utilities
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("💾 Part 5: Export/Import Utilities");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    // Demonstrate export/import with the existing SQLite database
    println!("💡 Export and import utilities are available:\n");
    println!("   • export_to_json(store, agent_id, path)");
    println!("   • export_to_msgpack(store, agent_id, path)");
    println!("   • import_from_json(store, path)");
    println!("   • import_from_msgpack(store, path)\n");

    println!("✓ These functions allow you to backup and restore agent memories\n");

    // ============================================
    // Summary
    // ============================================
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📊 Summary: Available Backends");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    println!("1. InMemoryStore (default)");
    println!("   • Fast, but data lost on restart");
    println!("   • Best for: Development, testing\n");

    println!("2. SqliteStore");
    println!("   • Persistent, efficient queries");
    println!("   • Best for: Production apps, large datasets\n");

    println!("3. FileStore (JSON)");
    println!("   • Human-readable, easy to inspect");
    println!("   • Best for: Debugging, data sharing\n");

    println!("4. FileStore (MessagePack)");
    println!("   • Compact binary format");
    println!("   • Best for: Large datasets, bandwidth constraints\n");

    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!("📝 Files Created:");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

    println!("• agent_memory.db         - SQLite database");
    println!("• agent_memory.json       - JSON storage");
    println!("• agent_memory.msgpack    - MessagePack storage");
    println!("• backup.json             - Migrated data");
    println!("• exported_memory.json    - Exported snapshot");
    println!("• exported_memory.msgpack - Exported snapshot (binary)\n");

    println!("✅ Example completed successfully!");
    println!("\n💡 Tip: Check the created files to see your persisted data!");
    println!("   Try running this example again - your SQLite data will persist!");
}

pub fn file_path(&self) -> &PathBuf

Returns the path to the storage file.

pub fn format(&self) -> StorageFormat

Returns the storage format being used.

Trait Implementations

impl Memory for FileStore

fn store<'life0, 'async_trait>( &'life0 self, entry: MemoryEntry, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Stores a conversation in memory.

fn get<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<MemoryEntry>, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Retrieves a specific conversation by ID.

fn get_agent_history<'life0, 'life1, 'async_trait>( &'life0 self, agent_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<MemoryEntry>, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Retrieves all conversations for an agent.

fn get_recent<'life0, 'life1, 'async_trait>( &'life0 self, agent_id: &'life1 str, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<MemoryEntry>, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Retrieves the most recent N conversations for an agent.

fn search<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, agent_id: &'life1 str, query: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<MemoryEntry>, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Searches conversations for a query string.

fn clear_agent_memory<'life0, 'life1, 'async_trait>( &'life0 self, agent_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Clears all memory for an agent.