@cerefox/memory 1.18.0 → 1.19.1

package/dist/server-assets/db/schema.sql

@@ -5,7 +5,7 @@
 -- Requires extensions: vector (pgvector), uuid-ossp
 -- These are enabled at the top of db_deploy.py before this file is applied.
 --
--- @version: 0.19.0
+-- @version: 0.21.1
 -- The `@version` marker above is read by the schema-version-mismatch banner
 -- (see /api/v1/schema-version). Bump it whenever schema.sql OR rpcs.sql
 -- changes in a way that requires `cerefox server deploy` to be re-run —
@@ -40,7 +40,9 @@ CREATE TABLE IF NOT EXISTS cerefox_documents (
     source          TEXT        NOT NULL DEFAULT 'manual',
     -- source values: 'file' | 'paste' | 'agent' | 'url' | 'manual'
     source_path     TEXT,
-    -- SHA-256 of raw markdown content; used for deduplication
+    -- SHA-256 of raw markdown content: the optimistic-concurrency token, and
+    -- the create-time duplicate check (live documents only, in
+    -- cerefox_ingest_document). Deliberately NOT unique (0.20.0, #332).
     content_hash    TEXT        NOT NULL,
     -- #212 (0.12.2): must be a JSON OBJECT — jsonb accepts any JSON value,
     -- but every reader assumes an object, and non-object values were silently
@@ -51,6 +53,12 @@ CREATE TABLE IF NOT EXISTS cerefox_documents (
     metadata        JSONB       NOT NULL DEFAULT '{}'::jsonb
                     CONSTRAINT cerefox_documents_metadata_object
                     CHECK (jsonb_typeof(metadata) = 'object'),
+    -- #333 (0.21.0): the metadata's optimistic-concurrency token, independent
+    -- of content_hash (which covers the body only). Starts at 1 and goes up by
+    -- one whenever `metadata` actually changes; maintained by the
+    -- trig_cerefox_documents_metadata_revision trigger below, so every writer
+    -- is covered and no caller can set it.
+    metadata_revision INT       NOT NULL DEFAULT 1,
     chunk_count     INT         NOT NULL DEFAULT 0,
     total_chars     INT         NOT NULL DEFAULT 0,
     -- review_status: human governance flag. 'approved' = validated by human,
@@ -71,7 +79,6 @@ CREATE TABLE IF NOT EXISTS cerefox_documents (
     -- Search indexes exclude soft-deleted docs. Purge does the real CASCADE DELETE.
     deleted_at      TIMESTAMPTZ DEFAULT NULL,
 
-    CONSTRAINT cerefox_documents_hash_unique UNIQUE (content_hash),
     CONSTRAINT cerefox_documents_review_status_check CHECK (review_status IN ('approved', 'pending_review'))
 );
 
@@ -127,6 +134,11 @@ CREATE TABLE IF NOT EXISTS cerefox_audit_log (
     -- author_type: 'user' (human via web UI/CLI) or 'agent' (AI via MCP/Edge Function)
     size_before     INT,
     size_after      INT,
+    -- #333 (0.21.0): on 'update-metadata' entries, the document's metadata
+    -- before and after the change, so every metadata change is recoverable
+    -- (content versions never captured metadata). NULL on other operations.
+    metadata_before JSONB,
+    metadata_after  JSONB,
     description     TEXT        NOT NULL DEFAULT '',
     -- description: free-text explaining what changed and why.
     -- Auto-generated for system actions (approval, archival, retention cleanup).
@@ -289,7 +301,7 @@ CREATE INDEX IF NOT EXISTS idx_cerefox_chunks_version
 CREATE INDEX IF NOT EXISTS idx_cerefox_docs_metadata
     ON cerefox_documents USING GIN(metadata);
 
--- Documents by content_hash (unique constraint covers equality; this covers range/prefix)
+-- Documents by content_hash (the create-time duplicate check and hash lookups)
 CREATE INDEX IF NOT EXISTS idx_cerefox_docs_hash
     ON cerefox_documents(content_hash);
 
@@ -344,6 +356,31 @@ CREATE OR REPLACE TRIGGER trig_cerefox_chunks_updated
     BEFORE UPDATE ON cerefox_chunks
     FOR EACH ROW EXECUTE FUNCTION cerefox_set_updated_at();
 
+-- ── metadata_revision trigger (#333, 0.21.0) ─────────────────────────────────
+-- Bumps metadata_revision when, and only when, metadata actually changes. A
+-- trigger rather than per-RPC code because metadata has several writers (the
+-- metadata RPC, the ingest RPC, direct table updates from older clients), and
+-- a counter that one of them forgets to bump is a token that lies. It also
+-- pins the column on every other UPDATE, so no caller can set it directly.
+CREATE OR REPLACE FUNCTION cerefox_bump_metadata_revision()
+RETURNS TRIGGER
+LANGUAGE plpgsql
+SET search_path = public, pg_catalog
+AS $$
+BEGIN
+    IF NEW.metadata IS DISTINCT FROM OLD.metadata THEN
+        NEW.metadata_revision := OLD.metadata_revision + 1;
+    ELSE
+        NEW.metadata_revision := OLD.metadata_revision;
+    END IF;
+    RETURN NEW;
+END;
+$$;
+
+CREATE OR REPLACE TRIGGER trig_cerefox_documents_metadata_revision
+    BEFORE UPDATE ON cerefox_documents
+    FOR EACH ROW EXECUTE FUNCTION cerefox_bump_metadata_revision();
+
 
 -- ── Live-database migration ───────────────────────────────────────────────────
 -- When applying this schema to an existing database that still has the old

package/dist/server-assets/supabase/functions/cerefox-get-document/index.ts

@@ -19,7 +19,8 @@ import { callerIdentity } from "../../../_shared/mcp-tools/identity.ts";
  *   { document_id: string, version_id?: string | null }
  *
  * Response (200):
- *   { document_id, doc_title, full_content, chunk_count, total_chars, is_archived, version_id, content_hash }
+ *   { document_id, doc_title, full_content, chunk_count, total_chars, is_archived, version_id, content_hash,
+ *     metadata, metadata_revision }
  * Response (404):
  *   { error: "Document not found" }
  * Response (400):
@@ -108,6 +109,8 @@ Deno.serve(async (req: Request): Promise<Response> => {
       chunk_count?: number;
       total_chars?: number;
       content_hash?: string;
+      doc_metadata?: Record<string, unknown> | null;
+      metadata_revision?: number | null;
     } | undefined;
 
     if (!row) {
@@ -138,6 +141,10 @@ Deno.serve(async (req: Request): Promise<Response> => {
         // Optimistic-concurrency token (iter-32): always the CURRENT hash —
         // pass back as expected_content_hash when updating via ingest.
         content_hash: row.content_hash ?? null,
+        // #333: the metadata and its own token — pass metadata_revision back as
+        // expected_metadata_revision when changing metadata via ingest.
+        metadata: row.doc_metadata ?? {},
+        metadata_revision: version_id === null ? (row.metadata_revision ?? null) : null,
       }),
       { status: 200, headers: { ...CORS_HEADERS, "Content-Type": "application/json" } },
     );

package/dist/server-assets/supabase/functions/cerefox-ingest/index.ts

@@ -3,6 +3,7 @@ import { createClient } from "jsr:@supabase/supabase-js@2";
 import { isVersionRequest, versionResponse } from "../../../_shared/ef-meta/index.ts";
 import { efAuthGate } from "../../../_shared/ef-auth/index.ts";
 import { callerIdentity } from "../../../_shared/mcp-tools/identity.ts";
+import { duplicateContentDocumentId, legacyContentUniqueError } from "../../../_shared/mcp-tools/_utils.ts";
 import { capEmbeddingInput } from "../../../_shared/embeddings/index.ts";
 import {
   ensureDocumentInProject,
@@ -61,24 +62,26 @@ interface IngestRequest {
   expected_content_hash?: string;
   // Explicitly skip the concurrency check (external source of truth).
   last_write_wins?: boolean;
+  // #333: the metadata's token, checked when `metadata` is passed on an update
+  // (metadata merges; a null value removes a key).
+  expected_metadata_revision?: number;
 }
 
 // Map the RPC's expected/validation errors to proper HTTP responses:
 //   CEREFOX_CONFLICT                → 409 (stale optimistic-concurrency token)
 //   CEREFOX_TOKEN_REQUIRED          → 400 (missing expected_content_hash)
-//   cerefox_documents_hash_unique   → 409 (content de-dup: another doc already
-//                                          holds identical content)
+//   CEREFOX_METADATA_CONFLICT       → 409 (stale expected_metadata_revision, #333)
 // Returns null for genuinely unexpected errors (→ 500 at the call site).
 function concurrencyErrorResponse(
   message: string,
   headers: Record<string, string>,
 ): Response | null {
-  if (message.includes("cerefox_documents_hash_unique")) {
+  if (message.includes("CEREFOX_METADATA_CONFLICT")) {
     return new Response(
       JSON.stringify({
-        error: "duplicate_content",
+        error: "metadata_conflict",
         message:
-          "Another document already has identical content. Cerefox de-duplicates by content hash — update that document instead of creating or editing a second copy to match it.",
+          "The document's metadata changed since it was read. Re-read it (getDocument), reapply your change, and retry with the new expected_metadata_revision.",
         detail: message,
       }),
       { status: 409, headers },
@@ -278,7 +281,7 @@ Deno.serve(async (req: Request) => {
   // metadata: null = "not provided" — the RPC keeps existing metadata on
   // update and uses {} on create (v0.11.1; a `= {}` default here used to wipe
   // a document's tags on every content update that didn't re-pass them).
-  const { title, content, document_id = null, project_name, source = "agent", metadata = null, update_if_exists = false, author_type = "agent", expected_content_hash = null, last_write_wins = false } = body;
+  const { title, content, document_id = null, project_name, source = "agent", metadata = null, update_if_exists = false, author_type = "agent", expected_content_hash = null, last_write_wins = false, expected_metadata_revision = null } = body;
   const callerName = callerIdentity(body as unknown as Record<string, unknown>);
   const author = callerName ?? "agent";
 
@@ -436,6 +439,9 @@ Deno.serve(async (req: Request) => {
       p_source_label: source,
       p_expected_content_hash: expected_content_hash,
       p_last_write_wins: last_write_wins,
+      // Only when set (#333 review): a null would name a signature a pre-0.21.0
+      // schema lacks, failing the whole update.
+      ...(expected_metadata_revision != null ? { p_expected_metadata_revision: expected_metadata_revision } : {}),
       p_content_format: CONTENT_FORMAT_BLIND_STITCH,
     });
 
@@ -554,6 +560,9 @@ Deno.serve(async (req: Request) => {
         p_source_label: source,
         p_expected_content_hash: expected_content_hash,
         p_last_write_wins: last_write_wins,
+        // Only when set (#333 review): a null would name a signature a pre-0.21.0
+      // schema lacks, failing the whole update.
+      ...(expected_metadata_revision != null ? { p_expected_metadata_revision: expected_metadata_revision } : {}),
       p_content_format: CONTENT_FORMAT_BLIND_STITCH,
       });
 
@@ -600,10 +609,14 @@ Deno.serve(async (req: Request) => {
   }
 
   // ── Hash deduplication (normal create path) ────────────────────────────────
+  // Creates only, against LIVE documents (#332). Saves the embedding spend;
+  // the RPC repeats the check authoritatively.
   const { data: hashMatch } = await supabase
     .from("cerefox_documents")
     .select("id, title")
     .eq("content_hash", contentHash)
+    .is("deleted_at", null)
+    .order("created_at", { ascending: true })
     .limit(1);
 
   if (hashMatch?.length) {
@@ -665,7 +678,30 @@ Deno.serve(async (req: Request) => {
     p_content_format: CONTENT_FORMAT_BLIND_STITCH,
   });
 
+  // The RPC's duplicate check caught an identical create that landed after
+  // the pre-check above. Nothing was written; answer as the pre-check does.
+  const duplicateId = duplicateContentDocumentId(ingestErr?.message ?? "");
+  if (duplicateId) {
+    const { data: existing } = await supabase
+      .from("cerefox_documents")
+      .select("title")
+      .eq("id", duplicateId)
+      .maybeSingle();
+    return new Response(
+      JSON.stringify({
+        document_id: duplicateId,
+        title: existing?.title ?? title.trim(),
+        skipped: true,
+        message: "Document already exists (content hash match)",
+      }),
+      { headers },
+    );
+  }
   if (ingestErr || !ingestResult?.length) {
+    // Functions deployed ahead of the schema still meet the pre-0.20.0
+    // store-wide content constraint.
+    const legacy = legacyContentUniqueError(ingestErr?.message ?? "");
+    if (legacy) return new Response(JSON.stringify({ error: legacy.message }), { status: 409, headers });
     return new Response(
       JSON.stringify({ error: `Ingest RPC failed: ${ingestErr?.message ?? "no data returned"}` }),
       { status: 500, headers },

package/docs/api/openapi.json

@@ -206,6 +206,34 @@
                       "created_at": {
                         "default": "",
                         "type": "string"
+                      },
+                      "metadata_before": {
+                        "anyOf": [
+                          {
+                            "type": "object",
+                            "propertyNames": {
+                              "type": "string"
+                            },
+                            "additionalProperties": {}
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ]
+                      },
+                      "metadata_after": {
+                        "anyOf": [
+                          {
+                            "type": "object",
+                            "propertyNames": {
+                              "type": "string"
+                            },
+                            "additionalProperties": {}
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ]
                       }
                     },
                     "required": [
@@ -1498,6 +1526,18 @@
                         "null"
                       ]
                     },
+                    "metadata_revision": {
+                      "anyOf": [
+                        {
+                          "type": "integer",
+                          "minimum": -9007199254740991,
+                          "maximum": 9007199254740991
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
                     "versions": {
                       "default": [],
                       "type": "array",
@@ -1880,6 +1920,12 @@
                     },
                     "projectsChanged": {
                       "type": "boolean"
+                    },
+                    "warnings": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
                     }
                   },
                   "required": [
@@ -2007,7 +2053,7 @@
                     }
                   },
                   "metadata": {
-                    "description": "Replaces the metadata. `{}` clears every key; omit to leave it unchanged.",
+                    "description": "Replaces the metadata (this route edits it as a whole form). `{}` clears every key; omit to leave it unchanged. Send expected_metadata_revision with it.",
                     "type": "object",
                     "propertyNames": {
                       "type": "string"
@@ -2021,6 +2067,19 @@
                       "null"
                     ]
                   },
+                  "expected_metadata_revision": {
+                    "description": "The metadata_revision you read (GET /documents/{id}). Required with `metadata` for an identified caller; a stale one is a 409.",
+                    "anyOf": [
+                      {
+                        "type": "integer",
+                        "minimum": -9007199254740991,
+                        "maximum": 9007199254740991
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
                   "last_write_wins": {
                     "description": "Skip the concurrency check. Only when an external source of truth makes a conflict meaningless.",
                     "type": "boolean"
@@ -3471,12 +3530,19 @@
                     "type": "string"
                   },
                   "metadata": {
+                    "description": "On an update it MERGES into the stored metadata: a null value removes a key, omitted keys are kept.",
                     "type": "object",
                     "propertyNames": {
                       "type": "string"
                     },
                     "additionalProperties": {}
                   },
+                  "expected_metadata_revision": {
+                    "description": "Optional, with metadata on an update: the metadata_revision you read. A stale one is a 409.",
+                    "type": "integer",
+                    "minimum": -9007199254740991,
+                    "maximum": 9007199254740991
+                  },
                   "source": {
                     "description": "Origin label. Defaults to \"paste\".",
                     "type": "string"

package/docs/guides/cli.md

@@ -278,7 +278,9 @@ cerefox document set-metadata [OPTIONS] DOCUMENT_ID
 | `-s, --set <key=value...>` | Set a key. Repeatable. |
 | `-r, --remove <key...>` | Remove a key. Repeatable. |
 | `--json <object>` | A JSON object of keys to set; a `null` value removes that key. |
-| `--replace` | Set the metadata to **exactly** what was given, discarding every key not listed. |
+| `--replace` | Set the metadata to **exactly** what was given, discarding every key not listed. Needs `--expected-metadata-revision` or `--last-write-wins` (v1.19.0). |
+| `--expected-metadata-revision <n>` | The `metadata_revision` you read (`document get` shows it). The write fails if the metadata changed since. Optional on a merge, required with `--replace`. |
+| `--last-write-wins` | Replace without a revision, regardless of concurrent changes (recorded in the audit log). |
 | `-a, --author <name>` | Caller identity (audit log). |
 | `--author-type <type>` | `user` (default) or `agent`. |
 | `--json-out` | Emit the result as JSON. |

package/docs/guides/configuration.md

@@ -183,7 +183,7 @@ This handles intermittent OpenAI API errors (500s) that would otherwise cause se
 | `CEREFOX_MIN_TERM_COVERAGE` | **Retired in v1.1.0 — no longer read.** | Now a store setting: `cerefox config set min_term_coverage <value>`, or the **Settings** page. A per-call override still works (`cerefox search --min-term-coverage`, the MCP `min_term_coverage` param). `cerefox doctor` and the Settings page report the variable if it is still set. |
 | `CEREFOX_EMBED_MAX_INPUT_CHARS` | `20000` | Safety cap on the characters sent to the embedding model per input. The full chunk content is always stored and reconstructed untouched; only the embedding uses the (rare) truncated prefix, so an oversized chunk can never fail an ingest. |
 | `CEREFOX_MODELS_DIR` | `~/.cerefox/models` (in-container: inside the data volume) | Where the local embedder caches downloaded model weights (Cerefox Local; `CEREFOX_EMBEDDER=local`). |
-| `CEREFOX_ONNX_BATCH` | `4` | Texts per local-embedder inference call. Peak memory scales with this; the small default keeps ingest/reindex safe on small Docker VMs. |
+| `CEREFOX_ONNX_BATCH` | `1` | Texts per local-embedder inference call. Peak memory grows with this (each batch is padded to its longest chunk), and on CPU a larger batch is not faster, so leave it at 1. Was 4 before v1.19.0 (#335). Cerefox Local forwards it from its `.env` (from v1.19.0; after upgrading, run `cerefox-local init` once for a value set there to apply). |
 
 ### Metadata filter
 

package/docs/guides/connect-agents.md

@@ -661,7 +661,7 @@ In the action editor, paste this schema (replace `<your-project-ref>`):
 openapi: 3.1.0
 info:
   title: Cerefox Knowledge Base
-  version: 4.3.0
+  version: 4.4.0
 servers:
   - url: https://<your-project-ref>.supabase.co/functions/v1
 paths:
@@ -793,9 +793,10 @@ paths:
                 metadata:
                   type: object
                   description: >
-                    Arbitrary JSON metadata. On an UPDATE, omitting this keeps
-                    the document's existing metadata (v2.1.0); pass {} to
-                    deliberately clear all tags.
+                    Arbitrary JSON metadata. On an UPDATE it is MERGED into the
+                    existing metadata (v4.4.0): keys you pass are set, a null
+                    value removes that key, keys you omit are kept. Omitting
+                    the field keeps the metadata as it is.
                 update_if_exists:
                   type: boolean
                   default: false
@@ -813,6 +814,13 @@ paths:
                     If the document changed since it was read, the update fails
                     with HTTP 409 — re-read the document, merge your changes,
                     retry with the new hash. Not needed when creating.
+                expected_metadata_revision:
+                  type: integer
+                  description: >
+                    Optional, with metadata on an update (v4.4.0): the
+                    metadata_revision returned by getDocument. If the metadata
+                    changed since, the update fails with HTTP 409
+                    (error "metadata_conflict").
                 last_write_wins:
                   type: boolean
                   default: false
@@ -862,7 +870,9 @@ paths:
             changes, and retry with the new hash — do not overwrite blindly),
             or the target document is soft-deleted (error
             "document_deleted") — restore it first, then retry, or create a
-            new document.
+            new document, or the metadata changed since it was read (error
+            "metadata_conflict") — re-read with getDocument and retry with
+            the new metadata_revision.
         '422':
           description: >
             Unresolved document links (error "unresolved_links") — the content
@@ -922,7 +932,8 @@ paths:
           description: >
             Document content and metadata:
             { document_id, doc_title, full_content, chunk_count, total_chars,
-              is_archived, version_id, content_hash }.
+              is_archived, version_id, content_hash, metadata,
+              metadata_revision }.
             content_hash is the document's CURRENT hash — pass it back as
             expected_content_hash when updating via ingestNote.
         '404':
@@ -1155,7 +1166,7 @@ curl -s -X POST \
   }'
 ```
 
-If the same content was already ingested (SHA-256 hash match), returns `"skipped": true`.
+If a live document already has the same content (SHA-256 hash match), a create returns that document with `"skipped": true` instead of a copy. Documents in the trash do not count, and updates never de-duplicate.
 
 **Edge Function parameters — `cerefox-search`:**
 

package/docs/guides/ops-scripts.md

@@ -177,7 +177,7 @@ Output: `backup-data/cerefox-20260308T143022Z-before-v2-migration.json`
 
 ## backup_restore.ts — Restore from a backup
 
-Restores documents and chunks from a previously created backup file. Idempotent — documents with the same content hash are skipped. (End users use `cerefox backup restore`.)
+Restores documents and chunks from a previously created backup file. Idempotent — a document is skipped when its id is already present, or when a live document outside the backup already has the same content. (End users use `cerefox backup restore`.)
 
 ```bash
 bun scripts/backup_restore.ts BACKUP_FILE [OPTIONS]

package/docs/guides/setup-local.md

@@ -4,9 +4,11 @@ Run Cerefox **fully on your own machine** — no hosted Supabase, no cloud datab
 Docker container bundles everything: Postgres + pgvector, the PostgREST Data API, and the
 Cerefox web server. You get the same web UI, CLI, and MCP server as the cloud setup.
 
-> **Embeddings still use the OpenAI API.** An `OPENAI_API_KEY` is required even for a
-> local setup (the database and web server are local; embedding generation is not). A
-> fully offline embedder is on the roadmap.
+> **Two embedding choices.** By default embeddings use the OpenAI API (an
+> `OPENAI_API_KEY` is needed). Or choose the **local embedder**
+> (`--local-embedder`, `CEREFOX_EMBEDDER=local`): a model that runs inside the
+> container, fully offline, no API key. See
+> [Choose your embedder](#choose-your-embedder-openai-vs-fully-local).
 
 ## Cloud vs. Local — pick one
 
@@ -49,9 +51,14 @@ install; switching later requires a re-index (see below).
 The local model (~130 MB) downloads once — at install/init when selected — into the
 data volume, so it survives `cerefox-local upgrade`.
 
-> **Memory**: give the Docker VM **≥ 4 GB** for comfortable local-embedder use
-> (Colima defaults to 2 GB: `colima start --memory 4`). Inference is
-> sub-batched to keep peak memory flat, so smaller VMs work — just slower.
+> **Memory**: with the local embedder, each Cerefox Local instance's web
+> process sits around **0.3–0.5 GB** idle and reaches about **1.5 GB** while
+> ingesting long documents dense with tables, ids or code (measured on
+> synthetic 20,000-character documents; Postgres and PostgREST add a little
+> more). Give the Docker VM room for **each** instance you run, plus everything
+> else in it: **4 GB is comfortable for one instance**, not two. Colima defaults
+> to 2 GB (`colima start --memory 4`, or `--memory 8` for two instances). If the
+> VM runs out, the kernel kills the web process; see Troubleshooting.
 
 > **Switching embedders on existing data is breaking**: the two models produce
 > incompatible vector spaces, so documents embedded with one are invisible to
@@ -193,6 +200,23 @@ Re-run the installer with the key, or set it and `cerefox-local upgrade`.
 
 **Port already in use** — re-install with a free port: `PORT=8017 sh -c "$(curl -fsSL …/install-local.sh)"`.
 
+**Requests fail with "socket connection closed", or the web process restarts on
+its own** — usually the Docker VM ran out of memory and the kernel killed the
+web process (most often during ingest with the local embedder). s6 restarts it
+within seconds, so the container keeps running. Since v1.19.0 the container log
+says so (`docker logs cerefox-local` shows "killed (SIGKILL), most likely by the
+kernel's out-of-memory killer"); on older versions the log shows only the
+restart. Confirm it in the VM's kernel log:
+
+```sh
+colima ssh -- sudo dmesg | grep -i "out of memory"   # Colima
+```
+
+(Docker Desktop: the same `dmesg` from a privileged container, e.g.
+`docker run --rm --privileged alpine dmesg | grep -i "out of memory"`.) The fix is
+more memory for the VM, or fewer instances in it; see **Memory** above.
+`CEREFOX_ONNX_BATCH` (default 1) trades memory for nothing useful above 1, so leave it.
+
 ---
 
 ## Contributor notes

package/docs/guides/upgrading.md

@@ -194,6 +194,20 @@ knowing about:
   document must be restored before its content can be updated.
 - **v1.13.0 — the review workflow is a store setting.** Upgraded stores keep
   it on; fresh installs start with it off. See the callout above.
+- **Schema 0.20.0 — content no longer has to be unique.** Updates that match
+  another document, or a document in the trash, are accepted; only creating a
+  document de-duplicates, against live documents. Needs `cerefox server deploy`.
+  Until the server is deployed, a 1.19.0 client writing content another
+  document (trashed ones included) already has gets an error telling it to
+  deploy. A client older than 1.19.0 against the new server is safe: when two
+  identical creates race, the loser gets an error, as it did before.
+- **Schema 0.21.0 — metadata merges on content updates and has its own token.**
+  A content update's `metadata` now merges (`null` removes a key) instead of
+  replacing, so `{}` no longer clears tags; `replace` needs
+  `expected_metadata_revision`. Scripts that relied on replace-on-update should
+  use `document set-metadata --replace`. Needs `cerefox server deploy`; then
+  restart MCP clients and `cerefox web`, since an older client's metadata
+  `replace` is refused for lack of the token.
 - **v1.13.1 — the flag hides, it does not rewrite.** Agent writes are
   recorded `pending_review` whether or not the workflow is shown (v1.13.0
   stored `approved` while off). Redeploy to pick it up.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.18.0",
+  "version": "1.19.1",
   "description": "Cerefox \u2014 user-owned shared memory for AI agents. CLI + stdio MCP server + web UI + ingestion for a knowledge base on your own Supabase project (or fully self-hosted with Cerefox Local).",
   "license": "Apache-2.0",
   "homepage": "https://github.com/fstamatelopoulos/cerefox",
@@ -39,12 +39,12 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@hono/node-server": "^2.1.1",
+    "@hono/node-server": "^2.1.4",
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "@supabase/supabase-js": "^2.117.2",
+    "@supabase/supabase-js": "^2.117.3",
     "cli-progress": "^3.12.0",
     "commander": "^15.0.0",
-    "hono": "^4.13.9",
+    "hono": "^4.13.13",
     "mammoth": "^1.13.0",
     "ora": "^9.4.0",
     "picocolors": "^1.0.0",
@@ -54,13 +54,13 @@
     "zod": "^4.6.5"
   },
   "optionalDependencies": {
-    "@huggingface/transformers": "^4.3.0",
+    "@huggingface/transformers": "^4.3.1",
     "onnxruntime-node": "^1.21.0"
   },
   "devDependencies": {
     "@types/bun": "^1.4.2",
     "@types/cli-progress": "^3.11.5",
-    "@types/node": "^24.19.0",
+    "@types/node": "^24.19.1",
     "@types/prompts": "^2.4.9",
     "typescript": "^6.0.3"
   },