A filesystem for AI agents, over your own S3.

What it is

agentic-fs gives an AI agent filesystem-style access to an organization's documents. It is not a chat box bolted onto a vector store. Your files stay in your S3, the single source of truth; a derived catalog makes list/glob/stat fast at scale; and the agent navigates with the same loop a coding agent uses on a repo. Documents (PDF, Office, and more) are extracted to text, so grep and read work on their contents.

Why it's shaped this way

• MCP-first. A bounded, scoped tool surface any MCP client can attach to, with REST alongside it.
• Grep is the floor. Two-stage, budgeted search over extracted text. Semantic search is an opt-in accelerator, not a dependency.
• Multi-tenant & secure. SSE-KMS everywhere, scope and namespace enforcement, an IdP-agnostic OAuth 2.1 resource server (bring your own IdP).
• Healable. S3 is canonical; the catalog is derived and reconciles back to S3.
• ~$2/mo idle. Serverless by default on Lambda, S3, and DynamoDB. You pay for what you use.
• Swappable everything. Object store, catalog, compute, extraction, connectors, and auth are each a small contract with a conformance kit.

The tool surface

whoami        who am I: tenant, scopes, namespaces
fs_list       list a namespace
fs_tree       directory tree (ls -R)
fs_glob       path globs (**/*.pdf)
fs_find       filter by type / size / mtime / status
fs_grep       two-stage regex over extracted text
fs_outline    a document's heading + page map
fs_read       ranged read, or by section
fs_tables     pull tables as structured rows
fs_diff       diff two documents
scratch_*     a per-principal scratch workspace

Tools are pluggable. Add your own as an entry point and it inherits scope enforcement, budgets, and audit for free.

Install

# the contracts (pydantic only)
pip install afs-core
# the service: stores, extraction, FastAPI + MCP mount, the afs CLI
pip install afs-server
# crawl your docs in (Local / S3 / Drive / LlamaHub readers)
pip install afs-connector-sdk

afs-core · afs-server · afs-connector-sdk  on PyPI · deploy with one terraform apply (terraform/).

Open to contributions

The core is built, and the platform is designed to grow without forking. New stores, connectors, extractors, and MCP tools are implement + register, certified by the same conformance kits. Good places to start are filed and labelled:

• good first issues: scoped, self-contained.
• help wanted: Redis/Valkey cache, Fargate, GuardDuty, a Postgres catalog, semantic search, more connectors.
• swap guides & decision records: how the seams work and why.

Read build-progress.md for what's done, what's next, and the thinking behind each slice.

What I'd love to do next

The core is built; these are the high-value ideas on deck. Each one is a filed, scoped issue with acceptance criteria, so you can pick one and run with it.

• More backends
  Postgres catalog · Redis/Valkey cache
• Serving & scale
  always-on Fargate · private VPC/network
• Search
  no-infra fs_search · Bedrock KB
• Security & auth
  S3 malware scan · managed Cognito IdP
• Connectors
  Google Drive incremental delta
• Good first issue
  ripgrep-parity grep flags

See the full open list, or open a new idea. Discussion welcome.

Acknowledgments

agentic-fs stands on ideas others published first:

• Mintlify: a virtual filesystem for their assistant. Two-stage grep, claims-pruned path tree, read-only semantics.
• Anthropic: effective context engineering & code execution with MCP.
• "Grep is the floor": Claude Code dropped indexing · why grep beat embeddings.
• Built on MCP · fsspec · LlamaHub · Docling.

A fuller reference list lives in the design doc.