Struct FilesystemBackend 

pub struct FilesystemBackend {
    base_path: PathBuf,
    encryptor: Option<Encryptor>,
}

Filesystem-based persistence backend.

Fields

base_path: PathBuf

Base directory for storage.

encryptor: Option<Encryptor>

Optional encryptor for encryption at rest.

Implementations

impl FilesystemBackend

pub fn new(base_path: impl Into<PathBuf>) -> Self

Creates a new filesystem backend.

If the encryption feature is enabled and SUBCOG_ENCRYPTION_KEY is set, encryption at rest is automatically enabled.

Errors

Returns an error if the directory cannot be created.

pub fn with_create(base_path: impl Into<PathBuf>) -> Result<Self>

Creates a new filesystem backend with checked directory creation.

Errors

Returns an error if the directory cannot be created.

fn try_create_encryptor() -> Option<Encryptor>

Tries to create an encryptor from environment configuration.

fn decrypt_if_needed(&self, raw_data: Vec<u8>) -> Result<Vec<u8>>

Decrypts data if it’s encrypted, returns as-is otherwise.

This helper reduces nesting in the get method (clippy::excessive_nesting fix).

pub const fn encryption_enabled(&self) -> bool

Returns whether encryption is enabled.

fn memory_path(&self, id: &MemoryId) -> Result<PathBuf>

Returns the path for a memory file.

Security

The memory ID is sanitized to prevent path traversal attacks. Only alphanumeric characters, dashes, and underscores are allowed.

fn is_safe_filename(name: &str) -> bool

Checks if a filename is safe (no path traversal).

pub fn base_path(&self) -> &Path

Returns the base path.

Trait Implementations

impl PersistenceBackend for FilesystemBackend

fn store(&self, memory: &Memory) -> Result<()>

Stores a memory.

fn get(&self, id: &MemoryId) -> Result<Option<Memory>>

Retrieves a memory by ID.

fn delete(&self, id: &MemoryId) -> Result<bool>

Deletes a memory by ID.

fn list_ids(&self) -> Result<Vec<MemoryId>>

Lists all memory IDs.

fn get_batch(&self, ids: &[MemoryId]) -> Result<Vec<Memory>>

Retrieves multiple memories by their IDs in a single batch operation.

fn exists(&self, id: &MemoryId) -> Result<bool>

Checks if a memory exists.

fn count(&self) -> Result<usize>

Returns the total count of memories.