A virtual file system built on top of SQLite. Navigate directories, read and edit files, grep contents, glob for patterns — all the filesystem operations you know, but the storage layer is a single .db file with full-text search.

fuzeddb gives you a real filesystem interface backed by SQLite. Not a document store, not a key-value store — an actual filesystem with paths, directories, and the full set of operations you'd expect. Point it at any SQLite database and you have a searchable, portable filesystem.

git clone https://github.com/jbuchananr/fuzeddb.git
cd fuzeddb
go build -o fuzeddb .

# Write files — parent directories are created automatically
fuzeddb write /projects/auth/notes.md -c "OAuth2 migration planned for Q3"
fuzeddb write /projects/api/endpoints.md -c "GET /api/v1/users"

# Read files
fuzeddb read /projects/auth/notes.md

# Read specific line ranges (great for large files)
fuzeddb read /projects/auth/notes.md --offset 2 --limit 10

# List directory contents
fuzeddb ls /projects
# d  api/
# d  auth/

fuzeddb ls /projects/auth
# f  notes.md  (35 bytes)

# See the full tree
fuzeddb tree
# /
# └── projects/
#     ├── api/
#     │   └── endpoints.md
#     └── auth/
#         └── notes.md

# Surgical edit — replace a string without overwriting the whole file
fuzeddb edit /projects/auth/notes.md --old "Q3" --new "Q2"

# Move and copy
fuzeddb mv /projects/auth/notes.md /archive/auth-notes.md
fuzeddb cp /projects/api /backup/api

# Delete
fuzeddb rm /archive/auth-notes.md
fuzeddb rm /backup -r    # recursive

# Grep — regex search across all file contents
fuzeddb grep "OAuth" /projects
# /projects/auth/notes.md:1: OAuth2 migration planned for Q2

# Find — glob pattern matching
fuzeddb find "/**/*.md"
# /projects/api/endpoints.md
# /projects/auth/notes.md

# Full-text search (FTS5 — faster than grep for natural language)
fuzeddb search "migration planned"

This is where fuzeddb shines. Run it as an MCP server and any LLM agent gets a full persistent filesystem.

Claude Code (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "fuzeddb": {
      "command": "/path/to/fuzeddb",
      "args": ["serve"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "fuzeddb": {
      "command": "/path/to/fuzeddb",
      "args": ["serve"]
    }
  }
}

The agent gets these tools — the same operations it uses on real filesystems:

# Default: ~/.fuzeddb/default.db
fuzeddb serve --db /path/to/custom.db
fuzeddb ls --db /path/to/custom.db

fuzeddb ships with agent skill files in skills/ — prompts that teach agents how to navigate and manage the filesystem, and when to proactively store their own observations.

• skills/memory-usage.md — How to navigate, read, write, search, and organize the filesystem
• skills/self-trace.md — How to automatically log decisions, learnings, and traces

See skills/README.md for setup instructions.

┌─────────────────────────────┐
│  Agent / CLI / MCP Client   │
├─────────────────────────────┤
│  MCP Server (stdio)         │
├─────────────────────────────┤
│  Backend Interface          │  ← filesystem operations
├─────────────────────────────┤
│  SQLite + FTS5              │  ← single .db file
└─────────────────────────────┘

The storage layer is abstracted behind a Backend interface. SQLite is the first implementation, but the same filesystem API can sit on top of any database:

type Backend interface {
    Write(ctx, path, content, metadata) error
    Read(ctx, path, offset, limit) (string, error)
    Edit(ctx, path, oldStr, newStr) error
    Mkdir(ctx, path) error
    Ls(ctx, path) ([]FileInfo, error)
    Stat(ctx, path) (*FileInfo, error)
    Rm(ctx, path, recursive) error
    Mv(ctx, src, dst) error
    Cp(ctx, src, dst) error
    Glob(ctx, pattern) ([]string, error)
    Grep(ctx, pattern, path) ([]GrepMatch, error)
    Tree(ctx, path, depth) (string, error)
    Search(ctx, query, limit) ([]SearchResult, error)
    Close() error
}

Implement this interface for Postgres, MySQL, or any SQL database — the filesystem works the same way.

• Postgres backend
• MySQL backend
• Redis backend (ephemeral/cache layer)
• Collections/namespaces for multi-project isolation
• Embedding-based semantic search
• HTTP transport (in addition to stdio)
• Import/export (JSON, Markdown, real filesystem sync)
• File versioning / history
• TTL / auto-expiry for ephemeral files

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Apache License 2.0 — see LICENSE for details.