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

# Read memory entry
GET /toolfs/memory/<entry_id>

# Write memory entry  
PUT /toolfs/memory/<entry_id>

# List memory entries
LIST /toolfs/memory

See Memory Skill for details.

RAG Search

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

See RAG Skill for details.

Filesystem Access

# Read file
GET /toolfs/<mount_point>/<relative_path>

# Write file
PUT /toolfs/<mount_point>/<relative_path>

# List directory
LIST /toolfs/<mount_point>/<relative_path>

See Filesystem Skill for details.

Skill Execution

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

See Skill Skill for details.

Snapshot Management

# Create snapshot
POST /toolfs/snapshots/create

# Rollback snapshot
POST /toolfs/snapshots/rollback

# List snapshots
GET /toolfs/snapshots

See Snapshot Skill for details.

Skill API (Chained Operations)

Chain multiple operations in a single request:

POST /toolfs/skills/chain
Content-Type: application/json

{
  "operations": [
    {
      "type": "search_memory",
      "query": "user preferences"
    },
    {
      "type": "search_rag",
      "query": "ToolFS configuration",
      "top_k": 5
    },
    {
      "type": "read_file",
      "path": "/toolfs/data/config/settings.json"
    }
  ]
}

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:

{
  "type": "memory|rag|file|skill|snapshot",
  "source": "identifier (ID, path, command, skill_name)",
  "content": "string content or data",
  "metadata": {},
  "success": true|false,
  "error": "error message if failed"
}

Error Handling

Errors are returned with structured responses:

{
  "success": false,
  "error": "Detailed error message",
  "type": "error_type",
  "source": "operation_identifier"
}

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.