MemoryStore

Frontend

The client application is a React 19 single-page application built with Vite, wrapped inside Capacitor for native mobile deployment. It uses Tailwind CSS for styling with a typography-driven "editorial dark" design system utilizing the Fraunces serif and Inter sans-serif typefaces. Client-side data caching is implemented via IndexedDB, using time-to-live (TTL) based invalidation to enable instant page loads without server round-trips.

Backend API

The backend runs on Cloudflare Workers, using the Hono web framework. It communicates with:

• Supabase for PostgreSQL database, authentication, and real-time subscriptions
• Cloudflare R2 for object storage (file uploads and thumbnails)
• Upstash Redis for rate limiting and caching
• Google Gemini for AI content processing, embeddings, and chat
• APNs and Firebase Cloud Messaging for push notifications

Cron-triggered background jobs handle push notification campaigns, rate-limit retry, and self-healing of stuck content items.

Save and Enrich

Users can save any URL, rich-text note, or plain text into their library. The platform auto-detects the source (YouTube, Instagram Reels, TikTok, Google Drive, or a general web page) and applies the appropriate processing pipeline. Saved content is enriched with:

• AI-generated summaries and key points
• Full transcripts (for video content from supported platforms)
• Auto-generated thumbnails
• Source metadata (platform, author, duration)

Semantic Search

All saved content is converted into vector embeddings, enabling natural-language search across the entire library. Users can ask questions such as "What was that video about fermentation I saved last month?" and the system surfaces the most semantically relevant items.

Thought Connect

Thought Connect, also referred to as "MCP" (Memory Connect Protocol), is a structured AI-assisted thinking tool that supports ten modes: connect, plan, decide, zoom, brainstorm, learn, troubleshoot, create, reflect, and compare. It pulls relevant saved memories into the conversation, grounding AI responses in the user's personal knowledge base.

Organization

• Groups: Saved items can be organized into named collections.
• Pinned items: Frequently accessed content can be pinned for quick access.
• Archive: Content can be archived rather than permanently deleted.
• Vaults: Private collections with collaborative presence indicators, functioning like shared digital workspaces.

Public Sharing

Users can generate public, read-only links to share collections. The platform also supports an "AI Context" page format — a structured rendering of saved content designed to be consumed by external AI systems.

Third-party Integration

MemoryStore provides several integration pathways:

• Browser Extension: A companion extension, paired via QR code scan, enables saving content directly from the browser.
• MCP Server: A Model Context Protocol server allows ChatGPT and Claude to search and retrieve a user's MemoryStore library during AI conversations. Users authenticate by approving the link from the MemoryStore mobile app.
• Developer Share API: A REST API permits external services to push content into a user's MemoryStore using a user-generated API key.
• iOS Shortcuts: A quick-save endpoint compatible with the Apple Shortcuts app.

Features

• Quick Save: Save any URL instantly with a single click.
• Batch Save: Save up to 20 URLs at once.
• Save with Content Extraction: Extract and save page title, description, full text, screenshots, tags, and notes alongside the URL.
• URL Check (Deduplication): Instantly check if a URL is already saved in your library.
• Recent Saves: View recently saved items directly in the extension popup.
• Group Management: List existing groups and create new ones from the extension.
• Device Management: View all linked extensions and disconnect unused ones.
• Apple Shortcuts Integration: Save content via Apple Shortcuts for iOS automation.

Supported Browsers

The extension supports all major browser platforms:

• Google Chrome (chrome-extension://)
• Safari (safari-web-extension://)

QR Pairing Mechanism

The extension uses a secure QR-based pairing system to link with a user's MemoryStore account:

1. Initialization: The browser extension calls POST /extension/pair/start to receive a pairing ID, a 6-character alphanumeric code, a 32-byte random token, and a QR data URL.
2. Scanning: The user scans the displayed QR code using the MemoryStore mobile app's built-in scanner (or via the device's camera using Universal Links).
3. Authorization: The app calls POST /extension/pair/complete to authorize the pairing on the backend.
4. Polling: The extension polls GET /extension/pair/status until the status changes to authorized.
5. Authentication: Once authorized, the extension authenticates using custom headers X-Extension-User-Id and X-Extension-Pairing-Id, validated against the extension_pairings database table.

Security Details

• Pairing Codes: 6-character alphanumerics with ambiguous characters (0, O, 1, I) excluded to prevent human error.
• Pairing Tokens: 32-byte cryptographically random hex strings, stored as SHA-256 hashes on the server.
• Time-to-Live: Pairing sessions expire after 10 minutes if not completed.
• Replay Protection: A replay guard system prevents the same QR code from being processed multiple times. Handled pairings are stored with a 15-minute TTL and a maximum of 12 entries.
• Status Gates: The backend validates that the pairing status is either authorized or consumed and checks expiry before allowing API access.
• Path Restriction: Extension identity authentication is only allowed on paths starting with /api/extension.

Authentication

• Session Token Model: Cryptographically random 64-hex-character tokens (256-bit) generated via Web Crypto API. Stored as SHA-256 hashes in the database. Valid for 1 year with auto-extension.
• JWT Fallback: Legacy Supabase JWT tokens verified with HS256 algorithm via the jose library. The system is fail-closed — if the JWT secret is not configured, the legacy path is completely disabled.
• Token Transport: Authorization: SessionToken <token> or Authorization: Bearer <token> header, or ms_session cookie (HttpOnly, Secure, SameSite=None).
• Last-Used Debounce: 60-second debounce to reduce database write pressure when tracking token usage.

CSRF and XSS Protection

• Origin Validation: All state-changing requests (POST, PUT, PATCH, DELETE) with an Origin header are validated against a strict allowlist. Blocked origins are logged with [security][origin] prefix.
• Input Sanitization: Regex-based middleware strips <script> tags, inline on* event handlers, javascript: URIs, data:text/html URIs, <iframe>, <object>, <embed>, and <link> tags from all JSON request bodies.
• Secure Headers: hono/secure-headers middleware applies HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, and other security headers globally.
• HTML Entity Escaping: All user-facing text in the MCP widget is HTML-escaped before rendering.

Rate Limiting

MemoryStore implements four layers of rate limiting:

1. Global IP Rate Limiting: 300 requests/minute per IP via Upstash Redis. In-memory fail-closed (60 req/min) when Redis is unavailable.
2. Per-User Rate Limiting: Plan-based limits — Free: 30 req/min, Basic: 60, Pro: 120, Ultimate: 300. Applied to content, chat, and share routes. Writes are cost-tracked (expensive endpoints cost 2x).
3. Auth Endpoint Rate Limiting: Cloudflare Cache API-based distributed rate limiting. OTP send: 3 per email per 5 min, 6 per IP per 5 min. OTP verify: 10 per email per 10 min, 30 per IP per 10 min (brute-force prevention).
4. MCP Tool Rate Limiting: Per-tool token-bucket rate limits — Thought Connect: 12/min, Video Context: 24/min, Search: 60/min, Save: 30/min. Anonymous requests receive 0.25x multiplier.

Input Validation

• Zod Schema Validation: All MCP server inputs are strictly typed with minimum/maximum bounds.
• URL Validation: URLs restricted to http: and https: protocols only, with a maximum length of 2048 characters.
• Email Normalization: Consistent trim().toLowerCase() applied.
• Password Validation: Minimum 6 characters.
• Database Constraints: Check constraints enforce valid status values and guard against invalid data states.

Encryption

• In Transit: All cookies use Secure; HttpOnly; SameSite=None.
• At Rest: Session tokens, ingest API keys, and pairing tokens are stored as SHA-256 hashes, not plaintext.
• End-to-End Encryption: Available on the Ultimate plan. Users can toggle E2E encryption per account.
• Gemini API Key Protection: User-provided API keys stored in a dedicated table, excluded from all API responses.

OAuth Flows

• Google OAuth 2.0: Standard authorization code flow with validated redirect hosts.
• ChatGPT MCP OAuth: Full OAuth 2.0 server with PKCE (Proof Key for Code Exchange). PKCE is mandatory (code_challenge_method: S256 required). Codes are single-use, stored in Durable Objects with automatic expiry.

Database Security

• Row-Level Security (RLS): Enabled on all sensitive tables (chat_messages, persistent_sessions, users view). Policies gate access to auth.uid() = user_id.
• SECURITY DEFINER Functions: All RPC functions use SECURITY DEFINER with SET search_path = public to prevent search path injection attacks.
• Service Role Isolation: Service role keys are strictly validated — anon and publishable keys are rejected with clear errors.

API Key Management

• Ingest API Keys: SHA-256 hashed, validated against database, support for revoked_at timestamp.
• Developer Share API Keys: Format ms_share_live_<random-secret> / ms_share_test_<random-secret>. Hash-only server-side storage with prefix for display. Scoped by user, key, route, and payload hash.
• Idempotency: Full idempotency key implementation using api_idempotency_keys table. Header: X-Idempotency-Key (12-256 chars). Replay returns original response. Same key + different body = 409 Conflict. Auto-TTL: 24 hours.

Additional Security Measures

• Webhook Signature Verification: RevenueCat webhooks use constant-time comparison against expected auth keys.
• Worker Dispatch Guard: Prevents duplicate worker dispatches via database guardrails table + in-memory cooldown (90-second default).
• Sentry PII Protection: beforeSend hook strips authorization, cookie, and x-admin-key headers before sending errors to Sentry.
• Request Tracing: X-Request-ID header on all API responses for traceability.
• Structured Security Logging: [security] prefixed logs for rate limit blocks, auth failures, and origin blocks.
• robots.txt: Disallows all crawlers on the API server.
• Health Endpoint Protection: Protected by X-Health-Secret header or known monitoring user agents.

MCP Tools

• memorystore_search_library: Search the user's library using natural language.
• memorystore_list_recent: List recently saved items.
• memorystore_save_url: Save a URL directly into the user's library.
• memorystore_retrieve_video_context: Retrieve full video transcripts and context.
• memorystore_thought_connect: Use the structured thinking assistant.
• memorystore_account_status: Check account subscription status and quotas.

Authentication Model

The MCP server uses a mobile-first account linking flow:

1. User initiates connection from ChatGPT/Claude.
2. MemoryStore MCP server generates a pairing token.
3. User opens MemoryStore mobile app and approves the link.
4. MCP server exchanges the pairing token for a persistent session.

This flow is designed for a predominantly mobile user base, eliminating the need for traditional desktop OAuth flows.

Authentication

• Header: Authorization: Bearer ms_share_live_xxx
• Keys are user-generated with hash-only server-side storage.

Features

• Idempotency: Idempotency-Key header prevents duplicate saves.
• Scopes: share:write (default). Future: library:read, library:search, groups:read.
• Rate Limits: 60 requests/minute per key, 1000 requests/day per user.
• Error Handling: Structured error codes and responses.