@cerefox/memory 1.0.0-rc.4 → 1.0.1-beta.1

package/dist/server-assets/db/migrations/0013_explicit_grants.sql

@@ -0,0 +1,32 @@
+-- 0013_explicit_grants.sql — issue #26: explicit Data API grants for service_role
+-- (Supabase implicit-grant removal). Idempotent; safe on existing deployments.
+
+-- ── Explicit Data API grants (issue #26; schema 0.8.2) ─────────────────────────
+-- Supabase is removing the implicit privileges the Data API roles get on
+-- `public` tables (default for projects created after 2026-05-30; enforced on
+-- existing projects 2026-10-30). Without explicit GRANTs a table is invisible
+-- to PostgREST even for service_role (42501). Cerefox grants ONLY service_role
+-- (the CLI / MCP / web all use service-role-equivalent keys; anon/authenticated
+-- deliberately get nothing, matching the RPC EXECUTE posture from iter-28B).
+-- Guarded: on the local (World B) stack this file deploys BEFORE roles.sql
+-- creates service_role, so missing-role must be a no-op (roles.sql re-runs the
+-- grants implicitly via its own PostgREST wiring; the next deploy picks them up).
+DO $$
+DECLARE t TEXT;
+BEGIN
+    IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'service_role') THEN
+        GRANT USAGE ON SCHEMA public TO service_role;
+        FOREACH t IN ARRAY ARRAY[
+            'cerefox_projects', 'cerefox_documents', 'cerefox_document_versions',
+            'cerefox_audit_log', 'cerefox_document_projects', 'cerefox_chunks',
+            'cerefox_migrations', 'cerefox_config', 'cerefox_usage_log'
+        ] LOOP
+            IF to_regclass('public.' || t) IS NOT NULL THEN
+                EXECUTE format('GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE public.%I TO service_role', t);
+            END IF;
+        END LOOP;
+        -- Future cerefox_* tables created by the deploying role keep working.
+        ALTER DEFAULT PRIVILEGES IN SCHEMA public
+            GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO service_role;
+    END IF;
+END $$;

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

@@ -1776,7 +1776,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.8.1'::TEXT;
+    SELECT '0.8.2'::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.8.1
+-- @version: 0.8.2
 -- 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 —
@@ -386,3 +386,33 @@ ALTER TABLE cerefox_audit_log              ENABLE ROW LEVEL SECURITY;
 ALTER TABLE cerefox_migrations            ENABLE ROW LEVEL SECURITY;
 ALTER TABLE cerefox_config                ENABLE ROW LEVEL SECURITY;
 ALTER TABLE cerefox_usage_log             ENABLE ROW LEVEL SECURITY;
+
+-- ── Explicit Data API grants (issue #26; schema 0.8.2) ─────────────────────────
+-- Supabase is removing the implicit privileges the Data API roles get on
+-- `public` tables (default for projects created after 2026-05-30; enforced on
+-- existing projects 2026-10-30). Without explicit GRANTs a table is invisible
+-- to PostgREST even for service_role (42501). Cerefox grants ONLY service_role
+-- (the CLI / MCP / web all use service-role-equivalent keys; anon/authenticated
+-- deliberately get nothing, matching the RPC EXECUTE posture from iter-28B).
+-- Guarded: on the local (World B) stack this file deploys BEFORE roles.sql
+-- creates service_role, so missing-role must be a no-op (roles.sql re-runs the
+-- grants implicitly via its own PostgREST wiring; the next deploy picks them up).
+DO $$
+DECLARE t TEXT;
+BEGIN
+    IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'service_role') THEN
+        GRANT USAGE ON SCHEMA public TO service_role;
+        FOREACH t IN ARRAY ARRAY[
+            'cerefox_projects', 'cerefox_documents', 'cerefox_document_versions',
+            'cerefox_audit_log', 'cerefox_document_projects', 'cerefox_chunks',
+            'cerefox_migrations', 'cerefox_config', 'cerefox_usage_log'
+        ] LOOP
+            IF to_regclass('public.' || t) IS NOT NULL THEN
+                EXECUTE format('GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE public.%I TO service_role', t);
+            END IF;
+        END LOOP;
+        -- Future cerefox_* tables created by the deploying role keep working.
+        ALTER DEFAULT PRIVILEGES IN SCHEMA public
+            GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO service_role;
+    END IF;
+END $$;

package/docs/guides/configuration.md

@@ -118,7 +118,10 @@ This handles intermittent OpenAI API errors (500s) that would otherwise cause se
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `CEREFOX_MAX_RESPONSE_BYTES` | `200000` | Maximum bytes in a single search response (local MCP path). See explanation below. |
-| `CEREFOX_MIN_SEARCH_SCORE` | `0.50` | Minimum cosine similarity for hybrid and semantic search results (0.0–1.0). In **hybrid search**, chunks that matched the FTS keyword operator (`@@`) always pass through regardless of their vector score — the threshold only filters vector-only results. In **semantic search**, all results are filtered. The pure **FTS search** mode is unaffected. Increase for stricter precision; decrease for wider recall. |
+| `CEREFOX_MIN_SEARCH_SCORE` | `0.50` (`0.60` with the local embedder) | Minimum cosine similarity for hybrid and semantic search results (0.0–1.0). The default is embedder-aware: nomic scores unrelated text higher than OpenAI, so `CEREFOX_EMBEDDER=local` raises the floor to 0.60. In **hybrid search**, chunks that matched the FTS keyword operator (`@@`) always pass through regardless of their vector score — the threshold only filters vector-only results. In **semantic search**, all results are filtered. The pure **FTS search** mode is unaffected. Increase for stricter precision; decrease for wider recall. |
+| `CEREFOX_EMBED_MAX_INPUT_CHARS` | `20000` | Safety cap on the characters sent to the embedding model per input. The full chunk content is always stored and reconstructed untouched; only the embedding uses the (rare) truncated prefix, so an oversized chunk can never fail an ingest. |
+| `CEREFOX_MODELS_DIR` | `~/.cerefox/models` (in-container: inside the data volume) | Where the local embedder caches downloaded model weights (Cerefox Local; `CEREFOX_EMBEDDER=local`). |
+| `CEREFOX_ONNX_BATCH` | `4` | Texts per local-embedder inference call. Peak memory scales with this; the small default keeps ingest/reindex safe on small Docker VMs. |
 
 ### Metadata filter
 
@@ -257,9 +260,9 @@ OPENAI_API_KEY=sk-...
 # All other settings use defaults
 ```
 
-> **Fireworks is not wired in the TS runtime yet** — `CEREFOX_EMBEDDER=fireworks` /
-> `CEREFOX_FIREWORKS_*` are documented but currently no-ops (OpenAI is the only embedder
-> implemented today). Tracked for a future release.
+> **Fireworks is not wired yet** — `CEREFOX_EMBEDDER=fireworks` / `CEREFOX_FIREWORKS_*`
+> are documented but currently no-ops. The wired embedders are `openai` (default) and
+> `local` (Cerefox Local only). Fireworks is tracked for a future release.
 
 ---
 

package/docs/guides/migration-1.0.md

@@ -4,9 +4,6 @@ Cerefox 1.0.0 is the first stable release. Two changes need attention when you
 upgrade an existing Supabase deployment; a third is automatic. **Nothing here
 affects the local/self-hosted (World B) backend.**
 
-Pre-releases are published on the `1.0.0-beta.N` line (breaking changes may still
-occur between betas) leading up to `1.0.0`.
-
 ## 1. Edge Function auth: anon key → Cerefox access token (action required)
 
 The legacy Supabase **anon JWT** is no longer accepted for calling Cerefox Edge
@@ -52,7 +49,7 @@ Claude uses OAuth).
 Rotating the token later: `cerefox token rotate` (accepts new + old for zero-downtime),
 then `cerefox token rotate --finalize` once every client is on the new token.
 
-## 2. New schema (0.7.0 → 0.8.0): document reconstruction fix (redeploy required, no data action)
+## 2. New schema (→ 0.8.1): document reconstruction fix (redeploy required, no data action)
 
 1.0.0 fixes a document-reconstruction bug that could corrupt documents containing large
 tables or blank-line-free paragraphs. It adds a `content_format` column on
@@ -90,7 +87,7 @@ unaffected — they are not Python and remain the source of truth for the schema
 ```bash
 cerefox self-update            # or: npm install -g @cerefox/memory@latest
 cerefox token generate         # change #1: mint + set the access token
-cerefox server deploy          # changes #1 + #2: token-gated EFs + schema 0.8.0
+cerefox server deploy          # changes #1 + #2: token-gated EFs + schema 0.8.1
 cerefox doctor                 # verify (edge-functions green; content-format ℹ)
 # then: update GPT Actions / remote MCP clients to the token; revoke the anon key
 ```

package/docs/guides/operational-cost.md

@@ -142,8 +142,11 @@ embedding costs" below.
 
 If you want to keep costs as low as possible:
 
-- **Cheaper embedding models**: a lower-cost OpenAI-compatible provider (e.g. Fireworks AI)
-  is on the roadmap — **not yet wired in the TS runtime** (OpenAI only today).
+- **Zero-cost embeddings (Cerefox Local)**: the self-hosted backend can run a local
+  embedding model in-container (`CEREFOX_EMBEDDER=local`) — no API key, no per-token
+  cost at all. See [setup-local.md](setup-local.md#choose-your-embedder-openai-vs-fully-local).
+- **Cheaper cloud models**: a lower-cost OpenAI-compatible provider (e.g. Fireworks AI)
+  is on the roadmap — not yet wired.
 - **Batch ingest, don't re-ingest**: Cerefox deduplicates by content hash — re-ingesting the
   same file twice costs nothing. Only new or changed content triggers embedding calls.
 - **`cerefox server reindex`**: Re-embeds all existing chunks if you switch embedders. Run this once

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.0.0-rc.4",
-  "description": "Cerefox — user-owned shared memory for AI agents. The local TypeScript runtime: stdio MCP server in v0.4; CLI binary added in v0.5; in-process web server in v0.6; ingestion pipeline in v0.7.",
+  "version": "1.0.1-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",
   "repository": {