# 🧠 Screen Memory MCP

> Give Claude a perfect memory of everything that's ever been on your screen.

**"What was I researching on ChatGPT an hour ago?"**
**"What code did I write this morning?"**
**"Walk me through what I did in the last 30 minutes."**

Just ask Claude. It remembers.

---

## How it works

```
Every N seconds:
  📸 Screenshot  →  🔤 Windows OCR  →  🧬 Embed  →  💾 SQLite
                    (built-in, accurate,  (local model,   (text only,
                     no hallucination)    no API calls)    ~5KB/capture)
```

**100% local. No images stored. No cloud. No API costs.**

---

## Features

- **Semantic search** — "find when I was reading about X" across your entire screen history
- **Activity timeline** — connected narrative of what you did and why, not just isolated snapshots
- **Code tracking** — detects VS Code / PyCharm, tracks which files you edited, computes diffs between captures
- **App awareness** — knows if you were in a browser, editor, or terminal and tags captures accordingly
- **Tiny footprint** — text + embeddings only, ~5KB per capture, ~30MB/day at 10s interval

---

## Requirements

- Windows 10 / 11
- Python 3.11+
- No Tesseract. No cloud APIs. No external accounts.

---

## Installation

```bash
git clone https://github.com/YOUR_USERNAME/screen-memory-mcp
cd screen-memory-mcp
pip install -r requirements.txt
```

---

## Usage

### 1. Start the capture daemon

```bash
python -m screen_memory.capture --interval 10
```

| Interval | Storage/day | Recommended for |
|----------|-------------|-----------------|
| 5s       | ~90MB       | Maximum detail  |
| 10s      | ~45MB       | Daily use ✓     |
| 30s      | ~15MB       | Light use       |

### 2. Connect to Claude Desktop

Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "screen-memory": {
      "command": "C:\\Python314\\python.exe",
      "args": ["-m", "screen_memory.server"],
      "cwd": "C:\\path\\to\\screen-memory-mcp",
      "env": {
        "PYTHONPATH": "C:\\path\\to\\screen-memory-mcp"
      }
    }
  }
}
```

Restart Claude Desktop. The `screen-memory` tools will appear automatically.

### 3. Ask Claude anything

```
"What was I doing 20 minutes ago?"
"Summarize my activity for the last hour"
"What code did I write today in VS Code?"
"Find when I was reading about async Python"
"How did server.py change during my coding session?"
```

---

## MCP Tools

| Tool | Description |
|------|-------------|
| `search_screen_memory` | Semantic search across all captures |
| `get_activity_timeline` | Chronological narrative of a time range |
| `get_code_changes` | Code diffs per file for a coding session |
| `get_recent_captures` | Latest N captures |
| `get_capture` | Full text of a specific capture by ID |
| `get_stats` | DB size, capture count, date range |

---

## Auto-start on login (Windows)

Run once in an elevated terminal:

```powershell
schtasks /create /tn "ScreenMemoryCapture" /tr "C:\path\to\start_capture.bat" /sc onlogon /ru YOUR_USERNAME /f
```

---

## Storage

All data lives in `~/.screen_memory/memory.db` — a single SQLite file.

To wipe everything: just delete it.

---

## Privacy

- ✅ Fully offline after install
- ✅ No screenshots saved to disk
- ✅ All text stays on your machine
- ✅ Open source — every line auditable
- ✅ Delete anytime: `rm -rf ~/.screen_memory`

---

## Roadmap

- [ ] macOS / Linux support
- [ ] Auto-cleanup (configurable retention period)
- [ ] System tray app (start/stop without terminal)
- [ ] Screenshot viewer (opt-in)
- [ ] Multi-monitor support

---

## License

MIT