omnifs

<div align="center"> # 🗄️ OmniFS **O filesystem que dá memória, time-travel e busca por significado pros seus agentes de IA.** NTFS e ext4 guardam *bytes*. O OmniFS guarda **bytes + história + sentido + autoria** — versionamento por-operação, busca semântica e proveniência, **offline e num binário só**.       </div> --- ## 📑 Índice - [Em 30 segundos](#-em-30-segundos) - [O problema](#-o-problema) - [OmniFS vs git vs FS comum](#-omnifs-vs-git-vs-fs-comum) - [Arquitetura](#-arquitetura) - [Como funciona](#-como-funciona) - [Instalação](#-instalação) - [Uso](#-uso) - [Claude Code (MCP)](#-claude-code-mcp) - [Resultados provados](#-resultados-provados) - [Medição empírica](#-medição-empírica-por-que-construímos-isto) - [Plataformas](#-plataformas) - [Roadmap](#-roadmap) - [Limitações honestas](#-limitações-honestas) - [FAQ](#-faq) - [Desenvolvimento](#-desenvolvimento) --- ## ⚡ Em 30 segundos ```console $ omnifs init ~/disco/.omnifs-drive $ omnifs mount ~/disco/.omnifs-drive ~/OmniDrive # vira um drive normal $ echo "função que valida o login e a senha" > ~/OmniDrive/auth.rs # salvou → auto-commit $ omnifs index ~/disco/.omnifs-drive indexados 1 arquivos $ omnifs search ~/disco/.omnifs-drive "onde verifica o acesso do usuário" 0.638 auth.rs — função que valida o login e a senha # achou por SIGNIFICADO, sem grep $ omnifs snapshot ~/disco/.omnifs-drive "antes de mexer" snapshot: b4b7f7cb8ffe... # ...agente faz besteira... $ omnifs rollback ~/disco/.omnifs-drive b4b7f7cb8ffe... # árvore inteira de volta, byte-fiel ``` Você trabalha num drive comum. Por baixo: **cada save é versionado**, **tudo é buscável por significado** e **dá pra voltar no tempo** — sem você (nem o agente) configurar nada. ## 🎯 O problema Um agente de IA (Claude Code) tem um perfil de I/O que NTFS/ext4 nunca foram feitos pra servir: | O agente… | …mas o FS comum oferece | |---|---| | edita em rajadas e **erra** | "salvou, era isso" (undo = você reza pra ter commitado) | | busca por **significado** ("a lógica de auth") | `grep` literal (acha `*.py`, não o conceito) | | trabalha **em paralelo** (N workers) | conflito por linha, stomp | | tem **context window finito** | ou lê o arquivo de 5000 linhas inteiro, ou nada | | toda escrita tem **autoria e intenção** | bytes anônimos; `git blame` por cima, na mão | O OmniFS roda **por cima do FS que já existe** (camada FUSE, não bloco). `cat`/`Edit`/`cp`/`grep` funcionam **idênticos a hoje** — e por baixo cada escrita vira versão + índice. ## 🆚 OmniFS vs git vs FS comum | | FS comum | git | **OmniFS** | |---|:---:|:---:|:---:| | Guarda bytes | ✅ | ✅ | ✅ | | Versão **automática** (sem `commit` na mão) | ❌ | ❌ | ✅ (no `release`) | | Rollback da árvore inteira | ❌ | ✅ | ✅ | | Busca por **significado** | ❌ | ❌ | ✅ (MiniLM) | | Dedup por conteúdo | ❌ | ✅ | ✅ (BLAKE3) | | Usável como **drive** transparente | ✅ | ❌ | ✅ (FUSE) | | Roda **git / symlinks / dev** por cima | ✅ | — | ✅ (POSIX completo) | | Escrita rápida | ✅ | ✅ | ✅ (**284 MB/s**, commit assíncrono) | | Tools nativas pro **agente** (MCP) | ❌ | ❌ | ✅ | | Offline / zero-dep de runtime | ✅ | ✅ | ✅ | ## 🧱 Arquitetura ``` ┌─ omnifs-cli ──── init · put · get · mount · snapshot · log · rollback · index · search ├─ omnifs-mcp ──── servidor MCP (stdio JSON-RPC); daemon unificado FUSE+MCP no mesmo store ├─ omnifs-fuse ─── projeção POSIX (fuser 0.14) + auto-commit no release; store via Arc ├─ omnifs-index ── busca semântica (fastembed MiniLM 384d + cosseno); cache em ~/.cache/omnifs ├─ omnifs-txn ──── versionamento CoW: commits content-addressed (tree + parent + ts + msg) └─ omnifs-store ── object store content-addressed (BLAKE3 + redb), dedup, refs (HEAD/branch) ``` > **Core ≠ Inteligência.** O core (store + versão + POSIX) é sempre ligado, rápido, zero-dep. A > busca semântica é módulo que liga em cima — o FS funciona perfeito sem ela. ## 🔬 Como funciona 1. **Você salva** um arquivo no mount (`~/OmniDrive`). 2. O **FUSE** intercepta o `release` (fechou o arquivo) e **enfileira** um auto-commit **assíncrono** (não bloqueia a escrita — daí 284 MB/s): um worker faz hash BLAKE3 → grava no **object store** (`redb`). Conteúdo idêntico = mesmo hash = guardado 1× (dedup). `.git`/`node_modules`/build são ignorados, então o store não incha com deps. 3. Um **snapshot** captura a árvore inteira como um *commit* (mapa `caminho → hash` + pai + msg), serializado e guardado no próprio store. `rollback` reescreve a árvore pro estado de um commit. 4. O **index** lê os arquivos-texto, gera embeddings (MiniLM, 384 dims, offline) e guarda os vetores. `search` embeda a query e ranqueia por **cosseno** — acha por significado. 5. O **MCP** expõe tudo como tools que o Claude chama. O **daemon unificado** roda FUSE e MCP no **mesmo `ObjectStore`** (via `Arc`), então mount + busca convivem sem brigar pelo lock do `redb`. ## 📦 Instalação ```bash sudo apt install fuse3 libfuse3-dev # único pré-req de SO git clone <repo> && cd omnifs cargo build --release cp target/release/{omnifs,omnifs-mcp} ~/.cargo/bin/ ``` ## 🚀 Uso ### Drive versionado (internos ocultos) ```bash omnifs init ~/disco/.omnifs-drive # dot-dir = oculto; guarda store + backing omnifs mount ~/disco/.omnifs-drive ~/OmniDrive # trabalhe em ~/OmniDrive como um drive normal — cada save é auto-commitado ``` ### Repo de dev (git e symlinks funcionam dentro do mount) ```console $ cd ~/OmniDrive $ git init && git add -A && git commit -m "v1" # commit funciona (handle table p/ loose objects 0444) $ ln -s src/main.rs atalho.rs # symlinks preservados (node_modules, venvs) $ df -h ~/OmniDrive # df reporta o tamanho real do disco ``` ### Time-travel ```console $ omnifs snapshot ~/disco/.omnifs-drive "v1" b565dc5ccce7... $ omnifs log ~/disco/.omnifs-drive 57d928c098d4 v2 b565dc5ccce7 v1 $ omnifs rollback ~/disco/.omnifs-drive b565dc5ccce7 # volta pro v1 (byte-fiel, remove órfãos) ``` ### Busca semântica ```console $ omnifs index ~/disco/.omnifs-drive indexados 5 arquivos $ omnifs search ~/disco/.omnifs-drive "mount a posix filesystem in userspace" 0.392 fuse.rs — projeção POSIX via FUSE... ``` ## 🤖 Claude Code (MCP) A busca semântica **não é transparente** — um FS não transforma `grep` em semântico (a intenção se perde no syscall). O agente usa **chamando a tool** via MCP: ```bash claude mcp add omnifs --scope user -- ~/.cargo/bin/omnifs-mcp ~/disco/.omnifs-drive ~/OmniDrive ``` Em cada sessão o Claude ganha `omnifs_snapshot · log · rollback · index · search`, a drive monta e a busca por significado fica disponível — **num processo só**, sem conflito de lock. ## ✅ Resultados provados | Verificação | Resultado | |---|---| | Auto-commit byte-fiel | ✅ binário com `\x00`/`\xff` idêntico mount↔store | | Rollback | ✅ restaura a árvore + remove órfãos do snapshot mais novo | | Semântica **cross-língua** | `auth`(EN, código) × `login/senha`(PT) = **0.419** · vs `cart` = **-0.043** | | Semântica em **código real** | **4/4 top-1** (nomes neutros, query sem nome de arquivo) | | Daemon unificado | FUSE + MCP simultâneos no mesmo store, **sem "Database already open"** | | **`git` real no mount** | `init`+`add`+`commit`×2, working tree limpo, `cat-file` lê objeto de volta | | **Symlinks · `df`** | `ln -s` preserva o link (node_modules/venvs); `df` reporta o tamanho real do disco | | **Throughput** | 300 MB com `fsync` em 1,1s = **284 MB/s** (era ~0,65 MB/s — ~437×) | | **Index + store filtrados** | `.git`/`node_modules`/build ignorados — **0 hit** na busca, **0 KB** no store | | Suíte | **8 testes verdes** (6 store + 1 txn + 1 index) | ## 📊 Medição empírica (por que construímos isto) Antes de uma linha de código, mineramos **666 transcripts reais do Claude Code (46.290 tool calls)** pra validar a premissa — não confiar em palpite: | Pilar | Sinal medido | Veredito | |---|---|---| | Busca semântica | **~10%** das ações são localizar código (refinado de 22,9% brutos) | 🟢 #1 — vale | | Time-travel linear | **0,32%** das ações usam `git reset` | 🔴 fraco no local (forte em infra) | | Ops remoto | **~50%** das buscas são ssh/docker/VPS | ⚠️ fora do alcance de um FS local | Custo dominante real: **38,7 bilhões de tokens de `cache_read`** (contexto reprocessado). Mineradores em [`docs/measurement/`](docs/measurement/) · decisões no [ADR 0001](docs/adr/0001-omnifs-arquitetura-e-medicao.md). ## 💻 Plataformas | | Core + busca + MCP | Mount transparente | |---|:---:|:---:| | **Linux** | ✅ | ✅ nativo | | **Windows (WSL2)** | ✅ | ✅ (kernel Linux real + `/dev/fuse`) | | **macOS** | ✅ | ✅ com macFUSE | | Windows nativo (Win32) | ✅ | ❌ (precisa backend WinFSP) | Núcleo é Rust puro + ONNX Runtime (binários pros 3 SOs). Só o mount transparente é específico de SO. ## 🗺️ Roadmap - [x] Object store content-addressed (BLAKE3 + redb) - [x] Time-travel (snapshot/log/rollback) - [x] Busca semântica (MiniLM + cosseno) - [x] Projeção POSIX (FUSE) + auto-commit — **POSIX completo**: rename · symlink · readlink · statfs · link · fsync - [x] **Dev-FS real** — `git commit`, symlinks e `df` funcionam dentro do mount - [x] **Throughput** — auto-commit assíncrono + buffers de 1 MB → **284 MB/s** (era 0,65) - [x] **Index + store filtrados** — pulam `.git`/`node_modules`/build e arquivos >512 KB - [x] MCP (5 tools) + daemon unificado - [ ] **Daemon por socket** — mount sempre ligado + busca, independente do Claude - [ ] **FUSE store-backed** — um arquivo opaco só, zero backing visível (ocultação total) - [ ] **Branches nomeadas + proveniência por-prompt** - [ ] **Extratores PDF/imagem** (pdftotext/OCR) — indexar mídia - [ ] **HNSW** — busca sub-linear (>10k arquivos; hoje é scan linear) - [ ] **AST-summaries** (tree-sitter) — resumos extrativos sem LLM ## ⚠️ Limitações honestas - **`redb` é single-writer** → FUSE + MCP coexistem via **daemon unificado** (resolvido); processos *fora* do daemon não escrevem no mesmo store ao vivo. - **Busca por-arquivo** (não por-função) e **scan linear** — ok até ~10k arquivos. - **Sem extrator de mídia** ainda — PDF/imagem são guardados byte-fiéis, mas não indexados. - **Migração em massa de origem lenta** (ex.: HDD falhando) é limitada pela *origem*, não pelo OmniFS — pra bulk de disco ruim, copie pro ext4 primeiro. - **Não formata nem apaga** disco — camada não-destrutiva por design. ## ❓ FAQ **Some com meus arquivos quando desmonta?** Não. Eles vivem no store oculto (content-addressed); o mount é só a *projeção*. Desmontar = a pasta fica vazia, montar de novo = tudo volta. **Preciso de internet / GPU / Ollama?** Não. Tudo offline, CPU. O modelo de embedding (~90 MB) baixa **uma vez** e fica em `~/.cache/omnifs`. **Funciona com mídia (PDF, foto)?** Guarda byte-fiel sim. Indexar (buscar por conteúdo) ainda não — está no roadmap. **É seguro? Pode apagar meu disco?** Não formata nada. Vive *dentro* de um diretório de um FS que já existe. ## 🛠️ Desenvolvimento ```bash cargo build # workspace (puxa fuser, redb, fastembed/ort, blake3) cargo test # 8 testes (index test é #[ignore] — baixa modelo) cargo build --release # binário otimizado ``` Estrutura: 6 crates em `crates/`, spec em [`docs/superpowers/specs/`](docs/superpowers/specs/), decisões em [`docs/adr/`](docs/adr/). ## 📄 Licença MIT. --- <div align="center">_{Construído com <b>medição antes de código</b>. 18 commits · 8 testes verdes · 100% offline · escrita 284 MB/s · git/symlinks dentro do mount.}</div>