ToolFS

ToolFS is a unified virtual filesystem framework for LLM agents that provides access to files, memory, RAG systems, skills, and snapshots through a single /toolfs namespace.

Overview

ToolFS integrates multiple data sources and operations into one virtual filesystem:

• Memory: Persistent key-value storage for session data and context
• RAG: Semantic search over vector databases for document retrieval
• Filesystem: Access to mounted local directories
• Skills: Execute WASM-based skills mounted to virtual paths
• Snapshots: Create point-in-time snapshots and restore previous states

All operations respect session isolation, permission control, and audit logging for safe execution in sandboxed environments.

Available Skills

ToolFS is organized into functional modules. Each module provides specific capabilities:

Quick Start

Memory Operations

bash
1# Read memory entry
2GET /toolfs/memory/<entry_id>
3
4# Write memory entry  
5PUT /toolfs/memory/<entry_id>
6
7# List memory entries
8LIST /toolfs/memory

See Memory Skill for details.

RAG Search

bash
1# Semantic search
2GET /toolfs/rag/query?text=<query>&top_k=<number>

See RAG Skill for details.

Filesystem Access

bash
1# Read file
2GET /toolfs/<mount_point>/<relative_path>
3
4# Write file
5PUT /toolfs/<mount_point>/<relative_path>
6
7# List directory
8LIST /toolfs/<mount_point>/<relative_path>

See Filesystem Skill for details.

Skill Execution

bash
1# Execute skill
2GET /toolfs/<skill_mount_path>?text=<query>

See Skill Skill for details.

Snapshot Management

bash
1# Create snapshot
2POST /toolfs/snapshots/create
3
4# Rollback snapshot
5POST /toolfs/snapshots/rollback
6
7# List snapshots
8GET /toolfs/snapshots

See Snapshot Skill for details.

Skill API (Chained Operations)

Chain multiple operations in a single request:

json
1POST /toolfs/skills/chain
2Content-Type: application/json
3
4{
5  "operations": [
6    {
7      "type": "search_memory",
8      "query": "user preferences"
9    },
10    {
11      "type": "search_rag",
12      "query": "ToolFS configuration",
13      "top_k": 5
14    },
15    {
16      "type": "read_file",
17      "path": "/toolfs/data/config/settings.json"
18    }
19  ]
20}

Common Use Cases

• File Operations: "Read the config file from the project directory"
• Memory Persistence: "Store this conversation summary in memory"
• Semantic Search: "Search documents for information about X"
• Skill Execution: "Execute the RAG skill to find relevant content"
• State Management: "Create a snapshot before making changes"
• Recovery: "Restore the previous state"

Output Format

All operations return standardized result structures:

json
1{
2  "type": "memory|rag|file|skill|snapshot",
3  "source": "identifier (ID, path, command, skill_name)",
4  "content": "string content or data",
5  "metadata": {},
6  "success": true|false,
7  "error": "error message if failed"
8}

Error Handling

Errors are returned with structured responses:

json
1{
2  "success": false,
3  "error": "Detailed error message",
4  "type": "error_type",
5  "source": "operation_identifier"
6}

Common error types:

• access_denied: Session does not have permission
• not_found: Resource not found
• skill_error: Skill execution failed
• validation_error: Invalid input parameters
• filesystem_error: Filesystem operation failed

Best Practices

1. Use Sessions: Always create sessions with appropriate allowed_paths for security
2. Chain Operations: Use ChainOperations to minimize round trips
3. Snapshot Before Changes: Create snapshots before major filesystem modifications
4. Handle Errors: Check success field in results and provide fallback strategies
5. Leverage Metadata: Use metadata fields to pass context between operations

Module Documentation

For detailed information about each module, see:

• Memory Skill - Persistent storage operations
• RAG Skill - Semantic search operations
• Filesystem Skill - File and directory operations
• Skill Skill - Skill execution and management
• Snapshot Skill - State management operations

This documentation describes ToolFS version 1.0.0. Each module has its own detailed SKILL.md for specific operations.