About AFS

What is AFS?

AFS (Agentic File System) is a virtual file system abstraction layer that provides a unified, file-system-like interface for AI agents to access various types of storage backends. It enables agents to interact with different data sources through a consistent, path-based API.

Core Philosophy

Everything is a File — Database rows, API endpoints, cloud resources, and configuration all appear as paths in a virtual file tree.
Providers are Pluggable — Each storage backend implements the same interface. Swap S3 for GCS, SQLite for JSON — the API stays the same.
Agent-First Design — Built-in metadata, structured actions, and WORLD.md context files help AI agents understand and navigate data autonomously.
Composable Mounts — Mount multiple providers at different paths to build a unified virtual namespace spanning databases, cloud storage, APIs, and local files.

Architecture

AFS is built as a monorepo with a core abstraction layer and pluggable providers:

packages/
  core/          — Core AFS engine, mount system, routing
  cli/           — Command-line interface
  explorer/      — Interactive file explorer

providers/
  fs/            — Local filesystem
  git/           — Git repositories
  github/        — GitHub Issues & PRs
  sqlite/        — SQLite databases
  json/          — JSON/YAML virtual FS
  s3/            — AWS S3 buckets
  gcs/           — Google Cloud Storage
  cloudflare/    — Workers, KV, Pages
  mcp/           — MCP Server bridge
  http/          — Remote AFS over HTTP
  ...

Key Features

Metadata System

Every node carries structured metadata — kind, content type, children count, platform references, and custom user metadata via .meta paths.

Actions

Providers expose executable actions at .actions/ paths with JSON Schema input validation. Deploy workers, insert rows, trigger builds.

WORLD.md

Each provider can expose a WORLD.md file that gives AI agents context about the data source — what it contains, how to use it, what actions are available.

Namespaces

Organize mounts into named namespaces. Access staging vs production environments with @staging/path vs @production/path.