# LatticeSearch Help

Task-by-task guides for finding anything on your PC — instantly and privately.

LatticeSearch searches your files by **meaning**, not just by filename. Ask for "the invoice from March" or "photos of the beach" and it finds them, even when those words appear nowhere in the file name. Everything runs on your own machine — nothing is uploaded.

---

## Table of contents

- [First run: what happens when you start](#first-run-what-happens-when-you-start)
- [Searching](#searching)
- [The quick-search palette (Ctrl+Alt+Space)](#the-quick-search-palette-ctrlaltspace)
- [Browsing files instantly](#browsing-files-instantly)
- [Photos and People](#photos-and-people)
- [The Knowledge Graph](#the-knowledge-graph)
- [Previewing media](#previewing-media)
- [File operations (move, rename, copy, delete)](#file-operations-move-rename-copy-delete)
- [Import to Drive vs. drop-to-search](#import-to-drive-vs-drop-to-search)
- [Reclaim space (duplicates)](#reclaim-space-duplicates)
- [Backup and restore](#backup-and-restore)
- [Recovery: find deleted files](#recovery-find-deleted-files)
- [Vault](#vault)
- [Lattice Sync](#lattice-sync)
- [Lattice Clipboard](#lattice-clipboard)
- [Lattice Memory](#lattice-memory)
- [Lattice Report](#lattice-report)
- [Privacy: Incognito, forgetting searches, Settings](#privacy-incognito-forgetting-searches-settings)
- [Connecting an AI (MCP + CLI)](#connecting-an-ai-mcp--cli)

---

## First run: what happens when you start

The first time you open LatticeSearch, it builds an index of your files. This is **tiered and progressive** — you can start searching almost immediately, and the deeper "senses" fill in behind the scenes.

1. **Names come first.** LatticeSearch scans your drive and builds an instant name index. This takes **minutes** (roughly 5 minutes for a large drive; under a minute on a machine with the fast-path name indexer). As soon as this finishes, **name search and the file explorer are fully live.**
2. **Meaning fills in behind it.** In the background, per file type, LatticeSearch adds:
   - **Images** — understood by content (CLIP), so you can search photos by describing them.
   - **Documents** — text extracted and chunked so you can search by what they say.
   - **Videos** — sampled frame by frame, with jump-to-timestamp results.
   - **Audio** — indexed by sound and by speech transcript.
   - **Heavy senses last** — text inside screenshots (OCR), spoken words (speech-to-text), scene captions, and face grouping. On a big library these run for hours, often overnight. This is a **one-time** cost.
3. **A banner shows progress.** While the deeper tiers build, a status banner reads "Search is live — AI layers filling in" with a checklist of tiers. You never have to wait for it — search stays instant throughout.

While indexing is still catching up, a file may be findable by name before it's findable by meaning. If you just added something and it hasn't appeared yet, its content sense may still be filling in.

> **Tip:** After the first build, LatticeSearch keeps itself fresh automatically. It watches your active folders for changes, and it runs a quiet maintenance pass in the small hours (roughly 3–5 a.m.) when your machine is idle to backfill anything new.

---

## Searching

The search bar sits at the top of every screen. Type a query and results stream in: instant name matches first, then images, videos, audio, and documents ranked by meaning below.

### Search by meaning

Just describe what you want in plain words.

- `a kitchen interior`
- `the invoice from March`
- `red things`
- `cartoon flame mascot`

LatticeSearch matches the *idea*, so a photo named `IMG_4821.jpg` still turns up under "beach sunset."

### Search by name

Type part of a filename or path. Name results are exact and instant, ranked so that exact stem matches beat basename matches beat path matches (searching `apple` surfaces `apple.py`, not WinSxS `applet` junk). Pure extension queries switch into filter mode:

- `.png` — every PNG on the drive, newest first
- `report.pdf`

### Search by dropping a file or a crop

You can search **with a file instead of words** — useful to find where something lives, or to find things that look or sound like it.

1. Drag an image, video, or audio file straight onto the **search bar** (it glows and shows "drop to search by content"), or onto the **drop zone on the Home page**.
2. LatticeSearch reports where that exact file lives, plus a pixel-identical-copy check and a list of similar files by content.

This works with **crops**, too. Drop a cropped piece of an image and LatticeSearch still finds the full original, because images are indexed as overlapping tiles as well as whole. You can also **paste an image** from your clipboard (Ctrl+V) anywhere in the app to search for it.

### Query operators

Mix these filters into any search to narrow it on the instant name path:

| Operator | Example | Meaning |
|---|---|---|
| `ext:` | `ext:png` | only files of this extension |
| `in:` | `in:downloads` | only inside a folder whose name matches |
| `size:>` / `size:<` | `size:>10mb`, `size:<2gb` | larger / smaller than |
| `before:` | `before:2025` | modified before a date |
| `after:` | `after:2024-06` | modified after a date |

They combine freely, e.g. `screenshot ext:png in:downloads size:>1mb`.

### Ask Lumen

**Lumen** is the crystalline assistant in the bottom-right corner. Click it to open a chat and ask in full sentences:

- "photos of the beach"
- "the recording where we discussed pricing"
- "my biggest videos"

Lumen interprets your request (pulling out time, size, and type filters automatically), searches every sense, and answers with the best hits — thumbnails included. Click any hit to preview it, or "Open all results" to see the full search. Lumen can also carry out actions like opening Backup, toggling Incognito, or walking you through connecting an AI. Longer, plain-language questions typed into the main search bar (four or more words) also trigger the assistant automatically.

### "Did you mean…" suggestions

If you mistype, LatticeSearch corrects toward the vocabulary of **your own machine** — the actual words in your filenames and documents. Search `fire safty poster` and a 💡 banner offers **fire safety poster**; click it to run the corrected search. Correct queries get no suggestion. This is *Lattice Suggest*, and it never slows the instant search path.

### Expand and Focus

On any search results screen:

- **⊕ Expand** broadens the search — it lowers the threshold and pulls in related items nearby.
- **⊙ Focus** narrows it — only the strongest, most on-target hits remain.

From a file preview you can also click **⊕ Expand from here** to pivot the whole search onto that file's meaning and explore its neighbourhood.

---

## The quick-search palette (Ctrl+Alt+Space)

The palette is a small always-on-top search bar you can summon **anywhere in Windows**, without switching to the app.

1. Press **Ctrl+Alt+Space**. A compact "Lattice Search Bar" appears on top of whatever you're doing.
2. Type your query. Results — image thumbnails, files, documents by meaning, and audio cued to the matched moment — appear as you type, with a Lattice Suggest row for typos.
3. Navigate with **↑ / ↓**, press **Enter** to open the top result (or **➜**), and **Esc** or **✕** to close.

**Drop a file onto the palette.** The palette stays pinned (it doesn't vanish when you click elsewhere), so you can drag a file from Explorer directly onto it to search by content — find where it lives, its pixel-identical copies, and similar files.

**Clipboard history from the palette.** Type `clip ` followed by words to search your [Lattice Clipboard](#lattice-clipboard) history by meaning — for example `clip that address I copied`. Click a match to paste it back to your clipboard.

---

## Browsing files instantly

Open **All files** (or the 🗂 rail icon) for a file explorer that never waits — folder listings are served from the in-memory index with zero disk I/O, so most folders open in a few milliseconds.

- **Breadcrumbs** across the top let you jump to any parent; **↑ Up** goes up one level; the timing readout ("listed in N ms") shows how instant it is.
- **Folders** appear as cards with live item counts; **files** honour your chosen layout.
- **Layout menu** (top-right) switches between **Grid**, **Large grid**, **List**, and **Details** (a list with a sticky preview pane). In List and Details you can click column headers to sort by name, modified, size, or type.
- **Back / Forward** work everywhere: the ‹ › buttons in the top bar, your mouse's back/forward buttons, and **Alt+← / Alt+→**.
- **Recents** and **Starred** live in the left nav. Star any file with the ☆ on its row or in its preview; starred files also appear in the nav for quick access.

> Listings come from the index snapshot. Brand-new files show up once the live watcher picks them up (seconds) or after a re-scan; very large folders are display-capped for speed.

---

## Photos and People

Open **Photos** for a timeline of all your images and videos (system folders and app internals are excluded).

- **Filter** the strip with **All Items · Photos · Videos · Starred**.
- **Group** by **Years · Months · Days** using the segmented control.
- Click any thumbnail to open it in the [lightbox](#previewing-media); video tiles carry a ▶ badge and preview on hover.

**People (faces).** When face grouping has run, a circular **People** strip appears at the top of Photos. Each circle is one person LatticeSearch clustered from your photos. Click a person to see every photo they appear in, then click any photo to view it. Face detection and clustering run entirely on your machine.

---

## The Knowledge Graph

Open **Knowledge graph** to see how your files relate, as an interactive force-directed map.

- Pick a **lens** to colour and connect the graph: **Related images**, **Related text**, **Largest**, **Smallest**, **By colour**, **By type**, or **By folder**.
- **The node is the thing.** Image nodes render as live thumbnails, audio nodes as little waveform tiles you can play, document nodes as cards showing their actual text snippet. Only hubs are plain circles.
- **Interact:** drag nodes around, scroll to zoom, drag the background to pan. **Click** a node for a detail card (with the real image, playable audio at the matched moment, or readable text); **double-click** to open the file.

Two more ways to reach the graph:

- On any search, click **🕸 Graph** to see the query as a hub with its multi-modal hits and a ring of second-order related files the flat list can't show.
- In the file explorer, click **🕸 Graph** to see how the files in the current folder cluster by meaning.

---

## Previewing media

You can inspect almost anything **inside the app** before deciding to open it.

- **Preview drawer.** Click any file to slide out a preview with a hero image (or video thumbnail / audio player), the filename, and a metadata table — type, size, dimensions, dates, clickable location, and which "lattice senses" know the file. Buttons: **Open**, **Open folder**, **Star**, **🎯 Similar**, **⊕ Expand from here**.
- **Lightbox.** Click a hero image, a photo, or a video to open the full-screen lightbox. Images zoom; videos and audio stream and are seekable (audio jumps to the **matched moment** when you arrived from a sound search). Close with **Esc** or by clicking the backdrop; buttons let you **Open file**, **Show in folder**, or see **Details**.
- **Hover-scrub video.** Hover a video thumbnail anywhere (results, Files grid, previews) and it plays silently; move your mouse left-to-right across it to scrub through the clip, YouTube-style.

---

## File operations (move, rename, copy, delete)

Right-click any file (in results, the explorer, or the graph) for a context menu:

- **Open** · **Find similar** · **Open in** → File Explorer or Quick view
- **Copy path**
- **Rename** · **Move** · **Copy** · **Delete**
- **File / Folder info** · **More** → Folder activity, Star

These are safe and fast:

- **Move on the same drive is instant.** A same-volume move is an O(1) rename — it completes in about a millisecond regardless of file size, and the toast says so.
- **Delete is recoverable.** Deleted files go to the Recycle Bin *and* are archived to LatticeSearch's recovery store, so you can restore them later (see [Recovery](#recovery-find-deleted-files)). Nothing is hard-deleted out from under you.
- Every operation is recorded in **Folder activity**, viewable per folder from the context menu's **More** submenu.

### From Windows itself (right-click and Send-To)

LatticeSearch can add entries to Windows Explorer's own right-click menu (installed per-user, no admin needed): **⚡ Instant Move to…**, **⚡ Fast Copy to…**, **♻ Delete (recoverable)**, and **🔎 Find similar** (which opens the app focused on that file). Matching **Send-To** entries — Find similar, Safe delete, and copy into your Lattice Drive — are installed too.

---

## Import to Drive vs. drop-to-search

These two look similar but do opposite things — the distinction matters:

- **Drop-to-search (the Home drop zone and the search bar):** you drop a file to **find** it — where it lives on your machine, its copies, and things like it. It does **not** move or copy anything.
- **Import to Drive (the ⬆ Import page):** you bring files **into** the lattice. They are **copied** into your **Lattice Drive** (at `L:\Imports`), which is always watched and indexed the moment files arrive. Use this to pull things off a USB stick, a camera, or your Downloads into an always-searchable home.

**To import:** open **Import**, then either **Choose files** / **Choose folder**, or drag files or a whole folder onto the drop area. They're searchable within seconds — by name first, by meaning shortly after.

**Lattice Drive** is a real drive letter (`L:`) that LatticeSearch live-watches, so anything you keep there is pre-indexed by construction.

---

## Reclaim space (duplicates)

Two tools find redundant files; both remove copies **reversibly** (originals are archived to Recovery and sent to the Recycle Bin, never hard-deleted).

### Reclaim Space — byte-identical duplicates

1. **More → Reclaim Space.**
2. Enter a folder to scan and click **Scan**. LatticeSearch buckets files by size, then hashes to find exact duplicates. It reports how many duplicate sets and how many MB are reclaimable.
3. Click **Remove … of duplicates** to clear them (keeping one of each set). You'll be asked to confirm; removed copies stay recoverable.

### Visual Duplicates — the same picture, different files

1. **More → Visual Duplicates.**
2. LatticeSearch groups images that are the *same picture* even when saved under different names, sizes, or formats — matched by pixel fingerprint, not just bytes.
3. Review each group and reclaim space, keeping the largest of each.

---

## Backup and restore

**More → Backup** makes deduplicated, compressed, integrity-verified snapshots of a folder.

**Create a snapshot**

1. Enter a **folder to back up** and, optionally, a **store location** (blank uses the app's backup store).
2. Click **Create snapshot**. Files are written to a content-addressed store: unchanged files cost almost nothing on the next snapshot, so backups are incremental forever.

**Verify** — click **Verify store integrity** to hash-check every stored blob; a flipped byte is pinpointed to the exact blob.

**Restore** — in the Snapshots list, type a target folder next to a snapshot and click **Restore**. Restores are byte-perfect.

---

## Recovery: find deleted files

**Deleted files** in the left nav (or **More → Recovery**) restores things you deleted **through LatticeSearch** — by *describing* them.

1. Open **Deleted files**.
2. Type what you remember, e.g. `the fire safety document I deleted last month`. Recovery searches the archived trash by meaning as well as by name.
3. Click **Restore** on a match. Files come back byte-identical (to a *LatticeSearch Recovered* folder).

Recoverable files are retained for **90 days**. Recovery covers files deleted via the app (and archived protected files); it can't resurrect files deleted by other tools that never touched LatticeSearch.

---

## Vault

The **Vault** (More → Vault) is a searchable **encrypted** archive. Files and their search index are sealed with AES-256 using a key derived from your passphrase, so you can **search inside the vault without exposing its contents** — even across languages. Without the passphrase, the stranger sees only opaque data.

**Vault USB** packages a vault plus a portable app onto a USB stick, so you can carry an encrypted, searchable archive that unlocks only with your passphrase.

> In this build the Vault is driven by its command-line tools; a guided in-app wizard is on the way. The encryption, sealing, and cross-language search inside the vault all work today.

---

## Lattice Sync

**More → Lattice Sync** keeps **any two folders** in step — Desktop ↔ Documents, a project ↔ a backup drive, or a USB ↔ this PC. Each side keeps its own manifest, so changes are detected in milliseconds and only real differences move.

**Pair two folders**

1. Enter **Location A** and **Location B**.
2. Choose a **mode**:
   - **⇄ Two-way** — changes flow both directions.
   - **→ A updates B** / **← B updates A** — one-way.
   - **⇉ Mirror A→B** / **⇇ Mirror B→A** — the target becomes an exact copy of the source. Files that exist only on the target are removed **to recoverable trash**, never hard-deleted.
3. Optionally add **ignore patterns** (comma-separated), e.g. `node_modules, *.tmp, .git`.
4. Click **Preview changes** to see exactly what would move, then **Sync now**.

**Conflicts are preserved, never silently overwritten.** Tick **Auto-sync** to register the pair for a background sync roughly every 90 seconds; an unplugged drive is skipped and resumes the next pass when you plug it back in. Registered pairs are listed below, where you can change mode, toggle auto, edit ignore patterns, or remove a pair in place.

---

## Lattice Clipboard

**More → Lattice Clipboard** is a clipboard history you can **search by meaning**.

1. Click **▶ Enable watching** to start capturing what you copy (text and copied files).
2. Copied items appear under **Recent** with timestamps. **Secrets are filtered out before anything is stored** — things that look like API keys, passwords, PEM blocks, or long base64 are never saved.
3. **Search** the history from the box at the top (by meaning), or from the palette with `clip <words>`.
4. Click **📋 Copy** on any item (or a palette match) to **paste it back** to your clipboard.

History retention defaults to **30 days** and is pruned automatically (adjust it in [Settings](#privacy-incognito-forgetting-searches-settings)). Capture pauses while [Incognito](#privacy-incognito-forgetting-searches-settings) is on.

---

## Lattice Memory

**Lattice Memory** lets an AI agent connected to LatticeSearch remember facts and recall them **by meaning** across sessions — a durable memory that survives conversation resets. It's used through the AI connection (MCP tools `memory_store` / `recall`, or the CLI `remember` / `recall`), not a screen you open yourself. Stored memories are searchable alongside your clipboard captures. Memory writes are refused while Incognito is on. See [Connecting an AI](#connecting-an-ai-mcp--cli).

---

## Lattice Report

**More → Lattice Report** generates a self-contained digest of what the lattice has been doing: coverage per sense (and how it changed), recent file activity, how much space is reclaimable, index freshness, and memory sessions. Click **Generate report** to build and open it.

---

## Privacy: Incognito, forgetting searches, Settings

### Incognito mode

Click the **🕶** button in the top bar to toggle Incognito. While it's on:

- Recent searches are **not recorded** (on the server or locally).
- The activity log stays silent.
- Lattice Memory writes are **refused**.
- Clipboard capture is **paused**.
- The search cache is skipped and preview history isn't kept.

The connection label changes to "incognito" so you always know it's active. Turn it off to resume normal recording.

**Honest scope:** Incognito leaves no trace **in the lattice**, but it is not an anti-forensics tool — Windows itself still journals activity (USN/MFT, event logs, jump lists), and that's outside LatticeSearch's control. Also by design, **deletes are still archived to Recovery even in Incognito** — safety is chosen over tracelessness there.

### Forgetting recent searches

- Open the **Recents** page (or the recent-searches dropdown in the search bar) and click the **✕** next to any search, or **Clear all**.
- A removed search enters a grace period: if you search it again within **7 days** it's un-forgotten; after 7 days it's purged for good. (You can change this "forget window" in Settings.)

### Settings

Open **⚙ Settings** (top bar or More → Settings) to adjust:

- **Privacy** — Incognito by default, the forget window (days), and clipboard retention (days).
- **Indexing** — extra watched folders (live-indexed on change) and per-folder chunk granularity (`fine` binds small facts, `coarse` suits archives).
- **System** — your quick-search hotkey, and whether the fast native name accelerator is active.

Click **Save settings** to apply.

---

## Connecting an AI (MCP + CLI)

LatticeSearch can act as an AI assistant's **eyes and hands** into your files — meaning-search over your whole machine in milliseconds instead of blind file walks. Measured against naive grep-and-read loops, this is about **44× fewer tokens and 12× faster** per task, and everything stays local.

Open **AI Access** (left nav, or More → AI Access — MCP + CLI). The page computes copy-paste-correct setup for your machine, each with a **Copy** button:

1. **Claude Desktop (MCP)** — paste the generated JSON into your Claude Desktop config file (the exact path is shown), then restart Claude Desktop.
2. **Claude Code (one command)** — run the generated `claude mcp add …` command in a terminal.
3. **Any MCP client (Cursor, VS Code, …)** — a generic MCP server entry (command + args + env).
4. **CLI — works with any agent, no MCP needed** — example `lattice` commands. Notably `lattice grep` narrows to the files that *mean* your query, then runs an exact grep only within them.
5. **Setup prompt** — a ready-made prompt you can hand your agent so it knows how to use the lattice on its own.

Through MCP or the CLI, an agent gets tools to **search / ask / find files / list folders / recover**, **read and edit files** (anchor-verified, index-synced, with safe recoverable deletes), run filesystem questions (`du` / `find` / `tree` / `largest`), find code symbols, and use [Lattice Memory](#lattice-memory). You can also just click **Ask Lumen → 🤖 Connect your AI** for a guided walkthrough.


## Power search operators (borrowed from Everything)

The instant search box understands power-user operators:

| Operator | Example | Meaning |
|---|---|---|
| `!term` | `apple !dll` | exclude — drop results containing *term* |
| `a\|b` | `invoice\|receipt` | OR — match either |
| `regex:` | `regex:apple.*\.png` | full regular-expression mode |
| `in:` | `apple in:downloads` | scope to a real directory segment (not just a substring) |
| natural dates/sizes | `big pdfs from last week` | size/date/type words become filters automatically |

These compose with the existing `ext:` `size:` `before:` `after:` operators.
