What Is InferenceFS, Why Does It Exist, How Does It Work, and What Does It Teach Us About LLMs?

Updated: September 2026

InferenceFS may be one of the most entertaining filesystem projects ever created—but underneath the joke is a surprisingly useful lesson about modern AI.

Its premise is wonderfully absurd:

Why store the contents of a file when a large language model can simply guess what the file probably contained from its filename?

Imagine creating:

requirements.txt
Code language: CSS (css)

without putting anything inside it.

When someone later runs:

cat requirements.txt
Code language: CSS (css)

InferenceFS asks an LLM something equivalent to:

What is the most likely contents of a file with the name /requirements.txt?
Code language: JavaScript (javascript)

The model might respond:

requests==2.32.5
flask==3.1.2
pytest==8.4.2

Those generated bytes become the contents returned by the filesystem.

Nothing resembling the original contents had to be stored.

Brilliant?

Terrifying?

Both.

InferenceFS is the 2026 successor to Philip Langdale’s earlier πfs, the famous experimental filesystem that represented file bytes as positions in the hexadecimal digits of π. The author explicitly describes InferenceFS as an April Fools’ project and warns users not to store anything they care about.

But the implementation itself is real.

It:

mounts through FUSE,
exposes normal-looking files and directories,
supports multiple LLM backends,
lazily generates file contents,
caches generated results,
attempts binary generation,
handles FUSE inode/file-descriptor lifecycle,
retries API calls after rate limits,
tracks apparent file sizes,
and lets normal programs operate against the mounted filesystem.

The project is therefore much more than a joke.

It is an unusually good laboratory for learning:

FUSE,
virtual filesystems,
LLM inference,
hallucination,
lossy compression,
caching,
binary generation,
AI reliability,
filesystem semantics,
lazy computation,
metadata,
API-backed infrastructure,
and the difference between plausible data and actual data.

1. What Is InferenceFS?

InferenceFS is a FUSE userspace filesystem written in Python.

Instead of storing the real contents of ordinary files, it maintains a source directory containing the filesystem structure and then asks an LLM to generate contents when a file is read.

Conceptually:

File path
   ↓
/project/config.yaml
   ↓
LLM
   ↓
"What would config.yaml probably contain?"
   ↓
Generated YAML
   ↓
Application sees it as file contents
Code language: JavaScript (javascript)

The official project describes the architecture this way:

The source directory supplies filenames and directory structure.
A read causes an LLM request based on the filename.
The model’s answer becomes file contents.
Binary responses may be returned as base64 and decoded.
Generated contents are cached.
Writes appear successful but their data is discarded.

That last point is critically important.

InferenceFS is not persistent generative storage.

It is closer to:

filesystem interface
        +
LLM-powered content generator
Code language: PHP (php)

than a conventional filesystem.

2. InferenceFS in One Sentence

InferenceFS is:

A FUSE filesystem where filenames act as prompts and LLM responses act as file contents.

3. The Most Important Thing to Understand

Suppose you run:

echo "My secret database password is abc123" > /mnt/inference/secret.txt
Code language: JavaScript (javascript)

A conventional filesystem stores:

My secret database password is abc123

InferenceFS does not.

The current implementation’s write() method returns:

len(buf)

to tell the calling program that the write succeeded.

But it does not persist buf.

Instead, it tracks only the highest written offset so that it can remember an apparent file size.

When the file is later read, InferenceFS asks the configured LLM approximately:

What is the most likely contents of a file with the name /secret.txt
Code language: JavaScript (javascript)

and returns whatever the model generates.

Therefore:

What you write
      ≠
what you later read

That difference defines InferenceFS.

4. InferenceFS vs πfs

InferenceFS directly continues the joke started by πfs.

πfs

πfs approximately says:

Your data already exists inside π.
Store locations into π.

InferenceFS

InferenceFS says:

Your data probably exists somewhere in the model's knowledge.
Just remember what the file was called.

The original project’s comparison is roughly:

Property	πfs	InferenceFS
Source of reconstructed content	π	LLM
Metadata	Byte positions	Filename/path
Retrieval	BBP computation	Model inference
Exact reconstruction	Intended	No
Computational model	Deterministic mathematics	Probabilistic generation
Main limitation	Metadata > data	Generated content ≠ original
FUSE generation	C/FUSE 2	Python/pyfuse3
Main lesson	Information theory	AI as extreme lossy compression

InferenceFS’s author describes πfs as having impractical metadata but theoretically exact reconstruction, while InferenceFS has tiny metadata but an extremely lossy “codec.”

5. Why Was InferenceFS Created?

On the surface:

because storing files is expensive

and:

LLMs already saw the internet

so perhaps they can “remember” your files.

That is the satire.

The deeper idea is much more interesting.

InferenceFS asks:

What does it mean when we claim that an LLM “knows” something?

Suppose an LLM has seen thousands of examples of:

Dockerfile

Then asking it to generate /Dockerfile may produce something extremely plausible.

For example:

FROM python:3.14-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python", "app.py"]
Code language: JavaScript (javascript)

The model has not necessarily retrieved your Dockerfile.

It has generated:

a statistically plausible Dockerfile

InferenceFS turns that distinction into something you can literally mount.

6. Retrieval vs Inference

This distinction is essential.

Retrieval

A storage system normally performs:

identifier
   ↓
retrieve stored bytes
   ↓
exact original bytes

Example:

/foo.txt
   ↓
disk block 12345
   ↓
Hello world

InferenceFS

InferenceFS performs:

identifier
   ↓
prompt LLM
   ↓
generate probable contents

Example:

/foo.txt
   ↓
"What probably belongs in /foo.txt?"
   ↓
Hello there!
Code language: JavaScript (javascript)

That is generation, not retrieval.

7. The Core Architecture

InferenceFS can be represented as:

                       Application
                           |
                    open/read/write
                           |
                           v
                     Linux VFS
                           |
                           v
                       FUSE 3
                           |
                           v
                       pyfuse3
                           |
                           v
                  +----------------+
                  |  InferenceFS   |
                  +----------------+
                    /      |      \
                   /       |       \
                  v        v        v
             Source     LRU Cache   LLM Backend
            Directory                  |
                                        |
                        +---------------+---------------+
                        |               |               |
                        v               v               v
                      Gemini          Claude       Claude Code

The source directory contains real filesystem metadata.

The generated contents live primarily:

inside memory cache

after generation.

8. Source Directory vs Mount Directory

InferenceFS needs two important paths:

source

and:

mountpoint

Example:

mkdir -p /tmp/inference-source
mkdir -p /tmp/inference-mount

The source directory might contain:

/tmp/inference-source/
├── hello.py
├── README.md
├── config.yaml
└── docs/
    └── architecture.md

You then mount:

/tmp/inference-source

through InferenceFS at:

/tmp/inference-mount

Applications access:

/tmp/inference-mount

9. What Is Actually Stored?

This deserves careful treatment.

InferenceFS does store real filesystem metadata:

directory names,
file names,
paths,
ownership,
permissions,
timestamps,
directory structure,
symbolic links,
extended attributes where supported.

The source files can also contain numeric file-size metadata after writes.

What it does not store is the written payload.

So a file might physically contain:

in the source directory.

That may mean:

"The virtual file was written up to 27 bytes."
Code language: JSON / JSON with Comments (json)

It does not mean the virtual contents are "27".

The content comes from the LLM.

10. What Happens When You Create a File?

Suppose:

touch /mnt/inference/hello.py

InferenceFS creates the corresponding source-side file.

Conceptually:

Mounted filesystem

/mnt/inference/hello.py

            ↓

Source metadata

/source/hello.py

The file contents have not yet been generated.

This is important.

InferenceFS uses lazy generation.

The model is not queried merely because a file exists.

11. Lazy Content Generation

The current implementation intentionally waits until:

read()

before generating content.

It does not generate on:

create()

or:

open()

This avoids spending API calls on files that are never read.

Flow:

touch file.py
     ↓
metadata created
     ↓
NO model call

open file.py
     ↓
NO model call

read file.py
     ↓
model call
Code language: CSS (css)

This is a solid systems-design choice even though the project itself is intentionally absurd.

12. What Happens During a Read?

Suppose:

cat /mnt/inference/hello.py

The flow becomes:

cat
 ↓
Linux VFS
 ↓
FUSE
 ↓
pyfuse3
 ↓
InferenceFS.read()
 ↓
_check cache
 ↓
cache miss
 ↓
_generate_content("/hello.py")
 ↓
LLM backend
 ↓
generated bytes
 ↓
LRU cache
 ↓
read requested slice
 ↓
cat
Code language: JavaScript (javascript)

The core implementation effectively performs:

content = await self._ensure_content(fd)
return content[offset:offset + length]
Code language: JavaScript (javascript)

and _ensure_content() consults the LRU cache before requesting generation.

13. The Prompt

The current source uses the core user prompt:

What is the most likely contents of a file with the name {filename}
Code language: JavaScript (javascript)

The path might therefore transform into:

What is the most likely contents of a file with the name /src/main.py
Code language: JavaScript (javascript)

or:

What is the most likely contents of a file with the name /kubernetes/deployment.yaml
Code language: JavaScript (javascript)

The filename and directory structure effectively become prompt engineering.

14. Directory Names Matter

This means:

/app/config.yaml

may generate something different from:

/kubernetes/config.yaml

or:

/prometheus/config.yaml

because InferenceFS sends the relative path rather than merely the basename.

That gives the model contextual hints.

For example:

/nginx/nginx.conf

is strongly suggestive.

So is:

/terraform/main.tf

or:

/python/requirements.txt

The directory hierarchy effectively becomes part of your prompt.

15. Filenames Become an API

In a normal filesystem:

filename = identifier

With InferenceFS:

filename = identifier + prompt

That is a very unusual design property.

Naming files becomes equivalent to specifying desired output.

Compare:

config.yaml
Code language: CSS (css)

with:

kubernetes-production-nginx-config.yaml
Code language: CSS (css)

The second provides much more semantic information to the model.

16. Supported LLM Backends

The current implementation has three registered backends:

claude
claude-code
gemini

Usage:

inferencefs --backend gemini SOURCE MOUNTPOINT

or:

inferencefs --backend claude SOURCE MOUNTPOINT

or:

inferencefs --backend claude-code SOURCE MOUNTPOINT

17. Google Gemini Backend

The project README currently recommends the Gemini backend.

Example:

export API_KEY="YOUR_API_KEY"

inferencefs \
    --backend gemini \
    /tmp/source \
    /tmp/mount
Code language: JavaScript (javascript)

The current main branch hard-codes:

gemini-3.1-flash-lite-preview
Code language: CSS (css)

inside the implementation at the time of this review.

Because model availability and provider pricing change frequently, treat that model identifier as an implementation detail of the current repository rather than a permanent interface.

18. Claude API Backend

Claude can be used directly:

export API_KEY="YOUR_ANTHROPIC_KEY"

inferencefs \
    --backend claude \
    /tmp/source \
    /tmp/mount
Code language: JavaScript (javascript)

The current source uses:

claude-sonnet-4-20250514

for that backend.

Again, model IDs are vendor-specific implementation details and may change in future project versions.

19. Claude Code Backend

InferenceFS can also call the locally installed Claude Code CLI:

inferencefs \
    --backend claude-code \
    /tmp/source \
    /tmp/mount

This backend does not use API_KEY through InferenceFS.

Instead, it shells out to:

claude

and relies on Claude Code’s existing authentication.

The implementation calls the CLI in noninteractive mode using JSON output and a one-turn request.

You therefore need the claude command installed, authenticated and visible in your PATH.

20. Backend Interface

Internally, each backend implements:

generate_file_contents(filename: str) -> bytes
Code language: HTTP (http)

Conceptually:

                  ContentGenerator
                         |
        +----------------+---------------+
        |                |               |
        v                v               v
     Claude         Claude Code       Gemini

This is clean separation.

The FUSE layer does not need to understand the model provider.

It simply asks:

generate_file_contents(filename)

and expects bytes.

21. Installation Requirements

As of September 2026, the PyPI project declares:

Python >= 3.14

and dependencies including:

anthropic >= 0.40.0
google-genai >= 1.68.0
pyfuse3 >= 3.4.2
trio >= 0.33.0

Because pyfuse3 interfaces with native FUSE libraries, Linux development packages are also required.

The project’s developer instructions call out:

libfuse3-dev
pkg-config
build-essential

22. Recommended Platform

The easiest environment is:

Linux

preferably:

Ubuntu / Debian

with FUSE 3.

InferenceFS uses:

pyfuse3

rather than the older FUSE 2 architecture used by πfs.

This is a much more modern foundation.

23. Install FUSE 3 on Ubuntu/Debian

Install the system prerequisites:

sudo apt update

sudo apt install -y \
    fuse3 \
    libfuse3-dev \
    pkg-config \
    build-essential

Verify:

fusermount3 --version

Check the FUSE device:

ls -l /dev/fuse

You should normally have:

/dev/fuse

available.

24. Python 3.14 Requirement

InferenceFS currently requires:

Python >= 3.14

This is important because many stable Linux distributions may have an older system Python.

Do not replace your operating system Python just to run InferenceFS.

A separate virtual environment or Python version manager is safer.

Using uv is particularly convenient because the project itself uses it.

25. Install From PyPI

The current published release is:

InferenceFS 1.0.0
Code language: CSS (css)

released:

April 1, 2026

With an existing Python 3.14 environment:

python --version

Confirm:

Python 3.14.x
Code language: CSS (css)

Then:

python -m venv .venv
source .venv/bin/activate

pip install --upgrade pip
pip install inferencefs

Verify:

inferencefs --help

26. Install Using `uv`

A clean setup is:

uv python install 3.14
Code language: CSS (css)

Create a virtual environment:

uv venv --python 3.14
Code language: CSS (css)

Activate it:

source .venv/bin/activate

Install:

uv pip install inferencefs

Then:

inferencefs --help

27. Install From Source

For development or source inspection:

git clone https://github.com/philipl/inferencefs.git
cd inferencefs
Code language: PHP (php)

Then:

uv sync

The project itself documents this workflow.

Run:

uv run inferencefs --help

Run the tests:

uv run pytest

Lint:

uv run ruff check src tests

The repository documents both test and lint commands.

28. Project Structure

The core repository is simple:

inferencefs/
├── src/
│   └── inferencefs/
│       ├── __init__.py
│       ├── inferencefs.py
│       ├── backends.py
│       └── main.py
│
├── tests/
│   ├── test_main.py
│   ├── test_inferencefs.py
│   └── test_backends.py
│
├── README.md
├── appendix.md
├── CLAUDE.md
├── pyproject.toml
└── LICENSE

29. Main Components

`main.py`

Handles:

CLI arguments,
backend selection,
API key loading,
FUSE options,
logging,
FUSE initialization,
Trio event loop,
clean unmount.

`inferencefs.py`

Implements:

FUSE operations,
inode tracking,
path mapping,
reads,
writes,
caching,
directory operations,
persisted size metadata,
rate-limit handling.

`backends.py`

Implements:

backend abstraction,
Claude API,
Claude Code,
Gemini,
text/binary response handling,
base64 recovery,
magic-byte detection.

30. Your First InferenceFS Filesystem

Create two directories:

mkdir -p /tmp/inference-source
mkdir -p /tmp/inference-mount

Set your Gemini API key:

export API_KEY="YOUR_API_KEY"
Code language: JavaScript (javascript)

Mount:

inferencefs \
    --backend gemini \
    /tmp/inference-source \
    /tmp/inference-mount

If running from source:

uv run inferencefs \
    --backend gemini \
    /tmp/inference-source \
    /tmp/inference-mount

31. Create Your First File

From another terminal:

touch /tmp/inference-mount/hello.py

Now:

ls -l /tmp/inference-mount

The interesting part happens when you read it:

cat /tmp/inference-mount/hello.py

InferenceFS asks the model what /hello.py should probably contain.

You might receive something like:

def main():
    print("Hello, World!")


if __name__ == "__main__":
    main()
Code language: PHP (php)

The exact output is model-dependent.

32. Try Different Filename Semantics

Create:

touch /tmp/inference-mount/requirements.txt

Read:

cat /tmp/inference-mount/requirements.txt

Then:

touch /tmp/inference-mount/Dockerfile
cat /tmp/inference-mount/Dockerfile

Then:

touch /tmp/inference-mount/docker-compose.yaml
cat /tmp/inference-mount/docker-compose.yaml

Then:

touch /tmp/inference-mount/index.html
cat /tmp/inference-mount/index.html

This is where InferenceFS becomes fascinating.

The filesystem effectively exposes the model’s priors about common filenames.

33. Contextual Path Experiment

Try:

mkdir -p /tmp/inference-mount/kubernetes
touch /tmp/inference-mount/kubernetes/deployment.yaml

Then:

cat /tmp/inference-mount/kubernetes/deployment.yaml

Compare with:

mkdir -p /tmp/inference-mount/github
touch /tmp/inference-mount/github/deployment.yaml

cat /tmp/inference-mount/github/deployment.yaml

The same basename may generate different content because the relative path provides context.

That is a great demonstration of prompt conditioning.

34. Configuration Options

The current CLI accepts approximately:

inferencefs
    [--backend {claude,claude-code,gemini}]
    [--api-key API_KEY]
    [--max-tokens MAX_TOKENS]
    [--cache-size CACHE_SIZE_MIB]
    [-d]
    [-o OPTIONS]
    source
    mountpoint
Code language: CSS (css)

The source currently defaults the backend to:

claude

although the README recommends Gemini for its preferred experience.

35. `--backend`

Choose the content generator:

--backend gemini

or:

--backend claude

or:

--backend claude-code

36. `--api-key`

Instead of using:

export API_KEY=...
Code language: JavaScript (javascript)

you may provide:

inferencefs \
    --backend gemini \
    --api-key "..." \
    SOURCE \
    MOUNT
Code language: JavaScript (javascript)

For security, environment variables or a secure secrets mechanism are generally preferable to putting secrets directly into command lines, because command arguments may be visible in process listings or shell history.

37. `API_KEY`

If --api-key is absent, the current CLI checks:

API_KEY

from the environment.

Example:

export API_KEY="$(cat ~/.config/inferencefs/gemini-key)"
Code language: JavaScript (javascript)

Then:

inferencefs --backend gemini source mount

38. `--max-tokens`

Control maximum model output:

--max-tokens 2048

Example:

inferencefs \
    --backend gemini \
    --max-tokens 2048 \
    /tmp/source \
    /tmp/mount

The backend default is currently:

tokens.

Larger limits can:

generate larger files,
increase latency,
increase provider cost,
consume more cache memory.

39. `--cache-size`

InferenceFS uses an in-memory LRU cache.

Default:

256 MiB

Override:

--cache-size 64

for:

64 MiB

Example:

inferencefs \
    --backend gemini \
    --cache-size 64 \
    /tmp/source \
    /tmp/mount

40. Why the Cache Matters

Without caching:

read file
 ↓
API request

read again
 ↓
another API request

read again
 ↓
another API request

That would be:

slow,
expensive,
inconsistent.

Instead:

first read
 ↓
LLM request
 ↓
cache

second read
 ↓
cache hit

The LRU policy removes older entries when the memory limit is exceeded.

41. Important Cache Consequence

The cache provides temporary consistency.

Suppose:

/config.yaml

generates:

port: 8080
Code language: HTTP (http)

While that content remains cached, reads generally see the same bytes.

But if:

the process restarts,
the filesystem is unmounted/remounted,
or the cache entry is evicted,

InferenceFS may query the model again.

The new result might be:

port: 3000
Code language: HTTP (http)

Therefore:

A filename does not permanently identify a particular byte sequence.

This is radically different from ordinary storage.

42. Cache Eviction Means Data Mutation

Consider:

read A
↓
generate A1

cache fills

A evicted

read A
↓
generate A2

Potentially:

A1 != A2

No rename.

No write.

No modification timestamp change required.

The “file” simply changed because inference was performed again.

That is completely unacceptable for real persistent storage—but fantastic for demonstrating why generative output is not retrieval.

43. Debug Mode

Run:

inferencefs \
    -d \
    --backend gemini \
    /tmp/source \
    /tmp/mount

The CLI enables debug-level logging and adds the FUSE debug option.

This is recommended while learning the project.

You can observe when content is:

Generating content for /something.txt

rather than served from cache.

44. Standard FUSE Options

InferenceFS accepts:

-o OPTIONS

with comma-separated FUSE options.

Example conceptually:

-o option1,option2

These are passed through to pyfuse3.

The program also sets:

fsname=inferencefs

on the mount.

45. How Writes Actually Work

This is one of the best parts of the project.

Consider:

printf "HELLO" > /tmp/inference-mount/test.txt
Code language: JavaScript (javascript)

The application’s write() call sends five bytes:

H E L L O

InferenceFS receives them.

But its implementation essentially does:

end = offset + len(buf)

if end > previous_size:
    written_size = end

return len(buf)
Code language: JavaScript (javascript)

The buf itself is discarded.

The program sees a successful write.

The data disappears.

46. The Ultimate `/dev/null` With Confidence

You can think of InferenceFS writes approximately as:

/dev/null
+
file-size tracking
+
future hallucination
Code language: JavaScript (javascript)

That is slightly simplified but captures the spirit.

47. Written Size Persistence

Why track the written size?

Suppose an application writes:

100 bytes

The system may later call:

stat()

and expect the file size to be:

InferenceFS therefore records the high-water mark.

When the file descriptor is released, the size may be written to the corresponding source file as an ASCII integer.

For example:

source/test.txt

might physically contain:

That means:

virtual apparent size = 100 bytes

not:

virtual content = "100"
Code language: JavaScript (javascript)

48. File Size Priority

The implementation determines regular-file size approximately in this order:

1. generated content exists in cache
       ↓
   actual generated content length

2. current written size exists in memory
       ↓
   written high-water mark

3. persisted numeric size exists in source file
       ↓
   persisted size

4. otherwise
       ↓
   fake size

49. Why Unread Files Pretend to Be 1 GiB

This is a clever implementation hack.

An empty source file normally reports:

size = 0

Some applications might therefore decide there is nothing to read.

InferenceFS instead reports unread regular files as:

1 GiB

using:

1 << 30

until content has actually been generated.

That encourages programs to call:

read()

where the actual content can be generated.

When the generated stream returns EOF, the application discovers the real end.

50. A Beautiful Filesystem Hack

This illustrates a broader systems principle.

Sometimes metadata cannot be known until an expensive operation occurs.

InferenceFS essentially says:

"I don't know the real size yet,
but please try reading."
Code language: PHP (php)

So it supplies a large placeholder.

It is a clever example of lazy metadata resolution.

51. Async Architecture

InferenceFS uses:

Trio

because pyfuse3 operates asynchronously.

The problem is that LLM SDK/API calls may block.

So the implementation runs model generation using:

trio.to_thread.run_sync(...)
Code language: CSS (css)

Architecture:

FUSE async loop
      |
      +---- ordinary FS operation
      |
      +---- LLM call
                |
                v
         worker thread
Code language: JavaScript (javascript)

This avoids blocking the Trio event loop while waiting for remote inference.

52. Rate-Limit Handling

InferenceFS recognizes rate-limit conditions.

Its generation flow can retry:

up to 3 retries

after the first request attempt.

For Gemini, it looks for signals such as:

429
RESOURCE_EXHAUSTED
retryDelay

For Anthropic, it recognizes rate-limit exception naming and attempts to derive a retry delay.

This is another example where the joke project contains real engineering.

53. Failure Behavior

If content generation ultimately fails, the FUSE layer raises:

EIO

or:

I/O error

to the calling program.

That makes sense.

From a filesystem consumer’s point of view:

the storage backend failed

even though the “storage backend” happens to be an LLM.

54. Binary File Support

InferenceFS does not restrict itself to text.

Its system prompt instructs models:

text file
   ↓
return raw text

binary file
   ↓
return base64-encoded binary
Code language: JavaScript (javascript)

The client then attempts to detect and decode base64.

This allows experiments such as:

touch /tmp/inference-mount/image.png

then:

cp /tmp/inference-mount/image.png /tmp/test.png

Whether the result is actually useful is another matter.

55. Binary Response Decoder

The response decoder is more sophisticated than you might expect.

It tries multiple strategies:

Strategy 1

Strictly decode the entire response as base64.

Strategy 2

Repair likely missing/truncated padding.

Strategy 3

Remove a small number of hallucinated non-base64 characters.

Strategy 4

Find the longest base64-looking block within mixed text.

Strategy 5

If no valid binary payload can be established, treat the response as UTF-8 text.

56. Binary Magic Bytes

To avoid interpreting ordinary text as binary, InferenceFS checks decoded content for known magic bytes.

The current table recognizes signatures associated with formats such as:

PNG
GIF
JPEG
ZIP
PDF
ELF
PE/MZ
WebAssembly
Mach-O
gzip
bzip2
xz
7-Zip
RIFF
ICO
BMP
RAR

It also checks for non-printable bytes.

57. Why Binary Generation Is Fascinating

Text-generation models are naturally good at formats such as:

.py
.yaml
.json
.html
.ini
.csv
.md
Code language: CSS (css)

because these formats are represented directly as textual tokens in massive quantities of training data.

Binary data is different.

To construct:

PNG
ZIP
gzip
SQLite
FLAC
ELF

the model may need to maintain:

exact bytes,
checksums,
offsets,
compressed streams,
length fields,
indexes,
internal references,
codec constraints.

That is much harder than predicting plausible textual syntax.

58. Binary Formats That Work Better

The author’s testing found relatively strong results for:

Text formats

Python
YAML
HTML
JSON
CSV
LaTeX
RTF
INI

Simpler/common binary headers

PNG
JPEG
GIF
WAV
MP4
PDF
ELF
PE
WASM

Header-oriented containers

RIFF
ISO BMFF
Ogg
FLV

“Works” here does not mean arbitrary production-grade files are guaranteed to be valid.

It means models often reproduce enough recognizable format structure to make interesting demonstrations.

59. Formats That Work Poorly

The author’s testing identifies significant problems with:

Compressed internals

ZIP
gzip
bzip2

Codec-specific formats

FLAC
AAC
MIDI

Cross-referenced structures

ZIP central directory
SQLite pages
OLE2

Why?

Because exact binary relationships must be calculated rather than merely approximated.

60. Predicting Bytes vs Executing Algorithms

This is one of InferenceFS’s deepest lessons.

An LLM may know that ZIP files begin with:

PK

or:

50 4B 03 04

That is pattern knowledge.

But producing a valid DEFLATE stream requires executing an exact algorithm.

Similarly, the model may know that PNG has recognizable chunks.

But if lengths, CRCs and compressed streams must all align exactly, probability alone is a poor substitute for computation.

The author’s appendix summarizes this distinction as a boundary between learned format patterns and algorithmically constrained structures.

61. LLMs as Lossy Compression

This is the intellectual heart of InferenceFS.

Imagine that a model’s weights are a giant lossy representation of its training distribution.

Then:

model weights
      =
shared decoder/codebook

and:

filename
      =
tiny index/query

The model “decompresses”:

config.yaml
Code language: CSS (css)

into:

server:
  port: 8080
database:
  host: localhost

The apparent compression ratio is extraordinary.

But there is a catch:

generated result != original result

The author explicitly frames this as extreme lossy compression: what comes back is plausible rather than faithful.

62. A Useful Analogy

Imagine destroying every recipe in the world but retaining filenames:

chocolate_cake_recipe.txt
carbonara.txt
naan_recipe.txt
Code language: CSS (css)

Then hiring a chef and saying:

"Tell me what this recipe probably contained."
Code language: JSON / JSON with Comments (json)

The chef may produce an excellent recipe.

But it is not necessarily:

the recipe you originally stored

InferenceFS does the digital equivalent.

63. Another Analogy: Human Memory

Suppose someone asks:

What did your high school classroom look like?

You may remember:

desks,
whiteboard,
windows,
teacher’s table.

Your answer may be highly plausible.

But perhaps the whiteboard was actually green.

Perhaps there were 28 desks rather than 24.

Your brain reconstructed a plausible memory.

InferenceFS intentionally treats an LLM somewhat like that reconstruction engine.

64. Determinism

Normal storage aims for:

write X
read X

InferenceFS has:

name N
generate approximately X₁

later:

name N
generate approximately X₂

where:

X₁ may not equal X₂

Reasons include:

stochastic generation,
backend differences,
provider model changes,
prompt interpretation,
model updates,
cache eviction,
different inference settings.

This means InferenceFS lacks one of the defining properties expected from persistent storage:

stable byte identity.

65. What Happens Across Unmounts?

Generated content is cached:

in process memory

not persisted as file payload.

Unmount:

fusermount3 -u /tmp/inference-mount

Then mount again.

Your file paths remain because the source directory persists.

But the generated-content cache does not.

The next read can trigger another model call.

Potentially:

before unmount:
file.py -> version A

after remount:
file.py -> version B
Code language: CSS (css)

66. Unmounting

Use:

fusermount3 -u /tmp/inference-mount

The project’s quick start documents fusermount3.

You can verify:

findmnt /tmp/inference-mount

67. File Operations Implemented

InferenceFS implements a surprisingly broad collection of filesystem operations, including behavior around:

lookup,
getattr,
setattr,
create,
open,
read,
write,
release,
mkdir,
readdir,
unlink,
rmdir,
rename,
hard links,
symbolic links,
fsync,
extended attributes,
access checks,
filesystem statistics.

The metadata behavior primarily delegates to the underlying source directory.

The content generation behavior is the unusual layer on top.

68. Low-Level FUSE API

InferenceFS uses:

pyfuse3.Operations
Code language: CSS (css)

and an inode-oriented API rather than a simple path-only abstraction.

It maintains structures for:

inode → path

file descriptor → inode

inode → file descriptor

lookup counts

open counts

file descriptor → virtual filename

This is useful source code for developers learning how a real FUSE filesystem manages kernel-facing object lifecycles.

69. Why Inode Tracking Exists

Applications operate on concepts such as:

inode
file descriptor
directory entry

not merely strings.

Suppose:

open("/a.txt")
Code language: JavaScript (javascript)

returns a handle.

The file might later:

rename()

while that handle still exists.

Filesystem implementations therefore need bookkeeping that is more sophisticated than:

dictionary[path] = content

InferenceFS gives you a compact example of these issues.

70. LRU Cache Architecture

The cache uses Python’s:

OrderedDict

and stores:

filename → bytes

It tracks:

current_bytes

and:

max_bytes

When inserting a new file would exceed the limit, least-recently-used entries are evicted until there is enough room.

Conceptually:

Cache:

A  ← oldest
B
C
D  ← newest

Need space

evict A

This is a classic LRU implementation.

71. Why Cache by Filename?

The generated content derives from:

filename/path

so that becomes the natural cache key.

Conceptually:

cache["/src/main.py"] = generated_bytes
Code language: JavaScript (javascript)

This makes repeated reads cheap.

But it also exposes a semantic issue:

filename is being treated like content identity

which it obviously is not in real-world storage.

That tension is part of the joke.

72. Cost Model

Ordinary filesystem read cost:

disk/NVMe latency

InferenceFS cold read cost:

network request
+
provider queue
+
LLM inference
+
tokens
+
API billing

Warm read:

RAM cache

Therefore:

first read = expensive
repeated read = cheap

until eviction.

73. Performance Characteristics

Expect latency to depend heavily on:

model,
provider,
prompt,
generated file size,
API region,
rate limiting,
network latency,
cache state,
max output tokens.

A simple text file may appear quickly.

A cold read requiring a large model output may be dramatically slower than local storage.

This is another excellent demonstration of how remote AI inference changes system architecture.

74. API Cost

InferenceFS can consume paid inference APIs.

Operations that seem harmless:

cat file

can potentially trigger billable model requests.

Commands that scan many files can be worse.

For example:

grep -R something /mnt/inference

could trigger reads across many files.

Similarly:

cp -R /mnt/inference /tmp/copy

may require generation for large numbers of files.

Treat the mount as an API execution surface, not just a filesystem.

75. A Surprisingly Important Operational Lesson

In cloud-backed filesystems:

filesystem operation

can map to:

network/API operation

InferenceFS exaggerates that relationship in a memorable way.

Running:

cat foo

looks local.

But underneath it may invoke:

remote LLM API

which has:

authentication,
pricing,
quotas,
rate limits,
external dependencies,
privacy consequences.

That principle applies to many real systems too.

76. Privacy Implications

The filename/path is sent to the selected model backend.

Suppose you create:

/customers/acme/merger-plan.txt

or:

/hr/alice-salary-review.txt

or:

/secrets/production-db-password.txt

Those names themselves may contain confidential information.

Therefore:

Do not mount sensitive directory structures against third-party AI APIs.

Even if file payloads are discarded, filenames alone can be sensitive metadata.

77. The Built-In Personal-Data Prompt

The current backend system prompt contains special wording for filenames suggesting private or personal data.

It asks the model to generate generic placeholder content rather than real private information.

That is sensible for the demonstration.

It does not transform InferenceFS into a secure storage mechanism.

78. Security Model

InferenceFS does not provide a traditional secure-storage model.

Risks include:

API keys

Protect:

API_KEY

Filename disclosure

Paths can be sent to third parties.

Generated malicious content

An LLM could potentially generate:

scripts
shell commands
configuration
source code

that should not automatically be trusted.

Supply-chain risk

Generated code is not trusted software.

Nondeterminism

Files can change without explicit writes.

External availability

The filesystem depends on remote services.

API compromise

Provider/API credentials become part of the storage dependency chain.

79. Never Execute Generated Binaries

InferenceFS can ask models to produce binary-looking files.

Do not interpret:

valid ELF header

as:

safe executable

Never blindly execute:

chmod +x generated-file
./generated-file

The same applies to:

shell scripts
PowerShell
Python
JavaScript
installers
macros

Treat all generated contents as untrusted.

80. Never Use It for Secrets

Do not create:

id_rsa

and expect your SSH key back.

Do not create:

production.env
Code language: CSS (css)

and expect credentials.

Do not create:

wallet.dat
Code language: CSS (css)

and expect cryptocurrency keys.

Do not create:

passwords.txt
Code language: CSS (css)

and expect your passwords.

InferenceFS cannot reconstruct arbitrary private information from a filename.

Any seemingly convincing result is generated content, not your original secret.

81. Never Use It for Backups

A backup must satisfy something like:

original bytes
     ↓
store
     ↓
later restore
     ↓
same original bytes

InferenceFS performs:

filename
     ↓
generate something plausible

That is the opposite of backup.

82. Never Use It for Databases

Databases depend on:

exact pages,
transaction logs,
checksums,
indexes,
transactional ordering,
durable writes,
crash consistency,
stable offsets.

InferenceFS intentionally violates several fundamental assumptions.

Do not use it for:

PostgreSQL
MySQL
SQLite
MongoDB
Redis persistence
RocksDB
LevelDB

or any real database data.

83. Never Use It for Kubernetes Persistent Volumes

A Kubernetes application expects:

write state
→ restart
→ state still exists

InferenceFS gives:

write state
→ bytes disappear
→ future read is generated

This would be spectacularly wrong.

Do not use it as a real PersistentVolume backend.

84. Real Use Cases

InferenceFS does have excellent legitimate uses.

84.1 Teaching FUSE

Study:

inode management
read/write callbacks
directory operations
async filesystems
FUSE lifecycle
Code language: JavaScript (javascript)

84.2 Teaching LLM Hallucination

Demonstrate the difference between:

looks correct

and:

is correct

84.3 Teaching Generative vs Retrieval Systems

It makes the distinction tangible.

84.4 Studying Model Priors

Ask:

What does the model think README.md contains?
Code language: CSS (css)

84.5 File Format Research

Explore what models understand about:

PNG
ZIP
ELF
PDF
WAV
SQLite

84.6 LLM Benchmarking

Use filenames as standardized prompts across different models.

84.7 AI Education

InferenceFS may be one of the funniest possible demonstrations of why:

plausibility != truth

85. Model-Prior Experiments

Create:

touch README.md
touch package.json
touch Cargo.toml
touch go.mod
touch pom.xml
touch Makefile
touch Dockerfile
touch Jenkinsfile
Code language: CSS (css)

Read each.

This reveals conventions learned by the model.

For example:

package.json
Code language: CSS (css)

may produce a plausible Node.js project.

Cargo.toml
Code language: CSS (css)

may produce Rust metadata.

go.mod
Code language: CSS (css)

may produce Go module information.

These are not “remembered files.”

They are samples from learned conventions.

86. DevOps Experiment

Try:

Dockerfile
docker-compose.yaml
Jenkinsfile
.github/workflows/ci.yml
terraform/main.tf
ansible/playbook.yaml
kubernetes/deployment.yaml
helm/Chart.yaml

Then inspect whether the model generates coherent infrastructure definitions.

This can reveal what default patterns and conventions a model has absorbed.

87. Observability Experiment

Create:

prometheus.yml
grafana-dashboard.json
datadog-agent.yaml
otel-collector.yaml
fluent-bit.conf
Code language: CSS (css)

Read them.

You can compare:

syntax validity,
modernity,
configuration conventions,
security defaults,
hallucinated settings.

Again, never treat generated configuration as authoritative.

88. Programming-Language Experiment

Create:

hello.py
hello.go
hello.rs
Hello.java
main.cpp
index.js
main.rb
Program.cs
Code language: CSS (css)

Ask:

What style does each backend generate?

Compare:

Claude
Gemini
Claude Code

This is an unusual but useful qualitative model benchmark.

89. Binary Experiment

Try:

touch image.png
touch document.pdf
touch application.exe
touch application.elf
touch archive.zip
touch database.sqlite
Code language: CSS (css)

Then use:

file image.png
Code language: CSS (css)

or:

xxd image.png | head

and format-specific validators.

You will likely observe an interesting boundary between:

recognizable header

and:

fully valid structured file

That boundary is exactly what the author’s appendix highlights.

90. Example Binary Validation Lab

For PNG:

file image.png
Code language: CSS (css)

Potentially:

pngcheck image.png
Code language: CSS (css)

For ZIP:

unzip -t archive.zip
Code language: CSS (css)

For PDF:

pdfinfo document.pdf
Code language: JavaScript (javascript)

For ELF:

readelf -h application.elf
Code language: CSS (css)

For SQLite:

sqlite3 database.sqlite '.schema'
Code language: JavaScript (javascript)

This can produce a fascinating comparison between:

superficially correct

and:

semantically valid

91. Testing Different Backends

Create the same source tree.

Mount with Gemini:

inferencefs \
    --backend gemini \
    source \
    mount-gemini

Mount separately with Claude:

inferencefs \
    --backend claude \
    source2 \
    mount-claude

Then compare:

diff \
    mount-gemini/Dockerfile \
    mount-claude/Dockerfile

This turns InferenceFS into a quirky comparative benchmark.

92. Testing Reproducibility

Mount:

inferencefs --backend gemini source mount

Read:

cat mount/config.yaml > first.txt

Unmount:

fusermount3 -u mount

Mount again.

Read:

cat mount/config.yaml > second.txt

Compare:

diff -u first.txt second.txt
Code language: CSS (css)

Any difference demonstrates the core issue:

filename alone is not a lossless content identifier

93. Inspect the Source Directory

Create:

printf 'Hello world' > /tmp/inference-mount/test.txt
Code language: JavaScript (javascript)

Unmount if necessary, then inspect:

cat /tmp/inference-source/test.txt

You may see a decimal size value representing the virtual written size rather than:

Hello world

That is one of the simplest demonstrations of how InferenceFS discards actual write payloads.

94. Troubleshooting: `pyfuse3` Build Failure

If installation complains about FUSE headers or pkg-config, install:

sudo apt install -y \
    fuse3 \
    libfuse3-dev \
    pkg-config \
    build-essential

Then retry your Python installation.

The project’s own developer documentation identifies these system dependencies.

95. Troubleshooting: Python Version

If you see something resembling:

requires Python >=3.14

check:

python --version

InferenceFS 1.0.0 declares Python 3.14 or newer.

Use a separate Python 3.14 environment.

96. Troubleshooting: Missing `/dev/fuse`

Check:

ls -l /dev/fuse

If unavailable on a normal Linux host:

sudo modprobe fuse

Containers may require explicit FUSE device access.

97. Troubleshooting: No API Key

The CLI requires an API key for backends whose class declares:

requires_api_key = True
Code language: PHP (php)

If none is available, it exits with an error telling you to use:

--api-key

or:

API_KEY

Check:

echo "${API_KEY:+API_KEY is set}"
Code language: PHP (php)

Do not print secrets to shared terminal logs.

98. Troubleshooting: `claude` Not Found

For:

--backend claude-code

InferenceFS expects the executable:

claude

to exist in PATH.

Check:

command -v claude

and make sure Claude Code is already authenticated.

The backend invokes the CLI through Python subprocess.run().

99. Troubleshooting: I/O Error

A read returning:

Input/output error

may indicate that generation failed.

Potential causes:

bad API key,
network failure,
model unavailable,
provider error,
rate limiting,
malformed provider response,
CLI backend failure.

Run debug mode:

inferencefs -d ...

to inspect logs.

100. Troubleshooting: File Suddenly Changed

That is expected behavior if generated content was no longer cached.

Possible causes:

process restart
mount restart
cache eviction
different backend
provider model update
nondeterministic generation

InferenceFS provides no content-addressed persistence for generated bytes.

101. Troubleshooting: Binary File Is Corrupt

Also expected.

An LLM can often imitate:

format structure

but may fail to calculate:

checksums,
compressed streams,
indexes,
internal offsets,
codec state.

The project’s own documented limitations explicitly call this out.

102. Containers

FUSE in containers is more complicated because the container needs:

/dev/fuse

and sufficient capabilities.

A typical experiment may require access resembling:

--device /dev/fuse

and additional security permissions depending on the runtime.

Do not jump directly to:

--privileged

for production environments simply to make FUSE work.

For learning InferenceFS:

Linux VM

is generally simpler.

103. macOS

InferenceFS specifically depends on:

pyfuse3

which targets Linux FUSE behavior.

For macOS users, the least-friction route is generally:

macOS
  ↓
Linux VM
  ↓
InferenceFS

rather than attempting to port the filesystem to macFUSE.

104. Windows

Similarly, the project is fundamentally designed around Linux/FUSE 3.

A Linux virtual machine is the cleanest environment for experimentation.

105. Testing

The repository includes dedicated tests for:

filesystem operations
InferenceFS generation behavior
cache behavior
size tracking
backends
response decoding

The project documentation uses:

uv run pytest

or:

uv run pytest -v

This is another reason the repository is worth studying beyond the joke itself.

106. Development Workflow

Clone:

git clone https://github.com/philipl/inferencefs.git
cd inferencefs
Code language: PHP (php)

Install dependencies:

uv sync

Run tests:

uv run pytest

Run lint:

uv run ruff check src tests

Build package:

uv build

Mount development version:

uv run inferencefs \
    --backend gemini \
    /tmp/source \
    /tmp/mount

107. Package Technology

The project currently uses:

hatchling
hatch-vcs

for its Python build system.

The console command:

inferencefs

maps to:

inferencefs.main:main
Code language: CSS (css)

That is defined directly in pyproject.toml.

108. License

InferenceFS declares:

AGPL-3.0-or-later
Code language: CSS (css)

Anyone modifying or deploying the project in contexts where licensing matters should review the AGPL obligations rather than assuming conventional permissive open-source terms.

109. Production Readiness

InferenceFS should not be treated as production persistent storage.

The author explicitly says:

Do not use it to store anything you care about.

It lacks the semantic contract required for persistent data because it intentionally does not preserve writes.

110. Do Not Use InferenceFS For

Do not use it for:

backups,
databases,
home directories,
source-of-truth repositories,
secrets,
SSH keys,
cryptocurrency wallets,
legal documents,
financial records,
Kubernetes persistent storage,
Docker volumes containing state,
VM disks,
configuration-of-record,
user uploads,
medical records,
build artifacts requiring reproducibility,
package repositories,
container registries,
logs requiring audit integrity,
compliance records.

If exact bytes matter, InferenceFS is fundamentally the wrong abstraction.

111. Excellent Uses For InferenceFS

Use it for:

computer-science demonstrations,
FUSE education,
LLM education,
hallucination demonstrations,
inference-vs-retrieval teaching,
model comparisons,
file-format experiments,
caching demonstrations,
API-backed filesystem study,
prompt engineering experiments,
AI reliability workshops,
information-theory discussions.

112. InferenceFS vs Conventional Filesystem

Property	ext4/XFS	InferenceFS
Writes preserved	Yes	No
Reads exact	Yes	No
Persistent content	Yes	No
Content source	Stored blocks	LLM
Metadata	Filesystem metadata	Source tree
Remote inference	No	Yes
API dependency	No	Usually
Cache	OS caches	Explicit generated-content LRU
Deterministic	Essentially	Not guaranteed
Production storage	Yes	No
Educational novelty	Moderate	Extremely high

113. InferenceFS vs Object Storage

Property	S3/Object Storage	InferenceFS
Upload object	Stored	Discarded
Get object	Exact stored bytes	Generated bytes
Object identity	Key + version/data	Filename prompt
Durability	Engineered	Not applicable
Versioning	Often	No generated-content versioning
Integrity	Checksums	No equivalent content guarantee
Cost basis	Storage + requests	LLM inference + cache

114. InferenceFS vs RAG

InferenceFS is not RAG.

RAG

query
 ↓
retrieve relevant documents
 ↓
model sees real evidence
 ↓
answer grounded in retrieved data

InferenceFS

filename
 ↓
model
 ↓
generate probable file contents

There is no retrieval database containing your original file contents.

This distinction is extremely important.

115. InferenceFS vs Generative AI

InferenceFS is essentially a filesystem-shaped wrapper around generative AI.

Normally:

prompt → generated response

InferenceFS maps that into:

filename → generated file

The operating system abstraction makes generation look like storage.

That inversion is what makes the project so clever.

116. InferenceFS vs `/dev/null`

Writes are philosophically close to:

/dev/null
Code language: JavaScript (javascript)

because bytes disappear.

But unlike /dev/null, InferenceFS preserves the existence of the filename and apparent write size.

Then, on read, it generates replacement content.

So approximately:

InferenceFS =
/dev/null
+
metadata
+
LLM
+
FUSE
+
confidence
Code language: JavaScript (javascript)

117. InferenceFS vs `/dev/urandom`

/dev/urandom generates bytes rather than storing them.

InferenceFS also generates bytes.

But /dev/urandom makes no claim that its bytes correspond to what you wanted.

InferenceFS generates semantically plausible data conditioned by the filename.

So:

/dev/urandom:
random-looking bytes

InferenceFS:
contextually plausible bytes

118. InferenceFS vs Templates

It also resembles an extremely sophisticated templating engine.

Traditional template:

Dockerfile.tpl
+
variables
=
Dockerfile

InferenceFS:

filename "Dockerfile"
+
LLM prior
=
Dockerfile
Code language: JavaScript (javascript)

The “template” lives inside the model weights.

119. InferenceFS vs Content-Addressed Storage

A system like Git says:

content
 ↓
cryptographic hash
 ↓
stable content identity

InferenceFS effectively says:

filename
 ↓
semantic prompt
 ↓
probable content

These are almost opposites.

A hash exists specifically to bind identity to exact bytes.

A filename contains insufficient information to do that.

120. InferenceFS vs Deduplication

Traditional deduplication:

same content
 ↓
same stored block

InferenceFS’s joke version is closer to:

same semantic filename
 ↓
generate something likely

The README jokes that files with the same name are aggressively “deduplicated,” but this is satire, not storage deduplication.

121. Why This Project Matters

InferenceFS exposes a problem that is easy to forget when chatting with AI:

A highly plausible answer can feel like retrieval even when nothing was retrieved.

Suppose you ask an LLM:

What normally goes in /etc/nginx/nginx.conf?

and it returns an excellent configuration.

Your brain may think:

"It knows nginx.conf."
Code language: JSON / JSON with Comments (json)

But what happened may really be:

learned probability distribution
+
prompt
+
generation

InferenceFS makes that distinction impossible to ignore because the generated answer appears as a literal “file.”

122. Plausibility Is Not Truth

InferenceFS teaches:

syntactically correct
≠
factually correct

and:

looks like original
≠
is original

and:

model confidence
≠
storage integrity

and:

generation
≠
retrieval

These distinctions are central to responsible AI engineering.

123. The Filename as Compressed Semantic Information

A filename like:

nginx.conf
Code language: CSS (css)

contains very little byte-level information.

But semantically it contains a lot.

It implies:

probably text,
probably NGINX syntax,
probably directives,
probably server,
perhaps port 80,
perhaps location /,
perhaps log paths.

An LLM can expand that semantic hint into hundreds of plausible bytes.

That is why the project feels like compression.

But the reconstructed details are largely invented.

124. Semantic Compression vs Lossless Compression

Consider:

wedding_photo.jpg
Code language: CSS (css)

The filename tells us:

photo
wedding
JPEG

But not:

who was present,
what anyone looked like,
where they stood,
exact pixels,
camera settings,
colors,
timestamp.

An LLM or generative image model could create a convincing wedding image.

But nearly all information from the original photograph has been lost.

That is semantic reconstruction, not lossless decompression.

125. Information-Theoretic Perspective

Suppose your original file contains:

N bits

A filename may contain only:

M bits

where:

M << N

There is no way for those M bits to uniquely distinguish all possible N-bit files.

The missing information must come from somewhere.

InferenceFS supplies it from:

model priors

rather than from the original file.

That is why the output can be plausible but cannot generally be exact.

126. A Simple Proof

Suppose the filename is:

a.txt
Code language: CSS (css)

Could the original content be:

Hello

Yes.

Could it also be:

Goodbye

Yes.

Could it contain an entire novel?

Yes.

Could it contain random bytes?

Yes.

The same filename corresponds to effectively unbounded possible contents.

Therefore:

filename alone

cannot uniquely identify the original content.

No model intelligence can change that fundamental information deficit.

127. LLM Weights Are Not a Filesystem

A model’s parameters encode statistical structure learned during training.

They are not generally a dictionary like:

/path/file1 → exact bytes
/path/file2 → exact bytes
/path/file3 → exact bytes

Even when models reproduce remembered passages, treating model parameters as a deterministic data archive is the wrong abstraction.

InferenceFS deliberately exaggerates that mistaken assumption.

128. A Gold-Standard Learning Lab

Install dependencies:

sudo apt update

sudo apt install -y \
    fuse3 \
    libfuse3-dev \
    pkg-config \
    build-essential

Clone:

git clone https://github.com/philipl/inferencefs.git
cd inferencefs
Code language: PHP (php)

Prepare Python environment:

uv sync

Create directories:

mkdir -p /tmp/inference-source
mkdir -p /tmp/inference-mount

Configure API:

export API_KEY="YOUR_API_KEY"
Code language: JavaScript (javascript)

Mount:

uv run inferencefs \
    -d \
    --backend gemini \
    /tmp/inference-source \
    /tmp/inference-mount

129. Lab 1 — Text Generation

Another terminal:

touch /tmp/inference-mount/hello.py

Read:

cat /tmp/inference-mount/hello.py

Observe the original terminal logs.

Read again:

cat /tmp/inference-mount/hello.py

The second read should normally be served from the cache rather than generate content again.

130. Lab 2 — Filename Semantics

Create:

touch /tmp/inference-mount/README.md
touch /tmp/inference-mount/Dockerfile
touch /tmp/inference-mount/package.json
touch /tmp/inference-mount/requirements.txt

Read each:

for f in README.md Dockerfile package.json requirements.txt; do
    echo "===== $f ====="
    cat "/tmp/inference-mount/$f"
done
Code language: PHP (php)

Observe what conventions the model associates with each filename.

131. Lab 3 — Write Discard

Run:

printf 'THIS IS MY EXACT CONTENT' \
    > /tmp/inference-mount/exact.txt
Code language: JavaScript (javascript)

Then read:

cat /tmp/inference-mount/exact.txt

Do not expect:

THIS IS MY EXACT CONTENT

Then inspect:

cat /tmp/inference-source/exact.txt

This demonstrates payload discard and size persistence.

132. Lab 4 — Cache

Run:

cat /tmp/inference-mount/config.yaml > /tmp/read1
cat /tmp/inference-mount/config.yaml > /tmp/read2

cmp /tmp/read1 /tmp/read2
Code language: JavaScript (javascript)

While cached, they should normally match.

Then restart the filesystem and compare again.

133. Lab 5 — Nondeterminism

Save one run:

cat /tmp/inference-mount/config.yaml > /tmp/version1
Code language: JavaScript (javascript)

Unmount:

fusermount3 -u /tmp/inference-mount

Start again.

Save:

cat /tmp/inference-mount/config.yaml > /tmp/version2
Code language: JavaScript (javascript)

Compare:

diff -u /tmp/version1 /tmp/version2

This is an excellent demonstration of generative persistence failure.

134. Lab 6 — Binary Formats

Create:

touch /tmp/inference-mount/photo.png
touch /tmp/inference-mount/report.pdf
touch /tmp/inference-mount/app.elf
touch /tmp/inference-mount/archive.zip

Copy generated bytes:

cp /tmp/inference-mount/photo.png /tmp/photo.png
cp /tmp/inference-mount/report.pdf /tmp/report.pdf
cp /tmp/inference-mount/app.elf /tmp/app.elf
cp /tmp/inference-mount/archive.zip /tmp/archive.zip

Inspect:

file /tmp/photo.png
file /tmp/report.pdf
file /tmp/app.elf
file /tmp/archive.zip

Then validate internals.

For ZIP:

unzip -t /tmp/archive.zip

This often highlights the difference between a recognizable header and a truly valid format.

135. Lab 7 — Compare Models

Generate the same filename using:

Gemini
Claude
Claude Code

Compare:

correctness
syntax
length
style
binary validity
latency

This turns InferenceFS into an entertaining qualitative model benchmark.

136. Lab 8 — Path Context

Create:

mkdir -p /tmp/inference-mount/aws
mkdir -p /tmp/inference-mount/kubernetes
mkdir -p /tmp/inference-mount/docker

Then:

touch /tmp/inference-mount/aws/config.yaml
touch /tmp/inference-mount/kubernetes/config.yaml
touch /tmp/inference-mount/docker/config.yaml

Read them.

The directory context should influence model interpretation.

137. Lab 9 — DevOps Model Knowledge

Create:

terraform/main.tf
kubernetes/deployment.yaml
helm/values.yaml
ansible/playbook.yaml
.github/workflows/ci.yaml
prometheus/prometheus.yml
otel/collector.yaml

Examine:

version freshness,
deprecated APIs,
security defaults,
syntax validity,
assumptions,
hallucinated properties.

This is particularly useful for AI-assisted DevOps education.

138. Lab 10 — What Models Don’t Know

Create obscure or invented filenames:

xyzzy-q91.conf
foo.bar.baz
company-secret-format.dat
customprotocol.v99
Code language: CSS (css)

Observe how the model fills information gaps.

You will likely see stronger hallucination as semantic hints decrease.

This demonstrates how generation quality depends heavily on prior probability.

139. Best Practices for Safe Experimentation

For an InferenceFS lab:

Use disposable directories.
Use no personal data.
Use no secrets.
Use no real production filenames if sensitive.
Monitor API spend.
Keep cache sizes reasonable.
Enable debug mode while learning.
Validate binary output before opening it.
Never execute generated binaries.
Assume all generated content is untrusted.
Never interpret output as recovered original data.
Unmount when finished.

140. Architecture Summary

                         User Program
                              |
                              | POSIX operations
                              v
                         Linux Kernel
                              |
                              | FUSE
                              v
                          pyfuse3
                              |
                              v
                       InferenceFS
                   +----------+----------+
                   |                     |
                   v                     v
            Source metadata         Content request
            directory                    |
                                         v
                                   LRU cache lookup
                                    /           \
                                 hit             miss
                                  |               |
                                  v               v
                               bytes         LLM backend
                                                  |
                              +-------------------+-------------------+
                              |                   |                   |
                              v                   v                   v
                           Gemini              Claude            Claude Code
                              |                   |                   |
                              +-------------------+-------------------+
                                                  |
                                                  v
                                       text / base64 response
                                                  |
                                                  v
                                      response decoder
                                                  |
                                                  v
                                          generated bytes
                                                  |
                                                  v
                                             LRU cache
                                                  |
                                                  v
                                             application

141. Read Workflow

cat foo.py
   |
   v
open(foo.py)
   |
   v
read(foo.py)
   |
   v
cache?
   |
   +---- yes ---> return cached bytes
   |
   +---- no
          |
          v
      prompt LLM
          |
          v
     receive output
          |
          v
   decode if binary
          |
          v
      cache bytes
          |
          v
     return slice
Code language: JavaScript (javascript)

142. Write Workflow

echo hello > foo.txt
       |
       v
     create
       |
       v
     write
       |
       +---- input bytes discarded
       |
       v
track max written offset
       |
       v
     release
       |
       v
persist numeric file size
Code language: PHP (php)

Later:

cat foo.txt
    |
    v
LLM generates "foo.txt"
Code language: JavaScript (javascript)

Not:

return "hello"
Code language: JavaScript (javascript)

143. What InferenceFS Gets Surprisingly Right

From an engineering perspective, several design decisions are sensible:

lazy generation,
backend abstraction,
bounded LRU cache,
asynchronous FUSE integration,
rate-limit handling,
binary response recovery,
API-key validation,
persistent apparent sizes,
inode lifecycle management,
extensive automated testing,
clean packaging.

That combination is why studying the repository is worthwhile even though its storage model is deliberately ridiculous.

144. What InferenceFS Deliberately Gets Wrong

The central storage semantics are intentionally broken:

writes do not preserve content
Code language: JavaScript (javascript)

and:

reads generate guesses

Consequently it cannot guarantee:

durability,
fidelity,
consistency,
reproducibility,
exact recovery,
data integrity,
stable content identity.

That is the point.

145. The Real Lesson About Generative AI

InferenceFS illustrates one of the most important rules of modern AI:

A generative model should not be treated as a database merely because it can produce answers that resemble stored information.

If exact source truth matters, use:

database
search
RAG
object storage
document store
source repository
API
verified external source
Code language: JavaScript (javascript)

and then use the model to reason over that evidence.

Do not ask probability to masquerade as persistence.

146. The Real Lesson About RAG

InferenceFS also explains why RAG exists.

Without retrieval:

question
 ↓
model prior
 ↓
plausible answer

With retrieval:

question
 ↓
search real source
 ↓
relevant evidence
 ↓
model reasoning
 ↓
grounded answer

The difference is similar to:

InferenceFS

versus:

an actual filesystem

That is a memorable mental model.

147. The Real Lesson About AI Coding

Suppose you ask:

Generate my company's existing deployment.yaml.

Without access to your repository, an LLM might produce an excellent Kubernetes manifest.

But that is:

a deployment.yaml
Code language: CSS (css)

not necessarily:

your deployment.yaml
Code language: CSS (css)

InferenceFS makes exactly this error intentionally.

The same principle applies to AI coding assistants:

Give the model the real codebase when exact project context matters.

148. The Real Lesson About “Memory”

If an AI model can generate a plausible:

README.md
Code language: CSS (css)

that does not establish that it retrieved a specific README from training.

Generation can arise from learned structure and probabilities.

InferenceFS helps separate:

memorization

from:

generalization

and from:

retrieval

Even when outputs look familiar, determining which mechanism produced them can be nontrivial.

149. Suggested Learning Path

Beginner

Understand:

FUSE,
filesystem mounts,
filenames vs contents,
LLM generation.

Intermediate

Run InferenceFS and experiment with:

text files,
path context,
cache behavior,
writes,
remounts.

Advanced

Study:

pyfuse3,
Trio,
inode lifecycle,
LRU caching,
API backends,
base64 decoder,
rate-limit behavior.

Expert

Use the project to study:

information theory,
LLM memorization,
semantic compression,
model priors,
hallucination,
reproducibility,
binary format generation,
retrieval vs generative knowledge.

150. Command Cheat Sheet

Install system dependencies:

sudo apt install \
    fuse3 \
    libfuse3-dev \
    pkg-config \
    build-essential

Clone:

git clone https://github.com/philipl/inferencefs.git
cd inferencefs
Code language: PHP (php)

Install:

uv sync

Prepare:

mkdir -p /tmp/source /tmp/mount

Gemini:

export API_KEY="..."
uv run inferencefs \
    --backend gemini \
    /tmp/source \
    /tmp/mount
Code language: JavaScript (javascript)

Claude:

export API_KEY="..."
uv run inferencefs \
    --backend claude \
    /tmp/source \
    /tmp/mount
Code language: JavaScript (javascript)

Claude Code:

uv run inferencefs \
    --backend claude-code \
    /tmp/source \
    /tmp/mount

Debug:

uv run inferencefs \
    -d \
    --backend gemini \
    /tmp/source \
    /tmp/mount

64 MiB cache:

uv run inferencefs \
    --backend gemini \
    --cache-size 64 \
    /tmp/source \
    /tmp/mount

Create:

touch /tmp/mount/hello.py

Read:

cat /tmp/mount/hello.py

Unmount:

fusermount3 -u /tmp/mount

Tests:

uv run pytest

Lint:

uv run ruff check src tests

151. Frequently Asked Questions

Is InferenceFS a real filesystem?

It is a real FUSE filesystem implementation.

Its persistence semantics are intentionally not those of normal storage.

Does it actually store my file contents?

No.

Written bytes are discarded by the current implementation.

Only metadata such as paths and apparent written sizes is retained.

Can it recover my original file?

Generally, no.

It asks an LLM to produce what that filename probably contains.

What happens if I write data and read it back?

You should not expect the written bytes.

The read result is generated by the model.

Why does `write()` report success?

Because the filesystem deliberately accepts writes while discarding payloads.

It reports the number of bytes as successfully written and records apparent size.

That behavior is part of the project’s design.

Is generated content cached?

Yes.

InferenceFS uses a configurable in-memory LRU cache.

The default is approximately:

256 MiB

Does the cache survive restart?

No.

The generated content cache is process memory.

Will the same filename always produce the same content?

No guarantee.

Outputs may change after regeneration.

Does InferenceFS support binary files?

It attempts to.

The model is asked for base64 representations, which the application decodes.

Common format headers can work surprisingly well, but complex compressed/cross-referenced structures may be invalid.

Is InferenceFS safe for production?

No.

The author explicitly labels it an April Fools’ project and warns against storing anything important with it.

What Python version does it require?

Current packaging requires:

Python 3.14+
Code language: CSS (css)

What is the latest published version?

As of September 2026, PyPI lists:

1.0.0
Code language: CSS (css)

released:

April 1, 2026

Which backend should I start with?

The project’s current README recommends Gemini for the preferred out-of-the-box demonstration.

Provider capabilities, prices and model availability can change, so check the provider before running large experiments.

Does Claude Code require an API key?

InferenceFS itself does not request one for the claude-code backend.

It relies on the locally installed Claude CLI’s authentication.

Can InferenceFS replace S3?

Absolutely not.

S3 stores bytes.

InferenceFS guesses bytes.

That distinction is rather important.

Can it replace Git?

No.

Git’s design is built around exact content identity.

InferenceFS intentionally provides no such guarantee.

Can it be used for generating boilerplate?

Technically, the underlying concept can inspire useful tools.

A system where:

filename/path
→ generate scaffold

could be useful.

But that is better implemented explicitly as a code generator, template engine or AI scaffolding tool—not disguised as persistent storage.

152. From Joke to Useful Design Pattern

Interestingly, a safer version of the concept could be genuinely useful.

Imagine a GenerativeFS where files marked as virtual are intentionally generated:

/generated/
├── README.md
├── architecture.md
├── api-examples.md
└── test-data.json

But unlike InferenceFS, the system would clearly distinguish:

generated virtual artifacts

from:

persistent files

It could:

persist generations,
record model/version,
record prompts,
store hashes,
track provenance,
regenerate explicitly,
show generated status.

That becomes a legitimate AI-powered virtual filesystem.

InferenceFS helps expose what safeguards such a real system would need.

153. What a Production Generative Filesystem Would Need

At minimum:

content persistence
content hashing
generation provenance
model identifier
prompt version
timestamps
explicit regeneration
version history
deterministic mode where possible
audit logs
API cost controls
secrets management
privacy boundaries
validation
content safety
checksums
user-visible generated status

Without those, generative content should never masquerade as durable storage.

154. πfs vs InferenceFS: The Bigger Lesson

πfs asks:

Can deterministic mathematics replace storage?

Answer:

Not without retaining enough information to identify the original data.

InferenceFS asks:

Can model knowledge replace storage?

Answer:

Only if you are willing to replace exact information with plausible reconstruction.
Code language: JavaScript (javascript)

Together, they make a wonderful pair.

πfs

exact-ish reconstruction
+
too much metadata

InferenceFS

almost no metadata
+
almost no guarantee of exact reconstruction

One preserves information and pays for it.

The other discards information and asks probability to fill the gaps.

155. Final Takeaway

InferenceFS begins with a wonderfully ridiculous proposition:

Why store files when an LLM can simply remember what files with those names usually look like?

The implementation then takes that idea seriously enough to expose its consequences.

A filename such as:

Dockerfile

really can expand into a convincing Dockerfile.

A filename such as:

config.yaml
Code language: CSS (css)

really can expand into plausible configuration.

A filename such as:

image.png
Code language: CSS (css)

may even cause a model to emit enough base64-encoded structure to resemble an actual PNG.

And that’s precisely why InferenceFS is valuable.

Because it demonstrates how easy it is to confuse:

plausibility

with:

truth

and:

generation

with:

retrieval

and:

semantic familiarity

with:

exact memory

and:

AI output

with:

stored evidence

A traditional filesystem promises:

Give me bytes and I will return the same bytes later.

InferenceFS promises something closer to:

Give me a filename and I’ll ask a model what probably belonged there.

Those are fundamentally different contracts.

InferenceFS deliberately chooses the second contract and wraps it inside an interface normally associated with the first.

That mismatch is the joke.

It is also the lesson.

And that makes InferenceFS a surprisingly powerful teaching tool for understanding not only filesystems, but the fundamental nature—and limits—of generative AI.

References

The primary source is the official philipl/inferencefs repository. The repository describes InferenceFS as the successor to πfs, documents its FUSE interface, backends, cache and quick-start workflow.

The project’s CLAUDE.md documents its internal architecture, lazy generation, pyfuse3 design, cache behavior, asynchronous execution, backend structure, testing and known limitations.

The current inferencefs.py implementation shows the actual read/write semantics, inode bookkeeping, LRU cache, retry handling, fake 1 GiB size, persisted written-size metadata and FUSE operations.

The current backends.py implementation documents the LLM prompts, Claude/Claude Code/Gemini integrations, binary base64 processing and magic-byte detection.

The project’s technical appendix explains the intended lesson around LLMs as lossy compression and records experimental limitations with compressed, codec-specific and cross-referenced binary formats.

PyPI currently lists InferenceFS 1.0.0, released April 1, 2026, requiring Python 3.14+, under the AGPL-3.0-or-later license.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.

Find Trusted Cardiac Hospitals

Compare heart hospitals by city and services — all in one place.

Explore Hospitals

Find the Best Cosmetic Hospitals

What Is InferenceFS, Why Does It Exist, How Does It Work, and What Does It Teach Us About LLMs?

1. What Is InferenceFS?

2. InferenceFS in One Sentence

3. The Most Important Thing to Understand

4. InferenceFS vs πfs

πfs

InferenceFS

5. Why Was InferenceFS Created?

6. Retrieval vs Inference

Retrieval

InferenceFS

7. The Core Architecture

8. Source Directory vs Mount Directory

9. What Is Actually Stored?

10. What Happens When You Create a File?

11. Lazy Content Generation

12. What Happens During a Read?

13. The Prompt

14. Directory Names Matter

15. Filenames Become an API

16. Supported LLM Backends

17. Google Gemini Backend

18. Claude API Backend

19. Claude Code Backend

20. Backend Interface

21. Installation Requirements

22. Recommended Platform

23. Install FUSE 3 on Ubuntu/Debian

24. Python 3.14 Requirement

25. Install From PyPI

26. Install Using uv

27. Install From Source

28. Project Structure

29. Main Components

main.py

inferencefs.py

backends.py

30. Your First InferenceFS Filesystem

31. Create Your First File

32. Try Different Filename Semantics

33. Contextual Path Experiment

34. Configuration Options

35. --backend

36. --api-key

37. API_KEY

38. --max-tokens

39. --cache-size

40. Why the Cache Matters

41. Important Cache Consequence

42. Cache Eviction Means Data Mutation

43. Debug Mode

44. Standard FUSE Options

45. How Writes Actually Work

46. The Ultimate /dev/null With Confidence

47. Written Size Persistence

48. File Size Priority

49. Why Unread Files Pretend to Be 1 GiB

50. A Beautiful Filesystem Hack

51. Async Architecture

52. Rate-Limit Handling

53. Failure Behavior

54. Binary File Support

55. Binary Response Decoder

Strategy 1

Strategy 2

Strategy 3

Strategy 4

Strategy 5

56. Binary Magic Bytes

57. Why Binary Generation Is Fascinating

58. Binary Formats That Work Better

Text formats

Simpler/common binary headers

Header-oriented containers

59. Formats That Work Poorly

Compressed internals

Codec-specific formats

Cross-referenced structures

60. Predicting Bytes vs Executing Algorithms

26. Install Using `uv`

`main.py`

`inferencefs.py`

`backends.py`

35. `--backend`

36. `--api-key`

37. `API_KEY`

38. `--max-tokens`

39. `--cache-size`

46. The Ultimate `/dev/null` With Confidence

94. Troubleshooting: `pyfuse3` Build Failure

96. Troubleshooting: Missing `/dev/fuse`

98. Troubleshooting: `claude` Not Found