mcp-scraper 0.34.1 → 0.36.0

package/docs/specs/multimodal-image-memory-architecture-spec.md

@@ -0,0 +1,1022 @@
+# Multimodal Image Memory Architecture and Technical Specification
+
+- **Status:** Proposed
+- **Date:** 2026-07-17
+- **Target release:** Incremental, behind feature flags
+- **Primary systems:** MCP Scraper, `mcpscraper-memory-tools`, `mcpscraper-memory-db`, memory Neon, private S3-compatible storage, Jina Embeddings API
+- **Related decision:** `docs/decisions/2026-07-17-private-object-storage-for-multimodal-memory.md`
+
+## 1. Executive summary
+
+MCP Scraper will gain governed image memory: users can save an image discovered by a scraper or supplied by URL/upload, keep the original bytes, organize it by project and folder, embed it with Jina Omni v5, and retrieve it using text or another image.
+
+The architecture preserves the current product boundaries:
+
+- A private S3-compatible bucket stores immutable original and derived image bytes.
+- The memory Neon database is the authoritative source for ownership, vault access, projects, folders, asset state, checksums, quotas, jobs, provenance, and embedding metadata.
+- `mcpscraper-memory-db` owns schema, repositories, object-store contracts, and embedding/index primitives.
+- `mcpscraper-memory-tools` owns authenticated workflows and public tool behavior.
+- MCP Scraper remains the canonical aggregate hosted MCP execution surface and supplies scraper-to-memory handoffs.
+- Image vectors use a new versioned PgVector index. Existing note vectors remain untouched.
+
+The current system is closer to this capability than it appears. MCP Scraper already has blob storage and image-download paths, while the memory database already defaults to `jina-embeddings-v5-omni-small` with 1,024-dimensional vectors. The required work is to add a private governed asset plane and make the Jina adapter genuinely multimodal.
+
+## 2. Goals
+
+1. Persist original image bytes independently from their source URL.
+2. Produce non-reversible image and optional fused image-plus-context embeddings.
+3. Support text-to-image and image-to-image semantic retrieval.
+4. Partition every asset by its owning identity and entitled vault.
+5. Add stable project and folder organization without coupling logical moves to object copies.
+6. Reuse existing memory authentication, sharing, quota, provenance, and aggregate MCP boundaries.
+7. Keep all original objects private and issue only short-lived authorized reads.
+8. Make ingest, embedding, retry, delete, and cleanup durable and observable.
+9. Preserve current text memory behavior and vector indexes during rollout.
+10. Leave an internal path to audio, video, and PDF assets without exposing those modalities in the first public contract.
+
+## 3. Non-goals
+
+- Reconstructing images from embeddings.
+- Automatically saving every image encountered during every scrape.
+- Replacing the current note Smart RAG implementation.
+- Re-embedding all existing notes in the first release.
+- Public image hosting or a public CDN library.
+- Cross-tenant binary deduplication.
+- Arbitrary file storage in the first release.
+- Image generation or editing.
+- Note-level sharing of individual assets in the first release; assets inherit vault access.
+- Self-hosting Jina Omni v5 in the first release.
+
+## 4. Verified current-state constraints
+
+### 4.1 MCP Scraper aggregate service
+
+- `src/api/blob-store.ts` provides local and Vercel Blob implementations.
+- The current Vercel implementation writes with `access: 'public'`; it is appropriate for existing public/temporary artifacts, not private memory assets.
+- `src/api/instagram-routes.ts` already downloads image bytes and writes them through `getBlobStore()`.
+- `src/mcp/report-artifact-offload.ts` already uses owner-prefixed object keys for temporary report artifacts.
+- Public MCP memory execution is routed through the hosted aggregate service; shared memory packages remain implementation sources of truth.
+
+### 4.2 Memory service
+
+- Durable notes, vault entitlements, usage, and provenance live in the memory Neon database.
+- `mcpscraper-memory-db` uses `@mastra/pg` `PgVector` with the current index name `memory`.
+- The configured default embed model is `jina-embeddings-v5-omni-small` with a default dimension of 1,024.
+- The current AI SDK adapter is typed as `EmbeddingModelV2<string>` and sends every request with `task: 'retrieval.passage'`.
+- Current note search embeds queries through that same adapter, so the task mode is not explicitly query-side.
+- Existing vault resolution translates caller-visible handles into owner-qualified physical vaults before data access.
+
+### 4.3 Thorbit Sites reuse pattern
+
+- Thorbit Sites uses `@mastra/s3` as a mounted workspace filesystem.
+- Its Postgres records carry `resource_id` and `project_id` independently of the object filesystem.
+- Its current capture key convention is domain-oriented and must not be copied as a tenant-isolation scheme.
+
+### 4.4 Jina v5 API contract
+
+The current Jina OpenAPI describes `jina-embeddings-v5-omni-small` as accepting:
+
+- text strings or `{ "text": "..." }`;
+- `{ "image": "https://..." }` or `{ "image": "<base64>" }`;
+- fused `{ "content": [{ "text": "..." }, { "image": "..." }] }` groups;
+- `retrieval.query` and `retrieval.passage` task modes;
+- normalized vectors with dimensions up to 1,024;
+- multimodal usage fields including `image_tokens`.
+
+Primary provider references:
+
+- `https://api.jina.ai/openapi.json`
+- `https://jina.ai/models/jina-embeddings-v5-omni-small/`
+- `https://huggingface.co/jinaai/jina-embeddings-v5-omni-small`
+
+### 4.5 Evidence baseline
+
+The design was checked against these authenticated repository snapshots:
+
+| Repository | Commit |
+|---|---|
+| `VilovietaSEO/mcp-scraper` | `b199e838d7ca2b9cf4945b18e84c3607edce925a` |
+| `VilovietaSEO/mcpscraper-memory-tools` | `3acfff6d844290d14af06621578b855d3328a84c` |
+| `VilovietaSEO/mcpscraper-memory-db` | `e22cae478f40b27995cef43357b2e03711b78559` |
+
+Implementation must recheck the active local and deployed revisions before applying migrations because these repositories release independently.
+
+## 5. System ownership
+
+| Concern | Owning system | Reason |
+|---|---|---|
+| User account, billing plan, aggregate API key | MCP Scraper | Existing product control plane |
+| Memory identity, key scopes, vault entitlement, sharing | Memory Neon / memory DB | Existing authorization source of truth |
+| Project, folder, asset, object, job, quota reservation | Memory Neon / memory DB | Must transact with memory authorization and vector lifecycle |
+| Original and derived bytes | Private S3-compatible bucket | Large immutable object workload |
+| Asset embeddings | Versioned PgVector index in memory Neon | Existing semantic retrieval infrastructure |
+| Authenticated asset workflows | `mcpscraper-memory-tools` | Shared by aggregate and standalone memory surfaces |
+| Public aggregate MCP registration and policy | MCP Scraper | Existing canonical execution boundary |
+| Scraper result to asset handoff | MCP Scraper | Has authenticated scraper context and safe-fetch utilities |
+| Standalone memory deployment | Memory service | Direct memory clients must retain parity |
+
+No caller may supply an owner identity, physical vault name, S3 namespace, or object key. Those values are derived from authenticated context.
+
+## 6. High-level architecture
+
+```text
+MCP / web caller
+      |
+      v
+MCP Scraper aggregate auth, billing, tool contract
+      |
+      v
+mcpscraper-memory-tools
+      |
+      +---- authorize identity + logical vault ----------+
+      |                                                   |
+      v                                                   v
+memory Neon                                      private S3-compatible bucket
+projects / folders / assets / objects / jobs     original + sanitized preview
+      |
+      v
+durable embedding worker
+      |
+      +---- signed object read or bounded base64 ----> Jina v5 Omni
+      |                                                   |
+      +<---------------- 1024-d normalized vector --------+
+      |
+      v
+PgVector index: memory_assets_v1
+```
+
+## 7. Tenant and authorization model
+
+### 7.1 Tenant boundary
+
+The canonical tenant is the memory `owner_identity`, not a caller-provided user ID. The existing vault entitlement model remains the authorization boundary:
+
+1. Authenticate the memory key or hosted MCP session.
+2. Resolve the caller-visible vault handle to `{ ownerIdentity, physicalVault }`.
+3. Check the requested operation through the existing FGA/scope implementation.
+4. Load projects, folders, and assets only through predicates containing both `owner_identity` and `physical_vault`.
+5. Build object keys only from the stored opaque namespace and server-generated IDs.
+
+Shared-vault readers may search and read assets in the shared vault. Shared-vault writers may create or mutate assets only if their entitlement grants write. Deletion requires the same destructive/admin rules used by governed memory deletion and must not be inferred from read access.
+
+### 7.2 Opaque object namespace
+
+Raw email addresses or other identity strings must never appear in object keys. Each owner receives an opaque namespace row generated server-side.
+
+```text
+{environment}/tenants/{namespace_id}/objects/{object_id}/original.{ext}
+{environment}/tenants/{namespace_id}/objects/{object_id}/preview.webp
+```
+
+Projects and folders are intentionally absent from physical keys. Renaming or moving a logical asset therefore updates Neon only.
+
+### 7.3 Database enforcement
+
+Repositories must use composite owner/vault predicates on every read and write. Composite foreign keys or equivalent transactional validation must prevent linking:
+
+- a folder to another owner's project;
+- an asset to another owner's folder;
+- an asset to an object in another namespace;
+- an embedding job to an asset outside the same owner.
+
+Application authorization is mandatory even if database RLS is later added. RLS is defense in depth, not a replacement for vault entitlement resolution.
+
+## 8. Object storage design
+
+### 8.1 Bucket policy
+
+- One private bucket per environment is preferred: development, staging, production.
+- Block all public access and ACLs.
+- Use TLS for all requests.
+- Enable provider-managed encryption at rest; use KMS only when compliance or customer contracts justify its operating cost.
+- Enable versioning only if recovery requirements justify retaining overwritten derivatives. Originals are immutable and do not require overwrite-based versioning.
+- Abort incomplete multipart uploads after one day.
+- Lifecycle-delete tombstoned objects after the configured recovery window, default seven days.
+- Do not expose bucket listing to clients.
+
+### 8.2 Asset object-store contract
+
+Add a private asset-specific contract rather than weakening the current public artifact behavior:
+
+```ts
+interface AssetObjectStore {
+  put(input: {
+    key: string
+    body: ReadableStream | Buffer
+    contentType: string
+    contentLength?: number
+    checksumSha256?: string
+  }): Promise<{ key: string; etag?: string; versionId?: string; bytes: number }>
+
+  head(key: string): Promise<{
+    exists: boolean
+    bytes?: number
+    contentType?: string
+    checksumSha256?: string
+    etag?: string
+  }>
+
+  getStream(key: string): Promise<ReadableStream | null>
+  createSignedGetUrl(key: string, expiresInSeconds: number): Promise<string>
+  createSignedPutUrl?(input: SignedPutInput): Promise<SignedPutResult>
+  delete(key: string): Promise<void>
+}
+```
+
+Implementations:
+
+- `S3AssetObjectStore` for production and S3-compatible providers;
+- `LocalAssetObjectStore` for local development and tests;
+- no public Vercel Blob implementation unless it supports private reads and equivalent deletion/head semantics.
+
+### 8.3 Logical versus physical records
+
+Physical objects and logical assets are separate:
+
+- an object is immutable bytes plus checksum and derived variants;
+- an asset is the user's governed record, title, source, vault, project, folder, tags, and lifecycle;
+- deduplication happens within one owner namespace only;
+- multiple logical assets may reference one owner-scoped object.
+
+This avoids cross-project surprises while preventing repeated storage of the same bytes for one owner.
+
+## 9. Neon schema
+
+IDs are generated by the application using opaque prefixed IDs such as `ans_`, `apr_`, `afl_`, `aob_`, `ast_`, and `aej_`. Timestamps are UTC.
+
+### 9.1 `mem_asset_namespaces`
+
+| Column | Type | Rules |
+|---|---|---|
+| `owner_identity` | text | primary key |
+| `namespace_id` | text | unique, opaque, immutable |
+| `used_bytes` | bigint | nonnegative cached counter |
+| `reserved_bytes` | bigint | nonnegative active upload reservations |
+| `created_at` | timestamptz | default now |
+| `updated_at` | timestamptz | default now |
+
+The byte counters support atomic quota admission and are periodically reconciled from authoritative object rows.
+
+### 9.2 `mem_asset_projects`
+
+| Column | Type | Rules |
+|---|---|---|
+| `id` | text | primary key |
+| `owner_identity` | text | required |
+| `vault` | text | owner-qualified physical vault, required |
+| `name` | text | 1-120 characters |
+| `description` | text | nullable, max 2,000 |
+| `status` | text | `active`, `archived`, `deleted` |
+| `created_by` | text | authenticated identity |
+| `created_at`, `updated_at` | timestamptz | required |
+| `deleted_at` | timestamptz | nullable |
+
+Unique active project name per `(owner_identity, vault, lower(name))`.
+
+### 9.3 `mem_asset_folders`
+
+| Column | Type | Rules |
+|---|---|---|
+| `id` | text | primary key |
+| `owner_identity` | text | required |
+| `vault` | text | required |
+| `project_id` | text | required, owner/vault scoped |
+| `parent_id` | text | nullable self-reference |
+| `name` | text | 1-120 characters |
+| `created_at`, `updated_at` | timestamptz | required |
+| `deleted_at` | timestamptz | nullable |
+
+Folder depth is capped at eight. Folder cycles are rejected transactionally. Names are unique among active siblings. Folder paths are computed for presentation and never used as object keys.
+
+### 9.4 `mem_asset_objects`
+
+| Column | Type | Rules |
+|---|---|---|
+| `id` | text | primary key |
+| `owner_identity` | text | required |
+| `namespace_id` | text | required |
+| `sha256` | text | lowercase hex, required |
+| `storage_key` | text | unique, server-generated |
+| `preview_storage_key` | text | nullable |
+| `mime_type` | text | validated MIME |
+| `extension` | text | normalized extension |
+| `bytes` | bigint | positive |
+| `width`, `height` | integer | positive |
+| `etag`, `version_id` | text | nullable provider receipts |
+| `status` | text | `pending`, `available`, `quarantined`, `deleting`, `deleted` |
+| `created_at`, `updated_at`, `deleted_at` | timestamptz | lifecycle timestamps |
+
+Unique `(owner_identity, sha256)` for active/available objects. Never deduplicate across owners.
+
+### 9.5 `mem_assets`
+
+| Column | Type | Rules |
+|---|---|---|
+| `id` | text | primary key |
+| `owner_identity` | text | required |
+| `vault` | text | owner-qualified physical vault |
+| `project_id` | text | nullable for Unfiled |
+| `folder_id` | text | nullable |
+| `object_id` | text | required |
+| `media_kind` | text | `image` in v1 |
+| `title` | text | 1-240 characters |
+| `description` | text | nullable |
+| `alt_text` | text | nullable |
+| `source_url` | text | nullable, normalized |
+| `source_kind` | text | `upload`, `scrape`, `screenshot`, `instagram`, `external_url`, `import` |
+| `source_ref` | jsonb | bounded provenance, no secrets |
+| `tags` | jsonb | canonical string array |
+| `metadata` | jsonb | bounded non-secret metadata |
+| `status` | text | `processing`, `ready`, `failed`, `deleting`, `deleted` |
+| `embedding_status` | text | `pending`, `running`, `ready`, `partial`, `failed` |
+| `failure_code`, `failure_message` | text | bounded, nullable |
+| `created_by`, `updated_by` | text | authenticated identity |
+| `created_at`, `updated_at`, `deleted_at` | timestamptz | lifecycle timestamps |
+
+Indexes:
+
+- `(owner_identity, vault, status, created_at desc)`;
+- `(owner_identity, project_id, folder_id, created_at desc)`;
+- GIN on `tags` only if observed query volume justifies it;
+- source URL hash for idempotent scraper handoffs.
+
+### 9.6 `mem_asset_embedding_jobs`
+
+| Column | Type | Rules |
+|---|---|---|
+| `id` | text | primary key |
+| `asset_id` | text | required |
+| `owner_identity` | text | required |
+| `representation` | text | `visual` or `fused` |
+| `model` | text | required |
+| `dimensions` | integer | required |
+| `status` | text | `queued`, `running`, `retry`, `done`, `failed`, `cancelled` |
+| `attempts` | integer | nonnegative |
+| `max_attempts` | integer | default 5 |
+| `run_after` | timestamptz | retry scheduling |
+| `lease_owner` | text | nullable |
+| `lease_until` | timestamptz | nullable |
+| `last_error_code`, `last_error` | text | bounded |
+| `usage` | jsonb | text/image/total token counts |
+| `created_at`, `updated_at`, `completed_at` | timestamptz | lifecycle timestamps |
+
+Unique active job per `(asset_id, representation, model, dimensions)`.
+
+### 9.7 `mem_asset_upload_reservations`
+
+Records bounded upload reservations with owner, expected bytes, expiry, idempotency key, and status. Finalization locks the owner namespace, validates quota against `used_bytes + reserved_bytes`, converts the reservation into used bytes, and creates or reuses the object row.
+
+Expired reservations release bytes automatically.
+
+## 10. Vector index
+
+### 10.1 Index contract
+
+```text
+index name: memory_assets_v1
+dimension: 1024
+distance: cosine
+normalization: true
+model: jina-embeddings-v5-omni-small
+document task: retrieval.passage
+query task: retrieval.query
+```
+
+The index name is versioned because model, dimensions, normalization, representations, or metadata contracts may change.
+
+### 10.2 Vector IDs and metadata
+
+Vector ID:
+
+```text
+sha256("asset-v1::{asset_id}::{representation}::{model}::{dimensions}")
+```
+
+Required metadata:
+
+```json
+{
+  "assetId": "ast_...",
+  "objectId": "aob_...",
+  "ownerIdentity": "owner-qualified internal identity",
+  "vault": "owner-qualified physical vault",
+  "projectId": "apr_... or null",
+  "folderId": "afl_... or null",
+  "representation": "visual",
+  "model": "jina-embeddings-v5-omni-small",
+  "dimensions": 1024,
+  "mimeType": "image/jpeg",
+  "sourceKind": "scrape",
+  "createdAt": "ISO-8601"
+}
+```
+
+Search authorization is derived before querying. Vector filters receive only entitled physical vaults and optional authorized project/folder IDs. Results are reloaded from Neon by asset ID under the same owner/vault predicates before they are returned. Vector metadata alone is never accepted as authorization proof.
+
+### 10.3 Representations
+
+V1 supports at most two vectors per asset:
+
+1. `visual`: the sanitized image only.
+2. `fused`: ordered image plus bounded title, alt text, description, and source context when meaningful text exists.
+
+The visual vector preserves image-to-image similarity. The fused vector improves text retrieval for screenshots, products, charts, and page imagery. Results from both representations are fused by asset ID so one asset is returned once.
+
+## 11. Jina embedding adapter
+
+Do not overload the current string-only AI SDK adapter with ambiguous task selection. Add a direct typed multimodal client:
+
+```ts
+type JinaInput =
+  | string
+  | { text: string }
+  | { image: string }
+  | { content: Array<{ text: string } | { image: string }> }
+
+embedJina(input: {
+  values: JinaInput[]
+  task: 'retrieval.query' | 'retrieval.passage'
+  model?: string
+  dimensions?: number
+  signal?: AbortSignal
+}): Promise<{
+  embeddings: number[][]
+  usage: {
+    totalTokens: number
+    promptTokens: number
+    imageTokens: number
+  }
+}>
+```
+
+Requirements:
+
+- validate exactly one 1,024-dimensional finite vector per input;
+- require L2 normalization from the provider and reject malformed vectors;
+- rotate existing Jina key pool on retryable errors;
+- retry 429, 524, and transient 5xx with capped exponential backoff and jitter;
+- do not retry validation, authentication, or unsupported-media errors;
+- record model, dimension, task, representation, usage, latency, and request ID without logging image bytes or signed URLs;
+- use a signed object URL with a five-minute lifetime by default;
+- support bounded base64 as a fallback when provider URL fetch fails;
+- never send the original source URL when a durable private object exists.
+
+The existing note adapter remains unchanged in the first asset release. Correcting query-side task selection for note Smart RAG is a separate measured migration because it can change ranking behavior.
+
+## 12. Ingestion pipeline
+
+### 12.1 Accepted inputs
+
+- HTTPS public image URL;
+- image URL returned by an MCP Scraper tool;
+- existing authorized MCP Scraper artifact reference;
+- direct web upload through presigned upload initiation/finalization;
+- bounded base64 only for MCP clients without an upload transport.
+
+Saving images is opt-in. Existing scrape tools must not automatically persist every discovered image.
+
+### 12.2 Validation limits
+
+Defaults are configuration constants, not caller-controlled values:
+
+- maximum original size: 20 MiB;
+- maximum redirect count: 5;
+- fetch timeout: 60 seconds;
+- supported v1 MIME: JPEG, PNG, WebP, and GIF;
+- GIF embeds the sanitized first frame while retaining the original;
+- maximum decoded pixels: 40 million;
+- maximum preview edge: 2,048 pixels;
+- reject SVG, HEIC, TIFF, archives, HTML, polyglots, and unknown MIME in v1;
+- sniff bytes and decode the image; do not trust filename or `Content-Type` alone;
+- revalidate every redirect against the public-URL/SSRF policy;
+- reject loopback, link-local, private, metadata-service, and non-HTTP(S) destinations.
+
+Use `sharp` or an equivalent bounded decoder to auto-orient, strip metadata, flatten unsafe animation behavior, and produce a WebP preview. Store the original unchanged and embed the sanitized derivative.
+
+### 12.3 Save flow
+
+1. Authenticate and resolve writable physical vault.
+2. Validate project and folder under the same owner/vault.
+3. Create an idempotent upload reservation.
+4. Fetch or receive bytes with streaming size enforcement.
+5. Sniff MIME, decode safely, compute SHA-256, dimensions, and sanitized preview.
+6. Lock the owner namespace and enforce quota.
+7. Reuse an existing owner-scoped object with the same SHA-256 or upload new immutable objects.
+8. Create the logical asset row with `status=processing`.
+9. Commit the database transaction and enqueue visual and optional fused jobs.
+10. Return immediately with asset ID and `embeddingStatus=pending`.
+11. Worker embeds representations and upserts vectors.
+12. Mark the asset `ready`, `partial`, or `failed` according to representation outcomes.
+
+Object upload and database commit cannot be one distributed transaction. Any upload that succeeds before a failed DB commit is tagged as an orphan candidate and removed by reconciliation after a safety window.
+
+### 12.4 Idempotency
+
+`image_asset_save` accepts an optional idempotency key. The unique key is scoped to authenticated owner plus operation. Repeating a completed request returns the same asset. Concurrent requests for identical bytes may converge on one owner-scoped object but may create distinct logical assets only when their idempotency keys differ.
+
+## 13. Embedding worker
+
+Use the existing durable Postgres worker pattern rather than an in-memory queue.
+
+### 13.1 Claiming
+
+- atomically claim eligible queued/retry jobs;
+- set a unique lease owner and expiration;
+- heartbeat long operations;
+- allow expired leases to be reclaimed;
+- cap attempts at five;
+- cancel jobs when the asset enters deletion.
+
+### 13.2 Execution
+
+1. Reload asset and object with owner predicates.
+2. Refuse deleted, quarantined, or unavailable objects.
+3. Produce a signed preview URL or bounded base64 payload.
+4. Build visual or fused Jina input.
+5. Call `embedJina` with `retrieval.passage`.
+6. Validate the vector.
+7. Upsert the vector with versioned metadata.
+8. Record Jina usage in `mem_usage_ledger` with source `embed_image`.
+9. Mark the job complete and reconcile aggregate asset embedding status.
+
+### 13.3 Failure policy
+
+| Failure | Action |
+|---|---|
+| 429, 524, transient 5xx, timeout | retry with backoff |
+| expired signed URL | refresh once within the same attempt |
+| provider cannot fetch URL | retry once using bounded base64 |
+| invalid or unsupported image | permanent failure, quarantine if validation missed it |
+| invalid vector length/non-finite values | permanent provider-contract failure and alert |
+| asset deleted during work | cancel and remove any newly written vectors |
+
+One failed optional fused representation yields `partial`; a failed visual representation yields `failed` because visual is required.
+
+## 14. Search and retrieval
+
+### 14.1 Query modes
+
+- text-to-image: embed query text with `retrieval.query`;
+- image-to-image: embed an authorized stored asset or validated temporary image with `retrieval.query`;
+- fused query: optional text plus image encoded as one query vector;
+- exact filtering without embedding: project, folder, tag, source kind, source host, MIME, and date.
+
+### 14.2 Retrieval flow
+
+1. Authenticate and resolve readable vaults.
+2. Validate project/folder filters against those vaults.
+3. Embed the query with `retrieval.query` unless exact-list mode is requested.
+4. Query `memory_assets_v1` with entitled physical-vault filters.
+5. Overfetch up to 50 representation hits.
+6. Fuse visual and fused hits by asset ID using reciprocal-rank fusion plus vector score.
+7. Reload candidate assets from Neon under authorization predicates.
+8. Apply exact metadata filters and remove deleted/not-ready rows.
+9. Optionally rerank using bounded textual metadata; multimodal reranking with `jina-reranker-m0` is a later gated enhancement.
+10. Return at most 30 compact asset results.
+
+### 14.3 Unified memory search
+
+Do not change `memory-search` defaults in the first release. Introduce asset search separately. After relevance evaluation:
+
+- add `includeAssets?: boolean`, default `false`;
+- query notes and assets independently;
+- fuse only at the final result layer;
+- preserve result modality and provenance;
+- never pretend an asset is a note or place binary data in note text.
+
+## 15. Public MCP contract
+
+Canonical public IDs use the product's generated tool naming convention; generated stdio/MCPB schemas must remain in parity with hosted execution.
+
+### 15.1 Initial tools
+
+| Tool | Purpose | Side effect |
+|---|---|---|
+| `image_project_create` | Create a stable image project in a writable vault | creates project |
+| `image_project_list` | List accessible projects | read-only |
+| `image_folder_create` | Create a nested folder in a project | creates folder |
+| `image_folder_list` | List project folder tree | read-only |
+| `image_asset_save` | Save URL/artifact/base64 image and queue embedding | stores bytes, consumes quota/provider usage |
+| `image_asset_get` | Read authorized metadata and optional short-lived preview link | read-only except access log |
+| `image_asset_list` | Exact project/folder/tag/date listing | read-only |
+| `image_asset_search` | Text/image semantic retrieval with filters | consumes embedding usage |
+| `image_asset_move` | Change project/folder placement without copying bytes | updates metadata |
+| `image_asset_delete` | Soft-delete, then purge vectors/object when unreferenced | destructive |
+
+Project and folder deletion are separate destructive tools only if product UI needs them in the first release. A project with active assets cannot be hard-deleted; archive is the default.
+
+### 15.2 `image_asset_save` input
+
+Exactly one source:
+
+```json
+{
+  "vault": "Library",
+  "projectId": "apr_...",
+  "folderId": "afl_...",
+  "sourceUrl": "https://example.com/image.jpg",
+  "artifactId": null,
+  "imageBase64": null,
+  "title": "Pricing table screenshot",
+  "description": "Optional retrieval context",
+  "altText": "Optional source alt text",
+  "tags": ["pricing", "competitor"],
+  "sourceRef": { "pageUrl": "https://example.com/pricing" },
+  "idempotencyKey": "caller-stable-key"
+}
+```
+
+The schema must use a discriminated union or a strict post-parse refinement so multiple sources are rejected.
+
+### 15.3 Search result
+
+```json
+{
+  "assetId": "ast_...",
+  "title": "Pricing table screenshot",
+  "mimeType": "image/webp",
+  "width": 1440,
+  "height": 900,
+  "projectId": "apr_...",
+  "folderId": "afl_...",
+  "sourceUrl": "https://example.com/pricing",
+  "score": 0.84,
+  "matchRepresentations": ["visual", "fused"],
+  "embeddingModel": "jina-embeddings-v5-omni-small",
+  "preview": {
+    "url": "short-lived authorized URL",
+    "expiresAt": "ISO-8601"
+  }
+}
+```
+
+Preview URLs are optional and short-lived. Persistent records store object keys, never signed URLs.
+
+## 16. Existing scraper integrations
+
+Add explicit save handoffs after the core asset tools are stable:
+
+- screenshots;
+- Instagram image downloads;
+- Facebook and Google ad image URLs;
+- site-audit image inventory;
+- browser screenshots;
+- extracted page image links.
+
+Default behavior remains unchanged. Callers either invoke `image_asset_save` with a returned URL/artifact or set an explicit save option where a compound workflow justifies it.
+
+Existing public/temporary blobs may be imported by server-side artifact reference. The importer must authenticate artifact ownership before reading it; it must not trust a caller-supplied blob URL.
+
+## 17. Quota, usage, and billing
+
+### 17.1 Storage quota
+
+Storage usage equals:
+
+```text
+note content bytes
++ note vector bytes
++ owner-scoped asset object bytes
++ derived preview bytes
++ asset vector bytes
+```
+
+Shared assets count against the owner, not each grantee. Deduplicated objects are counted once. Soft-deleted assets continue to count until the object is purged or no active references remain.
+
+### 17.2 Admission control
+
+- Reserve declared bytes before accepting an upload.
+- Reject when `used + reserved + requested > plan quota`.
+- Finalize against actual bytes.
+- Release unused reservation bytes.
+- Reconcile namespace counters from object rows daily and on operator request.
+
+### 17.3 Provider metering
+
+Record Jina `total_tokens`, `prompt_tokens`, and `image_tokens`. Use source names `embed_image_document`, `embed_image_query`, and later `rerank_image`. Pricing must be derived from the current rate table, not hard-coded in tools.
+
+## 18. Deletion and retention
+
+### 18.1 Asset deletion
+
+1. Require destructive scope and vault write/delete authority.
+2. Mark the logical asset `deleting` and cancel queued jobs.
+3. Delete all asset vectors.
+4. Mark the asset `deleted` with audit provenance.
+5. If no active logical asset references the object, mark the object `deleting`.
+6. Delete original and preview objects asynchronously.
+7. Decrement namespace used bytes and mark the object `deleted`.
+
+Retries are idempotent. A failed object deletion remains visible to the cleanup worker but never restores caller access.
+
+### 18.2 Project/folder deletion
+
+- Folders with assets must be moved or recursively deleted explicitly.
+- Project archive is non-destructive.
+- Project deletion requires an explicit recursive flag and a dry-run count/byte summary or a separate confirmation contract.
+
+### 18.3 Orphan reconciliation
+
+Scheduled reconciliation finds:
+
+- S3 objects with no available object row after the orphan safety window;
+- object rows whose S3 object is missing;
+- ready assets without required visual vectors;
+- vectors whose asset row is deleted or missing;
+- expired upload reservations;
+- stale leased jobs.
+
+## 19. Security requirements
+
+- Private bucket with no anonymous reads.
+- Short-lived signed GET URLs, default five minutes.
+- Signed PUTs are bound to exact key, content type, maximum length where supported, and short expiry.
+- All keys are server-generated and contain opaque tenant namespaces.
+- SSRF-safe URL fetch with redirect revalidation and DNS/IP checks.
+- MIME sniffing and bounded image decode before availability.
+- No SVG in v1; no active content served inline.
+- Response headers for previews use safe content types and `Content-Disposition` where appropriate.
+- Never log object bytes, base64, signed URLs, credentials, or private customer metadata.
+- Jina requests use the durable sanitized object, not an arbitrary unverified source URL.
+- Provider processing and retention terms require a production/legal check before launch.
+- The Hugging Face open-weight license must not be treated as permission for commercial self-hosting; managed API terms govern the initial deployment.
+
+## 20. Reliability and consistency
+
+### 20.1 Source of truth
+
+Neon rows are authoritative for existence and authorization. S3 is authoritative for bytes. PgVector is a rebuildable derived index.
+
+### 20.2 State invariants
+
+- `ready` asset implies an available object and a completed visual embedding.
+- `embedding_status=ready` implies all requested representations exist.
+- search never returns non-ready or deleted assets.
+- object deletion happens only after the last active logical reference is gone.
+- signed URLs are never persisted.
+- vectors can be deleted/rebuilt without losing the original asset.
+
+### 20.3 Recovery
+
+- Re-embedding is driven from asset/object rows, not source URLs.
+- Index rebuild writes to a new versioned index, verifies counts/recall, then switches an environment alias.
+- Object-store outage blocks new ingest and signed reads but does not corrupt metadata.
+- Jina outage leaves assets in retryable processing state; originals remain durable.
+
+## 21. Observability
+
+Metrics:
+
+- assets saved/ready/failed/deleted by source kind;
+- bytes uploaded, deduplicated, and purged;
+- upload reservation failures and quota rejections;
+- validation failures by code;
+- embedding latency, retries, token usage, and failure rate;
+- job queue depth, oldest age, stale leases, and terminal failures;
+- search latency, candidate counts, vector hit rate, and zero-result rate;
+- orphan and drift reconciliation counts;
+- signed-read issuance and denied access counts.
+
+Structured logs include request ID, asset ID, owner namespace ID, job ID, model, task, representation, and bounded error code. Do not log raw owner identity where a stable opaque namespace suffices.
+
+Provenance operations:
+
+```text
+asset_project_create
+asset_folder_create
+asset_save
+asset_embed
+asset_search
+asset_move
+asset_delete
+asset_object_purge
+asset_reconcile
+```
+
+## 22. Configuration
+
+```text
+ASSET_STORAGE_PROVIDER=s3|local
+ASSET_S3_BUCKET=
+ASSET_S3_REGION=
+ASSET_S3_ENDPOINT=                 # optional for S3-compatible providers
+ASSET_S3_ACCESS_KEY_ID=
+ASSET_S3_SECRET_ACCESS_KEY=
+ASSET_S3_FORCE_PATH_STYLE=false
+ASSET_STORAGE_ENV_PREFIX=production
+ASSET_SIGNED_GET_TTL_SECONDS=300
+ASSET_SIGNED_PUT_TTL_SECONDS=900
+ASSET_MAX_BYTES=20971520
+ASSET_MAX_DECODED_PIXELS=40000000
+ASSET_PREVIEW_MAX_EDGE=2048
+ASSET_DELETE_GRACE_HOURS=168
+ASSET_EMBED_INDEX=memory_assets_v1
+ASSET_EMBED_MODEL=jina-embeddings-v5-omni-small
+ASSET_EMBED_DIM=1024
+ASSET_EMBED_WORKER_CONCURRENCY=
+ASSET_FEATURE_ENABLED=false
+ASSET_SEARCH_ENABLED=false
+```
+
+Prefer workload identity or platform-managed credentials over long-lived access keys when the deployment provider supports it. Never expose these variables to browser bundles.
+
+## 23. Release and compatibility plan
+
+### Phase 0: provider and storage proof
+
+- Verify Jina v5 text-query, image-document, image-query, and fused inputs with non-sensitive fixtures.
+- Verify 1,024 dimensions, normalization, usage fields, latency, and retry semantics.
+- Verify private S3 put/head/signed-get/delete and local parity.
+- Confirm managed API commercial and retention terms.
+
+Exit: repeatable integration tests and no public object exposure.
+
+### Phase 1: schema and internal asset plane
+
+- Release memory DB schema/repositories and object-store contract.
+- Add project/folder/object/asset/job state machines.
+- Add quota reservations and reconciliation.
+- Keep public feature flag off.
+
+Exit: migration, repository tests, and destructive cleanup tests pass.
+
+### Phase 2: embedding and standalone tools
+
+- Add multimodal Jina client and worker.
+- Add asset tools to memory tools.
+- Add separate asset vector index and search.
+- Deploy and verify standalone memory service.
+
+Exit: authorized text-to-image and image-to-image live smoke pass; cross-tenant tests deny access.
+
+### Phase 3: aggregate MCP cutover
+
+- Update MCP Scraper package dependencies.
+- Register generated schemas and hosted cutovers.
+- Regenerate manifests, MCPB, SDK contracts, and docs.
+- Verify hosted, stdio, and MCPB parity.
+
+Exit: aggregate hosted MCP and direct memory MCP return the same contract.
+
+### Phase 4: scraper handoffs and product UI
+
+- Add opt-in save actions to selected image-producing tools.
+- Add project/folder browser and image search UI.
+- Add storage/usage visibility.
+
+Exit: end-to-end save from a real scraper result, async embed, search, signed preview, move, and delete.
+
+### Phase 5: optional unified Smart RAG
+
+- Evaluate `memory-search includeAssets` relevance.
+- Evaluate multimodal reranking.
+- Consider a fully re-embedded unified note/asset index only with migration and rollback proof.
+
+## 24. Test specification
+
+### 24.1 Unit
+
+- object-key generation never contains identity, filename, project name, or folder name;
+- source union rejects zero or multiple sources;
+- URL validation blocks private/metadata hosts and unsafe redirects;
+- MIME sniffing rejects mismatches and decompression bombs;
+- quota reservation/finalization/release arithmetic;
+- folder depth, cycles, sibling uniqueness, and cross-owner links;
+- Jina request shape for visual, fused, query, and passage tasks;
+- vector validation rejects wrong dimensions and non-finite values;
+- search fusion deduplicates representations by asset;
+- signed URLs are omitted from persisted records and logs.
+
+### 24.2 Database integration
+
+- owner A cannot read/write/move/delete owner B assets;
+- shared-vault read and write entitlements behave correctly;
+- project/folder/object composite ownership is enforced;
+- identical owner checksum reuses object; different owners do not;
+- concurrent quota reservations cannot oversubscribe;
+- lease expiry and job reclaim are safe;
+- deletion removes vectors and purges only unreferenced objects;
+- storage usage counts objects and vectors once.
+
+### 24.3 Provider integration
+
+- text query retrieves relevant fixture image;
+- fixture image retrieves itself and a visually similar fixture;
+- fused context improves a text-specific retrieval fixture without destroying visual recall;
+- signed URL and base64 fallback produce compatible normalized vectors;
+- recorded token usage matches response fields.
+
+### 24.4 MCP contract
+
+- tool schemas are strict and generated outputs validate;
+- destructive annotations are correct;
+- hosted, stdio, MCPB, standalone memory, and generated SDK schemas match;
+- responses stay bounded and never inline original image bytes by default;
+- expired preview links can be refreshed through an authorized read.
+
+### 24.5 Live end-to-end
+
+1. Save a public test image into a project/folder.
+2. Poll until embedding is ready.
+3. Retrieve it with a natural-language query.
+4. Retrieve it using a second similar image.
+5. Open the signed preview and verify private-bucket behavior after expiry.
+6. Move it to another folder without changing object key.
+7. Verify another user cannot discover metadata, vector hit, or object.
+8. Delete it and verify vector removal and eventual object purge.
+
+## 25. Acceptance criteria
+
+- Original bytes survive source URL removal.
+- No production asset object is anonymously readable.
+- Every asset access is authorized through existing memory identity/vault rules.
+- Object keys use opaque namespaces and server-generated IDs.
+- A project/folder move performs no S3 copy.
+- Text and image queries return relevant stored images from `memory_assets_v1`.
+- Existing note search behavior and the `memory` index remain unchanged in the first release.
+- Failed embeddings are retryable without re-uploading originals.
+- Quota accounting includes original, preview, and vector bytes.
+- Delete is idempotent and removes vectors before object purge.
+- Hosted MCP Scraper and standalone memory contracts remain in parity.
+- Cross-tenant, SSRF, MIME, quota-race, stale-job, and orphan-cleanup tests pass.
+
+## 26. Implementation slices
+
+1. **Asset storage contract:** S3/local private implementations, object-key builder, signed reads, delete/head operations.
+2. **Memory DB schema:** namespaces, projects, folders, objects, assets, reservations, jobs, repositories, migrations.
+3. **Multimodal Jina client:** typed request shapes, task separation, usage, retry, validation.
+4. **Ingest pipeline:** safe fetch/upload, decode, checksum, preview, dedupe, quota, idempotency.
+5. **Embedding worker:** leasing, visual/fused representations, versioned vector index, recovery.
+6. **Asset retrieval:** authorized list/get/search, fusion, signed previews, provenance.
+7. **Memory tools:** strict public schemas, project/folder/asset tools, standalone registration.
+8. **Aggregate MCP integration:** dependency updates, cutovers, generated manifests/SDK/MCPB parity.
+9. **Scraper handoffs:** explicit import from screenshots, Instagram, ad images, and audit inventories.
+10. **Operations:** metrics, reconciliation, quota display, cleanup, runbooks, live proof.
+
+Each slice requires paired tests. Public feature flags remain off until slices 1-8 and the cross-tenant live proof are complete.
+
+## 27. Open decisions requiring implementation-time confirmation
+
+These do not block the architecture but must be resolved with evidence before launch:
+
+1. Which S3-compatible provider and region will be the production object store.
+2. Whether provider workload identity is available or scoped access keys are required.
+3. Whether a five-minute Jina-fetchable signed URL is reliable enough or base64 should be the primary transport.
+4. Exact image-token pricing and plan margin thresholds.
+5. Whether projects are always vault-local or the UI needs one project spanning multiple vaults. This specification chooses vault-local projects.
+6. Whether `jina-reranker-m0` materially improves image retrieval enough to justify a second provider call.
+7. Whether soft-delete recovery is exposed to users or remains an internal seven-day cleanup window.
+
+Until changed by an accepted decision, the defaults in this specification govern implementation.
+
+## 28. Expected file-level implementation map
+
+Exact filenames may follow repository conventions, but ownership must remain as follows.
+
+### `mcpscraper-memory-db`
+
+```text
+src/db/schema.ts                         additive asset tables and indexes
+src/db/assets.ts                         owner/vault-scoped asset repositories
+src/db/asset-projects.ts                 project and folder repositories
+src/db/asset-jobs.ts                     leasing, retry, and reconciliation
+src/storage/asset-object-store.ts        provider-neutral private contract
+src/storage/s3-asset-object-store.ts     production S3-compatible adapter
+src/storage/local-asset-object-store.ts  local/test adapter
+src/rag/multimodal-embedder.ts           typed Jina v5 client
+src/rag/asset-vector-store.ts            memory_assets_v1 index operations
+src/rag/asset-search.ts                  authorized vector query primitives
+```
+
+### `mcpscraper-memory-tools`
+
+```text
+src/tools/assets/project-create.ts
+src/tools/assets/project-list.ts
+src/tools/assets/folder-create.ts
+src/tools/assets/folder-list.ts
+src/tools/assets/asset-save.ts
+src/tools/assets/asset-get.ts
+src/tools/assets/asset-list.ts
+src/tools/assets/asset-search.ts
+src/tools/assets/asset-move.ts
+src/tools/assets/asset-delete.ts
+src/lib/asset-ingest.ts                   validation and save orchestration
+src/lib/asset-access.ts                   entitlement-to-owner/vault resolution
+```
+
+The standalone memory server registers these tools from the shared package and runs the durable embedding/cleanup worker or invokes a dedicated worker process using the same DB package.
+
+### `mcp-scraper`
+
+```text
+src/mcp/memory-tool-schemas.ts            generated aggregate schemas
+src/mcp/memory-cutover/reads.ts           read/search cutovers
+src/mcp/memory-cutover/writes.ts          save/move/delete cutovers
+src/mcp/mcp-tool-schemas.ts               aggregate registration as generated
+src/api/asset-import.ts                    owned scraper-artifact handoff
+scripts/generate-mcp-tool-manifest.ts      regenerated contracts
+docs/mcp-tool-manifest.generated.json      generated output
+```
+
+Do not place private asset storage inside `src/api/blob-store.ts` by merely changing its current public behavior. Existing report and social-media artifact callers depend on that abstraction. Either leave it intact or refactor behind explicit public-artifact and private-asset interfaces with compatibility tests.