@cerefox/memory 1.20.0 → 1.22.0

package/dist/frontend/index.html

@@ -15,8 +15,9 @@
       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-BQKYExx3.js"></script>
-    <link rel="stylesheet" crossorigin href="/app/assets/index-01k5C3sG.css">
+    <script type="module" crossorigin src="/app/assets/index-Dhpoy6w3.js"></script>
+    <link rel="modulepreload" crossorigin href="/app/assets/rolldown-runtime-COiEfhsA.js">
+    <link rel="stylesheet" crossorigin href="/app/assets/index-CV1iy1p2.css">
   </head>
   <body>
     <div id="root"></div>

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.20.0";
+export const EF_VERSION = "1.22.0";
 
 /**
  * The Cerefox RELEASE version — what `cerefox --version` reports and what npm
@@ -36,7 +36,7 @@ export const EF_VERSION = "1.20.0";
  * is imported by the Deno Edge Functions, which cannot reach into the npm
  * package.
  */
-export const CEREFOX_VERSION = "1.20.0";
+export const CEREFOX_VERSION = "1.22.0";
 
 /**
  * The most recent version whose EF-side SOURCE actually changed (#127).
@@ -46,7 +46,7 @@ export const CEREFOX_VERSION = "1.20.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.19.0";
+export const EF_LAST_CHANGED = "1.22.0";
 
 /**
  * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp

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

@@ -263,6 +263,7 @@ export {
   isStoreLevelAuditOp,
   metadataChangeSummary,
   STORE_LEVEL_AUDIT_OPS,
+  storeChangeSummary,
 } from "./audit-ops.ts";
 
 /**

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

@@ -33,8 +33,9 @@ export const AUDIT_OPERATIONS = [
 ] as const;
 
 /** The document-column label for an audit row — title, short id, or the
- * NULL-document story: "(store)" for store-level ops, "(deleted)" for rows
- * whose document was purged. One implementation across MCP, CLI, and web. */
+ * NULL-document story: what a store-level op changed ("(setting)" for a config
+ * change, "(project)" for a project op, "(store)" for any other), "(deleted)" for rows whose document
+ * was purged. One implementation across MCP, CLI, and web. */
 export function auditDocLabel(
   docTitle: string | null | undefined,
   documentId: string | null | undefined,
@@ -42,9 +43,29 @@ export function auditDocLabel(
 ): string {
   if (docTitle) return docTitle;
   if (documentId) return documentId.slice(0, 8) + "…";
+  if (operation === "config-change") return "(setting)";
+  if (operation?.startsWith("project-")) return "(project)";
   return isStoreLevelAuditOp(operation) ? "(store)" : "(deleted)";
 }
 
+/**
+ * What a store-level entry changed, for a surface that shows a short "change"
+ * per row (the web audit log). The RPCs write the change into the
+ * description ("config: trash_auto_purge_enabled: 'false' → 'true'",
+ * "Project 'x' created"); a config change drops its "config: " prefix, since
+ * the row already says it is a setting. Null for document operations, which
+ * show a size or a metadata change instead.
+ */
+export function storeChangeSummary(
+  operation: string | null | undefined,
+  description: string | null | undefined,
+): string | null {
+  if (!isStoreLevelAuditOp(operation)) return null;
+  const d = (description ?? "").trim();
+  if (!d) return null;
+  return operation === "config-change" ? d.replace(/^config:\s*/, "") : d;
+}
+
 /**
  * One line describing a metadata change (#333): the keys set (with their new
  * values) and the keys removed. Built from an `update-metadata` audit entry's

package/docs/guides/configuration.md

@@ -341,6 +341,7 @@ there matters.
 |----------|---------|-------------|
 | `CEREFOX_BACKUP_DIR` | `~/.cerefox/backups` | Local directory where file system backups are stored. Created automatically if it doesn't exist. **Use an absolute path** — a relative value (such as the pre-v0.3.0 `./backups`) resolves against the current working directory, so snapshots scatter depending on where you run the command; `backup create` warns when it sees one. Does **not** follow `CEREFOX_CONFIG_DIR`, so a second environment must set it explicitly. |
 | `CEREFOX_ENV_LABEL` | _(unset)_ | Names a non-production environment (e.g. `staging`). Purely cosmetic and inert when unset. When set: the web UI shows a banner on every page, `doctor` shows `[LABEL]` on its title line, `backup create` puts the label in the snapshot filename and payload, and `backup restore` warns when a snapshot's environment differs from the target's, and `configure-agent` registers the MCP server as `cerefox-<label>` so a labeled environment sits alongside production instead of overwriting it (v1.4.0, #168). See [`staging-env.md`](staging-env.md). |
+| `CEREFOX_PROG_NAME` | _(unset)_ | The command you type for this environment, used in every hint and message that tells you what to run next (and in `--help`). Set it in an environment's `.env` when you reach it through an alias, for example `CEREFOX_PROG_NAME=cfx-stg` in `~/.cerefox/staging/.env`. A value in the `.env` wins over an inherited one, since it names that environment. `cerefox-local` sets it itself. When it is unset and `CEREFOX_CONFIG_DIR` is set, hints spell out `CEREFOX_CONFIG_DIR=<dir> cerefox …`, so a copied command never reaches your default environment (#352). |
 | `CEREFOX_VERSION_RETENTION_HOURS` | **Retired in v1.1.0 — no longer read.** | Version retention is now a property of the store: `cerefox config set version_retention_hours <hours>`, or the **Settings** page. It moved because it used to be passed per-call from each client's environment, so the surviving history depended on which client wrote last. `cerefox doctor` reports the variable if it is still set. |
 
 ---
@@ -354,8 +355,10 @@ container it points at `cerefox-local upgrade` instead of `cerefox self-update`.
 
 The only network call is a GET of the `latest` release from the npm registry
 (`registry.npmjs.org`), the same request `cerefox self-update` makes. It is made
-by `cerefox web` (at startup, then daily), `cerefox mcp` (at startup, when the
-last answer is over a day old), `cerefox doctor` and `cerefox self-update`.
+by `cerefox web` (at startup, then whenever the saved answer is over an hour old,
+so a new release shows in the web UI within about an hour), `cerefox mcp` (at
+startup, when the last answer is over an hour old), `cerefox doctor` and
+`cerefox self-update`.
 Every other command only reads the saved answer, `update-check.json` in
 `~/.cerefox` (or in `CEREFOX_CONFIG_DIR`, when set), so it never adds latency.
 Offline, the check stays quiet.

package/docs/guides/connect-agents.md

@@ -77,6 +77,10 @@ in the container.
   to `cerefox mcp` in the container; the same 15 core tools, identical behavior to every other path.
 - The cloud paths above (remote Edge Function, GPT Actions) **do not apply** to a local-only
   install — there are no Edge Functions.
+- **Cerefox Local on another machine** (a NAS or home server, v1.22.0+): `docker exec` is not
+  available from your other machines, so they use the ordinary local MCP server instead, with
+  the host's URL and its API key in a separate config directory, and
+  `cerefox-lan configure-agent`. See [`setup-lan.md`](setup-lan.md#the-cli-and-coding-agents-cerefox-local-only).
 
 ---
 

package/docs/guides/securing-local-access.md

@@ -181,6 +181,23 @@ The key authenticates; it does not identify. `X-Cerefox-Requestor` and
 described in [`api.md`](api.md#attribution-is-not-authentication). Holding the
 key does not make the name you send true.
 
+## What the key opens on Cerefox Local
+
+On Cerefox Local the gate covers two routes on the same port: `/api/v1`, the
+HTTP API, and `/rest/v1`, the database API the CLI and the local MCP server use.
+Since v1.22.0 (#351) a request that presents a valid key on `/rest/v1` reaches
+the database as the container's service role: the server swaps the key for the
+container's internal credential on the way in, the way Supabase's gateway does
+for an `sb_secret_` key, and that credential never leaves the container. This
+is what lets the CLI and coding agents on other machines use a Cerefox Local
+on a LAN host ([`setup-lan.md`](setup-lan.md)).
+
+It also means the key is the store's master key there: the database API can
+read and change every table directly, below the safeguards the RPCs apply
+(version history, the audit log). Give it only to clients you would give the
+whole store to. A request let in without a key (the gate off, or the loopback
+exemption) is forwarded exactly as before and gains nothing.
+
 ## Recipe: a harness in its own container
 
 The case where a key is genuinely needed, and the one worth automating.

package/docs/guides/setup-lan.md

@@ -2,7 +2,8 @@
 
 Run Cerefox on an always-on machine on your home or office network (a NAS, a
 mini PC, a home server) and use it from your other machines: agents, the CLI,
-and the web UI in a browser. Requires **v1.20.0 or newer**.
+and the web UI in a browser. Requires **v1.20.0 or newer** (the CLI and coding
+agents against Cerefox Local: **v1.22.0**).
 
 There are two ways to do it, and they do not depend on each other:
 
@@ -122,6 +123,101 @@ recreate the container. The data folder carries the database and, if you let the
 container mint it, the key. Cerefox Local applies pending schema migrations on
 boot.
 
+### On a Synology NAS
+
+Step by step with **Container Manager** on DSM 7.2. Menu names can differ a
+little between DSM versions.
+
+**1. Check the model can run it.** Container Manager has to be in Package
+Center for your model; if it is not there, the model cannot run containers. The
+image is published for both CPU types Synology uses, and Docker picks the right
+one when it pulls. You only need to know which one when you copy the image over
+as a file (step 3): **Control Panel → Info Center → General** shows the CPU. An
+Intel or AMD processor needs `linux/amd64`; an ARM one (Realtek, for example)
+needs `linux/arm64`.
+
+**2. Install Container Manager and make two folders.** Install it from Package
+Center; it creates a shared folder named `docker`. In File Station, create two
+folders inside it:
+
+- `docker/cerefox-db`: the database. Nothing else goes here.
+- `docker/cerefox-project`: the compose file. Keep it separate from the data.
+
+**3. Get the image.** Try **Container Manager → Registry** first. If the search
+or the download fails (some DSM versions answer `ghcr.io` with "registry
+returned bad result"), copy the image over as a file instead
+([above](#if-the-host-cannot-pull-the-image), with the `--platform` from step
+1), then **Image → Import → Add from file**. The image list must then show
+`ghcr.io/fstamatelopoulos/cerefox-local` with the tag you will put in the
+compose file, or Container Manager will try to pull it again.
+
+**4. Create the Project.** **Project → Create**:
+
+- **Project name:** `cerefox`.
+- **Path:** `docker/cerefox-project`.
+- **Source:** "Create docker-compose.yml", and paste:
+
+```yaml
+services:
+  cerefox:
+    image: ghcr.io/fstamatelopoulos/cerefox-local:v1.22.0
+    container_name: cerefox
+    restart: unless-stopped
+    ports:
+      - "8000:8000"
+    volumes:
+      - /volume1/docker/cerefox-db:/var/lib/postgresql/data
+    environment:
+      CEREFOX_API_REQUIRE_KEY: "1"
+      CEREFOX_API_KEY: "cfx_lak_YOUR-KEY"
+      CEREFOX_EMBEDDER: openai
+      OPENAI_API_KEY: "YOUR-OPENAI-KEY"
+    mem_limit: 2g
+```
+
+- **The volume path** is the full path on the NAS. `/volume1` is the first
+  storage volume; if your `docker` shared folder lives on another volume, File
+  Station shows which (right-click the folder, Properties).
+- **The left port** (`8000:`) is the one your other machines will use. Change
+  it if something on the NAS already uses 8000; leave the right one alone.
+- Skip the web portal (Web Station) step, then finish. Container Manager starts
+  the container.
+
+**5. Check it started.** **Container → cerefox → Log.** The first boot creates
+the database, which takes a minute; later boots apply any pending schema
+migrations and then the server starts. Then, from another machine, run the
+`curl` checks under [Using it from your other machines](#using-it-from-your-other-machines).
+
+**6. Keep it on your network.** Do not forward the port on your router, and do
+not publish it through QuickConnect, DSM's reverse proxy (Login Portal) or any
+other remote-access feature. To go one step further, **Control Panel → Security
+→ Firewall** can allow the port only from your local subnet.
+
+**Upgrading.** Back up first (below). Then:
+
+1. Stop the Project.
+2. Get the new image (step 3).
+3. Change the tag on the `image:` line in the Project's YAML.
+4. Build the Project again.
+
+The data folder carries the database, and the key stays in the Project's YAML
+(a key set there is not saved in the data folder), so nothing else changes.
+Once the new version is running, you can delete the old image under **Image**.
+
+**Protecting the data.** The NAS gives you three layers; use the last one in any
+case:
+
+- **Snapshots** (the Snapshot Replication package, on a Btrfs volume) of the
+  `docker` shared folder. A snapshot of a running database is only
+  *crash-consistent*, like pulling the power cord: Postgres recovers from it,
+  but stop the Project first if you want a clean copy.
+- **Hyper Backup** of the same folder to another disk or NAS. The same caveat
+  applies.
+- **`cerefox backup create`** from one of your machines, with the CLI set up as
+  below. It writes a JSON snapshot of your documents and projects to that
+  machine, which `cerefox backup restore` can load into a new Cerefox, on the
+  NAS or elsewhere.
+
 ## B. The web container, with your Supabase backend
 
 You need a working Supabase-backed Cerefox first (see
@@ -186,19 +282,69 @@ read it. It is readable by scripts running in the Cerefox page itself; the page
 renders documents without raw HTML, and the project's tests fail on any change
 that would let a document inject script.
 
-## What this does not protect
+### The CLI and coding agents (Cerefox Local only)
+
+Requires **v1.22.0 or newer** on the LAN host. Your other machines run the
+ordinary `cerefox` client (`npm install -g @cerefox/memory`) against the host,
+the same way they would run it against a Supabase project: a URL and a key in a
+`.env`. With the web container (B), point the client at your Supabase project as
+usual instead; the web container plays no part in it.
+
+Keep this setup in its own config directory, as you would a staging
+environment ([`staging-env.md`](staging-env.md)), so it never mixes with another
+Cerefox you use:
+
+```bash
+mkdir -p ~/.cerefox/lan && chmod 700 ~/.cerefox/lan
+cat > ~/.cerefox/lan/.env <<'ENV'
+CEREFOX_SUPABASE_URL=http://192.168.1.20:8000
+CEREFOX_SUPABASE_KEY=cfx_lak_YOUR-KEY
+CEREFOX_ENV_LABEL=lan
+CEREFOX_PROG_NAME=cerefox-lan
+CEREFOX_EMBEDDER=openai
+OPENAI_API_KEY=sk-YOUR-OPENAI-KEY
+ENV
+chmod 600 ~/.cerefox/lan/.env
+alias cerefox-lan='CEREFOX_CONFIG_DIR=~/.cerefox/lan cerefox'
+
+cerefox-lan doctor
+cerefox-lan configure-agent --tool claude-code   # adds an MCP server named cerefox-lan
+```
+
+- **The embedder must match the LAN host's.** The client computes the
+  embeddings for what it ingests and searches, as it does against Supabase, so
+  it needs the same `CEREFOX_EMBEDDER` as the host, and for `openai` its own
+  OpenAI key. A host that runs the local embedder needs `CEREFOX_EMBEDDER=local`
+  here, and the client then downloads the model once (about 130 MB).
+- **How the key gets in.** The client sends the key where a Supabase client
+  sends its secret key. The server checks it, then passes the request to the
+  database with the container's own internal credential, which never leaves
+  the container. This is the same exchange Supabase's gateway makes for an
+  `sb_secret_` key.
+- **`CEREFOX_PROG_NAME`** is the alias's name. Hints that tell you what to run
+  next (`doctor`'s suggestions, for example) then say `cerefox-lan …`, so a
+  copied one acts on the LAN host and not on another Cerefox you use.
+- **`CEREFOX_ENV_LABEL`** puts `[LAN]` on `doctor`'s title line and in backup
+  file names, and names the agent entry `cerefox-lan`.
+- **Agents without MCP.** A coding agent can also run `cerefox-lan` commands in
+  its shell, or call the HTTP API ([`api.md`](api.md)) with the key.
+- `configure-agent` pins the config directory into the agent's MCP entry, so
+  the agent reaches the LAN host whichever directory it starts in.
+
 
 **Traffic on the wire.** Plain `http://` on your network sends the key, and
-everything else, unencrypted. That is usually acceptable on a home network you
-control; it is not on a shared one. For TLS, put a reverse proxy in front (see
-[`securing-local-access.md`](securing-local-access.md#recipe-a-reverse-proxy-on-the-same-machine));
-the gate stays on, since a proxy makes every request look local.
+everything else, unencrypted. That is acceptable on a home network you control;
+do not run these setups on a network you share with people or devices you do
+not trust.
 
-**The internet.** Do not forward the port from your router. These setups are
-for your own network.
+**The internet.** These setups are for your own network only. Do not forward
+the port from your router, and do not publish the host's Cerefox port through
+a remote-access service or a proxy.
 
 **Anyone with the key**, or with access to the host's files, the data folder or
-the compose file.
+the compose file. On Cerefox Local the key is the store's master key: besides
+the web UI and the HTTP API, it opens the database API the CLI uses, which can
+read and change every table directly.
 
 ## Troubleshooting
 
@@ -209,6 +355,11 @@ planned.
 **Every data route returns 500 with the key, but `/version` works.** The image
 is older than v1.19.6. Upgrade.
 
+**The CLI or an agent fails with `Expected 3 parts in JWT; got 1`.** The
+Cerefox Local image on the LAN host is older than v1.22.0, which passed the key
+to the database unchanged. Upgrade the image; the client needs no change.
+`cerefox doctor` says the same.
+
 **The web UI shows a white page or keeps failing after the key.** The image is
 older than v1.20.0, which is the first version whose web UI can send a key.
 

package/docs/guides/staging-env.md

@@ -73,8 +73,12 @@ CEREFOX_CONFIG_DIR=~/.cerefox/staging cerefox init
 
 ```bash
 CEREFOX_ENV_LABEL=staging
+# The alias below; hints then say `cfx-stg …`. Comments go on their own line:
+# the .env parser keeps anything after `=` as the value.
+CEREFOX_PROG_NAME=cfx-stg
 CEREFOX_SUPABASE_URL=https://<staging-ref>.supabase.co
-CEREFOX_SUPABASE_KEY=sb_secret_…                 # staging project's secret key
+# The staging project's secret key:
+CEREFOX_SUPABASE_KEY=sb_secret_…
 CEREFOX_DATABASE_URL=postgresql://postgres.<staging-ref>:…@aws-0-<region>.pooler.supabase.com:5432/postgres?sslmode=require
 
 # Isolate snapshots. CEREFOX_BACKUP_DIR does NOT follow the config dir, so
@@ -84,7 +88,8 @@ CEREFOX_DATABASE_URL=postgresql://postgres.<staging-ref>:…@aws-0-<region>.pool
 CEREFOX_BACKUP_DIR=~/.cerefox/staging/backups
 
 OPENAI_API_KEY=sk-…
-SUPABASE_ACCESS_TOKEN=sbp_…                       # account-level; same as prod
+# Account-level; the same token as production:
+SUPABASE_ACCESS_TOKEN=sbp_…
 ```
 
 > **Snapshot isolation needs v1.1.0-beta.3 or later.** On **beta.2 and
@@ -262,6 +267,11 @@ otherwise:
 | `backup create` | Filename becomes `cerefox-staging-<stamp>.json`, and the label is stored in the payload |
 | `backup restore` | Warns when the snapshot's environment differs from the target's |
 
+Also set `CEREFOX_PROG_NAME` to your alias (`cfx-stg`). Hints that tell you what
+to run next, such as `doctor`'s `config set …` suggestions, then name the alias,
+so copying one acts on staging. Without it, they spell out
+`CEREFOX_CONFIG_DIR=… cerefox …`, which is just as safe, only longer.
+
 The filename and restore warning matter because `CEREFOX_BACKUP_DIR` does not
 follow `CEREFOX_CONFIG_DIR`: staging and production snapshots can end up in one
 directory, and a restore that picks "the most recent file" there would

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "Cerefox \u2014 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",
@@ -58,7 +58,7 @@
     "onnxruntime-node": "^1.21.0"
   },
   "devDependencies": {
-    "@types/bun": "^1.4.3",
+    "@types/bun": "^1.4.4",
     "@types/cli-progress": "^3.11.5",
     "@types/node": "^24.19.2",
     "@types/prompts": "^2.4.9",