Keepfor.me

Keepfor.me

A thin, fast read-it-later and personal library application running entirely on Cloudflare Python Workers, D1 SQLite with FTS5, Vectorize, R2, and the Model Context Protocol (MCP).

---

Features

• Four Core Jobs: Capture, Store, Search, and Share with AI Agents.
• Python Edge Runtime: Powered by FastAPI on Cloudflare Python Workers (Pyodide).
• Installable PWA & Native Sharing: Add to Home screen on Android and iOS. On Android, native Web Share Target integrates directly into the system share sheet. On iOS, 1-tap Apple Shortcuts integrate with the system share sheet using your Safari session, paired with smart clipboard detection in the PWA.
• Distraction-Free Reader: Customizable themes (Light, Sepia, Dark), fonts (Sans, Serif, Mono), and font sizes.
• Hybrid Search: Reciprocal Rank Fusion (RRF) combining D1 FTS5 BM25 keyword matching and Vectorize semantic embeddings (bge-base-en-v1.5). FTS and embedding calls run concurrently, and the vector path is time-bounded so a slow AI binding degrades to keyword-only instead of hanging.
• Resilient Content Extraction: Automated body parsing via trafilatura with OpenGraph metadata fallback so bookmarks are never lost. Browser-identical request headers plus an optional reader-proxy fallback (configurable via READER_PROXY_BASE, off by default) recover many bot-walled (HTTP 403) origins.
• Visible Extraction State: Every item shows Extracting…, content, or a failed reason (e.g. HTTP 403) rather than silently stalling. Bulk imports fan out through the queue, never blocking the request.
• Dual Snapshots in R2: Raw original HTML snapshot (raw.html) and sanitized reader HTML (clean.html).
• Trash, Not Data Loss: Deleting (from the UI or from an agent) moves an item to the Trash instead of destroying it. The row, the snapshots and the vectors stay, so Restore is instant; Delete forever in the Trash view is the only permanent path, and a scheduled purge clears the Trash after 30 days.
• Zero-Config Single-Tenant Lock: First registration automatically claims admin ownership and locks out external signups.
• Model Context Protocol (MCP): Remote Streamable HTTP server at /api/mcp (stateless, Bearer PAT auth) for opencode, Claude Desktop, and Cursor — no local install needed.
• Instant Browser Capture: Drag-and-drop JavaScript bookmarklet and unpacked Manifest V3 extension.
• Import & Export: Ingest Pocket, Instapaper, Omnivore, and browser bookmark exports (Netscape HTML & CSV). Chrome folder names are preserved as tags. Notes import from Google Keep Takeout zips, Evernote `.enex` files, and zips of Markdown/text files (Obsidian vaults, Apple Notes via Exporter, Simplenote): tags and original dates are kept, links inside notes become regular saves, attachments are listed but not stored, and re-imports never duplicate (50 MB cap for zips and .enex, 10 MB for HTML/CSV; inside a zip: 2 MB per file, 200 MB total and 20,000 files, so decompression bombs are refused). Every notes upload keeps a status record with its progress and final counts (notes imported, duplicates skipped, links queued, attachments not imported, parse errors, plan-limit skips) and a capped list of error messages, so the result survives a refresh.
• Mobile-First UI: Bottom tab bar and tag chip strip on phones, ≥32px touch targets, no horizontal overflow down to 360px.

---

Architecture Overview

flowchart LR

Browser["Web UI / PWA / Share Sheet"] -->|FastAPI| Worker["Cloudflare Python Worker"] Claude["Claude Desktop / MCP Agents"] -->|Streamable HTTP + Bearer PAT| Worker

Worker -->|Queries & FTS5| D1[("D1 Database")] Worker -->|Enqueue job| Queue["Cloudflare Queue"] Queue -->|Process batch| Worker Worker -->|Raw & Clean HTML| R2[("R2 Storage")] Worker -->|Embeddings| WAI["Workers AI"] Worker -->|Upsert vectors| Vec[("Vectorize")]

Extraction lifecycle

Saving a URL inserts the row with status='queued' and enqueues a job; the queue consumer fetches, extracts, stores snapshots, and flips it to ok or failed with a reason. Failures are always visible in the UI and reader.

Two deliberate design choices:

• No queue binding → extract inline. Local dev and tests have no queue consumer, so save_item extracts synchronously rather than leaving items stuck in queued forever.
• Bulk imports never run inline. A 900-bookmark import would issue thousands of D1 writes inside one request; instead it fans out as queue messages of 25 bookmarks, or a background task when no queue is bound.

If messages are ever lost, Settings → Re-queue stuck items re-sends jobs for rows stuck in queued (skips fresh rows so live messages aren't duplicated).

Trash and restore

Deleting never destroys. MCP delete_item and DELETE /api/items/{id} set items.deleted_at and stop there: the row, the R2 snapshots and the vector embeddings stay, so an agent cannot destroy library data. Trashed items are invisible everywhere (library, search, MCP reads, counts, exports) until they are restored.

The Trash view (/trash) lists them with two actions: Restore brings an item back into the library, Delete forever is the only permanent delete. Hosts can also run the scheduled cleanup themselves:

from keepfor.models.items import purge_trash

Hard-deletes trashed items older than 30 days (row, snapshots, vectors).

await purge_trash(db, env, user_id=None, older_than_days=30)

A multi-tenant host passes the tenant scope: it carries the R2 prefix

and the Vectorize namespace of the tenant. An unscoped call is refused.

await purge_trash(db, env, user_id=None, older_than_days=30, scope=scope)

Nothing is deleted behind the user's back: without a scheduler the Trash just grows.

Reader Proxy Fallback (READER_PROXY_BASE)

By default, Keepfor.me does not route failed fetches to any third-party service. When an origin rejects a direct fetch (HTTP 403, 429, 530), the item is recorded as failed.

To opt in to reader proxy fallback (e.g. using Jina Reader or a self-hosted readability proxy):

• Configure READER_PROXY_BASE in wrangler.jsonc (vars.READER_PROXY_BASE = "https://r.jina.ai/") or in .dev.vars.
• Privacy Notice: When enabled, blocked article URLs will be transmitted to the configured proxy service. Private IP ranges (e.g., 127.0.0.1, 10.0.0.0/8, 192.168.0.0/16) and local domains are strictly blocked by SSRF egress policy and are never forwarded to any reader proxy.

For full guidance on private / offline deployments and egress policies, see docs/self-hosting.md.

---

Deployment

1. Prerequisites

• Node.js 20 or newer and npm
• uv 0.12.3 or newer
• Cloudflare account with Workers, D1, R2, Vectorize, and Queues enabled
• Custom domain: keepfor.me (or standard *.workers.dev subdomain)

2. Provision Cloudflare Resources

Run the following commands once to create your D1 database, R2 bucket, Vectorize index, and Queue:

# 1. Create D1 Database

npx wrangler d1 create keepfor-me-db

Copy the returned database_id into wrangler.jsonc

2. Create R2 Bucket

npx wrangler r2 bucket create keepfor-me-bucket

3. Create Vectorize Index (768 dimensions for bge-base-en-v1.5)

npx wrangler vectorize create keepfor-me-index --dimensions=768 --metric=cosine

4. Create Queue

npx wrangler queues create keepfor-me-queue

3. Apply Database Migrations

Apply the initial schema (tables, FTS5 virtual table, indexes):

npx wrangler d1 migrations apply keepfor-me-db --remote

For local testing:

npx wrangler d1 migrations apply keepfor-me-db --local

4. Deploy

Deploys are manual: self-hosters deploy to their own Cloudflare account via pywrangler deploy or GitHub Actions workflow_dispatch (with input confirm: "deploy"). Pushing to main does not auto-deploy.

[!WARNING]

wrangler.jsonc has "remote": true on D1, R2, and Vectorize bindings. Never run local dev against wrangler.jsonc as it interacts directly with remote resources. For local simulation, copy wrangler.local.example.jsonc to wrangler.local.jsonc and run uvx --from workers-py pywrangler dev --config wrangler.local.jsonc.

PyWrangler bundles the Python dependencies declared in pyproject.toml.

# Always dry-run first and check the "Total (N modules)" row: the deploy

hard-fails if the bundle exceeds 64 MiB.

uvx --from workers-py pywrangler deploy --dry-run

uvx --from workers-py pywrangler deploy

A healthy bundle is roughly 52,000 KiB / ~4,500 modules. If .venv-workers/ paths appear in the module table, the build venv is being bundled and the deploy is one dependency bump away from failing.

Once deployed, visit your domain (e.g., https://app.keepfor.me or https://keepfor-me. .workers.dev). The first user to register automatically becomes the admin and locks public registration.

5. Custom Domain

wrangler.jsonc declares a route for app.keepfor.me. Create the DNS record once (Cloudflare dashboard → DNS → Add record):

The Worker route matches before the IP is ever contacted, so the placeholder address is fine. workers_dev is left enabled so the *.workers.dev URL keeps working.

---

Connecting AI Agents (Remote MCP)

Keepfor.me hosts a remote Streamable HTTP MCP server at https://app.keepfor.me/api/mcp, exposing 42 tools for capturing, finding, reading and tagging your library:

1. save_url: Save any webpage to your library.
2. save_urls: Save many webpages to your library in one call, with a status for each URL.
3. save_note: Save a note, snippet or prompt template.
4. search_library: Hybrid search across text and meaning.
5. search_passages: Passage-level search with permanent snapshot URLs.
6. find_item: Look up an item id by title or url (no search, no embeddings).
7. get_item: Read metadata and excerpt by id, url or exact title.
8. read_item: Paginated full-text reading.
9. list_items: Compact paginated browse with sorting and filters.
10. reading_history: What you saved and opened, with date filters.
11. related_items: Items similar to a given item or text.
12. list_tags / create_tag / describe_tag / update_tag / rename_tag / merge_tags / delete_tag: Full tag management.
13. tag_item / tag_items / set_item_tags / retag_by_query: Tagging, in bulk and safely (dry-run by default).
14. bulk_update: Update status, pin and tags on every item matching a filter (dry-run by default).
15. suggest_tags / search_tags / tag_stats / related_tags / tag_cleanup: Tag vocabulary tools.
16. find_cleanup: Read-onl