@cerefox/memory 1.1.1 → 1.2.1

package/dist/bin/cerefox.js

@@ -7438,7 +7438,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "1.1.1";
+var PKG_VERSION = "1.2.1";
 var init_meta = () => {};
 
 // ../../_shared/config/paths.ts
@@ -25858,7 +25858,7 @@ async function checkServerCompatibility(opts) {
 var COMPATIBILITY;
 var init_compatibility = __esm(() => {
   COMPATIBILITY = {
-    minSchema: "0.10.3",
+    minSchema: "0.10.5",
     minEdgeFunctions: "0.6.0"
   };
 });
@@ -55148,6 +55148,12 @@ var init_audit_log = __esm(() => {
   auditLogTool = {
     name: "cerefox_get_audit_log",
     description: "Retrieve audit log entries showing who changed what and when. Supports filtering by document, author, operation type, and time range. Returns entries with document titles, author attribution, size changes, and descriptions.",
+    annotations: {
+      title: "Read audit log",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     inputSchema: {
       type: "object",
       required: [],
@@ -55346,6 +55352,13 @@ var init_relations = __esm(() => {
   setRelationTool = {
     name: "cerefox_set_relation",
     description: "Link two documents with a typed, directed relation (source → target). " + `Known types with behaviour: ${KNOWN_TYPES}. Symmetric types (related_to, ` + "contradicts, duplicates) write both directions. `supersedes` marks the target " + "superseded; `contradicts` marks both stale. Any other type string is accepted " + "and stored, just without special behaviour. Re-setting the same edge updates it.",
+    annotations: {
+      title: "Link two documents",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     inputSchema: {
       type: "object",
       required: ["source_id", "target_id", "rel_type"],
@@ -55369,6 +55382,13 @@ var init_relations = __esm(() => {
   deleteRelationTool = {
     name: "cerefox_delete_relation",
     description: "Remove a typed relation between two documents. Symmetric types remove both " + "directions. Lifecycle status set by an earlier relation is NOT reverted.",
+    annotations: {
+      title: "Remove a relation",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     inputSchema: {
       type: "object",
       required: ["source_id", "target_id", "rel_type"],
@@ -55385,6 +55405,12 @@ var init_relations = __esm(() => {
   getRelationsTool = {
     name: "cerefox_get_relations",
     description: "List every relation touching a document, in both directions (→ outbound, " + "← inbound). Shows each neighbour's title and lifecycle status, so an agent " + "can tell whether retrieved knowledge has been superseded or contradicted.",
+    annotations: {
+      title: "List a document's relations",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     inputSchema: {
       type: "object",
       required: ["document_id"],
@@ -55398,6 +55424,12 @@ var init_relations = __esm(() => {
   getNeighborsTool = {
     name: "cerefox_get_neighbors",
     description: "Walk the relation graph outward from a document along ONE relation type. " + "Use after cerefox_get_relations shows which types exist. depth > 1 follows " + "chains (useful for follows / reply_to); cycles terminate safely. Optional " + "from_time / to_time filter neighbours by their creation time.",
+    annotations: {
+      title: "Walk the relation graph",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     inputSchema: {
       type: "object",
       required: ["document_id", "rel_type"],
@@ -55450,6 +55482,12 @@ var init_get_document = __esm(() => {
   getDocumentTool = {
     name: "cerefox_get_document",
     description: "Retrieve the full reconstructed content of a document. Pass version_id to retrieve an archived version; omit it (or pass null) for the current version. Version UUIDs are returned by cerefox_list_versions. The response header includes the document's current content_hash — pass it back as expected_content_hash when updating via cerefox_ingest (optimistic concurrency).",
+    annotations: {
+      title: "Read document",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     inputSchema: {
       type: "object",
       required: ["document_id"],
@@ -55535,6 +55573,12 @@ var init_get_help = __esm(() => {
   getHelpTool = {
     name: "cerefox_get_help",
     description: "Retrieve Cerefox's own agent-usage guidance (the AGENT_QUICK_REFERENCE.md content). Call with no arguments to get the full reference + a section index. Call with `topic` to get a single section (case-insensitive substring match against H2 headings). Use this whenever you're uncertain about Cerefox conventions — link forms, project-membership semantics, update workflows, etc.",
+    annotations: {
+      title: "Read Cerefox conventions",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -55789,6 +55833,13 @@ var init_ingest = __esm(() => {
   ingestTool = {
     name: "cerefox_ingest",
     description: "Save a note or document to the Cerefox knowledge base.",
+    annotations: {
+      title: "Save or update a document",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: false
+    },
     inputSchema: {
       type: "object",
       required: ["title", "content"],
@@ -55853,6 +55904,12 @@ var init_list_metadata_keys = __esm(() => {
   listMetadataKeysTool = {
     name: "cerefox_list_metadata_keys",
     description: "List all metadata keys currently in use across documents in the Cerefox knowledge base. Returns each key with its document count and up to 5 example values.",
+    annotations: {
+      title: "List metadata keys",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -55894,6 +55951,12 @@ var init_list_projects = __esm(() => {
   listProjectsTool = {
     name: "cerefox_list_projects",
     description: "List all projects with their names and IDs. Use this to discover available projects before filtering by project_name in other tools.",
+    annotations: {
+      title: "List projects",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -55939,6 +56002,12 @@ var init_list_versions = __esm(() => {
   listVersionsTool = {
     name: "cerefox_list_versions",
     description: "List all archived versions of a document, newest first. Returns version_id (use with cerefox_get_document), version_number, source, chunk_count, total_chars, and created_at.",
+    annotations: {
+      title: "List document versions",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     inputSchema: {
       type: "object",
       required: ["document_id"],
@@ -56032,6 +56101,12 @@ var init_metadata_search = __esm(() => {
   metadataSearchTool = {
     name: "cerefox_metadata_search",
     description: "Find or list documents by metadata key-value criteria without a text search term. Use to discover documents tagged with specific attributes, browse by taxonomy, retrieve messages/tasks by type and status, or list all documents in a project (pass project_name alone). At least one of metadata_filter, project_name, updated_since, or created_since must be supplied; results are ordered newest-updated first.",
+    annotations: {
+      title: "Find documents by metadata",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     inputSchema: {
       type: "object",
       properties: {
@@ -56192,6 +56267,12 @@ var init_search = __esm(() => {
   searchTool = {
     name: "cerefox_search",
     description: "Search the Cerefox personal knowledge base. Returns complete documents ranked by hybrid (FTS + semantic) relevance.",
+    annotations: {
+      title: "Search knowledge base",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     inputSchema: {
       type: "object",
       required: ["query"],
@@ -56277,6 +56358,13 @@ var init_set_document_projects = __esm(() => {
   setDocumentProjectsTool = {
     name: "cerefox_set_document_projects",
     description: "Set the document's project memberships to EXACTLY the given list. Destructive replace: any existing memberships not in this list are removed. Pass an empty list to clear all project memberships. Projects are looked up by name (case-insensitive); missing projects are created. Logged as update-metadata in the audit log — content is untouched. Use cerefox_ingest with project_names if you want to set memberships AND update content in one call. Use this tool when you only need to change project membership without re-writing the document body.",
+    annotations: {
+      title: "Replace project memberships",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
     inputSchema: {
       type: "object",
       required: ["document_id", "project_names"],
@@ -69491,7 +69579,8 @@ function buildServer() {
     tools: (await listEnabledTools(supabase)).map((t) => ({
       name: t.name,
       description: t.description,
-      inputSchema: t.inputSchema
+      inputSchema: t.inputSchema,
+      ...t.annotations ? { annotations: t.annotations } : {}
     }))
   }));
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
@@ -75610,8 +75699,8 @@ import { homedir as homedir6 } from "node:os";
 import { join as join9 } from "node:path";
 
 // ../../_shared/ef-meta/index.ts
-var EF_VERSION = "1.1.1";
-var EF_LAST_CHANGED = "1.1.0-beta.7";
+var EF_VERSION = "1.2.1";
+var EF_LAST_CHANGED = "1.2.0";
 
 // src/cli/util/checks.ts
 init_config();
@@ -76838,6 +76927,7 @@ class IngestionPipeline {
       text,
       title,
       source = "paste",
+      sourceLabel,
       sourcePath: sourcePathOpt,
       projectName,
       projectId,
@@ -76868,6 +76958,7 @@ class IngestionPipeline {
         text,
         title,
         source,
+        sourceLabel,
         projectIds: fullSetResolved,
         metadata,
         author,
@@ -76906,6 +76997,7 @@ class IngestionPipeline {
           text,
           title,
           source,
+          sourceLabel,
           projectIds: fullSetResolved,
           metadata,
           author,
@@ -76993,6 +77085,7 @@ class IngestionPipeline {
       text,
       title,
       source = "manual",
+      sourceLabel,
       projectId,
       projectIds,
       metadata,
@@ -77109,7 +77202,7 @@ class IngestionPipeline {
       contentFormat: CONTENT_FORMAT_BLIND_STITCH,
       author,
       authorType,
-      sourceLabel: source,
+      sourceLabel: sourceLabel ?? source,
       expectedContentHash: expectedContentHash ?? (forceRechunk && contentUnchanged ? existing.content_hash : null),
       lastWriteWins
     });
@@ -78286,7 +78379,8 @@ async function action28(options) {
         text: doc2.full_content,
         title: doc2.doc_title,
         documentId: id,
-        source: "migrate-format",
+        source: doc2.doc_source,
+        sourceLabel: "migrate-format",
         author,
         authorType,
         expectedContentHash: doc2.content_hash,

package/dist/server-assets/_shared/ef-meta/index.ts

@@ -18,7 +18,7 @@
  * doesn't touch `supabase/functions/` leaves it alone).
  */
 
-export const EF_VERSION = "1.1.1";
+export const EF_VERSION = "1.2.1";
 
 /**
  * The most recent version whose EF-side SOURCE actually changed (#127).
@@ -28,7 +28,7 @@ export const EF_VERSION = "1.1.1";
  * `cut_release.ts` ONLY when EF source changed since the last tag; doctor
  * uses it to stay silent on label-only drift.
  */
-export const EF_LAST_CHANGED = "1.1.0-beta.7";
+export const EF_LAST_CHANGED = "1.2.0";
 
 /**
  * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp

package/dist/server-assets/_shared/mcp-tools/audit-log.ts

@@ -65,6 +65,13 @@ export const auditLogTool: ToolDefinition = {
   name: "cerefox_get_audit_log",
   description:
     "Retrieve audit log entries showing who changed what and when. Supports filtering by document, author, operation type, and time range. Returns entries with document titles, author attribution, size changes, and descriptions.",
+  // Read-only: touches nothing. Safe for a client to run without prompting.
+  annotations: {
+    title: "Read audit log",
+    readOnlyHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
     type: "object",
     required: [],

package/dist/server-assets/_shared/mcp-tools/get-document.ts

@@ -57,6 +57,13 @@ export const getDocumentTool: ToolDefinition = {
   name: "cerefox_get_document",
   description:
     "Retrieve the full reconstructed content of a document. Pass version_id to retrieve an archived version; omit it (or pass null) for the current version. Version UUIDs are returned by cerefox_list_versions. The response header includes the document's current content_hash — pass it back as expected_content_hash when updating via cerefox_ingest (optimistic concurrency).",
+  // Read-only: touches nothing. Safe for a client to run without prompting.
+  annotations: {
+    title: "Read document",
+    readOnlyHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
     type: "object",
     required: ["document_id"],

package/dist/server-assets/_shared/mcp-tools/get-help.ts

@@ -71,6 +71,13 @@ export const getHelpTool: ToolDefinition = {
   name: "cerefox_get_help",
   description:
     "Retrieve Cerefox's own agent-usage guidance (the AGENT_QUICK_REFERENCE.md content). Call with no arguments to get the full reference + a section index. Call with `topic` to get a single section (case-insensitive substring match against H2 headings). Use this whenever you're uncertain about Cerefox conventions — link forms, project-membership semantics, update workflows, etc.",
+  // Read-only: touches nothing. Safe for a client to run without prompting.
+  annotations: {
+    title: "Read Cerefox conventions",
+    readOnlyHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
     type: "object",
     properties: {

package/dist/server-assets/_shared/mcp-tools/ingest.ts

@@ -350,6 +350,17 @@ async function handler(
 export const ingestTool: ToolDefinition = {
   name: "cerefox_ingest",
   description: "Save a note or document to the Cerefox knowledge base.",
+  /** Destructive: `project_names` REPLACES the document's project memberships, and
+ *  memberships have no version history — a partial list silently drops the rest.
+ *  Content itself is version-snapshotted and guarded by expected_content_hash, so
+ *  the destructive part is the membership replace, not the body. */
+  annotations: {
+    title: "Save or update a document",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
   inputSchema: {
     type: "object",
     required: ["title", "content"],

package/dist/server-assets/_shared/mcp-tools/list-metadata-keys.ts

@@ -41,6 +41,13 @@ export const listMetadataKeysTool: ToolDefinition = {
   name: "cerefox_list_metadata_keys",
   description:
     "List all metadata keys currently in use across documents in the Cerefox knowledge base. Returns each key with its document count and up to 5 example values.",
+  // Read-only: touches nothing. Safe for a client to run without prompting.
+  annotations: {
+    title: "List metadata keys",
+    readOnlyHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
     type: "object",
     properties: {

package/dist/server-assets/_shared/mcp-tools/list-projects.ts

@@ -45,6 +45,13 @@ export const listProjectsTool: ToolDefinition = {
   name: "cerefox_list_projects",
   description:
     "List all projects with their names and IDs. Use this to discover available projects before filtering by project_name in other tools.",
+  // Read-only: touches nothing. Safe for a client to run without prompting.
+  annotations: {
+    title: "List projects",
+    readOnlyHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
     type: "object",
     properties: {

package/dist/server-assets/_shared/mcp-tools/list-versions.ts

@@ -53,6 +53,13 @@ export const listVersionsTool: ToolDefinition = {
   name: "cerefox_list_versions",
   description:
     "List all archived versions of a document, newest first. Returns version_id (use with cerefox_get_document), version_number, source, chunk_count, total_chars, and created_at.",
+  // Read-only: touches nothing. Safe for a client to run without prompting.
+  annotations: {
+    title: "List document versions",
+    readOnlyHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
     type: "object",
     required: ["document_id"],

package/dist/server-assets/_shared/mcp-tools/metadata-search.ts

@@ -124,6 +124,13 @@ export const metadataSearchTool: ToolDefinition = {
   name: "cerefox_metadata_search",
   description:
     "Find or list documents by metadata key-value criteria without a text search term. Use to discover documents tagged with specific attributes, browse by taxonomy, retrieve messages/tasks by type and status, or list all documents in a project (pass project_name alone). At least one of metadata_filter, project_name, updated_since, or created_since must be supplied; results are ordered newest-updated first.",
+  // Read-only: touches nothing. Safe for a client to run without prompting.
+  annotations: {
+    title: "Find documents by metadata",
+    readOnlyHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
     type: "object",
     properties: {

package/dist/server-assets/_shared/mcp-tools/relations.ts

@@ -81,6 +81,14 @@ export const setRelationTool: ToolDefinition = {
     "contradicts, duplicates) write both directions. `supersedes` marks the target " +
     "superseded; `contradicts` marks both stale. Any other type string is accepted " +
     "and stored, just without special behaviour. Re-setting the same edge updates it.",
+  /** Upsert: re-running with the same edge changes nothing. Adds an edge; removes nothing. */
+  annotations: {
+    title: "Link two documents",
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
     type: "object",
     required: ["source_id", "target_id", "rel_type"],
@@ -143,6 +151,14 @@ export const deleteRelationTool: ToolDefinition = {
   description:
     "Remove a typed relation between two documents. Symmetric types remove both " +
     "directions. Lifecycle status set by an earlier relation is NOT reverted.",
+  /** Removes an edge (and its mirror for symmetric types). Relations are not versioned, so the edge is gone. */
+  annotations: {
+    title: "Remove a relation",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
     type: "object",
     required: ["source_id", "target_id", "rel_type"],
@@ -203,6 +219,13 @@ export const getRelationsTool: ToolDefinition = {
     "List every relation touching a document, in both directions (→ outbound, " +
     "← inbound). Shows each neighbour's title and lifecycle status, so an agent " +
     "can tell whether retrieved knowledge has been superseded or contradicted.",
+  // Read-only: traversal only, mutates nothing.
+  annotations: {
+    title: "List a document's relations",
+    readOnlyHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
     type: "object",
     required: ["document_id"],
@@ -267,6 +290,13 @@ export const getNeighborsTool: ToolDefinition = {
     "Use after cerefox_get_relations shows which types exist. depth > 1 follows " +
     "chains (useful for follows / reply_to); cycles terminate safely. Optional " +
     "from_time / to_time filter neighbours by their creation time.",
+  // Read-only: traversal only, mutates nothing.
+  annotations: {
+    title: "Walk the relation graph",
+    readOnlyHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
     type: "object",
     required: ["document_id", "rel_type"],

package/dist/server-assets/_shared/mcp-tools/search.ts

@@ -192,6 +192,13 @@ export const searchTool: ToolDefinition = {
   name: "cerefox_search",
   description:
     "Search the Cerefox personal knowledge base. Returns complete documents ranked by hybrid (FTS + semantic) relevance.",
+  // Read-only: touches nothing. Safe for a client to run without prompting.
+  annotations: {
+    title: "Search knowledge base",
+    readOnlyHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
     type: "object",
     required: ["query"],

package/dist/server-assets/_shared/mcp-tools/set-document-projects.ts

@@ -72,6 +72,15 @@ export const setDocumentProjectsTool: ToolDefinition = {
   name: "cerefox_set_document_projects",
   description:
     "Set the document's project memberships to EXACTLY the given list. Destructive replace: any existing memberships not in this list are removed. Pass an empty list to clear all project memberships. Projects are looked up by name (case-insensitive); missing projects are created. Logged as update-metadata in the audit log — content is untouched. Use cerefox_ingest with project_names if you want to set memberships AND update content in one call. Use this tool when you only need to change project membership without re-writing the document body.",
+  /** Destructive by contract: any membership not in the list is removed, and an
+ *  empty list clears all of them. No version history for memberships. */
+  annotations: {
+    title: "Replace project memberships",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   inputSchema: {
     type: "object",
     required: ["document_id", "project_names"],

package/dist/server-assets/_shared/mcp-tools/types.ts

@@ -66,10 +66,44 @@ export interface ToolContext {
   accessPath: AccessPath;
 }
 
+/**
+ * MCP tool annotations (spec revision 2025-03-26).
+ *
+ * Hints that let a client reason about a tool BEFORE calling it. Without them a
+ * tool inherits the spec defaults `readOnlyHint: false` and
+ * `destructiveHint: true` — i.e. "may do something irreversible" — so declaring
+ * nothing tells every client that `cerefox_search` is as dangerous as a
+ * destructive write. The usual result is that users blanket-approve the server,
+ * which drains the meaning from the prompt on the tools that genuinely warrant
+ * one.
+ *
+ * These are hints from a server the client may not trust, so a client must not
+ * use them as a security boundary. They exist to inform UX, not to enforce it.
+ */
+export interface ToolAnnotations {
+  /** Human-readable label for UIs. */
+  title?: string;
+  /** The tool does not modify anything. */
+  readOnlyHint?: boolean;
+  /** The tool may perform IRREVERSIBLE updates. Only meaningful when the tool
+   *  is not read-only. Static per tool: if any argument shape can destroy, the
+   *  tool is destructive. */
+  destructiveHint?: boolean;
+  /** Repeated calls with the same arguments have no additional effect. */
+  idempotentHint?: boolean;
+  /** The tool reaches external entities (a web search) rather than a closed
+   *  domain. False throughout Cerefox: every tool talks to the operator's own
+   *  store. */
+  openWorldHint?: boolean;
+}
+
 export interface ToolDefinition {
   name: string;
   description: string;
   inputSchema: JsonSchema;
+  /** See `ToolAnnotations`. Required in practice: a unit test fails if a tool
+   *  omits it, so adding a tool forces the read-only/destructive decision. */
+  annotations?: ToolAnnotations;
   /** Returns the MCP `TextContent.text` body. Tools that fail throw; the
    *  consumer's request wrapper translates thrown errors into JSON-RPC
    *  `-32603` (internal error) responses, or `-32602` (invalid params)

package/dist/server-assets/db/migrations/0018_ingest_defers_retention_to_config.sql

@@ -0,0 +1,48 @@
+-- 0018_ingest_defers_retention_to_config.sql — make the store's retention policy
+-- actually take effect on the write path (#183, reported by @tdebasis).
+--
+-- v1.1.0 moved version retention into `cerefox_config` and changed
+-- `cerefox_snapshot_version` to default its parameters to NULL so that
+-- COALESCE(param, config, default) could fall through to the store's policy.
+--
+-- That half worked. `cerefox_ingest_document` — snapshot_version's ONLY caller —
+-- kept the pre-1.1.0 concrete defaults:
+--
+--     p_retention_hours   INT     DEFAULT 48
+--     p_cleanup_enabled   BOOLEAN DEFAULT TRUE
+--
+-- and passed them straight through. So snapshot_version never once received NULL
+-- on a real write, and never once consulted `cerefox_config`. The store-level
+-- switch was inert on the only path that matters.
+--
+-- Consequences, all silent:
+--
+--   * `version_cleanup_enabled = false` did nothing. Pruning ran anyway.
+--   * Migration 0016's fail-safe — which seeds `false` on existing stores during
+--     the 1.1.0 upgrade precisely so history could not be quietly discarded —
+--     was defeated by this.
+--   * `version_retention_hours` did nothing. The window stayed at 48 hours, not
+--     the configured value (or the 120h default from migration 0017).
+--   * The v1.1.0 release notes promised "Nothing is deleted." That was false.
+--
+-- The damage is per-document and latent rather than immediate: cleanup only runs
+-- for a document when THAT document is next written. So versions older than the
+-- window survive until their document is edited, then vanish. On the maintainer's
+-- store, 362 of 397 versions were older than 48h and still intact when this was
+-- found — every one of them was one edit away from being pruned.
+--
+-- Fix: `cerefox_ingest_document`'s parameters default to NULL, so the store's
+-- policy resolves. An explicit value still overrides for a single call.
+--
+-- Lives in rpcs.sql, which `cerefox server deploy` re-applies. This migration
+-- exists so the schema version moves and operators are told to redeploy.
+--
+-- Idempotent: safe to re-run.
+
+DO $$
+BEGIN
+    RAISE NOTICE
+        'Migration 0018: cerefox_ingest_document now defers version retention to '
+        'cerefox_config. Before this, version_cleanup_enabled and '
+        'version_retention_hours were silently ignored on every write (#183).';
+END $$;

package/dist/server-assets/db/migrations/0020_ingest_preserves_source.sql

@@ -0,0 +1,59 @@
+-- 0020_ingest_preserves_source.sql — stop content updates from silently
+-- overwriting a document's provenance (#191, reported by @tdebasis).
+--
+-- `cerefox_ingest_document`'s UPDATE branch assigned the source column
+-- unconditionally:
+--
+--     source      = p_source                              -- unconditional
+--     source_path = COALESCE(p_source_path, source_path)  -- preserved
+--     metadata    = COALESCE(p_metadata, metadata)        -- preserved
+--
+-- with `p_source TEXT DEFAULT 'agent'` in the signature. The two columns either
+-- side of it already implement the "absent means keep" rule — metadata got it in
+-- v0.11.1, after content updates without metadata were found to be wiping tags.
+-- source was left out of that fix.
+--
+-- Two consequences, both silent:
+--
+--   * Any caller that updates a document without passing p_source rewrites that
+--     document's source to the parameter default 'agent'. Nothing in the RPC's
+--     output, the audit entry, or the version row records that it happened: the
+--     audit operation is 'update-content', and version rows carry their own
+--     source label rather than the document's prior value.
+--   * `cerefox server migrate-format` hit this at corpus scale. It hardcoded
+--     source: "migrate-format" for every document it converted, even though it
+--     reads each document first and cerefox_get_document returns doc_source. A
+--     format conversion is not a change of origin, so every converted document
+--     lost the label it came in with.
+--
+-- Reported impact on one store: 1,317 documents rewritten to 'migrate-format' in
+-- a single run, 201 of which carried no metadata.source_agent and so had no
+-- other provenance field to fall back on. A second store on the same instance
+-- independently reported 509 of 553. Recovery required a point-in-time dump from
+-- before the run.
+--
+-- Fix: p_source defaults to NULL and the UPDATE branch coalesces, matching
+-- metadata and source_path exactly. The CREATE path keeps 'agent' as its
+-- concrete fallback via COALESCE(p_source, 'agent'), so new documents are
+-- unchanged. An explicit value still relabels, so deliberate callers are
+-- unaffected.
+--
+-- Note the distinction this preserves: p_source is the document's origin, while
+-- p_source_label records how a particular write was triggered and is stored on
+-- the version row. migrate-format now passes the document's own source for the
+-- former and keeps "migrate-format" for the latter, so the version history still
+-- shows which run performed the conversion.
+--
+-- Lives in rpcs.sql, which `cerefox server deploy` re-applies. This migration
+-- exists so the schema version moves and operators are told to redeploy.
+--
+-- Idempotent: safe to re-run.
+
+DO $$
+BEGIN
+    RAISE NOTICE
+        'Migration 0020: cerefox_ingest_document now preserves a document''s '
+        'source when p_source is omitted. Before this, any content update '
+        'without an explicit source silently rewrote provenance to ''agent'', '
+        'and migrate-format relabelled every document it converted (#191).';
+END $$;

package/dist/server-assets/db/rpcs.sql

@@ -1258,7 +1258,12 @@ $$;
 --
 -- Parameters:
 --   p_document_id     : NULL for create, UUID for update
---   p_title, p_source, p_source_path, p_content_hash : document fields
+--   p_title, p_source_path, p_content_hash : document fields
+--   p_source          : origin label. NULL = "not provided" → create uses
+--                       'agent', update keeps the existing source (#191). Pass a
+--                       value explicitly to relabel. Distinct from
+--                       p_source_label, which records how THIS write was
+--                       triggered and is stored on the version row.
 --   p_metadata        : JSONB metadata. NULL = "not provided" → create uses '{}',
 --                       update keeps the existing metadata (v0.11.1). Pass '{}'
 --                       explicitly to clear all metadata.
@@ -1268,8 +1273,10 @@ $$;
 --                        content, char_count, embedding (float[]), embedder (text)
 --   p_author, p_author_type : for audit entry
 --   p_source_label    : version source label for snapshot ('file','paste','agent','manual')
---   p_retention_hours : for version cleanup (default 48)
---   p_cleanup_enabled : whether version cleanup runs (default true)
+--   p_retention_hours : version-cleanup window. NULL (default) = use the store's
+--                       `version_retention_hours` from cerefox_config.
+--   p_cleanup_enabled : whether cleanup runs. NULL (default) = use the store's
+--                       `version_cleanup_enabled`.
 --   p_expected_content_hash : optimistic-concurrency token (iter-32). On the UPDATE
 --                       path this must equal the document's current content_hash —
 --                       the caller proves they based their edit on the live version.
@@ -1289,7 +1296,10 @@ DROP FUNCTION IF EXISTS cerefox_ingest_document(UUID, TEXT, TEXT, TEXT, TEXT, JS
 CREATE FUNCTION cerefox_ingest_document(
     p_document_id       UUID        DEFAULT NULL,
     p_title             TEXT        DEFAULT 'Untitled',
-    p_source            TEXT        DEFAULT 'agent',
+    -- NULL = "not provided": create uses 'agent', update KEEPS the existing
+    -- source (#191 — a content update without a source used to overwrite the
+    -- document's provenance). Pass a value to relabel deliberately.
+    p_source            TEXT        DEFAULT NULL,
     p_source_path       TEXT        DEFAULT NULL,
     p_content_hash      TEXT        DEFAULT '',
     -- NULL = "not provided": create uses '{}', update KEEPS existing metadata
@@ -1301,8 +1311,14 @@ CREATE FUNCTION cerefox_ingest_document(
     p_author            TEXT        DEFAULT 'unknown',
     p_author_type       TEXT        DEFAULT 'user',
     p_source_label      TEXT        DEFAULT 'manual',
-    p_retention_hours   INT         DEFAULT 48,
-    p_cleanup_enabled   BOOLEAN     DEFAULT TRUE,
+    -- NULL, so `cerefox_snapshot_version` falls through to the store's policy in
+    -- cerefox_config. These carried concrete defaults (48 / TRUE) until v1.1.2,
+    -- which silently defeated the whole store-level retention feature: this is
+    -- snapshot_version's ONLY caller, so it never once received NULL and never
+    -- once consulted the config (#183, reported by @tdebasis). A caller may still
+    -- pass explicit values to override the store for one call.
+    p_retention_hours   INT         DEFAULT NULL,
+    p_cleanup_enabled   BOOLEAN     DEFAULT NULL,
     p_expected_content_hash TEXT    DEFAULT NULL,
     p_last_write_wins   BOOLEAN     DEFAULT FALSE,
     -- content_format for the chunks being written (iter-28D). 2 = exact-partition
@@ -1437,9 +1453,11 @@ BEGIN
 
         -- Update document record. metadata: NULL = keep existing (v0.11.1 —
         -- a content update without metadata must not wipe the document's tags).
+        -- source: same rule, same reason (#191 — a content update without a
+        -- source must not wipe the document's provenance).
         UPDATE cerefox_documents SET
             title = p_title,
-            source = p_source,
+            source = COALESCE(p_source, source),
             source_path = COALESCE(p_source_path, source_path),
             content_hash = p_content_hash,
             metadata = COALESCE(p_metadata, metadata),
@@ -1457,7 +1475,7 @@ BEGIN
             title, source, source_path, content_hash, metadata,
             chunk_count, total_chars, review_status
         ) VALUES (
-            p_title, p_source, p_source_path, p_content_hash, COALESCE(p_metadata, '{}'::JSONB),
+            p_title, COALESCE(p_source, 'agent'), p_source_path, p_content_hash, COALESCE(p_metadata, '{}'::JSONB),
             v_chunk_count, v_total_chars, v_status
         )
         RETURNING id INTO v_doc_id;
@@ -2325,7 +2343,7 @@ SET search_path = public, pg_catalog
 AS $$
     -- Keep in lockstep with the `@version:` marker in schema.sql (cut_release.ts
     -- enforces it). Bump whenever schema.sql OR rpcs.sql changes.
-    SELECT '0.10.4'::TEXT;
+    SELECT '0.10.6'::TEXT;
 $$;
 
 -- ── cerefox_content_format_stats ─────────────────────────────────────────────

package/dist/server-assets/db/schema.sql

@@ -5,7 +5,7 @@
 -- Requires extensions: vector (pgvector), uuid-ossp
 -- These are enabled at the top of db_deploy.py before this file is applied.
 --
--- @version: 0.10.4
+-- @version: 0.10.6
 -- The `@version` marker above is read by the schema-version-mismatch banner
 -- (see /api/v1/schema-version). Bump it whenever schema.sql OR rpcs.sql
 -- changes in a way that requires `cerefox server deploy` to be re-run —

package/dist/server-assets/supabase/functions/cerefox-mcp/index.ts

@@ -68,6 +68,8 @@ async function buildToolList(supabase: MCPSupabaseClient) {
     name: t.name,
     description: t.description,
     inputSchema: t.inputSchema,
+    // MCP 2025-03-26 tool annotations; MCP_VERSION already declares that revision.
+    ...(t.annotations ? { annotations: t.annotations } : {}),
   }));
 }
 

package/docs/guides/setup-local.md

@@ -145,13 +145,20 @@ cerefox-local start          # start a stopped container
 cerefox-local stop           # stop it (your data persists in the Docker volume)
 cerefox-local restart
 cerefox-local logs -f        # follow the logs
-cerefox-local upgrade        # upgrade to the newest release + recreate (keeps data + OPENAI key)
+cerefox-local upgrade        # newest stable release + recreate (keeps data + OPENAI key)
 cerefox-local upgrade v1.2.3 # pin an exact version (also how you downgrade)
 cerefox-local upgrade --latest  # follow the moving :latest tag from now on
 cerefox-local uninstall          # remove the container, KEEP the data volume
 cerefox-local uninstall --purge  # remove the container AND delete the data volume
 ```
 
+> **Coming from an image older than v1.1.0?** Run `cerefox-local upgrade v1.1.1`
+> (an explicit tag) once. A bare `upgrade` on those versions re-pulled the pinned
+> tag and reported success without changing anything (#153), and it cannot fix
+> itself: the launcher on your host is refreshed out of the container image, so an
+> old image keeps reinstalling the old launcher. See
+> [`upgrading.md`](upgrading.md).
+
 `upgrade` is the single update path: it pulls the newest image, recreates the container,
 and refreshes the `cerefox-local` script itself. Because the CLI, web server, PostgREST,
 and database schema all ship together in one versioned image, they never drift out of

package/docs/guides/upgrading.md

@@ -18,6 +18,33 @@ to re-run.
 > repo `.env` to `~/.cerefox/.env`, deploy the server, and wire up your agent.
 > After that you're on the end-user path below.
 
+> ### Cerefox Local on an image older than v1.1.0: upgrade once with an explicit tag
+>
+> If your container is on **v1.0.6 or earlier**, run this once:
+>
+> ```bash
+> cerefox-local upgrade v1.1.1     # or any newer tag
+> ```
+>
+> A bare `cerefox-local upgrade` will **not** get you off an old image, and it
+> fails quietly: it prints "Pulling …", "container (re)started" and "refreshed
+> cerefox-local from the new image", having changed nothing. Before v1.1.0 a bare
+> `upgrade` re-pulled the **pinned** tag rather than resolving the newest release
+> (#153).
+>
+> The reason it cannot fix itself is a bootstrap loop: the `cerefox-local`
+> launcher on your host is refreshed *out of the container image* at the end of
+> every upgrade, so an old image keeps reinstalling the old launcher. Naming a
+> tag explicitly bypasses the pin, pulls the new image, and the new launcher
+> comes with it. `curl … install-local.sh | sh` also works, since the installer
+> writes the launcher directly.
+>
+> **After that, a bare `cerefox-local upgrade` behaves as you would expect**: it
+> resolves the newest *stable* release and pins that exact version. It does not
+> start following the moving `:latest` tag — that is what `upgrade --latest`
+> does, and automatic operations (`init`, `start`, `restart`) never follow a
+> moving tag by design (#100).
+
 ## End-user upgrade
 
 > ### Upgrading to v1.1.0 — `cerefox server deploy` is required

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "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",