@cerefox/memory 1.5.0 → 1.6.0

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.5.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",