RAM File System

Overview

claw_ramfs is a RAM-backed file system implementation in ESP-Claw. It registers through the ESP-IDF VFS interface, allowing applications to read and write in-memory files like ordinary files. Compared with FATFS (Flash storage), RAMFS provides faster reads and writes and reduces Flash wear, making it suitable for temporary files, caches, and runtime-generated data.

Main uses

Temporary file cache: intermediate data during LLM inference
Fast exchange area: temporary files produced by Lua scripts at runtime
Cross-component data sharing: pass data between components through file paths
Multi-level read/write: support syncing RAMFS content to FATFS or loading it from FATFS

API

Mount and unmount

#include "claw_ramfs.h"

claw_ramfs_config_t config = {
    .base_path = "/ram",
    .max_files = 8,
    .max_bytes = 64 * 1024,
    .caps = MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT,
};
esp_err_t err = claw_ramfs_register(&config);

Config item	Description
`base_path`	VFS mount point such as `/ram`; must start with `/` and not end with `/`
`max_files`	Maximum number of simultaneously open files, not total stored files
`max_bytes`	Maximum total bytes available for file content, excluding directory metadata
`caps`	Heap allocation flags; must include `MALLOC_CAP_8BIT`

Unmount:

claw_ramfs_unregister("/ram");

Capacity query

size_t total, used;
claw_ramfs_info("/ram", &total, &used);

FATFS sync

RAMFS supports bidirectional file/directory sync with FATFS:

// Sync one file to FATFS
claw_ramfs_sync_file_to_fatfs("/ram/output.json", "/fatfs/backup/output.json");

// Sync an entire directory tree to FATFS
claw_ramfs_sync_tree_to_fatfs("/ram/results", "/fatfs/backup/results");

// Load a file from FATFS to RAMFS
claw_ramfs_load_file_from_fatfs("/fatfs/config.json", "/ram/config.json");

// Load a directory tree from FATFS to RAMFS
claw_ramfs_load_tree_from_fatfs("/fatfs/cache", "/ram/cache");

Relationship to other components

cap_files: file operation tools can manage files under both FATFS and RAMFS paths
cap_lua: Lua scripts can read and write RAMFS paths for high-speed temporary storage
claw_memory: some runtime memory data can be cached in RAMFS

Memory selection suggestions

Scenario	Recommended `caps`
Small temporary files (< 32KB)	`MALLOC_CAP_INTERNAL \| MALLOC_CAP_8BIT`
Large cache files	`MALLOC_CAP_SPIRAM \| MALLOC_CAP_8BIT`