@cerefox/memory 1.0.8 → 1.1.0-beta.2

package/docs/guides/configuration.md

@@ -117,6 +117,27 @@ This handles intermittent OpenAI API errors (500s) that would otherwise cause se
 
 ## Retrieval
 
+> **Optional features.** `relations_enabled` (default `false`) controls whether
+> the document-relation tools are exposed to agents. The feature ships
+> **dormant**: the table stays empty, `lifecycle_status` defaults to `active`,
+> search is untouched, and the tools do not appear in any agent's tool list
+> until you opt in with `cerefox config set relations_enabled true`.
+
+> **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/migration-1.0.md

@@ -61,9 +61,7 @@ The migration is **lazy and safe**:
 - Existing documents keep the legacy format and reconstruct **exactly as before** — nothing
   re-processes, nothing re-embeds.
 - A document moves to the new format automatically the next time it is edited/saved. To
-  convert everything now instead, run `cerefox server migrate-format` (it re-chunks and
-  re-embeds, so try `--dry-run` first). **Not `server reindex`** — that refreshes
-  embeddings on existing chunks and cannot change the stored format (#164).
+  convert everything now instead, run `cerefox server reindex`.
 - `cerefox doctor` shows how many documents still use the legacy format.
 
 Details: `cerefox guides show content-format` (or [`content-format.md`](content-format.md)).

package/docs/guides/ops-scripts.md

@@ -126,7 +126,7 @@ bun scripts/backup_create.ts && bun scripts/db_migrate.ts
 
 ## backup_create.ts — Create a backup
 
-Exports all documents, chunks, metadata, **projects and project memberships** to a JSON file in the backup directory. (End users use `cerefox backup create`.)
+Exports all documents, chunks, and metadata to a JSON file in the backup directory. (End users use `cerefox backup create`.)
 
 ```bash
 bun scripts/backup_create.ts [OPTIONS]
@@ -153,7 +153,7 @@ Output: `backup-data/cerefox-20260308T143022Z-before-v2-migration.json`
 
 ## backup_restore.ts — Restore from a backup
 
-Restores documents, chunks, projects and project memberships from a previously created backup file. Idempotent — documents with the same content hash are skipped, and projects/memberships are upserted. Snapshots taken before v1.0.7 contain no memberships; restoring one warns and recreates documents only. (End users use `cerefox backup restore`.)
+Restores documents and chunks from a previously created backup file. Idempotent — documents with the same content hash are skipped. (End users use `cerefox backup restore`.)
 
 ```bash
 bun scripts/backup_restore.ts BACKUP_FILE [OPTIONS]

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/setup-supabase.md

@@ -21,7 +21,22 @@ This guide walks you from a blank Supabase project to a fully deployed Cerefox s
 1. Go to [app.supabase.com](https://app.supabase.com) and sign in
 2. Click **New project**
 3. Choose a name (e.g. `cerefox`), set a strong database password, pick a region close to you
-4. Click **Create new project** and wait ~2 minutes for it to provision
+4. Review the security options offered at creation (defaults in brackets):
+   - **Enable Data API** *[on]* — **keep it on.** The CLI, web UI, and local MCP all reach
+     Supabase through PostgREST; without it nothing works.
+   - **Automatically expose new tables** *[on]* — **turn it off.** Cerefox grants its tables
+     to `service_role` explicitly (migration `0013`), so it does not rely on implicit
+     exposure, and leaving it on means any future table is exposed to the Data API roles by
+     default. Supabase recommends disabling it too.
+   - **Enable automatic RLS** *[off]* — optional. Cerefox's schema already runs
+     `ENABLE ROW LEVEL SECURITY` on every table it creates, so this only covers tables
+     Cerefox doesn't own. Harmless either way; every Cerefox access path authenticates as
+     `service_role`, which bypasses RLS by design.
+5. Click **Create new project** and wait ~2 minutes for it to provision
+
+> **Note on the database password**: it is used *only* by `cerefox server deploy` (a direct
+> Postgres connection for DDL). Everyday CLI, web, and MCP traffic uses the secret key
+> instead. Store it in a password manager — Supabase will not show it again.
 
 ---
 
@@ -56,14 +71,24 @@ Either way: keep this key secret — it bypasses Row Level Security and grants f
 
 This is used by `cerefox server deploy` (and the contributor scripts `bun scripts/db_deploy.ts` / `bun scripts/db_migrate.ts`). See the **[Connection pooling in 2026](#connection-pooling-2026)** reference section near the end of this guide for context. The short version:
 
-1. Open **Project Settings → Database → Connection pooling** (not the "Connect" dialog — that one usually omits the Session Pooler in the new UI).
+1. From the **project overview**, click the **Copy** button beside the project URL, then
+   **Get Connected** in the dropdown. Under **Direct Connection Pooling**, choose
+   **Session pooler**. *(Verified against a project created 2026-08-05. Supabase moves this
+   regularly — it used to live under Project Settings → Database → Connection pooling, which
+   may still work.)*
 2. Copy the **Session Pooler** URI (host ends in `.pooler.supabase.com`, port `5432`).
 3. Confirm the username has the form `postgres.<project-ref>` — without that suffix you'll get "Tenant or user not found".
 4. Append `?sslmode=require` to enforce TLS explicitly.
 
+The result looks like this — note both the ref-suffixed username **and** the pooler host:
+
+```
+postgresql://postgres.abcdefghijklmnop:<password>@aws-0-<region>.pooler.supabase.com:5432/postgres?sslmode=require
+```
+
 If you only see Direct Connection and Transaction Pooler in your dashboard, take the Transaction Pooler URI and change `:6543` → `:5432`. That gives you the Session Pooler. **Do not use port 6543** — Transaction Pooler does not support DDL and the schema deploy will fail mid-schema.
 
-The Direct Connection (`db.<project-ref>.supabase.co:5432`) is IPv6-only on the free tier and unusable on most home/office networks. The dashboard now warns about this directly.
+> **Don't take the Direct connection string** (`postgresql://postgres:<password>@db.<ref>.supabase.co:5432/postgres`). It is the most prominent option in the dialog, but it is IPv6-only on the free tier, so it times out on most home and office networks. The dashboard warns about this directly.
 
 ---
 
@@ -380,7 +405,13 @@ Not yet. The Supabase docs explicitly state: *"You can still use old anon and se
 
 ## Connection pooling in 2026 <a id="connection-pooling-2026"></a>
 
-Supabase's "Connect" dialog was redesigned in 2026 and the **Session Pooler** is no longer a first-class tab in many projects. The other two surfaces (Direct Connection and Transaction Pooler) are present but neither works for Cerefox's deployment scripts. Here's the full picture.
+Supabase's "Connect" dialog has been redesigned repeatedly through 2026, and where the
+**Session Pooler** lives has moved with it. As of **2026-08-05** it is inside the Connect
+dialog: project overview → **Copy** (beside the project URL) → **Get Connected** →
+**Direct Connection Pooling** → **Session pooler**. Earlier in the year it was only under
+Project Settings → Database → Connection pooling. Check both if one comes up empty — and the
+shape of the URI is the reliable signal, not the menu path: **ref-suffixed username plus a
+`.pooler.supabase.com` host on port 5432**. Here's the full picture.
 
 ### The three Postgres connection types
 

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.8",
+  "version": "1.1.0-beta.2",
   "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": {