TotalRecall

A local, searchable, encrypted index of everything that happens on your computer — built on .NET 10, fully open source, 100% on-device, with an optional MCP server so AI agents can query it.

---

What it does

Every N seconds (default: 10s), TotalRecall takes a screenshot of visible windows on your screen, skips windows that have not visually changed, runs OCR over changed images to extract the text, and stores the result in a local SQLite database:

• Window title and app name
• Process name + executable path
• Window bounds and whether it was in the foreground
• The full OCR text of what was visible
• The window screenshot itself, stored as a JPEG blob

You can then:

• Browse every snapshot in a dark-themed WinForms UI with a JPEG preview pane and full text view.
• Search across years of activity in milliseconds using SQLite FTS5 full-text search (with highlighted snippets).
• Filter by app, date range, or both.
• Optionally expose the database to AI agents over the Model Context Protocol so an assistant can answer questions like "what was that invoice number I was looking at last Tuesday?"

The vision is a personal, private "computer memory" — Microsoft Recall, but open source and entirely yours.

---

Install

Two install options for the full desktop app, plus a third for just the MCP server — pick whichever you prefer:

Option 1 — Installer 🟢 recommended

A single setup.exe, no admin/UAC, per-user install with a proper Add/Remove Programs entry.

1. Download TotalRecall-1.2.0-Setup.zip from https://github.com/ilyafainberg/TotalRecall/releases.
2. Unzip it (the installer is shipped inside a ZIP so browsers don't flag it as 'not commonly downloaded').
3. Double-click it.
4. Windows SmartScreen will say "Windows protected your PC" because this build isn't Authenticode-signed yet — click More info → Run anyway.
5. Pick install folder (default %LOCALAPPDATA%\Programs\TotalRecall\) and optional shortcuts (Start Menu / desktop / Start in tray on Windows sign-in). Click Install.
6. Launch TotalRecall from the Start Menu (or check Launch TotalRecall on the final wizard page).

The MCP server (TotalRecall.Mcp.exe) ships next to the main app in <install dir>\McpServer\.

Option 2 — Portable ZIP

If you prefer to control where the app lives (e.g. on a USB stick or under C:\Tools\), grab the portable ZIP — no install, no Start Menu entry, no Add/Remove Programs entry. Self-contained, no .NET runtime required.

1. Download TotalRecall-1.2.0-Portable-win-x64.zip from https://github.com/ilyafainberg/TotalRecall/releases.
2. Extract somewhere stable (e.g. C:\Tools\TotalRecall\). Don't run from Downloads — the MCP path you wire into your AI agent must be permanent.
3. Run TotalRecall\TotalRecall.exe.

The portable ZIP layout:

TotalRecall-1.2.0-Portable-win-x64\
├─ TotalRecall\
│  └─ TotalRecall.exe          ← the desktop app
├─ TotalRecall.Mcp\
│  └─ TotalRecall.Mcp.exe      ← the MCP server (see "MCP server setup" below)
├─ README.md
├─ INSTALL.txt
└─ LICENSE

Option 3 — MCP server only (no desktop app)

Just want the AI-agent integration and not the capture UI? Grab the standalone MCP bundle. Useful if you already have a TotalRecall database on the machine (from a previous install, or from another user) and only need the server to expose it.

1. Download TotalRecall-Mcp-1.2.0-win-x64.zip from the release page.
2. Extract somewhere stable (e.g. C:\Tools\TotalRecall.Mcp\).
3. Wire it into your MCP host — see the bundle's own README.md for snippets covering Microsoft Scout, GitHub Copilot CLI, Claude Desktop, VS Code Copilot Chat, and Cursor.

The bundle also ships an INSTALL-WITH-AGENT.md with a one-shot prompt you can paste into any AI agent that has shell + file-edit tools — the agent will download, extract, and merge the config into the right mcp-config.json for you. See MCP server setup below for both the manual walk-through and the agent-prompt path.

First-run setup (any option)

1. On the Settings tab, pick an encryption mode (default is Windows account — DPAPI-encrypted, silent unlock) and a capture interval (default 10 s). Click Save.
2. On the Capture tab, click Start.
3. (Optional) Wire TotalRecall.Mcp.exe into your AI agent — see MCP server setup for Microsoft Scout, GitHub Copilot CLI, and Claude Desktop wiring.

All packages are self-contained — no separate .NET runtime installation required.

About the SmartScreen warning: until the binaries are Authenticode-signed, Windows SmartScreen will warn on first launch for both the Inno Setup installer and the Portable ZIP — click More info → Run anyway.

Command-line flags

Flag	Effect
--tray	Launch hidden in the system tray (use with Settings → Minimize to tray enabled).
--capture-on	Force capture to start regardless of last remembered state.
--capture-off	Force capture to stay stopped regardless of last remembered state.
--minimized / -m	Start minimized (taskbar, or tray if tray mode is on).
--help / -h / /?	Print usage and exit.

If neither --capture-on nor --capture-off is passed, TotalRecall restores whatever capture state it had when it was last closed.

---

MCP server setup

The MCP server is a separate console executable that speaks JSON-RPC over stdio. It opens the same SQLite database the UI writes to and exposes 6 tools for an AI agent to query your activity history.

Tools exposed

Tool	Purpose
search_recall(query, app?, from?, to?, limit?)	FTS5 search; returns windows with highlighted snippet
get_window(window_id, include_image?)	Full window row including OCR text; optional base64 JPEG
list_snapshots(from?, to?, limit?)	Tick-level browse
get_snapshot(snapshot_id)	All windows from a single tick
list_apps()	Distinct app_name values that have been captured
stats()	Row counts, total image bytes, first/last timestamps

Configuration

The MCP server reads %LOCALAPPDATA%\TotalRecall\settings.json to find the DB path, OCR language, and encryption mode — so once you've configured the UI you usually don't need to pass anything. You can override:

Flag / env var	Purpose
--db <path> / TOTALRECALL_DB	Override the database path
--passphrase <s> / TOTALRECALL_PASSPHRASE	Supply a passphrase (required if you use passphrase encryption)

Two ways to install the MCP server

You can install the MCP server as part of the full TotalRecall desktop app (the Inno Setup installer ships it next to the WinForms app), or on its own from the standalone bundle. The standalone bundle is useful when:

• You're configuring an AI assistant on a machine where TotalRecall is already running but you don't want to install the desktop app twice.
• You're indexing a database that lives on a shared drive / NAS.
• You want to register the MCP server with a remote/CI agent host that doesn't need the GUI.

For the standalone bundle there are two install paths: hand the job to an AI agent (the easy path, below), or do it manually.

✨ Install with an AI agent (one-shot)

If you're already in an AI agent session (Microsoft Scout, GitHub Copilot CLI, Claude Code, Cursor, …), you can hand it the install job. Paste the prompt below verbatim into a fresh agent turn — the agent will download the zip from the latest GitHub release, extract it, sanity-check the binary, detect which MCP host you're running, and merge (not overwrite) a "totalrecall" entry into the right mcp-config.json:

You're going to install the TotalRecall MCP server on this Windows machine. Do all of the following without asking for confirmation between steps:

1. Download the latest TotalRecall MCP zip from the GitHub release:
     https://github.com/ilyafainberg/TotalRecall/releases/latest
   The asset name pattern is:  TotalRecall-Mcp-<version>-win-x64.zip
   Use the GitHub API (https://api.github.com/repos/ilyafainberg/TotalRecall/releases/latest) if you need to resolve the exact URL. Save it to %TEMP%.

2. Extract the zip into a stable per-user install dir:
     %LOCALAPPDATA%\Programs\TotalRecall.Mcp\
   Overwrite if it already exists. After extraction the server binary must be at:
     %LOCALAPPDATA%\Programs\TotalRecall.Mcp\TotalRecall.Mcp\TotalRecall.Mcp.exe

3. Sanity-check the server: run the .exe once with `--help` and confirm it prints a tools list without crashing. If it crashes, surface stderr to me and stop.

4. Detect which MCP host I'm running on (you are the agent — pick the right one):
   - Microsoft Scout / Clawpilot →  %USERPROFILE%\.clawpilot\mcp-config.json
   - GitHub Copilot CLI          →  %USERPROFILE%\.copilot\mcp-config.json
   - Claude Desktop              →  %APPDATA%\Claude\claude_desktop_config.json
   - VS Code Copilot Chat        →  %APPDATA%\Code\User\settings.json
                                    (key: github.copilot.chat.mcp.servers)
   - Cursor                      →  %USERPROFILE%\.cursor\mcp.json

   Read the existing file (or create it if missing) and merge — DO NOT replace — an entry under the appropriate "mcpServers" key:

     "totalrecall": {
       "command": "<full path to the .exe you installed in step 2>",
       "args": [],
       "env": {
         "TOTALRECALL_DB_PATH": "<%LOCALAPPDATA%>\\TotalRecall\\totalrecall.db"
       }
     }

   Preserve any other mcpServers already in the file. Pretty-print the JSON.

5. Tell me which host you configured, the absolute path to the installed .exe, whether the TotalRecall DB at TOTALRECALL_DB_PATH already exists, and that I need to restart the host before the server shows up.

If anything goes wrong, stop and tell me what failed.

Why it's safe to paste:

• Only writes to per-user dirs (%LOCALAPPDATA%, %USERPROFILE%, %APPDATA%) — no admin rights, no system-wide changes.
• Merges into existing mcp-config.json files, doesn't overwrite.
• Self-contained .NET 10 binary, no runtime install.
• Server is read-only by default; writes are gated by TOTALRECALL_READONLY=0.

The bundle's own INSTALL-WITH-AGENT.md ships the same prompt for sharing.

Manual install of the standalone bundle

1. Download TotalRecall-Mcp-1.2.0-win-x64.zip from https://github.com/ilyafainberg/TotalRecall/releases/latest.
2. Extract to a stable path (e.g. C:\Tools\TotalRecall.Mcp\). The .exe must end up at C:\Tools\TotalRecall.Mcp\TotalRecall.Mcp\TotalRecall.Mcp.exe.
3. Smoke-test the binary:

   C:\Tools\TotalRecall.Mcp\TotalRecall.Mcp\TotalRecall.Mcp.exe --help
   

4. Open the bundle's own README.md for copy-paste config snippets for each host (Microsoft Scout, GitHub Copilot CLI, Claude Desktop, VS Code, Cursor) — or use the templates in Registering with an AI assistant below.

Registering with an AI assistant

Microsoft Scout / GitHub Copilot CLI

Edit %USERPROFILE%\.copilot\mcp-config.json:

{
  "mcpServers": {
    "TotalRecall": {
      "type": "local",
      "command": "C:\\Tools\\TotalRecall\\TotalRecall.Mcp\\TotalRecall.Mcp.exe",
      "args": [],
      "tools": ["*"]
    }
  }
}

Restart the agent for the new server to be picked up.

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "totalrecall": {
      "command": "C:\\Tools\\TotalRecall\\TotalRecall.Mcp\\TotalRecall.Mcp.exe",
      "args": [],
      "env": {
        // Only needed if you chose passphrase encryption:
        // "TOTALRECALL_PASSPHRASE": "your phrase"
      }
    }
  }
}

Restart Claude Desktop.

Any other MCP-aware client

Spawn TotalRecall.Mcp.exe with stdio. Standard MCP initialize / tools/list / tools/call JSON-RPC over stdin/stdout.

Once registered, you can ask things like

• "Search my recall for any window mentioning 'invoice' in the last 3 hours."
• "What apps did I have open this morning?"
• "Find the window where I was reading about Power Platform pricing and summarize the text."
• "Show me the screenshot from window 4218." (the agent will call get_window with include_image: true)

The agent only ever sees the rows it explicitly queries — it cannot stream or exfiltrate the whole DB.

---

Roadmap / what's missing

• App allow-list / block-list (e.g. always skip 1Password, banking sites, etc.)
• Vector embedding of OCR text for semantic search alongside FTS5
• A "redact" pass on capture that masks anything that looks like a credential field
• Image-content embedding (CLIP / SigLIP) so the agent can do visual search ("the chart with the red bar")
• Export / share-out tools (encrypted snapshot archive, redacted JSON export)

PRs welcome.

---

On-device, open source, no AI in the loop

This is a deliberate design choice. The capture pipeline does not call any cloud service. Specifically:

• Screenshots are captured via Win32 PrintWindow — pixels never leave your machine.
• OCR runs locally with Tesseract 5 (Apache 2.0). No vision API, no cloud OCR, no telemetry.
• Storage is a local SQLite file encrypted at rest with SQLCipher (BSD/MIT).
• Search is local SQLite FTS5.

No AI model, LLM, or cloud service is involved in capture, OCR, storage, or search.

The only time AI becomes involved is when you choose to register the optional MCP server with your AI assistant (Claude Desktop, GitHub Copilot CLI, Microsoft Scout, etc.). In that case the agent calls the MCP server's tools, which return rows from your local database. The database still never leaves the machine — only the specific query results you asked the agent to fetch are sent to the model you've configured.

If you never enable the MCP server, no AI ever sees a byte of your data.

Licensing

TotalRecall is licensed under the GNU General Public License v3.0 (or any later version, at your option) — see the LICENSE file for the full text. Copyright © 2026 Ilya Fainberg. This is strong copyleft: you can use, study, share, and modify the code freely, but any work you distribute that incorporates TotalRecall must also be released under GPLv3.

Dependencies and their licenses:

Dependency	License
.NET 10 / WinForms	MIT
Tesseract (.NET wrapper + native Tesseract / Leptonica)	Apache 2.0
Microsoft.Data.Sqlite.Core	MIT
SQLitePCLRaw.bundle_e_sqlcipher (SQLCipher)	BSD-3 (wrapper) + zlib/MIT (SQLCipher)
ModelContextProtocol (C# SDK)	MIT

All of the above are compatible with GPLv3 distribution.

---

How it works

Solution layout

TotalRecall.sln
├── TotalRecall.Core/   class library — settings, key vault, DB schema, OCR,
│                       window enumeration, screenshot, snapshot service
├── TotalRecall/        WinForms UI (single-window: header + Browse, light theme)
└── TotalRecall.Mcp/    stdio MCP server (6 tools)

Capture pipeline (per tick)

1. Enumerate windows — EnumWindows + filters: skip invisible, minimized, DWM-cloaked (hidden UWP shells), tool windows, and anything < 32×32 px or without a title. Process metadata is cached across ticks.
2. Capture pixels — PrintWindow(hWnd, hdc, PW_RENDERFULLCONTENT) against a Bitmap. Works with modern apps using DirectComposition; a few hardware-accelerated surfaces (some games, DRM-protected video) may come back black — metadata is still recorded.
3. Detect change — A lightweight sampled visual hash skips unchanged windows before OCR, JPEG encoding, DB inserts, and FTS indexing.
4. Identify the app — Resolve PID → Process → FileVersionInfo.FileDescription for a friendly app name; fall back to ProcessName.
5. OCR — A single shared TesseractEngine (configurable language) runs over a grayscale, capped-size bitmap. Serialized through a lock to keep the native library happy.
6. Encode JPEG — Quality is configurable (30–95). The original lossless bitmap is used for OCR, then the JPEG is created purely for storage and preview.
7. Insert row — One snapshots row + N windows rows in a single SQLite transaction. FTS5 triggers keep the search index in sync.

Database schema

snapshots(id, ts, ts_unix, user, machine, window_count, elapsed_ms)

windows(id, snapshot_id → snapshots.id,
        title, app_name, process_name, process_id, executable_path,
        is_foreground,
        bounds_x, bounds_y, bounds_w, bounds_h,
        text, ocr_error, ocr_duration_ms,
        image_jpeg BLOB, image_bytes)

windows_fts  -- FTS5 virtual table over (title, app_name, process_name, text)

WAL mode, synchronous=NORMAL, foreign keys ON. Snippets use snippet(windows_fts, 3, '«', '»', '…', 12) so matched terms are highlighted in the UI.

---

Security: encryption options

The database can be encrypted at rest with SQLCipher (AES-256 CBC + PBKDF2 + HMAC). You pick the key source in Settings:

Mode	Where the key lives	Unlock UX	When to use
None	—	No key	Sandbox machines, throwaway testing
Windows account	32 random bytes generated once, DPAPI-encrypted with DataProtectionScope.CurrentUser at %LOCALAPPDATA%\TotalRecall\db.key. Decryptable only by your Windows user account on this machine.	Silent — auto-unlocks every launch	Default for personal machines
Passphrase	A passphrase you type. Never persisted.	Prompted each app launch (and required to start the MCP server)	Shared machines, second factor, USB-stick scenarios

Switching encryption mode only affects newly-created databases. To re-encrypt an existing DB, point at a new file path and re-capture.

Recommended hardening

• Run with Windows account encryption at minimum.
• Keep the DB on a BitLocker-encrypted drive.
• For shared machines, use Passphrase mode — even an admin can't unlock the file without your phrase.
• Use the built-in retention policy to strip old screenshots or delete old rows, then let automatic compaction run VACUUM to reclaim database file space.
• Never share the db.key file or the .db file. The db.key file is bound to your Windows user but is still a sensitive artifact.

What is captured (privacy)

TotalRecall captures whatever is visible on screen. That includes:

• Email subjects and bodies, chat messages, document text.
• Anything visible in browser tabs, including passwords if they are not masked.
• Notification banners, calendar previews, etc.

Treat the database accordingly. There is no allow-list / block-list yet for which apps to skip — if you don't want a specific app captured, minimize it before the next tick or stop the capture.

---

Build from source

Most users should just grab the release ZIP — this section is for contributors.

Prerequisites: .NET 10 SDK, Windows 10/11 x64.

git clone https://github.com/ilyafainberg/TotalRecall.git
cd TotalRecall
dotnet build TotalRecall.sln -c Release

To produce the same self-contained .zip that ships in releases:

.\build-release.ps1 -Version 1.0.0

Outputs:

TotalRecall\bin\x64\Release\net10.0-windows\TotalRecall.exe        # UI
TotalRecall.Mcp\bin\x64\Release\net10.0-windows\TotalRecall.Mcp.exe # MCP server

Run the UI:

.\TotalRecall\bin\x64\Release\net10.0-windows\TotalRecall.exe

The UI is a single window:

• Header — a compact capture bar with a live status pill (green dot ● Recording / gray ● Idle), interval/quality/encryption summary, the time + window count of the last snapshot, a single Start / Stop toggle button, and a ☰ hamburger menu.
• Body (Browse) — the three-pane workspace where you live:
  1. Results — FTS5 search box + app filter + a Time range dropdown (Any time · Today · Last 24 hours · Last 7 days · Last 30 days · This year · Custom…), sortable rows (click When / Title / App to sort).
  2. Preview — JPEG screenshot with a zoom slider (Fit · 25/50/75/100/150/200 %). Use Ctrl+0 for Fit, Ctrl+1 for 100 %, Ctrl+ / Ctrl- to step, or Ctrl+wheel. Right-click → Open in default viewer / Save image as….
  3. Captured text — full OCR transcript in a collapsible, resizable pane. Use the arrow-bar button to collapse it (a restore button reappears in the preview toolbar to bring it back). Right-click → Copy / Select all.
• Hamburger menu (☰) — Refresh results (F5), Activity log (Ctrl+L), Settings… (Ctrl+,), Open DB folder (Ctrl+Shift+D), Check for updates…, About, and Quit.
• Activity log and Settings are separate non-modal windows you open from the hamburger.

Settings live in %LOCALAPPDATA%\TotalRecall\settings.json. The default database path is %LOCALAPPDATA%\TotalRecall\recall.db.

Running in the background

Two settings under Settings → Behavior turn TotalRecall into a quiet background indexer:

• Start TotalRecall when I sign in to Windows — writes (or removes) a per-user entry under HKCU\Software\Microsoft\Windows\CurrentVersion\Run so the app launches with --minimized at every login. No admin rights, no scheduled task, no service. Only affects the current Windows user.
• Minimize to system tray — when on, the X button and the minimize button send the app to a tray icon instead of closing it. Right-click the tray icon for Open / Start capture / Stop capture / Exit. Double-click to restore the window.

When the app is launched with --minimized and tray mode is on, it starts hidden in the tray and auto-starts capture (so a fresh login immediately resumes indexing). With --minimized but tray mode off, it just opens minimized to the taskbar.

You can also start it from any shortcut or scheduled task with the same flag:

TotalRecall.exe --minimized

Adding OCR languages

Drop additional .traineddata files from https://github.com/tesseract-ocr/tessdata_fast into TotalRecall.Core\tessdata\ and rebuild. Then set the language in Settings (e.g. eng+fra for English + French).

---

License

TotalRecall — a local screen-activity indexer. Copyright © 2026 Ilya Fainberg.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program in the file LICENSE. If not, see https://www.gnu.org/licenses/.