{"id":49574794,"url":"https://github.com/andyleimc-source/pensieve-mcp","last_synced_at":"2026-05-03T16:08:22.785Z","repository":{"id":353709376,"uuid":"1220545402","full_name":"andyleimc-source/pensieve-mcp","owner":"andyleimc-source","description":"Apple Silicon installer + Claude Code MCP integration for arkohut/pensieve (local screen memory, searchable from Claude Code CLI)","archived":false,"fork":false,"pushed_at":"2026-04-25T05:02:58.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T07:14:39.435Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andyleimc-source.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-25T02:49:48.000Z","updated_at":"2026-04-25T05:03:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/andyleimc-source/pensieve-mcp","commit_stats":null,"previous_names":["andyleimc-source/pensieve-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/andyleimc-source/pensieve-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyleimc-source%2Fpensieve-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyleimc-source%2Fpensieve-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyleimc-source%2Fpensieve-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyleimc-source%2Fpensieve-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andyleimc-source","download_url":"https://codeload.github.com/andyleimc-source/pensieve-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyleimc-source%2Fpensieve-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32575263,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-03T16:08:22.090Z","updated_at":"2026-05-03T16:08:22.773Z","avatar_url":"https://github.com/andyleimc-source.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pensieve-mcp\n\n[![tests](https://github.com/andyleimc-source/pensieve-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/andyleimc-source/pensieve-mcp/actions/workflows/test.yml)\n\n**Apple Silicon installer + Claude Code MCP integration for [arkohut/pensieve](https://github.com/arkohut/pensieve).**\n\nTurn your Mac's screen into a searchable, local-first memory — and let Claude Code CLI query it directly.\n\n让你的 Mac 屏幕变成本地可搜的\"记忆库\"，Claude Code CLI 可直接调用。\n\n---\n\n## English\n\n### Features\n\n- **One-command installer** — pins the right `transformers` version so `/api/search` actually works on Apple Silicon, runs `memos init/start`, walks you through Screen Recording permission, and registers the MCP with Claude Code.\n- **Claude Code MCP integration** — ask *\"what did I work on this afternoon?\"* in Claude Code and it queries your local screen history directly. No external LLM key needed beyond Claude Code.\n- **Activity summary tool** — aggregate a time range into top apps + sample windows + hit count, so Claude can answer \"what did I do today?\" without bloating its context with raw OCR.\n- **Pause / resume capture** — tell Claude *\"pause for 2 hours\"* or *\"pause until 9am tomorrow\"*; survives sleep and reboot via launchd.\n- **Privacy controls** — retroactively purge screenshots from any time range (with a dry-run preview), or add apps to a recording blacklist so they're never captured in the first place.\n- **Power modes** — switch capture cadence between `eco` (slow, low CPU) and `performance` (fast, more detail) on the fly.\n- **Daily retention policy** — launchd job prunes screenshots older than `RETAIN_DAYS` (default 90). Pensieve has none built in.\n- **Optional cloud archive (Tencent COS)** — instead of deleting old screenshots, upload image bytes to your private COS bucket. OCR/embeddings stay local, so search still works; ~¥1–3/month per 100GB.\n- **Optional multi-device aggregation** — set `PENSIEVE_PEERS` to your other Macs (e.g. home + work over Tailscale) and one MCP transparently searches across all of them. Results tagged with `source=\u003chostname\u003e`.\n- **Optional Bearer-token auth** — drop a token into `~/.config/pensieve-mcp/auth.env` to authenticate every request to local Pensieve and to peers. Required if you expose `:8839` to a LAN or Tailnet.\n\n### What is this?\n\n[Pensieve](https://github.com/arkohut/pensieve) (the `memos` CLI) is an open-source, local-first screen-memory tool: it takes screenshots every few seconds, OCRs them, embeds them, and lets you search your screen history offline.\n\nThis repo is a **thin installer kit** on top of it, for Apple Silicon Macs, that adds:\n\n1. **A one-command installer** that pins the correct dependency versions so it actually works (upstream breaks with `transformers\u003e=5` — see [troubleshooting](docs/troubleshooting.md)).\n2. **An MCP server** so Claude Code CLI can search your screen history and answer questions like *\"what did I work on this afternoon?\"* without needing any external LLM API key.\n3. **A launchd-based retention policy** (default: delete screenshots older than 90 days) — Pensieve has none built in.\n\n### Why would I want this?\n\n- \"Where was that Supabase billing screen I saw last week?\"\n- \"Summarize everything I read about X today.\"\n- \"I was in a Figma file yesterday around 3pm — which one?\"\n\nAll answered locally, from your own screen history, through your existing Claude Code subscription — no DeepSeek / OpenAI / Anthropic API key needed beyond what Claude Code already uses.\n\n### Prerequisites\n\n- macOS (Apple Silicon strongly recommended; Intel untested)\n- [Homebrew](https://brew.sh)\n- [`uv`](https://docs.astral.sh/uv/) — `brew install uv`\n- [Claude Code CLI](https://docs.anthropic.com/claude-code) — `claude` on your PATH\n\n### Install\n\n```bash\ngit clone https://github.com/andyleimc-source/pensieve-mcp.git\ncd pensieve-mcp\n./install.sh\n```\n\nThe installer will:\n1. Install `memos` via `uv tool install memos --with \"transformers\u003c5\"`\n2. Run `memos init` and `memos start`\n3. Open System Settings for you to grant Screen Recording permission\n4. Install a daily LaunchAgent that prunes screenshots older than `RETAIN_DAYS` (default 90)\n5. Register the MCP server with Claude Code (user scope)\n\nTo change retention: `RETAIN_DAYS=30 ./install.sh`.\n\n### Verify\n\n```bash\nclaude mcp list                 # expect: pensieve ✓ Connected\nmemos ps                        # serve + record + watch all Running\nopen http://localhost:8839      # Pensieve Web UI\n```\n\nThen in a **new** Claude Code session, ask:\n\n\u003e \"What did I work on in the last 20 minutes? Use pensieve to check.\"\n\n### MCP tools exposed\n\nThe MCP server (`scripts/pensieve-mcp.py`) exposes these tools to Claude Code:\n\n| Tool | Purpose |\n|---|---|\n| `search_screenshots(query, limit?, app?)` | Semantic + keyword search. Returns up to `limit` hits with id, timestamp, app/window, and a ~800-char OCR snippet. Each hit carries `archive_status: local \\| archived \\| unknown`. |\n| `get_screenshot(entity_id)` | Full details + full OCR text for a single screenshot id. For archived items, returns `cos_key` instead of a usable local path. |\n| `download_archived(entity_id)` | Pull an archived screenshot from COS to a temp file. Call only when needed. |\n| `pause_recording(duration_seconds?, resume_at?)` | Stop screen recording. Optional auto-resume after duration or at ISO timestamp. Survives sleep/reboot. |\n| `resume_recording()` | Resume immediately, cancel any scheduled auto-resume. |\n| `recording_status()` | Whether record is running, plus any active pause schedule. |\n| `activity_summary(start?, end?, top_apps?)` | Aggregate what you worked on in a time range — top apps, sample windows, hit count — without dumping every OCR snippet into Claude's context. |\n| `get_power_mode()` / `set_power_mode(mode)` / `toggle_full_power()` | Switch capture cadence between `eco` (slow, low CPU) and `performance` (fast, more detail). Useful when you're about to do something you really want recorded. |\n| `purge_screenshots(start, end?, app?, confirm=False)` | Retroactively delete screenshots in a time range (and their DB rows) — for redacting sensitive activity captured by accident. Dry-run by default; pass `confirm=True` to actually delete. Local machine only; not cascaded to peers. |\n| `list_apps(start?, end?, min_count?, top_n?)` | List apps observed in screen history with their shot counts. Useful before `search_screenshots(app=...)` so you don't guess the wrong NSApplicationName (\"Code\" vs \"VSCode\" etc). |\n| `list_app_blacklist()` / `add_app_blacklist(app)` / `remove_app_blacklist(app)` | Manage the recording blacklist (`app_blacklist` in `~/.memos/config.yaml`). Apps in the list are skipped at capture time. Use for password managers, banking apps, anything you never want screenshotted. Auto-restarts `record` so changes are live. |\n| `health()` | Diagnostic: pings local Pensieve, probes each `PENSIEVE_PEERS` for reachability + auth + latency, reports auth-token status, archive config, disk usage with warnings. Call first when something feels off. |\n\n### Optional: cloud archive (Tencent COS)\n\nBy default, screenshots older than 90 days are deleted locally. Enable cloud archive during `./install.sh` (step 6) to upload them to a Tencent Cloud COS bucket instead — they stay searchable through the MCP, only the image bytes move to the cloud. ~¥1–3/month per 100GB.\n\nSee [docs/cos-archive.md](docs/cos-archive.md) for the full setup (bucket, CAM sub-account, policy) and how it interacts with the MCP.\n\n### Optional: weekly DB backup (requires cloud archive)\n\nIf cloud archive is enabled, `./install.sh` step 10 also offers to install a weekly LaunchAgent (Sunday 04:00) that uploads `~/.memos/database.db` + `config.yaml` to `cos://\u003cbucket\u003e/_backup/\u003cdevice\u003e/pensieve-YYYY-MM-DD.tar.gz`. Keeps the last 4 backups (rolling). Tiny — typically \u003c100MB compressed even for years of history.\n\nWhy it matters: image bytes already live in COS, but the SQLite DB (OCR text + embeddings + entity rows) and `config.yaml` are local-only. Lose them and your archive becomes unsearchable even though the .webp files survive. To restore:\n\n```bash\ncoscmd download \"/_backup/\u003cdevice\u003e/pensieve-2026-04-26.tar.gz\" /tmp/restore.tar.gz\ntar xzf /tmp/restore.tar.gz -C /tmp/\ncp /tmp/pensieve-2026-04-26/database.db ~/.memos/database.db\nmemos restart\n```\n\nRun on demand: `./scripts/backup-db.sh`.\n\n### Disk-usage safety\n\nThe daily prune LaunchAgent normally honors `RETAIN_DAYS` (default 90). If `~/.memos` exceeds `EMERGENCY_GB` (default 80GB), retention temporarily drops to `EMERGENCY_RETAIN_DAYS` (default 30) so a runaway day can't fill the disk before the next 03:30 tick. `health()` also reports `~/.memos` size + free disk space and warns before either becomes critical.\n\nTo tune: edit the LaunchAgent's `EnvironmentVariables` (`~/Library/LaunchAgents/com.user.pensieve.prune.plist`).\n\n### Optional: multi-device aggregation\n\nIf you run Pensieve on multiple Macs (e.g. home + work) and connect them via [Tailscale](https://tailscale.com), one MCP can transparently search across all of them. Set `PENSIEVE_PEERS` to a comma-separated list of peer base URLs (Tailscale IPs):\n\n```bash\nexport PENSIEVE_PEERS=\"http://100.x.y.z:8839,http://100.a.b.c:8839\"\n```\n\nSearch results from peers are tagged with `source=\u003chostname\u003e`; local hits stay tagged `source=local`. Failures on individual peers are swallowed (you still get local results).\n\nNotes:\n- Peers must use the **same** `PENSIEVE_TOKEN` (see below) for auth to work, or all be unauthenticated.\n- Peer queries skip httpx's auto-proxy detection (`trust_env=False`), since macOS system proxies (Clash/V2Ray) tend to break Tailscale CGNAT routing.\n- Configure on **each** Mac symmetrically and you get bidirectional aggregation — querying either machine searches both.\n\n### API authentication\n\nBy default, Pensieve's REST API on `:8839` is unauthenticated. That's fine for pure localhost use, but **dangerous if you expose it to a LAN or Tailnet** (which `PENSIEVE_PEERS` requires).\n\n`./install.sh` step 7 offers to generate a token for you. If you skipped it, or want to enable auth later:\n\n```bash\nmkdir -p ~/.config/pensieve-mcp \u0026\u0026 chmod 700 ~/.config/pensieve-mcp\nprintf \"PENSIEVE_TOKEN=%s\\n\" \"$(openssl rand -hex 32)\" \u003e ~/.config/pensieve-mcp/auth.env\nchmod 600 ~/.config/pensieve-mcp/auth.env\nmemos stop \u0026\u0026 memos start    # server.py middleware reads the file at boot\n```\n\nHow it works end-to-end:\n- **Server side** — `patches/server.py.patch` (applied by `./scripts/apply-patches.sh`, which `install.sh` invokes) installs a FastAPI middleware that, when `auth.env` is present, returns `401` on any non-localhost request lacking `Authorization: Bearer \u003ctoken\u003e`. Localhost (`127.0.0.1`, `::1`) is always allowed so the Web UI keeps working.\n- **Client side** — the MCP reads the same `auth.env` and sends `Authorization: Bearer \u003ctoken\u003e` on every request to local Pensieve and to any `PENSIEVE_PEERS`.\n\nFor multi-device, write the **same** token to `auth.env` on every machine. Mismatched tokens silently break peer queries.\n\n### Upgrading\n\nWhen upstream Pensieve releases a new version:\n\n```bash\nmemos stop\nuv tool upgrade memos --with \"transformers\u003c5\"\n./scripts/apply-patches.sh        # re-apply the three site-packages patches\nmemos start\n```\n\n`uv tool upgrade` (and `uv tool install --force`) wipe site-packages, removing the auth middleware, the power-mode override, and the mirror-display filter. `apply-patches.sh` is idempotent and detects upstream drift — if a patch fails after an upgrade, please open an issue.\n\nTo verify state at any time: `./scripts/apply-patches.sh --check`.\n\n### Uninstall\n\n```bash\n./uninstall.sh\n```\n\nRemoves the MCP registration, LaunchAgent, and (optionally) the `memos` tool. Your `~/.memos/` data directory is left alone — delete it yourself if you want.\n\n### Troubleshooting\n\nSee [docs/troubleshooting.md](docs/troubleshooting.md). The most common issue: upstream Pensieve ships without a hard pin on `transformers`, so `uv` resolves to 5.x, which breaks `/api/search`. This kit pins it for you.\n\n### Development\n\nPure-helper tests live in `tests/` and run on push via GitHub Actions (Python 3.11 + 3.12). To run locally:\n\n```bash\nuv run --with pytest --with httpx --with 'mcp\u003e=1.2.0' --with psutil --with 'ruamel.yaml\u003e=0.18' \\\n  python -m pytest tests/ -v\n```\n\nNetwork-touching tools (`search_screenshots`, `purge_screenshots`, `health`, etc.) are not unit-tested by design — exercise them through Claude Code against a live `memos serve`.\n\n### Credits\n\n- Upstream: [arkohut/pensieve](https://github.com/arkohut/pensieve) — all the heavy lifting (capture, OCR, embedding, REST API, Web UI) is theirs.\n- This repo: install wrapper + MCP server.\n\nLicense: MIT.\n\n---\n\n## 中文\n\n### 主要特性\n\n- **一键安装**：pin 住 `transformers` 版本（不 pin 上游会装到 5.x 把 `/api/search` 搞挂），自动跑 `memos init/start`，引导授权\"屏幕录制\"，注册 MCP 到 Claude Code\n- **Claude Code MCP 集成**：在 Claude Code 里直接问\"我下午都在干嘛\"，它会查你本地的屏幕历史回答。**不需要额外 API key**，用你订阅里的 Claude 即可\n- **活动汇总工具**：`activity_summary` 把时间段聚合成 top apps + 窗口样本 + 命中数，让 Claude 答\"今天我都干了啥\"时不会被海量 OCR 撑爆上下文\n- **暂停 / 恢复截屏**：直接对 Claude 说\"暂停 2 小时\"\"暂停到明早 9 点\"\"暂停一下\"都行；通过 launchd 实现，睡眠 / 重启都能正常恢复\n- **隐私控制**：事后撤回任意时间段的截图（带 dry-run 预览），或把敏感 app 加进录制黑名单从源头就不录\n- **电源模式切换**：`eco`（慢、省电）和 `performance`（快、记得多）随时切，要专心做某件事且希望被完整记录就拉满\n- **每日保留策略**：launchd 每天凌晨清理 `RETAIN_DAYS`（默认 90）天外的截图。Pensieve 官方没有这功能\n- **可选云归档（腾讯云 COS）**：超期截图不直接删，传到你私人 COS 桶，OCR 文本和向量留在本地——**搜索照常工作**，只是图片本体上云。100GB 一年 ~¥10-30\n- **可选多设备聚合**：`PENSIEVE_PEERS` 配上其他 Mac（比如家 + 公司，Tailscale 互通），一个 MCP 就能跨设备透明搜索，结果带 `source=\u003chostname\u003e` 标签\n- **可选 Bearer token 鉴权**：把 token 放进 `~/.config/pensieve-mcp/auth.env`，所有调本地 Pensieve 和 peer 的请求都自动带 `Authorization` 头。把 `:8839` 暴露到 LAN/Tailnet 时**必须**配\n\n### 这是什么？\n\n[Pensieve](https://github.com/arkohut/pensieve)（命令叫 `memos`）是一个开源的本地屏幕记忆工具：每隔几秒自动截屏 → OCR → 向量化 → 入本地库，可离线搜索\"我之前在屏幕上看到过什么\"。\n\n本仓库是它的 **Apple Silicon 薄安装套件**，补齐了三件事：\n\n1. **一键安装脚本**：固定正确依赖版本让它跑起来（上游在 `transformers\u003e=5` 时会挂，详见 [troubleshooting](docs/troubleshooting.md)）\n2. **MCP server**：让 Claude Code CLI 直接查你的屏幕历史，回答\"我下午都在干嘛\"这种问题。**不需要配 DeepSeek/OpenAI 的 key**，用你订阅里的 Claude 就行\n3. **launchd 自动保留策略**：默认 90 天外的截图每天凌晨自动清理。Pensieve 官方没有这个功能\n\n### 为什么要装\n\n- \"上周看到的那张 Supabase 账单截图在哪？\"\n- \"今天关于 X 的内容我都看了啥，总结一下\"\n- \"昨天下午三点我在 Figma 里打开的是哪个文件？\"\n\n全部**本地检索**，通过你已有的 Claude Code 订阅回答——不需要额外 API key、不需要把数据发到第三方 LLM。\n\n### 前置条件\n\n- macOS（强烈推荐 Apple Silicon；Intel 未测试）\n- [Homebrew](https://brew.sh)\n- [`uv`](https://docs.astral.sh/uv/)：`brew install uv`\n- [Claude Code CLI](https://docs.anthropic.com/claude-code)：`claude` 在 PATH 里\n\n### 安装\n\n```bash\ngit clone https://github.com/andyleimc-source/pensieve-mcp.git\ncd pensieve-mcp\n./install.sh\n```\n\n脚本会：\n1. `uv tool install memos --with \"transformers\u003c5\"` 装好 Pensieve（带正确 pin）\n2. `memos init` + `memos start`\n3. 帮你打开\"系统设置→隐私与安全性→屏幕录制\"去授权\n4. 装一个每天凌晨跑的 LaunchAgent，清理 `RETAIN_DAYS`（默认 90）天外的截图\n5. 把 MCP server 注册到 Claude Code（user scope）\n\n要改保留天数：`RETAIN_DAYS=30 ./install.sh`。\n\n### 验证\n\n```bash\nclaude mcp list                 # 看到 pensieve ✓ Connected\nmemos ps                        # serve + record + watch 都是 Running\nopen http://localhost:8839      # Pensieve Web UI\n```\n\n然后在**新**的 Claude Code 会话里问：\n\n\u003e \"帮我看看最近 20 分钟我都在干嘛，用 pensieve 查一下\"\n\n### MCP 暴露的工具\n\n| 工具 | 作用 |\n|---|---|\n| `search_screenshots(query, limit?, app?)` | 语义 + 关键词搜索。返回 id、时间、app/window、截断后的 OCR 片段；每条 hit 带 `archive_status`（local/archived/unknown）|\n| `get_screenshot(entity_id)` | 拿某张截图的完整信息（含完整 OCR 文本）；归档对象返回 `cos_key` 指向云端位置 |\n| `download_archived(entity_id)` | 按需把归档对象从 COS 拉到本地临时文件 |\n| `pause_recording(duration_seconds?, resume_at?)` | 暂停截屏。可选自动恢复（按时长或绝对时间），睡眠/重启都能正常恢复 |\n| `resume_recording()` | 立刻恢复截屏，取消计划中的自动恢复 |\n| `recording_status()` | 报告 record 进程是否运行 + 当前暂停状态 |\n| `activity_summary(start?, end?, top_apps?)` | 聚合时间段内的活动概况——top apps、窗口样本、命中数——避免把每张截图的 OCR 全塞进 Claude 上下文 |\n| `get_power_mode()` / `set_power_mode(mode)` / `toggle_full_power()` | 切换截屏节奏：`eco`（慢、省电）/ `performance`（快、记得多）。要专心做某件事且希望它被完整记录时拉满 |\n| `purge_screenshots(start, end?, app?, confirm=False)` | 事后删除某段时间的截图（连 DB 行一起删），用于撤回意外被录到的敏感操作（网银、密码管理器等）。默认 dry_run，要 `confirm=True` 才真删；只作用于本机，不级联到 peer |\n| `list_apps(start?, end?, min_count?, top_n?)` | 列出屏幕历史中观察到的 app 名 + 截图数。先调它看准确字符串再 `search_screenshots(app=...)`，免得猜错 NSApplicationName（\"Code\" vs \"VSCode\"） |\n| `list_app_blacklist()` / `add_app_blacklist(app)` / `remove_app_blacklist(app)` | 管理录制黑名单（`~/.memos/config.yaml` 里的 `app_blacklist`）。黑名单里的 app 在前台时整个 tick 跳过截屏。适合密码管理器、网银、医疗等永不录制的场景。改完自动 `memos restart record` |\n| `health()` | 综合诊断：本机 Pensieve 探活 + 每个 `PENSIEVE_PEERS` 的可达性/auth/延迟 + token 状态 + 归档配置 + 磁盘占用（带告警）。出问题先调它 |\n\n直接对 Claude 说：\"暂停截屏 2 小时\"、\"暂停到明早 9 点\"、\"暂停一下\"（无限期）都能识别。\n\n### 可选：云归档（腾讯云 COS）\n\n默认行为是 90 天外的截图本地直接删。在 `./install.sh` 第 6 步可以选启用云归档——超期截图先传到你私人的 COS 桶再删本地，**搜索照常工作**（OCR 文本和向量在本地 SQLite，没动），只是图片本体上云。100GB 一年 ~¥10-30。\n\n详见 [docs/cos-archive.md](docs/cos-archive.md)：建桶、CAM 子账号、最小权限策略、和 MCP 怎么联动。\n\n### 可选：DB 周备份（依赖云归档）\n\n启用了云归档之后，`./install.sh` 第 10 步会再问一次是否装周备份 LaunchAgent（每周日 04:00），把 `~/.memos/database.db` + `config.yaml` 打包传到 `cos://\u003cbucket\u003e/_backup/\u003cdevice\u003e/pensieve-YYYY-MM-DD.tar.gz`，保留最近 4 周。压缩后通常 \u003c100MB，几年的历史也撑不大。\n\n为什么要单独备份 DB：图片字节已经在 COS 了，但 SQLite DB（OCR 文本 + 向量 + entity 行）和 `config.yaml` 还是纯本地——丢了的话即使 webp 还在云上，整个归档也不可搜索。恢复方法：\n\n```bash\ncoscmd download \"/_backup/\u003cdevice\u003e/pensieve-2026-04-26.tar.gz\" /tmp/restore.tar.gz\ntar xzf /tmp/restore.tar.gz -C /tmp/\ncp /tmp/pensieve-2026-04-26/database.db ~/.memos/database.db\nmemos restart\n```\n\n手动跑一次：`./scripts/backup-db.sh`。\n\n### 磁盘占用兜底\n\n每日 prune LaunchAgent 默认按 `RETAIN_DAYS`（90 天）保留。如果 `~/.memos` 超过 `EMERGENCY_GB`（默认 80GB），保留期临时降到 `EMERGENCY_RETAIN_DAYS`（默认 30），避免某个失控的白天撑爆磁盘等不到第二天 03:30。`health()` 也会报 `~/.memos` 大小和可用空间，临界前就告警。\n\n调整阈值：改 LaunchAgent plist（`~/Library/LaunchAgents/com.user.pensieve.prune.plist`）的 `EnvironmentVariables`。\n\n### 可选：多设备聚合\n\n如果你在多台 Mac 上都跑了 Pensieve（比如家里 + 公司），又用 [Tailscale](https://tailscale.com) 把它们连起来，一个 MCP 就能透明地跨设备搜。`PENSIEVE_PEERS` 设成逗号分隔的 peer URL 列表（Tailscale IP）：\n\n```bash\nexport PENSIEVE_PEERS=\"http://100.x.y.z:8839,http://100.a.b.c:8839\"\n```\n\npeer 来的结果会带 `source=\u003chostname\u003e` 标签；本地命中标 `source=local`。某个 peer 抽风也不影响——本地结果照样返回。\n\n说明：\n- peer 必须**统一**用同一个 `PENSIEVE_TOKEN`（见下文），或者全部都不带 auth\n- peer 查询会跳过 httpx 的自动代理探测（`trust_env=False`），因为 macOS 系统代理（Clash/V2Ray）一般不会路由 Tailscale CGNAT 段，会反 502\n- 两台机器**对称**配置就能双向聚合——查任一台都搜两台\n\n### API 鉴权\n\nPensieve 的 `:8839` REST API 默认不带鉴权，纯 localhost 用没问题，**但暴露到 LAN 或 Tailnet（PENSIEVE_PEERS 必须暴露）裸奔很危险**。\n\n`./install.sh` 第 7 步会询问是否生成 token；跳过了或之后想开启：\n\n```bash\nmkdir -p ~/.config/pensieve-mcp \u0026\u0026 chmod 700 ~/.config/pensieve-mcp\nprintf \"PENSIEVE_TOKEN=%s\\n\" \"$(openssl rand -hex 32)\" \u003e ~/.config/pensieve-mcp/auth.env\nchmod 600 ~/.config/pensieve-mcp/auth.env\nmemos stop \u0026\u0026 memos start    # server.py middleware 在启动时读 auth.env\n```\n\n工作原理（端到端）：\n- **服务端**：`patches/server.py.patch`（由 `./scripts/apply-patches.sh` apply，install.sh 自动调）注入了一个 FastAPI middleware——`auth.env` 存在时，任何**非 localhost** 请求若没带 `Authorization: Bearer \u003ctoken\u003e` 直接 401。`127.0.0.1` / `::1` 永远放行（Web UI 不受影响）\n- **客户端**：MCP 读同一个 `auth.env`，调本地 Pensieve 和所有 peer 都带 `Authorization: Bearer \u003ctoken\u003e`\n\n多设备时**每台机器写同一个 token**到各自的 `auth.env`。token 不一致会导致 peer 查询静默失败。\n\n### 升级\n\n上游 Pensieve 发新版时：\n\n```bash\nmemos stop\nuv tool upgrade memos --with \"transformers\u003c5\"\n./scripts/apply-patches.sh        # 重新打三个 site-packages patch\nmemos start\n```\n\n`uv tool upgrade` / `uv tool install --force` 会清掉 site-packages，把鉴权 middleware、电源模式 override、镜像显示器过滤一并吹飞。`apply-patches.sh` 幂等，并且会探测上游飘移——升级后某个 patch apply 失败请开 issue。\n\n随时检查状态：`./scripts/apply-patches.sh --check`。\n\n### 卸载\n\n```bash\n./uninstall.sh\n```\n\n移除 MCP 注册、LaunchAgent，可选卸载 `memos`。`~/.memos/` 数据目录**不会**被删——如果你真的想删，自己 `rm -rf ~/.memos`。\n\n### 常见问题\n\n看 [docs/troubleshooting.md](docs/troubleshooting.md)。最常见的坑：上游没 pin `transformers`，uv 装到 5.x 会把 `/api/search` 搞挂。本套件帮你 pin 好了。\n\n### 致谢\n\n- 上游：[arkohut/pensieve](https://github.com/arkohut/pensieve) — 核心能力（截屏、OCR、embedding、REST API、Web UI）都是它的功劳\n- 本仓库：安装 wrapper + MCP server\n\nLicense: MIT。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyleimc-source%2Fpensieve-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandyleimc-source%2Fpensieve-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyleimc-source%2Fpensieve-mcp/lists"}