Indentia AgentFS

AgentFS is a shared, writable filesystem for coding agents. It lets Claude Code, Codex harnesses, and other agent runtimes mount the same workspace inside Kubernetes pods, use normal POSIX tools against it, and still feed a deeper retrieval layer through Indentia Cortex.

The core idea is simple:

• keep the hot path as a real filesystem
• keep lexical search close to the mount
• keep expensive semantic and graph-style indexing off the write path

That split matters when you run fleets of coding agents. Instead of paying for a fresh clone, index warm-up, cache warm-up, and workspace reconstruction in every pod, AgentFS gives each pod the same shared working state immediately.

Why AgentFS Is Useful

Coding-agent infrastructure in Kubernetes has a recurring set of problems:

1. Every pod starts cold. A new pod has to clone a repository, rehydrate caches, and discover the project structure before it can do useful work.
2. Every pod has its own copy of the workspace. Ten pods usually means ten clones, ten sets of git objects, ten copies of node_modules targets, and ten divergent scratch states.
3. Agent tools expect a real filesystem. Claude Code and Codex harnesses work best when they can cat, grep, find, git status, go test, and edit files directly.
4. Deep retrieval is expensive. Semantic search, dependency tracing, and graph reasoning should not block file reads, file writes, or git operations.

AgentFS addresses that by turning the workspace into shared infrastructure:

• one logical workspace
• many pods
• ordinary POSIX tools
• asynchronous indexing into Cortex

What This Enables

• A pool of Claude Code or Codex workers can attach to the same repository state without re-cloning it.
• Pods can restart without losing the shared workspace.
• Multiple agents can inspect and modify the same tree with cross-pod visibility.
• Git refs and objects can live in shared storage while per-pod build artifacts stay on local scratch disks.
• The hot path stays fast enough for agent loops, while Cortex handles the slower semantic and graph-aware questions.

At A Glance

Path	Purpose	Typical latency
/mnt/agentfs/...	byte-exact reads and writes, git, editors, build tools	sub-ms to low-ms
/.trigrep/... or agentfs-grep	warm lexical and regex search	low-ms
Cortex	semantic, dependency, and graph-style retrieval	seconds

The hot path never waits for Cortex.

Architecture

flowchart LR
subgraph Pods["Kubernetes Agent Pods"]
A["Claude Code Pod"]
B["Codex Harness Pod"]
C["Background Worker Pod"]
end
subgraph Mount["AgentFS Mount Plane"]
M["agentfs-mount sidecar"]
T["trigrep index + search"]
J["agentfs-janitor"]
end
subgraph Storage["Hot Storage"]
R["Redis Stack\npath tree\nfile blobs\nchunk index\nchange stream"]
end
subgraph Cold["Cold Retrieval Plane"]
I["agentfs-indexer"]
X["Indentia Cortex"]
end
A --> M
B --> M
C --> M
M --> R
M --> T
J --> R
I --> R
I --> X

Loading

Shared Workspace Pattern

flowchart TD
R["Shared git object database on AgentFS"] --> W1["Pod 1 worktree on /scratch"]
R --> W2["Pod 2 worktree on /scratch"]
R --> W3["Pod 3 worktree on /scratch"]
W1 --> B1["go build / npm install / cargo build"]
W2 --> B2["tests / edits / commits"]
W3 --> B3["agent review / indexing / grep"]

Loading

This split is often the best deployment model:

• shared .git and repository state on AgentFS
• pod-local working trees and build artifacts on emptyDir or node-local disks

It keeps collaboration and history shared while avoiding unnecessary FUSE round-trips for compiler output and build caches.

Why This Works Well For Claude Code And Codex Harnesses

Claude Code and Codex-style harnesses are filesystem-native. They are strongest when they can do ordinary developer operations:

• inspect files with cat
• search with grep, rg, and find
• run git status, git diff, and git worktree
• write files directly
• run builds and tests from a real checkout

AgentFS gives them that environment without forcing each pod to own a private clone.

Instead of this

new pod
-> clone repo
-> hydrate working tree
-> warm caches
-> rediscover context
-> finally begin work

You get this

new pod
-> mount AgentFS
-> immediately sees the shared tree
-> starts reading, editing, testing, and committing

That is especially useful when:

• you scale agent pools up and down
• pods are preemptible
• you want one repo to be worked on by several agents
• you want restarts to preserve workspace state
• you want retrieval systems to stay in sync with the current working tree

Why Not Just Use NFS Or Fresh Clones

Fresh clone per pod

Fresh clones are simple, but they amplify costs:

• clone time on every startup
• duplicated git objects
• duplicated caches
• duplicated workspace state
• stale copies when several pods work at once

Traditional shared filesystems

Traditional shared filesystems solve some of the duplication problem but do not give you the AgentFS-specific behavior:

• Redis-backed path-tree mutations
• change-stream driven indexing
• warm lexical search through trigrep
• explicit support for coding-agent access patterns
• optional Cortex integration for the cold path

Design Principles

AgentFS is structured around three deliberately separate layers.

1. Hot path: filesystem correctness and speed

The mount has to support the operations agents actually do:

• read and write files
• rename and delete files
• create directories and symlinks
• run git commands
• surface a normal POSIX-like interface

The byte-exact file blob is the source of truth for reads. Search indexes are secondary.

2. Warm path: lexical search close to the mount

Agents spend a lot of time asking lexical questions:

• where is handleLogin used?
• which files mention this symbol?
• which line contains this regex?

That should not go through a slow semantic stack. AgentFS therefore supports:

• /.trigrep/<query>/
• agentfs-grep
• agentfs-find
• agentfs_regex_search through the MCP server

3. Cold path: semantic and graph-aware retrieval

Questions like these belong in Cortex:

• why does this module exist?
• what depends on this package?
• what architectural path connects these concepts?
• where should an agent start editing?

AgentFS emits change events; agentfs-indexer pushes those updates into Cortex asynchronously.

Internal Data Model

The Redis layout is optimized for shared workspaces and incremental indexing.

Redis key	Type	Purpose
agentfs:tree	Hash	path tree metadata
agentfs:file:<slug>	Hash	byte-exact file blob + metadata
agentfs:chunk:<slug>:<idx>	Hash	text/vector chunk record
agentfs:chunks:<slug>	Set	chunk ids for a file
agentfs:lazy:<slug>	Hash	pointer for externally stored large files
agentfs:lock:<key>	String	advisory locks
agentfs:changes	Stream	async change feed for indexers and watchers
agentfs:idx:chunks	FT index	RediSearch full-text + vector search

Shared Workspace Semantics

AgentFS is designed for multiple pods reading and writing the same workspace.

Cross-pod sync

• every write emits a ChangeEvent
• other mounts tail the change stream
• remote events trigger tree reloads and cache invalidation
• pods quickly observe each other's updates

Git-aware operating model

For large teams of agents, the best practice is usually:

• keep .git on AgentFS
• create per-pod worktrees on /scratch
• let agentfs-janitor own scheduled git gc and shared maintenance

That reduces clone amplification while keeping build output local to each node.

Search Surfaces

POSIX mount

The default and most important surface. Agents use ordinary tools directly against /mnt/agentfs.

/.trigrep/...

A synthetic directory tree for literal and regex search, exposed by the mount.

agentfs-grep

A grep-compatible wrapper that can accelerate recursive search over AgentFS mounts.

agentfs-find

A find-compatible wrapper that avoids expensive FUSE-heavy traversals where possible.

MCP server

cmd/agentfs-mcp exposes regex-oriented search helpers to MCP clients without putting that logic in the hot path.

Kubernetes Deployment Model

flowchart LR
subgraph Pod1["Pod A"]
A1["agent runtime"]
A2["agentfs-mount"]
end
subgraph Pod2["Pod B"]
B1["agent runtime"]
B2["agentfs-mount"]
end
subgraph Infra["Cluster Services"]
R["Redis Stack"]
I["agentfs-indexer deployment"]
C["Cortex"]
end
A1 --> A2
B1 --> B2
A2 --> R
B2 --> R
I --> R
I --> C

Loading

This is the typical pattern:

• one agentfs-mount sidecar per pod
• one shared Redis deployment per workspace or tenant
• one or more agentfs-indexer replicas
• Cortex as the cold retrieval service

Current Boundaries

• Writable FUSE mode currently requires the Redis backend.
• SQLite, Milvus, and Zilliz remain useful for CLI workflows and read/search use cases, but they do not implement the full mutable mount path.
• Cortex integration is optional. AgentFS still works as a filesystem without the indexer.

Quick Start

1. Start Redis Stack

docker run --rm -d \
--name agentfs-redis \
-p 6379:6379 \
redis/redis-stack-server:latest

2. Install FUSE support

macOS:

brew tap macos-fuse-t/cask
brew install --cask fuse-t

Linux:

sudo apt-get update
sudo apt-get install -y fuse3 libfuse3-dev

3. Build

make build
make build-mount

4. Configure

cp config.example.yaml ~/.agentfs/config.yaml

At minimum, set:

• vectorstore.backend=redis
• vectorstore.redis.addr=localhost:6379
• one embedding provider

5. Initialize the tree

./bin/agentfs-admin init

6. Mount the filesystem

mkdir -p /mnt/agentfs
./bin/agentfs-mount /mnt/agentfs

7. Optionally run the Cortex indexer

./bin/agentfs-indexer

8. Use the mount

echo"hello"> /mnt/agentfs/hello.md
cat /mnt/agentfs/hello.md
grep -r hello /mnt/agentfs

CLI Examples

agentfs ls /
agentfs stat /docs/readme.md
agentfs cat /docs/readme.md
agentfs find /docs -name "*.md"
agentfs grep "embedding" /docs
agentfs search "how does the indexer work" /docs --top-k 5
agentfs ingest ./local-docs /docs

Configuration

config.example.yaml includes public examples for:

• Redis
• SQLite
• Milvus
• Zilliz
• Ollama
• OpenAI
• Cortex indexing
• FUSE cache and prefetch settings

AgentFS reads config from:

1. AGENTFS_CONFIG
2. ~/.agentfs/config.yaml

Repository Layout

cmd/
agentfs/ CLI for ls/cat/find/grep/search/ingest/bench
agentfs-admin/ bootstrap and admin commands
agentfs-mount/ FUSE mount
agentfs-indexer/ Redis change-stream consumer for Cortex
agentfs-janitor/ shared git workspace janitor
agentfs-mcp/ MCP server exposing AgentFS search helpers
agentfs-grep/ grep-compatible wrapper for trigrep acceleration
agentfs-find/ find-compatible wrapper for cache-backed trees
pkg/
vfs/ virtual filesystem core
vectorstore/ Redis, SQLite, Milvus, and Zilliz adapters
fuse/ FUSE implementation and cache layers
trigrep/ warm lexical search indexer
indexer/ Cortex integration
janitor/ git maintenance for shared workspaces
mcp/ MCP tools
embedding/ embedding providers
deploy/k8s/
reference Kubernetes manifests

Container Images

The Containerfile builds:

• ghcr.io/indentiaplatform/agentfs:latest
• ghcr.io/indentiaplatform/agentfs-mount:latest

docker build --target runtime -t ghcr.io/indentiaplatform/agentfs:latest .
docker build --target mount -t ghcr.io/indentiaplatform/agentfs-mount:latest .

Development

go test ./...
make fuse-test-docker

Useful areas:

• pkg/vfs for filesystem semantics
• pkg/fuse for mount behavior
• pkg/trigrep for warm lexical search
• pkg/indexer for Cortex integration
• pkg/janitor for shared git maintenance

Related Repositories

• AgentFS: https://github.com/IndentiaPlatform/AgentFS
• Cortex: https://github.com/IndentiaPlatform/Cortex

Origin

AgentFS is the current Indentia-maintained implementation of a shared, agent-oriented virtual filesystem. It is built specifically for coding-agent workflows where many pods need one coherent workspace.