@cerefox/memory 1.4.0 → 1.6.0

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
 
@@ -603,3 +603,91 @@ printf '...new content...' \
 cerefox audit list --json --limit 1000 --requestor "claude-code" \
   | jq 'select(.author_type == "agent")'
 ```
+
+## Timestamps are UTC
+
+Every timestamp Cerefox returns — `created_at` on audit entries, version
+history, document metadata — is **UTC**, and now carries its `Z` marker so it
+cannot be mistaken for local time.
+
+**When you write a date into a document's CONTENT, use your own clock, not a
+Cerefox timestamp.** These are different things: a timestamp records when the
+server stored something; a date in a log entry or a heading is authored content
+and belongs to your timezone. An agent working a Pacific afternoon read
+`2026-08-11` from version history, wrote "8/11" into its entries, and put a
+day's work in the future — the timestamp was correct, and copying it into
+content was not.
+
+Cerefox deliberately does not convert to local time on the API or MCP paths.
+"Local" has no server-side meaning: the remote MCP server runs in a cloud
+function whose local time *is* UTC, while a local MCP server runs in yours, so
+the same document would report two different times depending on transport. The
+web UI converts because a browser knows the viewer's timezone; nothing
+server-side does.
+
+## Mistakes that have actually happened
+
+Each of these comes from a real agent session, and each is easy to make.
+
+- **`cerefox_ingest` always replaces the ENTIRE document.** Never a section.
+  Before sending, check that the tool name matches the intent: if the intent is
+  "change one section", the call is `cerefox_edit` with `replace_section`. A
+  section-sized edit sent as a full ingest truncated a 13,000-character index to
+  a single word. It was recovered from version history within the minute, but
+  only because it was noticed immediately.
+
+- **Do not include the anchor's own heading in your text.** `replace_section`
+  keeps the heading and `insert` places your text inside the section, so
+  including it produces two. This is now refused rather than silently applied,
+  but the shape is worth knowing: it happened twice in one session, the second
+  time while trying to repair the first. A *deeper* sub-heading inside your text
+  is fine.
+
+- **Content between sections belongs to the section ABOVE it.** A section runs
+  to the next heading of the same or higher level, so a `---` rule, a note, or
+  any trailing text sitting just above the next heading is part of the section
+  before it — even when it visually reads as belonging below. Replacing that
+  section takes it too. An agent hit exactly this: a `---` that separated two
+  major sections disappeared when the section above it was replaced. The write
+  was correct by the addressing rules; the surprise is that "the end of this
+  section" is further down the page than it looks. Note the loss warning will
+  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.
+
+- **A rejected batch is safe.** Operations in one `cerefox_edit` are
+  all-or-nothing: if any is invalid, nothing is written. A refusal costs you a
+  retry, not data — so prefer one call for changes that belong together, and do
+  not split a batch to "make it more likely to succeed".
+
+- **Read before replacing.** `cerefox_get_document(section: "## Heading")`
+  returns exactly what a `replace_section` on that anchor would overwrite. Use it
+  for any section you did not write in this session. The outline gives a
+  section's *size*, never its *text*.
+
+- **Verify after writing** — read the result back before reporting success, and
+  report what the read actually shows.
+
+- **Partial edits cannot change a document's stored TITLE.** `rename_section`
+  changes a heading inside the content; the title is a separate field and still
+  needs `cerefox_ingest`.
+
+- **If a capability seems missing from one server, suspect your client first.**
+  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
+  such report so far has been a stale client.

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) |
@@ -135,3 +137,91 @@ Same operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/g
 - Reads: `--requestor "<your-name>"`
 
 Or have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.
+
+## Timestamps are UTC
+
+Every timestamp Cerefox returns — `created_at` on audit entries, version
+history, document metadata — is **UTC**, and now carries its `Z` marker so it
+cannot be mistaken for local time.
+
+**When you write a date into a document's CONTENT, use your own clock, not a
+Cerefox timestamp.** These are different things: a timestamp records when the
+server stored something; a date in a log entry or a heading is authored content
+and belongs to your timezone. An agent working a Pacific afternoon read
+`2026-08-11` from version history, wrote "8/11" into its entries, and put a
+day's work in the future — the timestamp was correct, and copying it into
+content was not.
+
+Cerefox deliberately does not convert to local time on the API or MCP paths.
+"Local" has no server-side meaning: the remote MCP server runs in a cloud
+function whose local time *is* UTC, while a local MCP server runs in yours, so
+the same document would report two different times depending on transport. The
+web UI converts because a browser knows the viewer's timezone; nothing
+server-side does.
+
+## Mistakes that have actually happened
+
+Each of these comes from a real agent session, and each is easy to make.
+
+- **`cerefox_ingest` always replaces the ENTIRE document.** Never a section.
+  Before sending, check that the tool name matches the intent: if the intent is
+  "change one section", the call is `cerefox_edit` with `replace_section`. A
+  section-sized edit sent as a full ingest truncated a 13,000-character index to
+  a single word. It was recovered from version history within the minute, but
+  only because it was noticed immediately.
+
+- **Do not include the anchor's own heading in your text.** `replace_section`
+  keeps the heading and `insert` places your text inside the section, so
+  including it produces two. This is now refused rather than silently applied,
+  but the shape is worth knowing: it happened twice in one session, the second
+  time while trying to repair the first. A *deeper* sub-heading inside your text
+  is fine.
+
+- **Content between sections belongs to the section ABOVE it.** A section runs
+  to the next heading of the same or higher level, so a `---` rule, a note, or
+  any trailing text sitting just above the next heading is part of the section
+  before it — even when it visually reads as belonging below. Replacing that
+  section takes it too. An agent hit exactly this: a `---` that separated two
+  major sections disappeared when the section above it was replaced. The write
+  was correct by the addressing rules; the surprise is that "the end of this
+  section" is further down the page than it looks. Note the loss warning will
+  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.
+
+- **A rejected batch is safe.** Operations in one `cerefox_edit` are
+  all-or-nothing: if any is invalid, nothing is written. A refusal costs you a
+  retry, not data — so prefer one call for changes that belong together, and do
+  not split a batch to "make it more likely to succeed".
+
+- **Read before replacing.** `cerefox_get_document(section: "## Heading")`
+  returns exactly what a `replace_section` on that anchor would overwrite. Use it
+  for any section you did not write in this session. The outline gives a
+  section's *size*, never its *text*.
+
+- **Verify after writing** — read the result back before reporting success, and
+  report what the read actually shows.
+
+- **Partial edits cannot change a document's stored TITLE.** `rename_section`
+  changes a heading inside the content; the title is a separate field and still
+  needs `cerefox_ingest`.
+
+- **If a capability seems missing from one server, suspect your client first.**
+  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
+  such report so far has been a stale client.

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