ToolFS is a specialized virtual filesystem framework designed for Large Language Model (LLM) agents. It unifies disparate interfaces—files, persistent memory, semantic search (RAG), and code execution (WASM skills)—into a single, POSIX-compliant /toolfs namespace.
By mapping complex state and capabilities to filesystem operations, ToolFS leverages the LLM's inherent understanding of path structures and file manipulation, significantly reducing the complexity of tool integration.
Current AI agent architectures often suffer from "tool bloat," where managing dozens of disparate APIs becomes a bottleneck. ToolFS solves this by providing:
- Natural Abstraction: LLMs inherently understand files and directories. Mapping tools to paths simplifies intent recognition.
- Unified State: Session history, knowledge bases, and local files share a single lifecycle.
- Agentic Autonomy: Context-aware skill documentation allows agents to discover and chain tools without hardcoded logic.
- Unified Namespace: A single entry point (
/toolfs) for files, session-bounded memory, vector-based RAG queries, and autonomous skills. - Unified Skill API: Register and execute WASM-based or native skills with context-aware documentation that helps agents understand when and how to use them.
- Session-Bounded Security: Fine-grained path-based permissions and isolated environments for multi-tenant agent deployments.
- Atomic Snapshots: Create instant, copy-on-write snapshots of the entire agent environment for rollback, debugging, and perfect reproducibility.
- Audit-Ready: Transparent JSON-based audit logging for every operation, ensuring compliance and observability.
ToolFS acts as an abstraction layer between the Agent and its environment:
ToolFS Internal Architecture
[ Agent ] <──> [ /toolfs Virtual Path ] <──> [ ToolFS Core ]
│
┌──────────────┬──────────────┬───────┴──────┬──────────────┐
▼ ▼ ▼ ▼ ▼
[ Local FS ] [ Memory KV ] [ RAG Store ] [ WASM Skills ] [ Snapshots ]
go get github.com/IceWhaleTech/toolfsCombine memory, RAG, and file access in a few lines:
package main
import (
"github.com/IceWhaleTech/toolfs"
)
func main() {
// Initialize with a root mount point
fs := toolfs.NewToolFS("/toolfs")
// Isolated session with path-level permissions
session, _ := fs.NewSession("agent-007", []string{"/toolfs/data", "/toolfs/memory", "/toolfs/rag"})
// Persistent Context (Memory)
fs.WriteFileWithSession("/toolfs/memory/last_query", []byte("How to build an agent?"), session)
// Semantic Retrieval (RAG)
// Simply read a virtual path!
results, _ := fs.ReadFileWithSession("/toolfs/rag/query?text=agent+design&top_k=3", session)
// Skill Execution
// Chains multiple operations: search memory -> execute skill -> save result
ops := []toolfs.Operation{
{Type: "search_memory", Query: "preferences"},
{Type: "execute_code_skill", SkillPath: "/toolfs/skills/processor"},
}
fs.ChainOperations(ops, session)
}Optimized for high-frequency agent loops. Tested on Apple M4 Pro.
| Operation | Throughput | Latency | Overhead |
|---|---|---|---|
| Memory Access | 1,200,000+ ops/s | <1 μs | 0 allocations |
| Path Resolution | 35,000,000+ ops/s | <30 ns | Cache-driven |
| RAG Search | 170,000+ ops/s | ~6 μs | Highly efficient |
| File I/O (Small) | 110,000+ ops/s | ~9 μs | Local-first |
While both focus on agent state, they serve different primary roles:
| Feature | ToolFS | AgentFS |
|---|---|---|
| Primary Goal | Unified Tool/Storage Abstraction | Structured State & Audit Trails |
| Storage Engine | Virtual Layer (File, Memory, RAG) | SQLite-backed |
| Tool Execution | Native & WASM Skills (Unified API) | Focus on CRUD of state |
| Audit Model | Per-path/Per-session logs | Transactional SQL logs |
Intersection: Both can be used together—AgentFS for deep structured memory, and ToolFS for providing a standard filesystem-like API to that memory alongside other tools.
ToolFS is inspired by the pattern of using filesystems as the primary interface for autonomous agents:
- How to Build Agents with Filesystems and Bash: Demonstrates 75% cost reduction by replacing custom tools with standard FS patterns.
- FUSE is All You Need: Exploring virtual filesystems for agent tool access.
- We Removed 80% of our Agents' Tools: Case study on radical simplification via filesystem-based tool design.
- Unified Skill System: Deep dive into the "Skill is Skill" architecture.
- RAG Implementation Guide: Building custom semantic search skills.
- Go API Reference: Detailed package documentation.
Built for the future of Autonomous Agents.