@cerefox/memory 1.5.0 → 1.6.1

package/AGENT_GUIDE.md

@@ -15,7 +15,7 @@ It is not a message bus -- it is curated, versioned, searchable memory backed by
 
 You'll be using **one** of these — whichever your user (or the harness) has configured:
 
-1. **MCP tools (default)** — 12 named tools (`cerefox_search`, `cerefox_ingest`, …, `cerefox_get_help`) exposed by either a local MCP server (`@cerefox/memory` via npm, run as `cerefox mcp`) or the remote `cerefox-mcp` Edge Function. Tool names and parameters are documented in **The 12 Tools** below. This is the recommended path for purpose-built agent clients.
+1. **MCP tools (default)** — 12 named tools (`cerefox_search`, `cerefox_ingest`, …, `cerefox_get_help`) exposed by either a local MCP server (`@cerefox/memory` via npm, run as `cerefox mcp`) or the remote `cerefox-mcp` Edge Function. Tool names and parameters are documented in **The 13 Tools** below. This is the recommended path for purpose-built agent clients.
 2. **Shell CLI (Bash tool)** — the same operations exposed as a local `cerefox …` command (the TypeScript CLI from `@cerefox/memory`, resource-verb shape — e.g. `cerefox document get`, `cerefox project list`), invoked via your Bash tool. Used when your user prefers not to install/configure an MCP server. The semantics are identical; only the surface differs. See **Using Cerefox via the CLI** near the bottom of this guide for the MCP-tool → CLI-command mapping and the small list of behavioural differences.
 
 If you're not sure which mode you're in: check whether `cerefox_search` shows up in your tool list. If yes, use MCP. If no, ask your user where the Cerefox checkout lives — they'll have told you, typically in `CLAUDE.md`, `AGENTS.md`, or an equivalent project memory file.
@@ -34,7 +34,7 @@ The tool is intentionally MCP-only so an agent that has been dropped into Cerefo
 
 ---
 
-## The 12 Tools
+## The 13 Tools
 
 ### cerefox_search
 
@@ -654,6 +654,13 @@ Each of these comes from a real agent session, and each is easy to make.
   not catch it if your replacement text is longer than what it replaced, since
   there is then no net loss to report.
 
+- **To change only tags, use `cerefox_set_document_metadata`, never `cerefox_ingest`.**
+  Ingest replaces the whole document, so re-sending it to set one tag carries the
+  full transcription risk for no reason. The metadata tool merges: the keys you
+  pass are set, everything else is left alone, so you do not need to read the
+  document first and cannot drop a tag another agent set. Pass `null` as a value
+  to remove a key.
+
 - **Never partial-edit to fix a partial edit.** If a write leaves unexpected
   structure, stop. Use `cerefox_list_versions`, retrieve the last good version,
   and re-ingest cleanly. Repairing edits with more edits compounds the damage.
@@ -676,8 +683,10 @@ Each of these comes from a real agent session, and each is easy to make.
   needs `cerefox_ingest`.
 
 - **If a capability seems missing from one server, suspect your client first.**
-  Local and remote run the same code. Call `cerefox_get_help(topic: "server")`:
-  it reports the server's own version and the operations it registers. If that
+  Local and remote run the same code. **Every `cerefox_get_help()` response
+  begins with the server's version and the operations it registers** — you do
+  not need a special topic, and the *absence* of that block is itself an answer:
+  a server that does not print it predates v1.5.0. If that
   disagrees with your tool list, the client is holding a list it fetched before
   an upgrade — clients cache it at connect time. Ask the user to restart the
   client. Do not record a capability difference between servers as a fact; every

package/AGENT_QUICK_REFERENCE.md

@@ -1,6 +1,6 @@
 # Cerefox Knowledge Base -- Agent Quick Reference
 
-Cerefox is a persistent, shared knowledge base. You have **16 MCP tools** (15 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for "How AI Agents Use Cerefox" or call `cerefox_get_help` to retrieve this content over MCP.
+Cerefox is a persistent, shared knowledge base. You have **17 MCP tools** (16 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for "How AI Agents Use Cerefox" or call `cerefox_get_help` to retrieve this content over MCP.
 
 ## Tools
 
@@ -19,6 +19,7 @@ Cerefox is a persistent, shared knowledge base. You have **16 MCP tools** (15 of
 | `cerefox_metadata_search` | Find or list docs by metadata, project, or time (no text query) | `metadata_filter`, `project_name` (list a project's docs), `updated_since`, `include_content` — **at least one** of metadata_filter/project_name/updated_since/created_since |
 | `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |
 | `cerefox_list_projects` | List all projects | (none required) |
+| `cerefox_set_document_metadata` | Change tags WITHOUT resending content. **Merges** by default; a `null` value removes a key | `document_id`, `metadata` (required), `replace` (rare: set exactly this object), `author` |
 | `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |
 | `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |
 | `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |
@@ -126,6 +127,7 @@ Same operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/g
 | `cerefox_get_relations` ⚑ | All relations touching a document, both directions | `document_id` |
 | `cerefox_get_neighbors` ⚑ | Walk the graph along ONE relation type | `document_id`, `rel_type` (required), `depth`, `from_time`, `to_time`, `limit` |
 | `cerefox_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --requestor "<your-name>"` (list a project: `cerefox document list --project <name>`) |
+| `cerefox_set_document_metadata` | `cerefox document set-metadata <id> --set key=value` (also `--remove key`, `--json '{...}'`, `--replace`) |
 | `cerefox_set_document_projects` | `cerefox document set-projects <id> <name...> --author "<your-name>" --author-type agent` (or `--clear` to remove all) |
 | `cerefox_get_audit_log` | `cerefox audit list --requestor "<your-name>"` (add `--json` for scripted access) |
 | `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |
@@ -186,6 +188,13 @@ Each of these comes from a real agent session, and each is easy to make.
   not catch it if your replacement text is longer than what it replaced, since
   there is then no net loss to report.
 
+- **To change only tags, use `cerefox_set_document_metadata`, never `cerefox_ingest`.**
+  Ingest replaces the whole document, so re-sending it to set one tag carries the
+  full transcription risk for no reason. The metadata tool merges: the keys you
+  pass are set, everything else is left alone, so you do not need to read the
+  document first and cannot drop a tag another agent set. Pass `null` as a value
+  to remove a key.
+
 - **Never partial-edit to fix a partial edit.** If a write leaves unexpected
   structure, stop. Use `cerefox_list_versions`, retrieve the last good version,
   and re-ingest cleanly. Repairing edits with more edits compounds the damage.
@@ -208,8 +217,10 @@ Each of these comes from a real agent session, and each is easy to make.
   needs `cerefox_ingest`.
 
 - **If a capability seems missing from one server, suspect your client first.**
-  Local and remote run the same code. Call `cerefox_get_help(topic: "server")`:
-  it reports the server's own version and the operations it registers. If that
+  Local and remote run the same code. **Every `cerefox_get_help()` response
+  begins with the server's version and the operations it registers** — you do
+  not need a special topic, and the *absence* of that block is itself an answer:
+  a server that does not print it predates v1.5.0. If that
   disagrees with your tool list, the client is holding a list it fetched before
   an upgrade — clients cache it at connect time. Ask the user to restart the
   client. Do not record a capability difference between servers as a fact; every

package/README.md

@@ -29,7 +29,7 @@ This package contains a single binary, **`cerefox`**:
 | Subcommand | What it does |
 |---|---|
 | `cerefox <command>` | CLI — search, ingest, list, version-history, audit-log, lifecycle (`init`, `doctor`, `configure-agent`, `self-update`). Callable from any directory. |
-| `cerefox mcp` | Local stdio MCP server. Drop-in for Claude Code, Cursor, Claude Desktop, Codex CLI, Gemini CLI. Exposes the same 12 core MCP tools as the remote `cerefox-mcp` Edge Function, plus 4 document-relation tools that stay hidden until enabled. |
+| `cerefox mcp` | Local stdio MCP server. Drop-in for Claude Code, Cursor, Claude Desktop, Codex CLI, Gemini CLI. Exposes the same 13 core MCP tools as the remote `cerefox-mcp` Edge Function, plus 4 document-relation tools that stay hidden until enabled. |
 | `cerefox web` | Local web app at `http://localhost:8000` — React UI for browsing, searching, editing, and ingesting documents. Backed by an in-process Hono server that exposes the same `/api/v1/*` REST surface as the bundled Edge Functions. |
 
 > **What this package isn't:** the source of truth for Cerefox's architecture
@@ -148,10 +148,11 @@ For manual configuration (any other MCP client), the canonical entry is:
 ```
 
 Once configured, any of these clients can search + write your Cerefox KB via
-the 12 core MCP tools (`cerefox_search`, `cerefox_ingest`, `cerefox_insert`,
+the 13 core MCP tools (`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_set_document_metadata`,
 `cerefox_get_audit_log`, `cerefox_get_help`).
 
 `cerefox_insert` and `cerefox_edit` change part of a document without resending