npm - @cerefox/memory - Versions diffs - 1.1.0 → 1.2.0 - Mend

@cerefox/memory 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/dist/frontend/index.html CHANGED Viewed

@@ -15,7 +15,7 @@
       href="https://fonts.googleapis.com/css2?family=Geist:wght@300;400;500;600;700&display=swap"
     />
     <title>Cerefox</title>
-    <script type="module" crossorigin src="/app/assets/index-DD7DDGGU.js"></script>
+    <script type="module" crossorigin src="/app/assets/index-B1pgikxA.js"></script>
     <link rel="stylesheet" crossorigin href="/app/assets/index-C1JXZA9m.css">
   </head>
   <body>

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

@@ -18,7 +18,7 @@
  * doesn't touch `supabase/functions/` leaves it alone).
  */
-export const EF_VERSION = "1.1.0";
+export const EF_VERSION = "1.2.0";
 /**
  * The most recent version whose EF-side SOURCE actually changed (#127).
@@ -28,7 +28,7 @@ export const EF_VERSION = "1.1.0";
  * `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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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/rpcs.sql CHANGED Viewed

@@ -1268,8 +1268,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.
@@ -1301,8 +1303,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
@@ -2325,7 +2333,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.5'::TEXT;
 $$;
 -- ── cerefox_content_format_stats ─────────────────────────────────────────────

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

@@ -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.5
 -- 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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

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