surrealfs

What This Skill Does

SurrealFS is a high-performance virtual filesystem engineered specifically for AI agents, functioning as a persistent, queryable storage layer backed by SurrealDB. Unlike standard local filesystems, SurrealFS provides a unified hierarchical structure that exists independently of the underlying host operating system. This allows agents to maintain state, context, and long-term knowledge across disparate sessions. By utilizing a Rust-based core for high-throughput operations and a Python-based agent interface built on Pydantic AI, it bridges the gap between structured databases and traditional file manipulation. It supports standard POSIX-like operations such as ls, cat, grep, and write_file, but augments them with the power of SurrealDB, allowing for advanced metadata querying and multi-agent concurrency control. The architecture ensures that all filesystem interactions remain isolated within the virtual environment, effectively preventing agent actions from compromising the host machine's integrity.

Installation

To get started, first ensure you have Rust and Cargo installed. Install the core filesystem engine by running cargo install surrealfs. Once installed, you can launch the interactive REPL locally using surrealfs or connect to a remote database using surrealfs --endpoint ws://your-db-url. For AI integration, install the Python package via pip install surrealfs-ai. Finally, deploy the skill through the OpenClaw CLI using clawhub install openclaw/skills/skills/24601/surrealfs. Ensure your environment variables for database credentials are set if using a remote SurrealDB cluster.

Use Cases

• Persistent Agent Memory: Maintain project notes, code snippets, and session logs that persist even after the agent process is restarted.
• Collaborative Workspaces: Multiple agents can read from and write to the same virtual filesystem, utilizing SurrealDB permissions to manage data access.
• Knowledge Retrieval: Use the built-in grep and search capabilities to query vast amounts of document data stored in the virtual hierarchy.
• Automated Scaffolding: Programmatically generate project files, templates, and configurations that are instantly accessible to subsequent agent tasks.

Example Prompts

1. "Create a new directory named 'project_alpha' and write a summary of my current task into a file called 'notes.txt' within that directory."
2. "Search for all files containing the string 'TODO' in the '/workspace/projects' directory and print the last 10 lines of the first match found."
3. "Copy the contents of 'report_v1.md' to a new file named 'report_final.md' and ensure the file permissions are indexed in the database."

Tips & Limitations

SurrealFS shines when dealing with medium-to-large datasets where hierarchical search is frequent. While it supports piping from external commands, ensure the source input is sanitized. Note that while it mimics POSIX behavior, it does not replace the host's actual operating system; all paths are relative to the virtual root. Always prefer the WebSocket interface for production environments to enable better load balancing and database scalability.