@cerefox/memory 1.14.4 → 1.15.0-beta.1

package/AGENT_GUIDE.md

@@ -481,7 +481,7 @@ changing.
 3. **Always set `author`** to your agent name for attribution, on reads and writes alike. Every tool takes the same `author` parameter, no exceptions. (`requestor` is still accepted on every tool as the pre-1.13.1 alias, so older configurations keep working.)
 4. **Use the `document_id` from search results** for `cerefox_get_document`, `cerefox_list_versions`, and targeted `cerefox_ingest` updates.
 5. **Add metadata**: at minimum `type` (e.g., "research", "decision-log") and `status` ("active", "draft").
-6. **Write structured Markdown** with H1/H2/H3 headings. The chunker uses heading structure.
+6. **Name the document for what it is about, then write structured Markdown** with H1/H2/H3 headings. The title is weighted more heavily than the body and reaches every chunk's embedding, so it is the single biggest lever on whether this document is found later. See "How titles affect search" below. The chunker uses heading structure.
 7. **Distill, don't dump.** Summaries > transcripts. Decisions > discussions. Insights > raw data.
 8. **Prove freshness on updates.** Pass `expected_content_hash` (the hash you read) on every content update. On conflict: re-read → merge → retry. Never `last_write_wins` your way out of a conflict.
 
@@ -500,6 +500,54 @@ Call `cerefox_list_metadata_keys` for the current list -- conventions evolve.
 
 ---
 
+## How titles affect search
+
+A Cerefox document's title is not just a label. It is indexed, and it is
+indexed **twice over**, which makes it the strongest single influence on
+whether a document is found later.
+
+**Keyword search.** When a document is written, each chunk's full-text vector
+is built from three parts at two weights: the **document title at weight A**,
+the **chunk's own heading at weight A**, and the **chunk body at weight B**.
+Postgres ranks weight-A matches above weight-B ones, so a query term that
+appears in the title lifts the whole document above one where the same term
+appears only in the prose.
+
+**Semantic search.** Every chunk is embedded as `# {document title}` followed
+by its heading breadcrumb and its text. The stored content is untouched, but
+the vector each chunk is retrieved by is coloured by the title. A document
+called "Notes" contributes nothing to any of its chunks' vectors; a document
+called "Postgres connection pooling limits on the free tier" contributes to
+all of them.
+
+### What to do about it
+
+- **Title with the words a future searcher would use.** Distinctive nouns over
+  generic labels. "Cerefox Response Size Limits" is findable; "Notes",
+  "Update 3", "Meeting" and "Misc" are not, and they dilute every chunk they
+  are attached to.
+- **Put the subject in the title, not only in the body.** If the document is
+  about one system, one decision or one incident, name it. Search cannot boost
+  a term that is not there.
+- **Do not stuff.** The title is also what a human reads in a result list and
+  in the web UI. A keyword-crammed title is worse than a clear one: relevance
+  is not the only thing a title has to do.
+- **Fixing a bad title is cheap.** Renaming a document re-computes the
+  full-text vectors and re-embeds its current chunks, so the improvement
+  applies to everything already stored. If you meet a document whose title
+  does not describe it, say so, or fix it.
+- **Titles cannot be changed by a partial edit.** `rename_section` changes a
+  heading inside the content; the stored title is a separate field and needs
+  `cerefox_ingest` (with `document_id` and `expected_content_hash`).
+
+### Why this matters more for you than for a human
+
+A person browsing a list can open three plausible documents and skim. An agent
+usually takes the top result, and is working against a byte budget that may
+admit only one. A precise title is what puts the right document in that slot.
+
+---
+
 ## Writing linkable content
 
 Documents you ingest may contain markdown links to other Cerefox documents. The Cerefox web UI intercepts these links at click time and resolves them to the target document. The resolution happens entirely in the browser; the stored markdown is untouched. (User-facing overview of the whole linking system, including *why* long ids corrupt during regeneration: [`docs/guides/linking.md`](docs/guides/linking.md).)

package/AGENT_QUICK_REFERENCE.md

@@ -7,7 +7,7 @@ Cerefox is a persistent, shared knowledge base. You have **15 core MCP tools** (
 | Tool | Purpose | Key params |
 |------|---------|------------|
 | `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `author` |
-| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |
+| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 10), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |
 | `cerefox_insert` | **Add** to a document without resending it. Cannot destroy content. | `document_id`, `text`, `position` (`end_of_document`/`end_of_section`/`after_heading`/`before_heading`), `expected_content_hash` (required), `anchor_heading` (unless `end_of_document`), `section_part`, `author` |
 | `cerefox_edit` | **Change** parts of a document: 1..n operations applied atomically | `document_id`, `operations` (`insert`/`replace_section`/`delete_section`/`rename_section`), `expected_content_hash` (required), `author` |
 | `cerefox_delete_document` | **Soft**-delete a document (to trash; excluded from search; permanent purge is human-only) | `document_id`, `expected_content_hash` (**required** — a delete must follow a read), `reason` (recorded in the audit log — give one), `author` |
@@ -78,7 +78,7 @@ recoverable answer, not a failure: retry with what it gave you.
 4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.
 5. **`max_bytes` has to fit a whole document.** Search returns COMPLETE documents, so a budget smaller than the top hit fits nothing. You get a header-only list saying so (never "No results found." — that means the store really has nothing). Raise `max_bytes`, or read one document with `cerefox_get_document` using `outline: true` or `section`.
 6. **Add metadata** -- at minimum `type` ("decision-log", "research", "design-doc") and `status` ("active", "draft").
-7. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.
+7. **Write for retrieval: the title does real work.** The document title is indexed at the **highest weight** *and* prepended to every chunk before it is embedded, so it steers both halves of hybrid search (keyword and semantic) for every chunk in the document. Name the document with the distinctive terms someone would actually search for -- "Cerefox Response Size Limits", not "Notes" or "Update 3". Renaming re-indexes and re-embeds, so correcting a vague title is cheap and takes effect immediately. Inside the content, write structured Markdown with H1/H2/H3 headings: the chunker follows them, and a chunk's own heading carries the same weight as the title.
 8. **Deletes are soft (recoverable); permanent purge is web-UI-only.** `cerefox_delete_document` requires the document's `content_hash` as you read it (read before you delete) and takes a `reason` — give one; it is what the human reviewing the trash sees. `cerefox_restore_document` undoes a mistaken delete (also audited, also takes a `reason`). Always surface deletes AND restores to the user. Once a human purges from the web UI, the document is gone for good.
 9. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. **The server validates `](uuid)` links on every write** (v1.7.0): a link to a nonexistent id rejects the write, naming the offender — that means you mangled the UUID; re-read the source and correct it, do not retry unchanged. Example ids go in backticks (code is not validated). `[[Wikilinks]]` may dangle. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.
 10. **Concurrency: content updates require `expected_content_hash`.** Pass the `content_hash` you last saw — every read shows one (`cerefox_get_document` incl. outline mode, `cerefox_search`, `cerefox_metadata_search`) and **every write returns the new one, including create** (v1.3.0, #189), so after writing you already hold the token for your next edit; no re-read needed. If it's stale you get a **conflict** — re-read the document, merge your changes into the latest content, retry with the new hash. **Never resolve a conflict by overwriting blindly** — the current content includes another writer's work. `last_write_wins: true` skips the check; use it ONLY when an external source of truth makes conflicts meaningless (file re-sync), never to silence a conflict.

package/README.md

@@ -57,7 +57,7 @@ You deploy the server side with this package's CLI — `cerefox server deploy` s
 |---|---|---|
 | A **Supabase project** | Hosts Postgres + pgvector + Edge Functions. Free tier is enough for most personal use. | [supabase.com](https://supabase.com) → New project |
 | An **embedding API key** | OpenAI `text-embedding-3-small` (the cloud backend's embedder; Cerefox Local can instead run a fully-offline local model). Pennies/month for typical personal use (see [operational-cost.md](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/operational-cost.md)). | Get an [OpenAI API key](https://platform.openai.com/api-keys). |
-| **Node ≥ 20** or **Bun ≥ 1.0** | Runtime for the `cerefox` bin (and the bundled `cerefox mcp` server). | [nodejs.org](https://nodejs.org) · [bun.sh](https://bun.sh). The one-line installer below bootstraps Bun if neither is present. |
+| **Node ≥ 24** or **Bun ≥ 1.0** | Runtime for the `cerefox` bin (and the bundled `cerefox mcp` server). | [nodejs.org](https://nodejs.org) · [bun.sh](https://bun.sh). The one-line installer below bootstraps Bun if neither is present. |
 
 ### One-time server-side setup (~10 min — no clone needed)