@cerefox/memory 1.4.0 → 1.6.0

package/dist/server-assets/db/migrations/0022_rls_on_document_relations.sql

@@ -0,0 +1,38 @@
+-- 0022_rls_on_document_relations.sql — close the one-table RLS gap (iteration 36).
+--
+-- `cerefox_document_relations` was added in iteration 29 and never added to
+-- schema.sql's RLS block, so it alone among the ten tables had row-level
+-- security disabled. Cerefox's model is "RLS ON with NO policies" — the
+-- service-role key bypasses RLS and everything else is denied — so a table
+-- without RLS is reachable by any role holding a table grant.
+--
+-- On projects created before Supabase stopped granting `anon` blanket
+-- privileges on `public` (the maintainer's production project is one), `anon`
+-- holds SELECT/INSERT/UPDATE/DELETE here. The anon / publishable key is
+-- designed to be public, so that means world read AND write on this table.
+-- Supabase's advisor flagged it as `rls_disabled_in_public` on 2026-08-09.
+--
+-- Newer projects grant `anon` nothing, so they were never exposed — which is
+-- why the maintainer's staging project showed no privileges while production
+-- showed all four. Both get RLS regardless: relying on the absence of a grant
+-- is not the same as denying access.
+--
+-- Impact of the gap: the relations feature is opt-in (`relations_enabled`,
+-- default false), so the table is empty on a default install and no document
+-- content was ever reachable through it. Content, chunks, versions, audit log
+-- and config were correctly protected throughout.
+--
+-- Idempotent, and safe on a table that already has RLS.
+
+ALTER TABLE cerefox_document_relations ENABLE ROW LEVEL SECURITY;
+
+-- Defence in depth: revoke the legacy blanket grants so the table is denied by
+-- privilege as well as by RLS. Harmless where the grants were never made.
+REVOKE ALL ON TABLE cerefox_document_relations FROM anon;
+
+DO $$
+BEGIN
+    RAISE NOTICE
+        'Migration 0022: RLS enabled on cerefox_document_relations and anon '
+        'grants revoked (Supabase rls_disabled_in_public). Schema version 0.11.2.';
+END $$;

package/dist/server-assets/db/migrations/0023_set_document_metadata.sql

@@ -0,0 +1,16 @@
+-- 0023_set_document_metadata.sql — metadata-only writes (#204).
+--
+-- Adds cerefox_set_document_metadata. No table DDL: the function itself ships
+-- in rpcs.sql, which `cerefox server deploy` re-applies wholesale. This
+-- migration exists so the schema version advances in step, which is what tells
+-- an existing deployment it needs that redeploy.
+--
+-- Schema version 0.11.2 → 0.11.3. Purely additive.
+
+DO $$
+BEGIN
+    RAISE NOTICE
+        'Migration 0023: cerefox_set_document_metadata arrives with rpcs.sql on '
+        'this deploy — metadata-only writes, merge by default, JSON null removes '
+        'a key (RFC 7386). Schema version 0.11.3.';
+END $$;

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

@@ -2416,6 +2416,120 @@ $$;
 -- redeploy. The web UI's /api/v1/schema-version endpoint compares the bundled
 -- and deployed values and surfaces a 'redeploy needed' banner on mismatch.
 
+-- ── cerefox_set_document_metadata ────────────────────────────────────────────
+-- Change a document's metadata WITHOUT touching its content (#204).
+--
+-- Until this existed, `cerefox_ingest` was the only way to set a tag, and it
+-- requires title + content — so changing one key meant resending the whole
+-- document, reproducing every untouched character. That is the transcription
+-- risk the partial-edit tools were built to remove, and it was still fully
+-- present for metadata. Project membership had a metadata-only writer
+-- (`cerefox_set_document_projects`) all along; tags simply never got one.
+--
+-- MERGE is the default, not replace. Several agent roles write to the same
+-- documents, so a destructive default would let a caller setting `status`
+-- silently drop `type`, `seq` and `agent_role` written by someone else — a
+-- default shadowing stored state, which is the defect class behind #183 and
+-- #191. It would also force a read-modify-write, which is the cost this
+-- function exists to remove.
+--
+-- REMOVAL uses a JSON null, following RFC 7386 (JSON Merge Patch):
+--     {"status": "active", "stale_key": null}  -- sets status, deletes stale_key
+-- Unambiguous because Cerefox metadata values are JSON strings by convention,
+-- so a null can never be a legitimate value. Same spirit as `cerefox_ingest`,
+-- where NULL means "not provided, keep existing" and '{}' means "clear all".
+--
+-- The merge happens inside one UPDATE against a locked row, so two agents
+-- setting different keys concurrently cannot clobber each other. Doing this
+-- client-side would reintroduce exactly that race.
+--
+-- Metadata-only: no re-chunk, no re-embed, no content version snapshot. The
+-- audit trail records it as 'update-metadata', which the CHECK already allows.
+DROP FUNCTION IF EXISTS cerefox_set_document_metadata(UUID, JSONB, BOOLEAN, TEXT, TEXT);
+CREATE FUNCTION cerefox_set_document_metadata(
+    p_document_id   UUID,
+    p_metadata      JSONB,
+    p_replace       BOOLEAN DEFAULT FALSE,
+    p_author        TEXT    DEFAULT 'unknown',
+    p_author_type   TEXT    DEFAULT 'user'
+)
+RETURNS TABLE (
+    document_id     UUID,
+    metadata        JSONB,
+    keys_set        INT,
+    keys_removed    INT
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+    v_before      JSONB;
+    v_after       JSONB;
+    v_null_keys   TEXT[];
+    v_title       TEXT;
+    v_removed     INT;
+    v_set         INT;
+BEGIN
+    IF p_metadata IS NULL OR jsonb_typeof(p_metadata) <> 'object' THEN
+        RAISE EXCEPTION 'metadata must be a JSON object'
+            USING ERRCODE = '22023';
+    END IF;
+
+    -- Lock the row so a concurrent metadata write cannot interleave between
+    -- the read and the merge.
+    SELECT d.metadata, d.title INTO v_before, v_title
+    FROM cerefox_documents d
+    WHERE d.id = p_document_id AND d.deleted_at IS NULL
+    FOR UPDATE;
+
+    IF v_title IS NULL THEN
+        RAISE EXCEPTION 'Document % not found (or is deleted)', p_document_id
+            USING ERRCODE = 'P0002';
+    END IF;
+
+    -- Keys explicitly set to null are removals, never stored values.
+    SELECT COALESCE(array_agg(key), ARRAY[]::TEXT[]) INTO v_null_keys
+    FROM jsonb_each(p_metadata)
+    WHERE value = 'null'::jsonb;
+
+    IF p_replace THEN
+        v_after := p_metadata - v_null_keys;
+    ELSE
+        v_after := (COALESCE(v_before, '{}'::jsonb) || p_metadata) - v_null_keys;
+    END IF;
+
+    UPDATE cerefox_documents
+    SET metadata = v_after, updated_at = NOW()
+    WHERE id = p_document_id;
+
+    -- Report what actually changed, not what was asked for: a caller that sets
+    -- a key to the value it already had should see 0, so "nothing happened" is
+    -- distinguishable from "it worked".
+    SELECT count(*)::INT INTO v_removed
+    FROM jsonb_object_keys(COALESCE(v_before, '{}'::jsonb)) k
+    WHERE NOT v_after ? k;
+
+    SELECT count(*)::INT INTO v_set
+    FROM jsonb_each(v_after) e
+    WHERE COALESCE(v_before, '{}'::jsonb) -> e.key IS DISTINCT FROM e.value;
+
+    PERFORM cerefox_create_audit_entry(
+        p_document_id := p_document_id,
+        p_operation   := 'update-metadata',
+        p_author      := p_author,
+        p_author_type := p_author_type,
+        p_description := format(
+            'Metadata %s on "%s": %s key(s) set, %s removed',
+            CASE WHEN p_replace THEN 'replaced' ELSE 'merged' END,
+            v_title, v_set, v_removed
+        )
+    );
+
+    RETURN QUERY SELECT p_document_id, v_after, v_set, v_removed;
+END;
+$$;
+
 CREATE OR REPLACE FUNCTION cerefox_schema_version()
 RETURNS TEXT
 LANGUAGE sql
@@ -2425,11 +2539,14 @@ SET search_path = public, pg_catalog
 AS $$
     -- Keep in lockstep with the `@version:` marker in schema.sql (cut_release.ts
     -- enforces it). Bump whenever schema.sql OR rpcs.sql changes.
+    -- 0.11.3 (#204): cerefox_set_document_metadata — metadata-only writes.
+    -- 0.11.2 (iteration 36): RLS enabled on cerefox_document_relations,
+    -- which iteration 29 left off the list (Supabase rls_disabled_in_public).
     -- 0.11.1 (iteration 35, #197): audit CHECK accepts 'rename-section'.
     -- 0.11.0 supersedes 0.10.6 (v1.2.1, #191): this branch carries that fix plus
     -- the partial-edit surface, and both migrations (0019, 0020) are in the
     -- sequence, so a store deploying this gets everything from both lines.
-    SELECT '0.11.1'::TEXT;
+    SELECT '0.11.3'::TEXT;
 $$;
 
 -- ── cerefox_content_format_stats ─────────────────────────────────────────────

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.11.1
+-- @version: 0.11.3
 -- 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 —
@@ -431,6 +431,13 @@ ALTER TABLE cerefox_audit_log              ENABLE ROW LEVEL SECURITY;
 ALTER TABLE cerefox_migrations            ENABLE ROW LEVEL SECURITY;
 ALTER TABLE cerefox_config                ENABLE ROW LEVEL SECURITY;
 ALTER TABLE cerefox_usage_log             ENABLE ROW LEVEL SECURITY;
+-- iteration 29 added this table and did not add it here, so it stayed
+-- world-accessible on any project whose `anon` role holds the legacy
+-- GRANT ... ON ALL TABLES IN SCHEMA public. Supabase's linter flagged it as
+-- `rls_disabled_in_public` (2026-08-09). Every other table on this list denies
+-- anon by having RLS on with NO policies; this one did not, so the model had a
+-- hole exactly one table wide. See the guard test in _shared/__tests__.
+ALTER TABLE cerefox_document_relations    ENABLE ROW LEVEL SECURITY;
 
 -- ── Explicit Data API grants (issue #26; schema 0.8.2) ─────────────────────────
 -- Supabase is removing the implicit privileges the Data API roles get on

package/docs/guides/cli.md

@@ -251,6 +251,59 @@ cerefox document edit <doc-id> --set-meta status=archived --unset-meta draft
 
 ---
 
+### `cerefox document set-metadata`
+
+**Purpose**: change a document's metadata **without resending its content**. Before this existed, `cerefox document ingest` was the only way to set a tag, and it needs the whole document — so changing one key meant reproducing every untouched character, which is the transcription risk the partial-edit commands exist to remove.
+
+**Merges by default.** The keys you pass are set; every other key is left alone. That means you do not need to read the document first, and you cannot accidentally drop a tag someone else set. Content, chunks and embeddings are untouched and no new version is created; the change is logged as an `update-metadata` audit entry.
+
+CLI equivalent of the `cerefox_set_document_metadata` MCP tool. Both call the same RPC, so the semantics cannot drift between them.
+
+**Synopsis**:
+
+```
+cerefox document set-metadata [OPTIONS] DOCUMENT_ID
+```
+
+**Options**:
+
+| Flag | Meaning |
+|---|---|
+| `-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. |
+| `-a, --author <name>` | Caller identity (audit log). |
+| `--author-type <type>` | `user` (default) or `agent`. |
+| `--json-out` | Emit the result as JSON. |
+
+**Examples**:
+
+```bash
+# Add or update one tag; everything else is preserved
+cerefox document set-metadata <id> --set status=active
+
+# Several at once
+cerefox document set-metadata <id> --set type=decision-log --set seq=8
+
+# Remove a key
+cerefox document set-metadata <id> --remove stale_key
+
+# Set and remove in one call, from a script that already holds an object
+cerefox document set-metadata <id> --json '{"status":"active","stale_key":null}'
+
+# Reset a document's tags wholesale (rare)
+cerefox document set-metadata <id> --replace --json '{"type":"note"}'
+```
+
+**Values are stored as JSON strings**, matching the convention elsewhere: a `metadata_filter` matches JSONB as strings, so a stored boolean `true` would never match a filter looking for `"true"`.
+
+**`--set key=null` is refused.** Over MCP a JSON null *removes* a key (RFC 7386), but on a command line the same text could equally mean the literal word "null" — so rather than guess, the command points you at `--remove key` (to delete) or `--json '{"key":"null"}'` (to store the word).
+
+**Output**: reports what actually changed, not what was asked for. Setting a key to the value it already holds reports no change, so re-running a script is distinguishable from doing work.
+
+---
+
 ### `cerefox document set-projects`
 
 **Purpose**: replace a document's project memberships with **exactly** the given set (full-set replace — any project not listed is removed). This is the CLI equivalent of the `cerefox_set_document_projects` MCP tool; both share one membership-replace core, so they behave identically. Content is untouched; the change is logged as an `update-metadata` audit entry.
@@ -611,7 +664,7 @@ cerefox config set relations_enabled true    # tools appear in every agent's lis
 cerefox config set relations_enabled false   # hidden again; no data removed
 ```
 
-Agents see 12 tools with the flag off and 16 with it on. See
+Agents see 13 tools with the flag off and 16 with it on. See
 [`configuration.md`](configuration.md) for the full runtime-config surface.
 
 ### `cerefox config list` / `cerefox config get` / `cerefox config set`

package/docs/guides/connect-agents.md

@@ -72,7 +72,7 @@ in the container.
 - **Easiest:** `cerefox-local configure-agent` wires it up (registers an MCP server named
   `cerefox-local` with Claude Code if the `claude` CLI is present, else prints the snippet).
 - **Manual:** point the client at `command: cerefox-local, args: ["mcp"]` (stdio). That proxies
-  to `cerefox mcp` in the container; the same 12 core tools, identical behavior to every other path.
+  to `cerefox mcp` in the container; the same 13 core tools, identical behavior to every other path.
 - The cloud paths above (remote Edge Function, GPT Actions) **do not apply** to a local-only
   install — there are no Edge Functions.
 
@@ -131,7 +131,7 @@ in the container.
 
 ### What it is
 
-The local Cerefox MCP server runs on your machine and exposes the same 12 core tools as the remote
+The local Cerefox MCP server runs on your machine and exposes the same 13 core tools as the remote
 Edge Function, communicating with clients over stdio.
 
 The local server ships as an npm package — **[`@cerefox/memory`](https://www.npmjs.com/package/@cerefox/memory)** — built with the official `@modelcontextprotocol/sdk`.
@@ -196,10 +196,11 @@ Once configured, every Path A client has these tools:
 | `cerefox_get_audit_log` | Query audit log entries with filters (document, author, operation, time range) |
 | `cerefox_list_projects` | List all projects with names and IDs. Use for discovering available projects. |
 | `cerefox_metadata_search` | Find documents by metadata key-value criteria without a text search term. Supports project, date, and content filters. |
+| `cerefox_set_document_metadata` | Change a document's metadata without resending its content. **Merges** by default (keys you pass are set, others left alone); a `null` value removes a key (RFC 7386); `replace: true` sets exactly the object given. No re-chunk, no re-embed, no new version. |
 | `cerefox_set_document_projects` | Set a document's project memberships to exactly the given list (destructive replace; metadata-only, no content change). Use `cerefox_ingest` with singular `project_name` for non-destructive "add". |
 | `cerefox_get_help` | Retrieve Cerefox conventions (the same content as `AGENT_QUICK_REFERENCE.md`) over MCP. Optional `topic` parameter does a case-insensitive H2 substring match. Call this whenever you are uncertain. |
 
-> All 12 core tools are available on both Path A (local and remote MCP) and Path B (GPT Actions
+> All 13 core tools are available on both Path A (local and remote MCP) and Path B (GPT Actions
 > via dedicated Edge Functions, except `cerefox_get_help` which is MCP-only). MCP tools use
 > `project_name` (human-readable); primitive Edge Functions (Path B) use `project_id` (UUID).
 
@@ -225,9 +226,10 @@ For the full tool reference, search Cerefox for "How AI Agents Use Cerefox".
 After setup, ask your client:
 
 > "What tools do you have available?"
-> Expected: 12 tools listed (`cerefox_search`, `cerefox_ingest`, `cerefox_insert`, `cerefox_edit`, `cerefox_get_document`,
+> Expected: 13 tools listed (`cerefox_search`, `cerefox_ingest`, `cerefox_insert`, `cerefox_edit`, `cerefox_get_document`,
 > `cerefox_list_versions`, `cerefox_list_projects`, `cerefox_list_metadata_keys`,
-> `cerefox_metadata_search`, `cerefox_set_document_projects`, `cerefox_get_audit_log`,
+> `cerefox_metadata_search`, `cerefox_set_document_projects`,
+> `cerefox_set_document_metadata`, `cerefox_get_audit_log`,
 > `cerefox_get_help`).
 
 > "Use cerefox_search with query='second brain' and match_count=3. What did you find?"
@@ -319,7 +321,7 @@ pick it up automatically.
 to primitive Edge Functions. This means each MCP tool call costs a single Edge Function
 invocation.
 
-A single HTTPS URL gives any remote-capable MCP client all 12 core tools with full hybrid
+A single HTTPS URL gives any remote-capable MCP client all 13 core tools with full hybrid
 search -- no Python, no `uv`, no local repository clone needed.
 
 **URL format:**
@@ -500,7 +502,7 @@ Replace `<your-project-ref>` with your Supabase project ref.
 **Step 3 — Verify:**
 
 Launch Codex and use the `/mcp` slash command to confirm the `cerefox` server is connected
-and all 12 tools are listed.
+and all 13 tools are listed.
 
 **Notes:**
 - `bearer_token_env_var` is the **name** of the env var (e.g. `"CEREFOX_ACCESS_TOKEN"`), not the
@@ -1149,7 +1151,7 @@ user + `CEREFOX_OAUTH_OWNER_ID` pin, and register the Claude OAuth App
    Client Secret from the pre-registered OAuth App (setup-supabase Step 7d).
 5. Save. Claude runs the OAuth flow → redirects you to the **Cerefox consent page** (sign
    in with the owner email/password from Step 7c, then **Allow**) → returns to Claude. The
-   connector shows as connected with **12 tools** (16 if you have enabled document relations). (If you've approved before, Supabase
+   connector shows as connected with **13 tools** (16 if you have enabled document relations). (If you've approved before, Supabase
    auto-consents and the page just flashes through — that's expected.)
 6. **Mobile**: connectors are account-level, so `CerefoxMCP` appears in the Claude mobile
    app automatically — run one search from your phone to confirm.
@@ -1245,6 +1247,7 @@ The agent docs are written around MCP tool names. **CLI flag names match MCP par
 | `cerefox_get_document` | `cerefox document get <document-id> --version-id <vid> --requestor <name>` |
 | `cerefox_list_versions` | `cerefox document version list <document-id> --requestor <name>` |
 | `cerefox_list_projects` | `cerefox project list --requestor <name>` |
+| `cerefox_set_document_metadata` | `cerefox document set-metadata <document-id> --set key=value` (also `--remove key`, `--json '{...}'`, `--replace`) |
 | `cerefox_set_document_projects` | `cerefox document set-projects <document-id> <name...> --author <a> --author-type user\|agent` (or `--clear`) |
 | `cerefox_list_metadata_keys` | `cerefox metadata keys` |
 | `cerefox_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --project-name <n> --requestor <name>` |

package/docs/guides/operational-cost.md

@@ -74,7 +74,7 @@ paths go through **Edge Functions**, which the free tier caps at 500,000/month:
 500K/month is generous for a single human-driven agent. But **automated or
 high-frequency agents on the remote path** can approach it. The lever: point those
 agents at the **local stdio MCP server** (`cerefox mcp`) instead of the remote Edge
-Function — it exposes the identical 12 core tools (plus the 4 relation tools when enabled), talks to the Data API directly, and
+Function — it exposes the identical 13 core tools (plus the 4 relation tools when enabled), talks to the Data API directly, and
 costs **zero** Edge Function invocations (bonus: lower latency, and it works offline
 against a reachable database). If you do exceed the free EF quota, Supabase's Pro
 plan ($25/mo, 2M invocations included) is the next step.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Cerefox — 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",