# LatticeSearch — Features

Everything LatticeSearch does today, grouped by what you'd actually reach for. Every capability
below is built and verified on a real 1.66M-file machine (see `LATTICESEARCH-BRIEF-2026-07-18.md`
for the raw build log and measured numbers). Where a feature has a real limit, it's stated plainly.

**One-line summary:** instant search by name *and* meaning across your whole PC — photos, docs,
video, audio, speech, screenshots, faces — plus a full file explorer, safe file operations,
backup/dedup/recovery, an encrypted vault, and an MCP/CLI surface that lets your AI agents search
the machine. All local, all offline, on CPU (GPU auto-accelerates when present).

---

## 1. Search & Find

| # | Feature | What it does |
|---|---|---|
| 1 | **Instant name search** | Filename/path lookup over the whole drive (1.66M files here). Sub-10ms over ~1M names; with the optional Rust sidecar, 9.6–16.7ms median over 1,849,709 rows. This is the Everything-class "table stakes" tier — free-fast, always on. |
| 2 | **Meaning search** | Type what a file *is about* and get it back even if the words never appear in the name. Runs across every modality below through one search box; cheap tiers scan inline (~72–88ms fresh, 2–3ms cached), heavy models never block the search path. |
| 3 | **Ranked, deduped results** | Exact-stem > basename > path ordering (so "apple" surfaces `apple.dll`, not WinSxS "applet" junk); content-duplicates collapse to one hit; live category counts per query (images · docs · video · …). |

**Meaning search covers every modality — all local, all CPU:**

| Modality | Model | What you can find |
|---|---|---|
| Images | CLIP | "a red apple", "cartoon flame mascot" → the actual picture; image→image similarity. |
| Documents | multilingual-e5 (100+ languages) | Cross-lingual: an English query finds Japanese/German/Hindi docs. PDF/DOCX/XLSX/PPTX/MD/RTF/code/logs/ebooks/emails/subtitles/bookmarks/archives all chunked and searchable. |
| Video | CLIP frame sampling | Search scenes; results jump to the matched timestamp. Drop a still frame → find the source video. |
| Audio | CLAP | Text→sound ("bell sound", "dog barking") and sound→sound ("find similar speeches") — matches on *content*, proven with neutral filenames. |
| Speech | Whisper | Search **what was said** inside recordings and video soundtracks; results cue to the exact moment. |
| Screenshots / images with text | OCR (RapidOCR) | Find a screenshot by the text inside it ("runpod pricing console"). |
| Photo scenes | Florence-2 captions | Find photos by description ("cats on a table") even with no text or tags. |
| People | insightface face clustering | Groups faces into people; browse per-person photo grids. |
| AI renders | PNG metadata parser | Search your ComfyUI/A1111 images by their **generation prompt**. |

| # | Feature | What it does |
|---|---|---|
| 4 | **Crop / partial-image search** | Index-time tiling embeds 5 crops per image (center + 4 quadrants), so a cropped fragment finds its source. Verified: a Union-Jack crop → original rank #1. *Limit:* highly symmetric/patterned images can still land at rank #2. |
| 5 | **Find by example (drop a file)** | Drop any image/video/audio/other file onto the search bar or drop zone → finds the exact copy (and every duplicate location), similar files, and where it lives. |
| 6 | **Query operators** | `ext:png in:downloads size:>10mb size:<2gb before:2025 after:2024-06` parsed on the instant name path; combine freely with meaning terms. |
| 7 | **Lattice Suggest ("did you mean")** | Spelling corrected toward *this machine's* vocabulary (120k tokens from your filenames + doc words). "fire safty poster" → "fire safety poster" in ~12ms; correct queries get no nag. |
| 8 | **Expand / Focus** | Broaden (pull in neighbours of the top hits) or narrow (raise the bar) any result set; seed from a specific result to pivot the whole search onto its embedding. |
| 9 | **`lattice grep` (semantic-narrowed grep)** | Meaning narrows 1.66M files to the handful that *mean* your query, then exact ripgrep runs only inside them — "grep the 8 files that matter" instead of grepping the whole drive. |
| 10 | **Lumen — the built-in agent** | A crystalline search-sprite (bottom-right) opens a chat wired to the on-device agent: conversational answers plus real result hits with thumbnails. Understands time/size/type ("big barcast videos from this month") and returns **action deep-links** — buttons that jump to Backup, Sync, People, Reclaim Space, Settings, etc. |

---

## 2. Browse & Explore

| # | Feature | What it does |
|---|---|---|
| 11 | **Instant file explorer** | Folders list from an in-memory directory index with zero disk I/O — 3–26ms for most folders vs Windows Explorer's 16–163ms. Breadcrumbs, Up, folder counts, "listed in N ms". *Limit:* lists from the snapshot; brand-new files appear via live-watch or re-scan. |
| 12 | **Photos timeline** | A media timeline grouped by Years / Months / Days with All / Photos / Videos / Starred filters, square thumbnails, and a ▶ badge on video. Precomputed rows load in ~168ms (down from 2.1s). |
| 13 | **People (face clusters)** | A People strip in Photos: click a person → their photo grid → lightbox. Faces are clustered offline; this is browse-by-person, not surveillance. |
| 14 | **Knowledge Graph** | A force-directed graph of your files across 7 lenses (related images, related text, largest/smallest, by colour, by type, by folder, and a live search lens). Nodes render the *actual content* — image/video thumbnails, audio waveforms, doc snippet cards — not just circles. Drag/zoom/pan, click to preview, double-click to open. |
| 15 | **Media previews (in-app)** | Universal lightbox for image/video/audio with HTTP Range streaming (seekable, no whole-file RAM). YouTube-style hover-scrub silent video previews in results and grids; audio plays **at the matched moment**; SVG renders natively. |
| 16 | **View layouts** | Grid · Large grid · List · Details (list + sticky preview pane), with sortable columns (name/modified/size/type). Persisted per session. |
| 17 | **Rich preview panel** | Hero image/video thumbnail + a metadata table (type, size+bytes, dimensions/megapixels, dates, clickable location) plus "lattice senses" — which indexes actually know this file. |
| 18 | **Recents & Starred (server-side)** | Stored in the lattice itself (not just localStorage), so they persist across sessions; star toggles on every row and preview; committed-search-only recents (no keystroke spam). |

---

## 3. Lattice Hands & lattice fs — file operations built for agents (and you)

Index-synced, instant, and *reversible* — safer than raw shell, and every write is searchable the
instant it lands. All exposed via GUI, CLI, and MCP.

| # | Feature | What it does |
|---|---|---|
| 19 | **Read (`read --about`)** | Return the whole file, or only the indexed chunks relevant to a topic — so an agent gets the 40 lines it needs, not 2,000. Graceful full-read fallback. |
| 20 | **Write** | Atomic write that is searchable immediately (proven: a unique filename is found by search right after writing). |
| 21 | **Edit (anchor-verified)** | Exact string-replace that verifies the anchor first — 409s on a missing/ambiguous anchor instead of corrupting the file. Atomic, index-synced. |
| 22 | **Move / rename** | O(1) same-volume rename/move — 1.14ms regardless of file size. |
| 23 | **Copy** | Parallel verified copy. |
| 24 | **Safe delete** | Archives the bytes to the recovery store **and** sends to the Recycle Bin — reversible, unlike a shell `rm`. |
| 25 | **`lattice fs` (filesystem questions from the index)** | `du` / `find` / `tree` / `glob` / `largest` answered from RAM — no process spawn, no disk walk, milliseconds. `du` on 468MB/1,062 files returns in ~0ms; `find` merges the live layer so files written seconds ago are found. |
| 26 | **`lattice sh` (batch / REPL)** | Run many verbs in one process. A 6-step real workflow (du, find, glob, write, read, delete) ran **22.6×** faster than six PowerShell spawns (658ms vs 14,865ms) — du's recursive disk walk dominates the shell baseline. |
| 27 | **Code-symbol search** | Functions/classes indexed (ctags-style + embeddings): "where is the jitter latency guard" → `jitter_check` at `server.py:132`. Incremental rebuild in ~100ms. |

**Per-op Lattice Hands vs a PowerShell spawn** (measured): write 13.6× · read 20.1× · copy 16.3× ·
rename 18.0× · delete 5.4× (and *recoverable*, where the shell's is permanent).

---

## 4. Files & Space

| # | Feature | What it does |
|---|---|---|
| 28 | **Reclaim Space (byte duplicates)** | Same-size → sha256 to find byte-identical files; shows reclaimable MB and duplicate sets; "apply" archives to recovery first, then Recycle Bin (reversible). *Note: saves disk, not RAM.* |
| 29 | **Visual Duplicates** | Same picture saved twice under different names/sizes/formats, found by pixel fingerprint (dhash), not just bytes — found 6.1GB reclaimable across 120 groups on the test machine. |
| 30 | **Backup** | Deduplicated, zstd-compressed, integrity-verified snapshots. Measured on a 167MB corpus: **5.5× smaller** than the source (vs zip 2.55×) and **6.7× faster** to create than zip; a second backup of an unchanged tree is nearly free (incremental 0.38MB vs a fresh 65.4MB zip); a flipped byte is pinpointed to its blob; restores are byte-perfect. *Limit: empty dirs not preserved.* |
| 31 | **Recovery (restore-by-description)** | Restore deleted files by *describing* them ("document about checking smoke alarms") for up to 90 days, byte-perfect. *Honest boundary:* works only for files the app archived (protected-folder archiving + Recycle Bin) — embeddings **cannot** reconstruct bytes, so this is not magic un-deletion of arbitrary files. |
| 32 | **Compression (index & models)** | Native zstd folds the on-disk index **10.8×** (212MB → 20MB, lossless); int8 quantization makes shipped models ~4× smaller. *Honest boundary:* this compresses the index and model weights, not your user files — and there is no novel lattice compressor that beats zstd/xz losslessly. |

---

## 5. Organize, Move & Protect

| # | Feature | What it does |
|---|---|---|
| 33 | **Vault** | AES-256-GCM **searchable encrypted archive**: files and their index are sealed; you can run cross-lingual semantic search *inside* the sealed vault. Key = scrypt(passphrase); unlock ~109ms; tampering is rejected (GCM InvalidTag). |
| 34 | **Vault USB** | Package a vault + a portable app + launcher onto a USB stick. A stranger sees only opaque `data.bin`; the passphrase unlocks and searches it from the stick. |
| 35 | **Hidden vault layer** | Vaulted files (and optionally their originals) are hidden from Explorer and excluded from normal results — reachable only through the vault module + passphrase. |
| 36 | **Lattice Sync** | Pair any two folders (USB is just one case). **5 modes:** two-way, a→b, b→a, mirror-a→b, mirror-b→a; per-pair ignore patterns; conflict protection (won't clobber like `robocopy /MIR`); background auto-sync (~90s) that skips offline roots and resumes. No-change status check is hash-backed at ~43ms. |
| 37 | **Lattice Drive** | Mount `L:` (a watched folder) — anything dropped in is pre-indexed by construction, findable via `fs` in ~1ms and by search within seconds. |
| 38 | **Import to Drive** | Import files or whole folders (USB/camera) into `L:\Imports`, which is live-watched and indexed on arrival. (Distinct from the Home drop-zone, which *searches* a dropped file.) |
| 39 | **Drives (multi-drive)** | Enumerate and index additional/removable volumes (one index each); removable drives pair with Lattice Sync. Handles hot-swap, unplug=offline-tag, BitLocker, network-drive hazards. |
| 40 | **Lattice Clipboard** | Clipboard history you can search **by meaning**; text auto-embeds into memory; a secret filter (AWS keys, `password=`, PEM blocks, long base64) drops sensitive content before anything is stored; click a past entry to paste it back. |
| 41 | **Lattice Memory (cross-session recall)** | A private namespace where facts/notes are stored and recalled by meaning across sessions — the anti-compaction long-term memory for agents and for you. ~20ms recall at 500 entries. |
| 42 | **Lattice Report** | A self-contained weekly digest: index coverage + deltas, recent activity, reclaimable space, freshness, memory sessions. |
| 43 | **Index Health** | Coverage bars per "sense" — names, image meaning, text, sound, pixels — so you can see exactly what the lattice knows and what's still backfilling. |
| 44 | **Regeneration cycle** | Idle-time maintenance (03:00–05:00 when unused): condense shards, backfill docs/images/audio newest-first, refresh captions/pixel-hashes/colours/symbols, re-scan if stale — all bounded and resumable. |

---

## 6. AI-Agent Substrate

Turns LatticeSearch into the filesystem layer for your AI tools.

| # | Feature | What it does |
|---|---|---|
| 45 | **MCP server (20 tools)** | stdio JSON-RPC exposing search/ask/find_file/photos/list_folder, the full `fs_*` family, Lattice Hands (read/write/move/copy/delete/glob/edit), memory store/recall, and find_symbol. Drops into Claude Desktop/Code, Cursor, or any MCP agent. Proven **44× fewer tokens and 12× faster** than naive grep-and-read for a 3-lookup task (1,230 tokens / 11s vs 54,465 tokens / 133s). |
| 46 | **CLI (`lattice`)** | search/find/ask/recover/photos/ls/star/open/health plus the fs, Hands, memory, clipboard, and symbol verbs; `--json` for scripting. |
| 47 | **AI Access page** | Generates copy-paste-correct configs (Claude Desktop JSON, `claude mcp add` one-liner, generic MCP, CLI examples, an agent setup prompt) so connecting an agent is one click. |
| 48 | **Warm model host** | A separate process holds CLIP/e5 (CLAP lazy) resident and serves encodes over a local socket, so the engine restarts in ~19s instead of ~60s, multiple engines can share one host, and low-RAM/netbook boxes get semantic search. |
| 49 | **`lattice make` (build caching)** | Content-addressed zstd artifact cache with an instant input fingerprint: a real 56.5s Rust build became a **57ms cache hit (~1000×)**, and it can restore a deleted build artifact without recompiling. |

---

## 7. Privacy

| # | Feature | What it does |
|---|---|---|
| 50 | **Local-only, zero telemetry** | Nothing leaves the machine; air-gap capable and firewall-provable. The anti-Recall. |
| 51 | **Incognito mode** | 🕶 toggle: no recents, no activity log, memory-store refused, clipboard capture paused, search-cache skipped, jitter labels redacted. *Honest boundary:* leaves **no trace in the lattice** — but the OS still journals (USN/MFT, event logs, jump lists); this is not an anti-forensics tool. Deletes are still recovery-archived by design (safety over tracelessness). |
| 52 | **True-forget with grace** | Removing a recent (✕) soft-deletes it; re-searching within 7 days un-forgets it; after the window it's purged for good, client mirrors included. |
| 53 | **Secret filter** | Clipboard capture screens out API keys, passwords, PEM blocks and long base64 before anything is stored. |
| 54 | **Local API token** | Every mutating endpoint (including open/reveal) requires a per-install token; foreign-origin requests are refused — no drive-by launches. |
| 55 | **Cloud-placeholder safety** | Online-only files (e.g. 30% of a Dropbox tree) stay name-searchable but are never hydrated/downloaded by background indexing. |

---

## 8. Platform

| # | Feature | What it does |
|---|---|---|
| 56 | **Native Windows shell** | A tiny Tauri/wry desktop app (~0.6MB exe) wraps the engine in a real window — light/dark, theme-aware. |
| 57 | **Global hotkey palette** | Ctrl+Alt+Space anywhere pops a frameless, always-on-top Lattice Search Bar: instant results, multimodal thumbnails, Lattice Suggest, recent searches, drag-a-file-in to content-search; ↑↓/Enter/Esc. |
| 58 | **Right-click menu** | In-app Dropbox-style context menu (Open, Find similar, Copy path, Rename/Move/Copy/Delete, info) **and** a Windows Explorer right-click integration (per-user, no admin): Instant Move / Fast Copy / Recoverable Delete / Find similar. |
| 59 | **Send-To entries** | Windows Send-To: Lattice Find-similar, Safe-delete, and Lattice Drive. |
| 60 | **Lite / no-admin mode** | `--lite` runs name search + instant explorer + browse with the ML models off (RAM ~1.27GB vs ~3.5GB). Snapshotting needs no admin — it indexes whatever the user can read; the fast NTFS MFT path just makes the first scan quicker. |
| 61 | **Cross-platform seams** | Native open/reveal and hidden-file handling on Windows/Mac/Linux; auto-device (CPU by default, CUDA auto-boost when present with graceful fallback). |
| 62 | **Headless Linux / server edition** | Runs as a bounded, localhost-only, token-gated service: indexed **700,588 files in 16.6s** (42k files/s) at **360MB RSS**, search 10–22ms. |
| 63 | **Debug / monitoring console** | Live request + error tail with per-endpoint timing and a latency guard that flags any search over its budget. |

---

**Features documented: 63** (grouped into 8 areas), plus the 9 searchable modalities in the meaning-search table.

*Recurring honest boundary across the product:* the lattice answers from its index — milliseconds,
but as fresh as the last scan/watch tick. The name tier is live-watched; embedding tiers backfill
continuously; real execution (builds, tests, git) stays with the shell. Meaning search is
probabilistic — which is exactly why `lattice grep` (semantic narrow → exact match) is the pattern
wherever precision matters.
