@cerefox/memory 1.0.6 → 1.1.0-beta.1

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

@@ -99,10 +99,13 @@ CREATE OR REPLACE FUNCTION cerefox_hybrid_search(
     p_query_text      TEXT,
     p_query_embedding VECTOR(768),
     p_match_count     INT     DEFAULT 10,
-    p_alpha           FLOAT   DEFAULT 0.7,
+    p_alpha           FLOAT   DEFAULT NULL,
     p_use_upgrade     BOOLEAN DEFAULT FALSE,
     p_project_id      UUID    DEFAULT NULL,
-    p_min_score       FLOAT   DEFAULT 0.0,
+    -- NULL means "not specified by the caller" (#133): resolve from
+    -- cerefox_config, else the built-in default. Callers that pass a value
+    -- still win — the chain is per-call > client .env > DB config > default.
+    p_min_score       FLOAT   DEFAULT NULL,
     p_metadata_filter JSONB   DEFAULT NULL,
     -- 28I follow-up (v1.0.4): in OR-fallback mode, the unconditional FTS pass
     -- requires at least this fraction of the query's meaningful (non-stopword,
@@ -110,7 +113,7 @@ CREATE OR REPLACE FUNCTION cerefox_hybrid_search(
     -- meant 100% of terms — the pass this gate generalizes. Chunks below the
     -- bar can still pass via the vector threshold, else they are
     -- below-confidence material. 0 restores the pre-gate OR behavior.
-    p_min_term_coverage FLOAT DEFAULT 0.5
+    p_min_term_coverage FLOAT DEFAULT NULL
 )
 RETURNS TABLE (
     chunk_id        UUID,
@@ -164,6 +167,13 @@ DECLARE
     seen_tokens   TEXT[]    := '{}';
     total_tokens  INT;
     candidate_count INT := p_match_count * 5;
+    -- #133 resolution: caller value, else deployment config, else built-in.
+    v_min_score     FLOAT := COALESCE(p_min_score,
+                                      cerefox_config_float('min_search_score', 0.5));
+    v_alpha         FLOAT := COALESCE(p_alpha,
+                                      cerefox_config_float('search_alpha', 0.7));
+    v_min_coverage  FLOAT := COALESCE(p_min_term_coverage,
+                                      cerefox_config_float('min_term_coverage', 0.5));
 BEGIN
     -- Build the OR-composed query: plainto each whitespace token (so tokens get
     -- the same normalization/stemming as the AND path), skip stopword-only
@@ -217,7 +227,7 @@ BEGIN
                     WHEN and_matches OR total_tokens = 0 THEN TRUE
                     ELSE (SELECT COUNT(*) FROM unnest(tok_queries) tq
                           WHERE c.fts @@ tq)::FLOAT
-                         >= p_min_term_coverage * total_tokens
+                         >= v_min_coverage * total_tokens
                 END AS coverage_ok
             FROM cerefox_chunks c
             JOIN cerefox_documents d ON c.document_id = d.id
@@ -261,8 +271,8 @@ BEGIN
         combined AS (
             SELECT
                 COALESCE(f.id, v.id) AS id,
-                (   p_alpha * COALESCE(v.vec_score, 0.0) +
-                    (1.0 - p_alpha) * COALESCE(f.fts_score, 0.0)
+                (   v_alpha * COALESCE(v.vec_score, 0.0) +
+                    (1.0 - v_alpha) * COALESCE(f.fts_score, 0.0)
                 ) AS score,
                 COALESCE(v.vec_score, 0.0) AS vec_score,
                 -- TRUE when the chunk matched the @@ FTS operator WITH enough
@@ -282,7 +292,7 @@ BEGIN
         -- results (no FTS match) are filtered by the cosine threshold.
         flagged AS (
             SELECT *,
-                   (combined.has_fts_match OR combined.vec_score >= p_min_score) AS passes
+                   (combined.has_fts_match OR combined.vec_score >= v_min_score) AS passes
             FROM combined
         ),
         any_pass AS (SELECT bool_or(fl.passes) AS ok FROM flagged fl),
@@ -349,7 +359,7 @@ CREATE OR REPLACE FUNCTION cerefox_fts_search(
     p_metadata_filter JSONB DEFAULT NULL,
     -- v1.0.4: see cerefox_hybrid_search. In OR-fallback mode results must
     -- match at least this fraction of the query's meaningful terms.
-    p_min_term_coverage FLOAT DEFAULT 0.5
+    p_min_term_coverage FLOAT DEFAULT NULL
 )
 RETURNS TABLE (
     chunk_id        UUID,
@@ -383,6 +393,8 @@ DECLARE
     tok_queries   tsquery[] := '{}';
     seen_tokens   TEXT[]    := '{}';
     total_tokens  INT;
+    v_min_coverage FLOAT := COALESCE(p_min_term_coverage,
+                                     cerefox_config_float('min_term_coverage', 0.5));
 BEGIN
     FOR tok IN SELECT unnest(regexp_split_to_array(trim(p_query_text), '\s+')) LOOP
         tok_q := plainto_tsquery('english', tok);
@@ -443,7 +455,7 @@ BEGIN
       -- returns only chunks matching enough of the query's terms.
       AND (and_matches OR total_tokens = 0
            OR (SELECT COUNT(*) FROM unnest(tok_queries) tq
-               WHERE c.fts @@ tq)::FLOAT >= p_min_term_coverage * total_tokens)
+               WHERE c.fts @@ tq)::FLOAT >= v_min_coverage * total_tokens)
       AND (p_project_id IS NULL OR EXISTS (
               SELECT 1 FROM cerefox_document_projects dp
               WHERE dp.document_id = d.id AND dp.project_id = p_project_id
@@ -749,13 +761,15 @@ CREATE OR REPLACE FUNCTION cerefox_search_docs(
     p_query_text             TEXT,
     p_query_embedding        VECTOR(768),
     p_match_count            INT   DEFAULT 5,
-    p_alpha                  FLOAT DEFAULT 0.7,
+    p_alpha                  FLOAT DEFAULT NULL,
     p_project_id             UUID  DEFAULT NULL,
-    p_min_score              FLOAT DEFAULT 0.0,
+    p_min_score              FLOAT DEFAULT NULL,
     p_small_to_big_threshold INT   DEFAULT 20000,
     p_context_window         INT   DEFAULT 1,
     p_metadata_filter        JSONB DEFAULT NULL,
-    p_min_term_coverage      FLOAT DEFAULT 0.5
+    -- NULL flows through to cerefox_hybrid_search, which resolves the
+    -- caller > cerefox_config > built-in chain in one place (#133).
+    p_min_term_coverage      FLOAT DEFAULT NULL
 )
 RETURNS TABLE (
     document_id              UUID,
@@ -1740,6 +1754,239 @@ BEGIN
 END;
 $$;
 
+-- ══ Document relations (iteration 29) ═════════════════════════════════════════
+-- Typed edges between documents. Design:
+-- docs/research/document-relations-and-semantic-graph.md
+--
+-- Type dictionary: rel_type is free text (any string is accepted and returned),
+-- but a few KNOWN types carry behaviour. Keeping the dictionary in one place
+-- here — rather than scattered CASE expressions — is what lets the set/delete
+-- RPCs stay symmetric with each other.
+--   symmetric   both directions are written/removed together
+--   supersedes  target becomes 'superseded'
+--   contradicts both documents become 'stale'
+CREATE OR REPLACE FUNCTION cerefox_relation_is_symmetric(p_rel_type TEXT)
+RETURNS BOOLEAN
+LANGUAGE sql
+IMMUTABLE
+SET search_path = public, pg_catalog
+AS $$
+    SELECT p_rel_type IN ('related_to', 'contradicts', 'duplicates');
+$$;
+
+-- Create (or update) a relation. Symmetric types write both directions in one
+-- transaction, so a half-written pair is impossible.
+CREATE OR REPLACE FUNCTION cerefox_set_relation(
+    p_source_id   UUID,
+    p_target_id   UUID,
+    p_rel_type    TEXT,
+    p_author      TEXT    DEFAULT 'unknown',
+    p_author_type TEXT    DEFAULT 'agent',
+    p_metadata    JSONB   DEFAULT '{}'::jsonb
+)
+RETURNS TABLE (
+    relation_id UUID,
+    source_id   UUID,
+    target_id   UUID,
+    rel_type      TEXT,
+    is_symmetric  BOOLEAN
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+-- The OUT columns (source_id, target_id, rel_type) share names with the
+-- table's columns; inside the INSERT/ON CONFLICT below the COLUMN is meant.
+#variable_conflict use_column
+DECLARE
+    v_symmetric BOOLEAN := cerefox_relation_is_symmetric(p_rel_type);
+    v_id        UUID;
+BEGIN
+    IF p_source_id = p_target_id THEN
+        RAISE EXCEPTION 'A document cannot relate to itself (%).', p_source_id
+            USING ERRCODE = '22023';
+    END IF;
+    IF p_rel_type IS NULL OR btrim(p_rel_type) = '' THEN
+        RAISE EXCEPTION 'rel_type is required.' USING ERRCODE = '22023';
+    END IF;
+    -- Explicit existence checks give a clear error instead of an FK violation.
+    IF NOT EXISTS (SELECT 1 FROM cerefox_documents d
+                   WHERE d.id = p_source_id AND d.deleted_at IS NULL) THEN
+        RAISE EXCEPTION 'Source document % not found (or deleted).', p_source_id
+            USING ERRCODE = '22023';
+    END IF;
+    IF NOT EXISTS (SELECT 1 FROM cerefox_documents d
+                   WHERE d.id = p_target_id AND d.deleted_at IS NULL) THEN
+        RAISE EXCEPTION 'Target document % not found (or deleted).', p_target_id
+            USING ERRCODE = '22023';
+    END IF;
+
+    INSERT INTO cerefox_document_relations AS r
+        (source_id, target_id, rel_type, metadata, author, author_type)
+    VALUES (p_source_id, p_target_id, btrim(p_rel_type), COALESCE(p_metadata, '{}'::jsonb),
+            p_author, p_author_type)
+    ON CONFLICT (source_id, target_id, rel_type) DO UPDATE
+        SET metadata = EXCLUDED.metadata,
+            author = EXCLUDED.author,
+            author_type = EXCLUDED.author_type
+    RETURNING r.id INTO v_id;
+
+    IF v_symmetric THEN
+        INSERT INTO cerefox_document_relations
+            (source_id, target_id, rel_type, metadata, author, author_type)
+        VALUES (p_target_id, p_source_id, btrim(p_rel_type),
+                COALESCE(p_metadata, '{}'::jsonb), p_author, p_author_type)
+        ON CONFLICT (source_id, target_id, rel_type) DO UPDATE
+            SET metadata = EXCLUDED.metadata,
+                author = EXCLUDED.author,
+                author_type = EXCLUDED.author_type;
+    END IF;
+
+    -- Lifecycle side effects (type dictionary).
+    IF btrim(p_rel_type) = 'supersedes' THEN
+        UPDATE cerefox_documents SET lifecycle_status = 'superseded'
+        WHERE id = p_target_id;
+    ELSIF btrim(p_rel_type) = 'contradicts' THEN
+        UPDATE cerefox_documents SET lifecycle_status = 'stale'
+        WHERE id IN (p_source_id, p_target_id);
+    END IF;
+
+    INSERT INTO cerefox_audit_log (document_id, operation, author, author_type, description)
+    VALUES (p_source_id, 'relation-set', p_author, p_author_type,
+            format('%s → %s (%s)', p_source_id, p_target_id, btrim(p_rel_type)));
+
+    RETURN QUERY SELECT v_id, p_source_id, p_target_id, btrim(p_rel_type), v_symmetric;
+END;
+$$;
+
+-- Remove a relation. Symmetric types remove both directions. Lifecycle side
+-- effects are NOT auto-reverted: a document marked superseded may have been
+-- superseded by something else too, and guessing wrong is worse than leaving
+-- the operator to set it explicitly.
+CREATE OR REPLACE FUNCTION cerefox_delete_relation(
+    p_source_id   UUID,
+    p_target_id   UUID,
+    p_rel_type    TEXT,
+    p_author      TEXT DEFAULT 'unknown',
+    p_author_type TEXT DEFAULT 'agent'
+)
+RETURNS INT
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+    v_deleted INT := 0;
+    v_n       INT;
+BEGIN
+    DELETE FROM cerefox_document_relations
+    WHERE source_id = p_source_id AND target_id = p_target_id
+      AND rel_type = btrim(p_rel_type);
+    GET DIAGNOSTICS v_n = ROW_COUNT; v_deleted := v_deleted + v_n;
+
+    IF cerefox_relation_is_symmetric(p_rel_type) THEN
+        DELETE FROM cerefox_document_relations
+        WHERE source_id = p_target_id AND target_id = p_source_id
+          AND rel_type = btrim(p_rel_type);
+        GET DIAGNOSTICS v_n = ROW_COUNT; v_deleted := v_deleted + v_n;
+    END IF;
+
+    IF v_deleted > 0 THEN
+        INSERT INTO cerefox_audit_log (document_id, operation, author, author_type, description)
+        VALUES (p_source_id, 'relation-delete', p_author, p_author_type,
+                format('%s → %s (%s)', p_source_id, p_target_id, btrim(p_rel_type)));
+    END IF;
+    RETURN v_deleted;
+END;
+$$;
+
+-- All edges touching a document, in both directions. `direction` tells the
+-- caller which way each edge points relative to the document asked about.
+CREATE OR REPLACE FUNCTION cerefox_get_relations(p_document_id UUID)
+RETURNS TABLE (
+    relation_id      UUID,
+    direction        TEXT,
+    rel_type         TEXT,
+    other_id         UUID,
+    other_title      TEXT,
+    other_lifecycle  TEXT,
+    metadata         JSONB,
+    author           TEXT,
+    created_at       TIMESTAMPTZ
+)
+LANGUAGE sql
+SECURITY DEFINER
+STABLE
+SET search_path = public, pg_catalog
+AS $$
+    SELECT r.id, 'outbound'::TEXT, r.rel_type, r.target_id, d.title,
+           d.lifecycle_status, r.metadata, r.author, r.created_at
+    FROM cerefox_document_relations r
+    JOIN cerefox_documents d ON d.id = r.target_id
+    WHERE r.source_id = p_document_id AND d.deleted_at IS NULL
+    UNION ALL
+    SELECT r.id, 'inbound'::TEXT, r.rel_type, r.source_id, d.title,
+           d.lifecycle_status, r.metadata, r.author, r.created_at
+    FROM cerefox_document_relations r
+    JOIN cerefox_documents d ON d.id = r.source_id
+    WHERE r.target_id = p_document_id AND d.deleted_at IS NULL
+    ORDER BY 3, 9 DESC;
+$$;
+
+-- Walk the graph from a document along ONE relation type. Depth > 1 follows
+-- chains (meaningful for e.g. `follows` / `reply_to`); a visited-set stops
+-- cycles, which free-text types make possible.
+CREATE OR REPLACE FUNCTION cerefox_get_neighbors(
+    p_document_id UUID,
+    p_rel_type    TEXT,
+    p_depth       INT DEFAULT 1,
+    p_from_time   TIMESTAMPTZ DEFAULT NULL,
+    p_to_time     TIMESTAMPTZ DEFAULT NULL,
+    p_limit       INT DEFAULT 50
+)
+RETURNS TABLE (
+    document_id     UUID,
+    title           TEXT,
+    lifecycle_status TEXT,
+    depth           INT,
+    direction       TEXT,
+    doc_created_at  TIMESTAMPTZ
+)
+LANGUAGE sql
+SECURITY DEFINER
+STABLE
+SET search_path = public, pg_catalog
+AS $$
+    WITH RECURSIVE walk AS (
+        SELECT p_document_id AS id, 0 AS depth, 'self'::TEXT AS direction,
+               ARRAY[p_document_id] AS seen
+        UNION ALL
+        SELECT nxt.id, w.depth + 1, nxt.direction, w.seen || nxt.id
+        FROM walk w
+        CROSS JOIN LATERAL (
+            SELECT r.target_id AS id, 'outbound'::TEXT AS direction
+            FROM cerefox_document_relations r
+            WHERE r.source_id = w.id AND r.rel_type = btrim(p_rel_type)
+            UNION ALL
+            SELECT r.source_id, 'inbound'::TEXT
+            FROM cerefox_document_relations r
+            WHERE r.target_id = w.id AND r.rel_type = btrim(p_rel_type)
+        ) nxt
+        WHERE w.depth < GREATEST(p_depth, 1)
+          AND NOT (nxt.id = ANY(w.seen))   -- cycle guard
+    )
+    SELECT DISTINCT ON (w.id)
+           w.id, d.title, d.lifecycle_status, w.depth, w.direction, d.created_at
+    FROM walk w
+    JOIN cerefox_documents d ON d.id = w.id
+    WHERE w.depth > 0
+      AND d.deleted_at IS NULL
+      AND (p_from_time IS NULL OR d.created_at >= p_from_time)
+      AND (p_to_time   IS NULL OR d.created_at <= p_to_time)
+    ORDER BY w.id, w.depth
+    LIMIT GREATEST(p_limit, 1);
+$$;
+
 -- ── cerefox_get_config / cerefox_set_config ──────────────────────────────────
 -- Read/write key-value config from cerefox_config table.
 
@@ -1753,6 +2000,31 @@ AS $$
     SELECT value FROM cerefox_config WHERE key = p_key;
 $$;
 
+-- Numeric config reader with a fallback (v1.1.0, #133). Returns p_fallback
+-- when the key is unset or unparseable, so a malformed row can never break
+-- search — it just reverts to the built-in default.
+CREATE OR REPLACE FUNCTION cerefox_config_float(p_key TEXT, p_fallback FLOAT)
+RETURNS FLOAT
+LANGUAGE plpgsql
+SECURITY DEFINER
+STABLE
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+    v_raw TEXT;
+    v_num FLOAT;
+BEGIN
+    SELECT value INTO v_raw FROM cerefox_config WHERE key = p_key;
+    IF v_raw IS NULL OR v_raw = '' THEN RETURN p_fallback; END IF;
+    BEGIN
+        v_num := v_raw::FLOAT;
+    EXCEPTION WHEN others THEN
+        RETURN p_fallback;
+    END;
+    RETURN v_num;
+END;
+$$;
+
 CREATE OR REPLACE FUNCTION cerefox_set_config(p_key TEXT, p_value TEXT)
 RETURNS VOID
 LANGUAGE plpgsql
@@ -1760,7 +2032,13 @@ SECURITY DEFINER
 SET search_path = public, pg_catalog
 AS $$
 DECLARE
-    v_allowed TEXT[] := ARRAY['usage_tracking_enabled', 'require_requestor_identity', 'requestor_identity_format'];
+    -- Retrieval tunables (#133) join the governance keys: setting one here
+    -- governs EVERY access path (CLI, local + remote MCP, Edge Functions, web),
+    -- because they all resolve through these RPCs.
+    v_allowed TEXT[] := ARRAY[
+        'usage_tracking_enabled', 'require_requestor_identity', 'requestor_identity_format',
+        'min_search_score', 'min_term_coverage', 'search_alpha'
+    ];
 BEGIN
     IF NOT (p_key = ANY(v_allowed)) THEN
         RAISE EXCEPTION 'Unknown config key: %. Allowed keys: %', p_key, v_allowed;
@@ -1954,7 +2232,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.9.2'::TEXT;
+    SELECT '0.10.0'::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.9.2
+-- @version: 0.10.0
 -- 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 —
@@ -49,6 +49,11 @@ CREATE TABLE IF NOT EXISTS cerefox_documents (
     -- 'pending_review' = modified by agent, not yet reviewed.
     -- Content is searchable in both states.
     review_status   TEXT        NOT NULL DEFAULT 'approved',
+    -- lifecycle_status: where this document stands relative to the graph —
+    -- 'active' | 'superseded' | 'stale' | 'archived'. Distinct from
+    -- review_status (editorial state) and deleted_at (existence). Maintained by
+    -- the relation RPCs (e.g. `supersedes` marks its target superseded).
+    lifecycle_status TEXT       NOT NULL DEFAULT 'active',
     created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
     updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
     -- Soft delete: NULL = active, timestamp = deleted (recoverable).
@@ -118,7 +123,9 @@ CREATE TABLE IF NOT EXISTS cerefox_audit_log (
 
     CONSTRAINT cerefox_audit_log_operation_check CHECK (
         operation IN ('create', 'update-content', 'update-metadata', 'delete',
-                      'status-change', 'archive', 'unarchive', 'restore')
+                      'status-change', 'archive', 'unarchive', 'restore',
+                      -- iteration 29: graph edges are auditable writes too
+                      'relation-set', 'relation-delete')
     ),
     CONSTRAINT cerefox_audit_log_author_type_check CHECK (author_type IN ('user', 'agent'))
 );
@@ -132,6 +139,32 @@ CREATE TABLE IF NOT EXISTS cerefox_document_projects (
     PRIMARY KEY (document_id, project_id)
 );
 
+-- ── Document relations (iteration 29) ─────────────────────────────────────────
+-- Typed, directed edges between documents. rel_type is free text by design so
+-- agents can define new types without a migration; the type dictionary lives in
+-- the RPCs and gives KNOWN types behaviour (symmetry, lifecycle side effects).
+-- Design: docs/research/document-relations-and-semantic-graph.md §2.2.
+
+CREATE TABLE IF NOT EXISTS cerefox_document_relations (
+    id           UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
+    source_id    UUID        NOT NULL REFERENCES cerefox_documents(id) ON DELETE CASCADE,
+    target_id    UUID        NOT NULL REFERENCES cerefox_documents(id) ON DELETE CASCADE,
+    rel_type     TEXT        NOT NULL,
+    metadata     JSONB       NOT NULL DEFAULT '{}'::jsonb,
+    author       TEXT        NOT NULL DEFAULT 'unknown',
+    author_type  TEXT        NOT NULL DEFAULT 'agent',
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE (source_id, target_id, rel_type),
+    CONSTRAINT cerefox_relations_no_self_edge CHECK (source_id <> target_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_cerefox_relations_source ON cerefox_document_relations(source_id);
+CREATE INDEX IF NOT EXISTS idx_cerefox_relations_target ON cerefox_document_relations(target_id);
+CREATE INDEX IF NOT EXISTS idx_cerefox_relations_type   ON cerefox_document_relations(rel_type);
+CREATE INDEX IF NOT EXISTS idx_cerefox_docs_lifecycle
+    ON cerefox_documents(lifecycle_status)
+    WHERE lifecycle_status <> 'active';
+
 -- ── Chunks ────────────────────────────────────────────────────────────────────
 -- One row per chunk of a document. Embeddings and FTS live here.
 --

package/docs/guides/configuration.md

@@ -117,6 +117,21 @@ This handles intermittent OpenAI API errors (500s) that would otherwise cause se
 
 ## Retrieval
 
+> **Deployment-wide defaults (v1.1.0+).** `min_search_score`,
+> `min_term_coverage`, and `search_alpha` can also be set **once, in the
+> database**, and every access path obeys — CLI, local and remote MCP, Edge
+> Functions, web — because they all resolve through the same search RPCs:
+>
+> ```bash
+> cerefox config set min_search_score 0.6
+> cerefox config list          # shows every settable key
+> ```
+>
+> Resolution order, highest first: **per-call argument** (`--min-score`, the
+> `min_score` MCP parameter) → **client env var** below → **`cerefox_config`**
+> → built-in default. A malformed stored value is ignored in favour of the
+> built-in, so a bad setting can never break search.
+
 > **Which paths read these?** Client-side tunables in this section are read
 > from *your* `.env` by the **CLI**, the **local MCP server**, and `cerefox
 > web`. Since **v1.0.6** the same values are also honored on the **remote MCP /

package/docs/guides/setup-local.md

@@ -143,7 +143,9 @@ 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        # pull the latest image + recreate (keeps data + OPENAI key)
+cerefox-local upgrade        # upgrade to the newest 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
 ```

package/docs/guides/upgrading.md

@@ -10,7 +10,7 @@ to re-run.
 |---|---|
 | **Installer / npm** (end user, no repo clone) | `cerefox self-update` (or re-run the [installer](quickstart.md#1-install), or `bun/npm update -g @cerefox/memory`). Then `cerefox server deploy` **if the release notes flag a server-side change**. `cerefox doctor` verifies. |
 | **Source checkout** (`git clone`, contributor) | `git pull`, then `cerefox server deploy` (or the lower-level `bun scripts/db_*.ts` + `npx supabase functions deploy`). Rebuild the SPA if you run `cerefox web` from source. |
-| **Local / self-hosted (Docker, World B)** | `cerefox-local upgrade` — pulls the new image and recreates the container (data persists in the volume; OpenAI key + tuning overrides preserved). **No separate `server deploy`/`reindex`**: the CLI, web, PostgREST, and schema all ship together in one versioned image, so they can't drift. See [`setup-local.md`](setup-local.md). |
+| **Local / self-hosted (Docker, World B)** | `cerefox-local upgrade` — resolves the newest release, pulls it, and recreates the container (`upgrade <tag>` pins an exact version; `upgrade --latest` follows the moving tag). Data persists in the volume; OpenAI key + tuning overrides preserved. **No separate `server deploy`/`reindex`**: the CLI, web, PostgREST, and schema all ship together in one versioned image, so they can't drift. See [`setup-local.md`](setup-local.md). |
 
 > **On an old pre-installer clone (0.1.x)?** The cleanest upgrade is to stop
 > running from the repo and install the package: follow the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.0.6",
+  "version": "1.1.0-beta.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",
@@ -43,7 +43,7 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@supabase/supabase-js": "^2.45.0",
     "cli-progress": "^3.12.0",
-    "commander": "^12.1.0",
+    "commander": "^14.0.3",
     "hono": "^4.12.34",
     "mammoth": "^1.9.0",
     "ora": "^9.4.0",
@@ -54,7 +54,7 @@
     "zod": "^3.23.0"
   },
   "optionalDependencies": {
-    "@huggingface/transformers": "^3.5.0",
+    "@huggingface/transformers": "^4.2.0",
     "onnxruntime-node": "^1.21.0"
   },
   "devDependencies": {