@cerefox/memory 0.5.0 → 0.5.1

package/README.md

@@ -2,15 +2,22 @@
 
 **User-owned shared memory for AI agents.** The local TypeScript runtime for
 [Cerefox](https://github.com/fstamatelopoulos/cerefox) — a persistent,
-curated knowledge layer that multiple AI tools can read and write, backed by
-Postgres + pgvector.
+curated knowledge layer that multiple AI tools can read and write.
 
-This package contains two binaries:
+> **Cerefox is BYO-storage.** This package is the *client* — the CLI + local
+> MCP server. The knowledge base itself lives in **your own Supabase project**
+> (Postgres + pgvector; free tier works). Installing this npm package does
+> **not** give you a working KB on its own; you also need a Supabase project +
+> an embedding API key. The first-run `cerefox init` wires everything together
+> in ~2 minutes once you have those in hand. **See "Before you install"
+> below.**
 
-| Bin | What it does |
+This package contains a single binary, **`cerefox`**:
+
+| Subcommand | What it does |
 |---|---|
-| **`cerefox`** | Main CLI — search, ingest, list, version-history, audit-log, lifecycle (`init`, `doctor`, `configure-agent`, `self-update`). Callable from any directory. |
-| **`cerefox-mcp`** | Local stdio MCP server. Drop-in for Claude Code, Cursor, Claude Desktop, Codex CLI, Gemini CLI. Exposes the same 10 MCP tools as the remote `cerefox-mcp` Edge Function. |
+| `cerefox <command>` | CLI — search, ingest, list, version-history, audit-log, lifecycle (`init`, `doctor`, `configure-agent`, `self-update`). Callable from any directory. |
+| `cerefox mcp` | Local stdio MCP server. Drop-in for Claude Code, Cursor, Claude Desktop, Codex CLI, Gemini CLI. Exposes the same 10 MCP tools as the remote `cerefox-mcp` Edge Function. |
 
 > **What this package isn't:** the source of truth for Cerefox's architecture
 > or docs. Those live in the [GitHub repo](https://github.com/fstamatelopoulos/cerefox).
@@ -18,37 +25,59 @@ This package contains two binaries:
 
 ---
 
+## Before you install
+
+Cerefox is a self-hosted memory layer. To use it you need three things, none
+of which this npm package brings with it:
+
+| Prerequisite | Why | How |
+|---|---|---|
+| A **Supabase project** | The knowledge base (documents + chunks + embeddings) lives in your Supabase project's Postgres database, with pgvector for semantic search. Free tier is enough for most personal use. | Sign up at [supabase.com](https://supabase.com), create a project, then follow the [Supabase setup guide](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/setup-supabase.md) — deploy the Cerefox schema (one script), then deploy the Edge Functions (one command). Estimate: 10–15 minutes the first time. |
+| An **embedding API key** | Cerefox embeds your documents for semantic search. OpenAI's `text-embedding-3-small` is the default; Fireworks AI is an alternative. | Get an [OpenAI API key](https://platform.openai.com/api-keys) — costs are pennies/month for typical personal use (see [operational-cost.md](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/operational-cost.md)). |
+| **Node ≥ 20** or **Bun ≥ 1.0** | Runtime for the `cerefox` bin (and the bundled `cerefox mcp` server). | [nodejs.org](https://nodejs.org) or [bun.sh](https://bun.sh). The one-line installer below bootstraps Bun for you if neither is present. |
+
+If you don't yet have Supabase + an OpenAI key, the [Cerefox
+quickstart](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/quickstart.md)
+walks through the whole setup in one place.
+
+---
+
 ## Install
 
+Once you have the prerequisites above in hand:
+
 ```bash
-# One-line install (recommended on a fresh machine):
+# One-line install (recommended on a fresh machine; bootstraps Bun if needed):
 curl -fsSL https://github.com/fstamatelopoulos/cerefox/releases/latest/download/install.sh | sh
 
-# Direct (any of these):
+# Or direct (any of these):
 bun install -g @cerefox/memory
 npm install -g @cerefox/memory
 pnpm add -g @cerefox/memory
 yarn global add @cerefox/memory
 ```
 
-Runtime requirements: **Node ≥ 20** or **Bun ≥ 1.0**.
-
 ---
 
 ## First-run setup
 
 ```bash
-cerefox init        # 5-step interactive bootstrap (Supabase, OpenAI, identity)
+cerefox init        # 5-step interactive bootstrap (asks for Supabase URL,
+                    # Supabase key, OpenAI key, optional Postgres URL, identity)
 cerefox doctor      # verify everything reaches
 ```
 
-Cerefox needs:
-
-- A **Supabase project** (free tier works) — see
-  [`docs/guides/setup-supabase.md`](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/setup-supabase.md).
-- An **OpenAI API key** for embeddings (or Fireworks AI as an alternative).
+`cerefox init` prompts for the credentials you collected above, validates them
+against the live services, writes `~/.cerefox/.env` (chmod 0600), and
+optionally wires up an MCP client. **It does not create the Supabase project
+for you** — you'll be asked for the URL + key, so make sure those are
+already provisioned (see "Before you install").
 
-`cerefox init` walks you through both.
+> **Schema deploy (v0.5):** if your Supabase project is fresh, `cerefox init`
+> tells you to run `uv run python scripts/db_deploy.py` from a Cerefox repo
+> clone to install the schema. This last manual step goes away in v0.6 when
+> the deploy logic is ported to the TS CLI. For now, the setup-supabase
+> guide walks through it.
 
 ---
 
@@ -68,7 +97,7 @@ is:
   "mcpServers": {
     "cerefox": {
       "command": "npx",
-      "args": ["-y", "--package=@cerefox/memory", "cerefox-mcp"]
+      "args": ["-y", "--package=@cerefox/memory", "cerefox", "mcp"]
     }
   }
 }
@@ -101,8 +130,9 @@ by category).
 
 ## Why install the CLI when I already have MCP wired up?
 
-You don't have to. `cerefox-mcp` works standalone — wire it into any MCP
-client and your AI agent has full access. The `cerefox` CLI is useful for:
+You don't have to. `cerefox mcp` (started as a stdio subprocess by any
+MCP client) gives your AI agent full access to the knowledge base on
+its own. The rest of the `cerefox` CLI is useful for:
 
 - **One-off shell operations**: search, ingest, list, audit-log.
 - **Power-user workflows**: `cerefox ingest-dir ./meeting-notes`,

package/dist/bin/cerefox.js

@@ -7179,7 +7179,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "0.5.0";
+var PKG_VERSION = "0.5.1";
 var init_meta = () => {};
 
 // ../../node_modules/.bun/tslib@2.8.1/node_modules/tslib/tslib.js
@@ -38141,7 +38141,7 @@ import { dirname, join as join3 } from "node:path";
 function defaultCerefoxEntry() {
   return {
     command: "npx",
-    args: ["-y", "--package=@cerefox/memory", "cerefox-mcp"]
+    args: ["-y", "--package=@cerefox/memory", "cerefox", "mcp"]
   };
 }
 function claudeCodeConfigPath() {
@@ -39343,7 +39343,7 @@ function registerListVersions(program2) {
 
 // src/cli/commands/mcp.ts
 function registerMcp(program2) {
-  program2.command("mcp").description("Start the local stdio MCP server (same as the cerefox-mcp bin).").action(async () => {
+  program2.command("mcp").description("Start the local stdio MCP server.").action(async () => {
     const { buildServer: buildServer2 } = await Promise.resolve().then(() => (init_server3(), exports_server));
     const handle = buildServer2();
     await handle.run();

package/docs/guides/connect-agents.md

@@ -68,7 +68,7 @@ Three top-level paths plus a few special cases:
 - Some content ingested (`cerefox ingest my-notes.md`)
 
 **For Path A-Local only:**
-- **Recommended (v0.4.0+):** [Node.js ≥20](https://nodejs.org) (for `npx --package=@cerefox/memory cerefox-mcp`)
+- **Recommended (v0.4.0+):** [Node.js ≥20](https://nodejs.org) (for `npx --package=@cerefox/memory cerefox mcp`)
   + `.env` file in the working directory the client launches the server from (see "env block"
   in the per-client configs below if your client can't see the file)
 - **Alternative:** [`uv`](https://docs.astral.sh/uv/getting-started/installation/) installed on your machine + Cerefox repository cloned locally (e.g. `/Users/yourname/src/cerefox`)
@@ -112,10 +112,10 @@ The local Cerefox MCP server runs on your machine and exposes the same 10 tools
 Edge Function, communicating with clients over stdio.
 
 As of **v0.4.0** the local server ships as an npm package — **[`@cerefox/memory`](https://www.npmjs.com/package/@cerefox/memory)** — built with the official `@modelcontextprotocol/sdk`.
-The bin entry is `cerefox-mcp`. The recommended client config is `npx -y --package=@cerefox/memory cerefox-mcp`.
+The bin entry is `cerefox` (run as `cerefox mcp`). The recommended client config is `npx -y --package=@cerefox/memory cerefox mcp`.
 
 The legacy `uv run cerefox mcp` invocation **still works** and is preserved as a soft
-wrapper: it tries `npx --no-install @cerefox/memory cerefox-mcp` first and falls back to the
+wrapper: it tries `npx --no-install @cerefox/memory cerefox mcp` first and falls back to the
 Python MCP server if npm is unavailable or `@cerefox/memory` isn't installed. New users
 should prefer the npm-native config; existing users don't have to change anything.
 
@@ -199,7 +199,7 @@ After setup, ask your client:
   "mcpServers": {
     "cerefox": {
       "command": "npx",
-      "args": ["-y", "--package=@cerefox/memory", "cerefox-mcp"],
+      "args": ["-y", "--package=@cerefox/memory", "cerefox", "mcp"],
       "env": {
         "CEREFOX_SUPABASE_URL": "https://<your-project-ref>.supabase.co",
         "CEREFOX_SUPABASE_KEY": "<your-service-role-or-sb_secret-key>",
@@ -228,7 +228,7 @@ server can find — the server resolves `.env` from the current working director
 
 Replace `/path/to/cerefox` with the absolute path to your Cerefox checkout
 (e.g. `/Users/yourname/src/cerefox` on macOS, `C:\Users\yourname\src\cerefox` on Windows).
-This invocation soft-wraps `npx --package=@cerefox/memory cerefox-mcp` when available; otherwise the
+This invocation soft-wraps `npx --package=@cerefox/memory cerefox mcp` when available; otherwise the
 legacy Python MCP server takes over.
 
 **Important:**
@@ -262,7 +262,7 @@ legacy Python MCP server takes over.
   "mcpServers": {
     "cerefox": {
       "command": "npx",
-      "args": ["-y", "--package=@cerefox/memory", "cerefox-mcp"],
+      "args": ["-y", "--package=@cerefox/memory", "cerefox", "mcp"],
       "env": {
         "CEREFOX_SUPABASE_URL": "https://<your-project-ref>.supabase.co",
         "CEREFOX_SUPABASE_KEY": "<your-service-role-or-sb_secret-key>",
@@ -302,7 +302,7 @@ separate from `claude_desktop_config.json`. Changes made in one do not affect th
 
 ```bash
 claude mcp add --scope user cerefox \
-  npx -- -y --package=@cerefox/memory cerefox-mcp
+  npx -- -y --package=@cerefox/memory cerefox mcp
 ```
 
 - `--scope user` makes the server available in every project (stored in `~/.claude/mcp.json`).
@@ -324,7 +324,7 @@ claude mcp add --scope user cerefox \
   uv -- --directory /path/to/cerefox run cerefox mcp
 ```
 
-This soft-wraps `npx --package=@cerefox/memory cerefox-mcp` when available; otherwise falls back to
+This soft-wraps `npx --package=@cerefox/memory cerefox mcp` when available; otherwise falls back to
 the legacy Python MCP server.
 
 **Option 3: `.mcp.json` in project root (project-scoped, committable)**
@@ -336,7 +336,7 @@ Create `.mcp.json` in the root of the repo you work in:
   "mcpServers": {
     "cerefox": {
       "command": "npx",
-      "args": ["-y", "--package=@cerefox/memory", "cerefox-mcp"]
+      "args": ["-y", "--package=@cerefox/memory", "cerefox", "mcp"]
     }
   }
 }

package/docs/guides/migration-v0.5.md

@@ -6,10 +6,10 @@ one-line ⚠ banner now), but the npm path is faster, doesn't need a
 local clone, and adds new lifecycle commands (`init`, `doctor`,
 `configure-agent`, `self-update`).
 
-> **Existing v0.4.x users:** your MCP client configs keep working.
-> v0.4.0 already shipped the `cerefox-mcp` bin on npm; v0.5 adds the
-> `cerefox` CLI bin **inside the same `@cerefox/memory` package**. One
-> install, both bins.
+> **Existing v0.4.x users:** your MCP client configs need a one-line
+> update (the `cerefox-mcp` bin from v0.4 → v0.5.0 was removed in
+> v0.5.1 — it's redundant with `cerefox mcp`). See the
+> ["Upgrading an existing MCP client config"](#upgrading-an-existing-mcp-client-config) section below for the exact diff.
 
 ---
 
@@ -106,7 +106,7 @@ If your usage hits any of these, keep your Python install around for now.
 
 ## Upgrading an existing MCP client config
 
-The v0.4.x config you may have written looked like:
+The v0.4.x → v0.5.0 config you may have written looked like:
 
 ```json
 {
@@ -119,12 +119,27 @@ The v0.4.x config you may have written looked like:
 }
 ```
 
-**That keeps working.** v0.5 ships the **same** `cerefox-mcp` bin in
-the **same** npm package. No change required.
+**In v0.5.1 this breaks.** The standalone `cerefox-mcp` bin was removed
+in v0.5.1 — it duplicated `cerefox mcp` for no functional gain. Update
+the `args` array to invoke the `mcp` subcommand of the main bin
+instead:
+
+```diff
+   "args": [
+     "-y",
+     "--package=@cerefox/memory",
+-    "cerefox-mcp"
++    "cerefox",
++    "mcp"
+   ]
+```
+
+The behaviour is identical — same `buildServer()` factory, same 10
+MCP tools, same stdio transport. Only the bin name changes.
 
-If you want the v0.5 `cerefox configure-agent` to (re)write the config
-for you, the command is non-destructive: it backs up the existing file
-to `<file>.pre-cerefox.bak` and merges. Existing `mcpServers` entries
+If you want `cerefox configure-agent` to rewrite the config for you,
+the command is non-destructive: it backs up the existing file to
+`<file>.pre-cerefox.bak` and merges. Existing `mcpServers` entries
 are preserved.
 
 ```bash
@@ -139,7 +154,7 @@ cerefox configure-agent --tool claude-code              # apply
 ### `npx` from inside an npm workspace
 
 The v0.4 gotcha still applies: running `npx -y --package=@cerefox/memory
-cerefox-mcp` from inside another npm workspace can fail with "command
+cerefox mcp` from inside another npm workspace can fail with "command
 not found." Use `bunx` instead, run from outside any workspace, or
 `npm install -g`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/fstamatelopoulos/cerefox",
@@ -27,7 +27,6 @@
     "bun": ">=1.0.0"
   },
   "bin": {
-    "cerefox-mcp": "dist/bin/cerefox-mcp.js",
     "cerefox": "dist/bin/cerefox.js"
   },
   "files": [
@@ -56,13 +55,11 @@
     "typescript": "^6.0.3"
   },
   "scripts": {
-    "build": "bun build src/bin/cerefox-mcp.ts src/bin/cerefox.ts --outdir dist/bin --target node --format esm",
-    "build:mcp": "bun build src/bin/cerefox-mcp.ts --outdir dist/bin --target node --format esm",
-    "build:cli": "bun build src/bin/cerefox.ts --outdir dist/bin --target node --format esm",
+    "build": "bun build src/bin/cerefox.ts --outdir dist/bin --target node --format esm",
     "clean": "rm -rf dist docs AGENT_GUIDE.md AGENT_QUICK_REFERENCE.md",
     "bundle-docs": "bun run ../../scripts/bundle_package_docs.ts",
     "prepublishOnly": "bun run clean && bun run bundle-docs && bun run build",
-    "smoke": "node dist/bin/cerefox-mcp.js --help && node dist/bin/cerefox.js --help"
+    "smoke": "node dist/bin/cerefox.js --help && node dist/bin/cerefox.js mcp --help"
   },
   "publishConfig": {
     "access": "public",