@cerefox/memory 1.16.1 → 1.17.1

package/AGENT_GUIDE.md

@@ -52,6 +52,8 @@ Find documents using hybrid search (full-text + semantic vector similarity).
 **Results format**: Each result shows `## Title [id: <uuid>] (score: X.XXX)` followed by content (in `hybrid` and `fts` modes the heading also carries the section path and the chunk index: `## Title › Section › Subsection [id: <uuid>] (chunk 4) (score: …)`).
 Save the `document_id` from `[id: ...]` -- you need it for `cerefox_get_document` and `cerefox_ingest` updates.
 
+**Reading scores**: in `docs` and `hybrid` modes a score is between 0 and 1 (since v1.17.0; scores above 1 came from older servers). Use it to compare results within one response, not across queries: a short or unusual phrasing scores lower than a full title even when it finds the same document. If a search returns a below-confidence notice, the results are best guesses, so try another phrasing before concluding the knowledge isn't there.
+
 For large documents, results may be partial (`is_partial` flag). Use `cerefox_get_document` with the ID to get the full text.
 
 **Rule**: Always search before answering questions about stored knowledge. Always search before ingesting to check for duplicates.
@@ -557,7 +559,7 @@ Documents you ingest may contain markdown links to other Cerefox documents. The
 **For any cross-reference you author, use the target document's UUID.** Period.
 
 ```markdown
-[Opportunity Index](c937b70f-77af-43d3-b9bc-9f31e0d2041d)
+[Q3 Goals](3f2b9c1e-8a47-4d2e-9b6a-1c5e7d0a4f82)
 ```
 
 **The server validates these links on every write (v1.7.0, #214).** A write
@@ -606,7 +608,7 @@ The resolver also accepts three other link forms, but **agents should not write
 |---|---|---|
 | Repo-relative path | `[Quickstart](docs/guides/quickstart.md)` | Only when the target has a `source_path` from repo ingest. Don't construct manually. |
 | Basename only | `[Quickstart](quickstart.md)` | Same — best-effort path fallback. Don't construct manually. |
-| Angle-bracket title | `[Career Coach](<Career Coach: Lisa Nichols>)` | **Fragile**. Breaks on titles containing colons, parentheses, ampersands, brackets, or other punctuation. Web UI's URL sanitizer strips suspicious-looking URLs (e.g. anything before a `:` that looks like a scheme) → link silently navigates to current page. **Never use this form in agent-authored content.** |
+| Angle-bracket title | `[Release Notes](<Release Notes: Version 2>)` | **Fragile**. Breaks on titles containing colons, parentheses, ampersands, brackets, or other punctuation. Web UI's URL sanitizer strips suspicious-looking URLs (e.g. anything before a `:` that looks like a scheme) → link silently navigates to current page. **Never use this form in agent-authored content.** |
 
 If you're tempted to write `[Title With Spaces](<Title With Spaces>)` because you don't have the ID, **do an extra `cerefox_search` and use the ID instead**. The one extra tool call is much cheaper than the user encountering a broken link.
 
@@ -617,8 +619,8 @@ The `[Link Text](target)` syntax has two halves:
 - **Link text** (`[…]`): what the human reader sees. Use the actual title.
 - **Target** (`(…)`): what the resolver consumes. Always a UUID for agent-authored content.
 
-Bad: `[c937b70f-77af-...](c937b70f-77af-...)` — opaque to the reader.
-Good: `[Job Hunting - Opportunity Index](c937b70f-77af-43d3-b9bc-9f31e0d2041d)`.
+Bad: `[3f2b9c1e-8a47-...](3f2b9c1e-8a47-...)` — opaque to the reader.
+Good: `[Quarterly Planning - Q3 Goals](3f2b9c1e-8a47-4d2e-9b6a-1c5e7d0a4f82)`.
 
 ### What you don't need to do
 

package/AGENT_QUICK_REFERENCE.md

@@ -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 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.
+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. Write the characters themselves: `&` and `<>`, never `&amp;` or `&lt;&gt;` (entities are stored literally and the write reply will say so). 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; so is one auto-purged after `trash_retention_days`, if the operator has turned trash auto-purge on.
 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.