@cerefox/memory 0.4.3 → 0.5.0

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

@@ -0,0 +1,231 @@
+# Migrating to Cerefox v0.4.0
+
+**TL;DR**: nothing urgent. Your existing `cerefox mcp` configs keep
+working unchanged. The Python `cerefox mcp` command is now a soft
+wrapper that transparently uses the new TypeScript MCP server if it's
+installed, falling back to the legacy Python implementation otherwise.
+Switch to the npm-installed TS server at your convenience for faster
+boot times and fewer Python dependencies.
+
+This guide is for **existing users** of `cerefox mcp` who want to
+optionally upgrade. **New users** should follow
+[`docs/guides/connect-agents.md`](connect-agents.md) instead — that's
+the canonical configuration recipe per MCP client.
+
+## What changed in v0.4.0
+
+- **`@cerefox/memory`** is a new npm package containing the Cerefox
+  local stdio MCP server. Same 10 MCP tools, same protocol, faster
+  boot.
+- **The Edge Function (`cerefox-mcp`) shares tool handlers** with the
+  new local server via `_shared/mcp-tools/`. One source of truth; no
+  drift.
+- **`cerefox_get_help`** is a new MCP tool (10 total now, was 9). Layer
+  3 of MCP discoverability — agents can now retrieve
+  `AGENT_QUICK_REFERENCE.md` content over MCP without filesystem
+  access.
+- **`cerefox mcp` (Python CLI) is a soft wrapper**: tries to delegate
+  to `npx --package=@cerefox/memory cerefox-mcp` first; falls back to the legacy
+  Python implementation if npm/Bun isn't available.
+
+## The optional one-time upgrade
+
+If you have Node 20+ installed, install `@cerefox/memory` globally:
+
+```bash
+npm install -g @cerefox/memory
+# or, if you have Bun:
+bun install -g @cerefox/memory
+```
+
+After this, your existing `cerefox mcp` configs automatically use the
+TS server (the soft wrapper detects the package and delegates).
+
+You can also point your MCP client directly at `cerefox-mcp` (the bin
+shipped by the package) and bypass the Python wrapper entirely:
+
+### Claude Code
+
+**Old:**
+
+```bash
+claude mcp add cerefox -- uv run --directory /path/to/cerefox cerefox mcp
+```
+
+**New (optional):**
+
+```bash
+claude mcp add cerefox -- npx -y --package=@cerefox/memory cerefox-mcp
+```
+
+### Cursor
+
+**Old** (`mcp.json` in your project or `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "cerefox": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/cerefox", "cerefox", "mcp"]
+    }
+  }
+}
+```
+
+**New (optional):**
+
+```json
+{
+  "mcpServers": {
+    "cerefox": {
+      "command": "npx",
+      "args": ["-y", "--package=@cerefox/memory", "cerefox-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+**Old** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "cerefox": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/cerefox", "run", "cerefox", "mcp"]
+    }
+  }
+}
+```
+
+**New (optional):**
+
+```json
+{
+  "mcpServers": {
+    "cerefox": {
+      "command": "npx",
+      "args": ["-y", "--package=@cerefox/memory", "cerefox-mcp"]
+    }
+  }
+}
+```
+
+### Codex CLI
+
+**Old** (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.cerefox]
+command = "uv"
+args = ["--directory", "/path/to/cerefox", "run", "cerefox", "mcp"]
+```
+
+**New (optional):**
+
+```toml
+[mcp_servers.cerefox]
+command = "npx"
+args = ["-y", "--package=@cerefox/memory", "cerefox-mcp"]
+```
+
+## Environment
+
+The new TS server reads `.env` the same way the Python CLI does (per
+v0.3.0's `_resolve_config_dir()`):
+
+1. `CEREFOX_CONFIG_DIR` env var override.
+2. `./.env` in the current working directory.
+3. `~/.cerefox/.env`.
+
+For most users with an existing Cerefox install, your `.env` is already
+where it needs to be. If you want to verify:
+
+```bash
+npx --package=@cerefox/memory cerefox-mcp --help
+```
+
+(That's the help text, not a server start — safe to run anywhere.)
+
+## Schema-version-mismatch banner
+
+The new server prints a one-line warning to stderr at boot if the
+bundled `@cerefox/memory` schema version doesn't match what's deployed
+to your Supabase. Run `uv run python scripts/db_deploy.py` from the
+repo to update.
+
+## Falling back
+
+If the npm path doesn't work for any reason (npx missing, package not
+installed, network issue during `npx` resolution), `cerefox mcp` falls
+back to the legacy Python server with a one-line stderr nudge. Your
+MCP client never notices — same stdio interface, same tools.
+
+To force the legacy path even when `@cerefox/memory` is installed:
+uninstall it (`npm uninstall -g @cerefox/memory`) or invoke the Python
+CLI from a shell without `npx` in `$PATH`.
+
+## `cerefox_get_help` — the new tool
+
+If you use Cerefox through an MCP client and ever wonder "wait, what's
+the right way to do X in Cerefox?", you can now ask the server
+directly:
+
+- `cerefox_get_help()` — returns the full `AGENT_QUICK_REFERENCE.md`
+  plus a section index.
+- `cerefox_get_help(topic: "links")` — returns just the cross-document
+  linking section.
+- `cerefox_get_help(topic: "update")` — returns the update workflow
+  sections.
+
+The topic match is a case-insensitive substring against H2 headings.
+Both the new TS server AND the legacy Python fallback expose this tool
+— consistent surface regardless of which path serves your session.
+
+## When v0.5.0 ships
+
+The TypeScript CLI lands in v0.5.0. At that point `@cerefox/memory`
+will gain a second binary (`cerefox`) for the full CLI surface
+(`cerefox search`, `cerefox ingest`, etc.) plus a `cerefox
+configure-agent` command that writes the right MCP config for each
+client automatically. For now, the manual recipes above are the way.
+
+## Known gotchas
+
+- **`npx` from inside an npm workspace can fail with "command not
+  found"** even when the package is correctly published. Running
+  `npx -y --package=@cerefox/memory cerefox-mcp` from the root of a
+  surrounding npm-workspace monorepo (your own project) confuses npx's
+  bin-resolution path. Symptoms: `sh: cerefox-mcp: command not found`
+  even though the published package has the bin entry. Workarounds —
+  any one of these works:
+  - Use `bunx` instead: `bunx --package @cerefox/memory cerefox-mcp` —
+    cleanly handles workspace contexts.
+  - Run from a non-workspace directory (e.g. `cd /tmp` first).
+  - Install globally and invoke from PATH:
+    `npm install -g @cerefox/memory` then `cerefox-mcp`.
+  - When configuring an MCP client (Claude Code, Cursor, Claude
+    Desktop, Codex CLI), the launched process inherits the client's
+    own working directory rather than your shell's, so this gotcha
+    usually doesn't bite real MCP usage — only manual `npx` smoke
+    tests run from a project root.
+
+- **The minimum npm version for OIDC publish is 11.5.1.** The shipped
+  `release.yml` workflow already pins this; only relevant if you're
+  forking the project for your own publish target.
+
+## What didn't change
+
+- The Edge Function (remote MCP) URL and auth: unchanged. Same
+  Bearer-with-anon-JWT pattern; the EF just shares its tool handlers
+  with the local TS server now.
+- The Postgres RPC contracts: unchanged. v0.4.0 ships zero schema
+  changes — the `cerefox_schema_version()` RPC introduced in v0.3.0
+  still returns `0.3.1`. (The mismatch warning at TS server startup
+  fires until you redeploy from `main`, which is what you'd do
+  whenever the schema version actually bumps.)
+- Web UI, ingestion pipeline, CLI subcommands: all unchanged in v0.4.
+  Those migrate in v0.6 and v0.7.

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

@@ -0,0 +1,165 @@
+# Migrating to Cerefox v0.5.0
+
+**TL;DR:** the Cerefox CLI is now a TypeScript binary published to npm.
+You can keep using the Python CLI through v0.7.x (it just prints a
+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.
+
+---
+
+## What changed
+
+### `cerefox` is now an npm-installable binary
+
+```bash
+npm install -g @cerefox/memory     # or: bun install -g @cerefox/memory
+cerefox doctor                     # callable from any directory
+```
+
+The Python `cerefox` CLI (installed via `uv sync` in a Cerefox checkout)
+keeps working, but now prints a deprecation banner. Removal is v0.8 /
+v0.9 — see iter-23 plan / Decision Log Q2 for the schedule.
+
+### New lifecycle commands
+
+| Command | What it does |
+|---|---|
+| `cerefox init` | Interactive 5-step bootstrap (Supabase URL, key, OpenAI, Postgres URL, identity). Writes `~/.cerefox/.env`, validates credentials, ingests bundled self-docs, optionally wires Claude Code or Claude Desktop. |
+| `cerefox doctor` | 9 diagnostic checks (runtime, config, Supabase, OpenAI, schema version, MCP clients, …). |
+| `cerefox status` | Fast 3-check subset of `doctor`. |
+| `cerefox configure-agent --tool claude-code` | Writes `~/.claude/mcp.json` (or merges) to wire up the `cerefox` MCP server. Phase 1: Claude Code + Claude Desktop. Cursor / Codex / Gemini ship in v0.5.x. |
+| `cerefox self-update` (alias `cerefox upgrade`) | Detects installer (bun / npm / yarn / pnpm) and upgrades in place. Also refreshes the bundled-docs ingest. |
+| `cerefox sync-self-docs` | Ingests bundled `AGENT_GUIDE.md` + `AGENT_QUICK_REFERENCE.md` + curated `docs/guides/*.md` under the `_cerefox-self-docs` project. Layer 2 of the MCP discoverability story (§10d in the design doc). |
+
+### Improved help + tab completion
+
+```bash
+cerefox --help                     # commands grouped READS / WRITES / SERVERS / LIFECYCLE / OPS
+cerefox completion bash > ~/.cerefox-completion.bash
+echo 'source ~/.cerefox-completion.bash' >> ~/.bashrc
+```
+
+### Documented exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | User error (bad flag, missing arg, malformed JSON) |
+| 2 | System error (Supabase unreachable, RPC failure) |
+| 3 | Not found (document / version / project) |
+
+---
+
+## Install paths
+
+### Option A — one-line install (recommended for new machines)
+
+```bash
+curl -fsSL https://github.com/fstamatelopoulos/cerefox/releases/latest/download/install.sh | sh
+```
+
+The script detects Bun first, falls back to npm, bootstraps Bun if
+neither is available. Then runs `<runtime> install -g @cerefox/memory`.
+
+### Option B — direct npm install
+
+```bash
+npm install -g @cerefox/memory       # Node ≥ 20 required
+# or
+bun install -g @cerefox/memory       # faster install + bin start
+# or
+pnpm add -g @cerefox/memory
+yarn global add @cerefox/memory
+```
+
+### Option C — keep the Python install (no change required)
+
+Your existing `uv run cerefox …` keeps working. You'll see a one-line ⚠
+banner pointing at the migration path; suppress with
+`CEREFOX_NO_DEPRECATION_BANNER=1`.
+
+---
+
+## What's NOT in v0.5
+
+Three commands are deliberately Python-only (or deferred) for v0.5:
+
+- **`cerefox web`** — the TypeScript web server lands in v0.6. For now,
+  the npm-installed `cerefox web` prints a "use `uv run cerefox web` from
+  a clone" message and exits 0. The Python web server keeps working.
+- **`cerefox reindex`** — depends on the v0.7 TS ingestion pipeline.
+  Same "use uv" message; exit 0.
+- **Schema deploy in `cerefox init`** — needs a Postgres direct
+  connection that v0.5 doesn't ship. `init` prints the
+  `uv run python scripts/db_deploy.py` command at the right moment; v0.6
+  ports the deploy step.
+
+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:
+
+```json
+{
+  "mcpServers": {
+    "cerefox": {
+      "command": "npx",
+      "args": ["-y", "--package=@cerefox/memory", "cerefox-mcp"]
+    }
+  }
+}
+```
+
+**That keeps working.** v0.5 ships the **same** `cerefox-mcp` bin in
+the **same** npm package. No change required.
+
+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
+are preserved.
+
+```bash
+cerefox configure-agent --tool claude-code --dry-run    # preview
+cerefox configure-agent --tool claude-code              # apply
+```
+
+---
+
+## Known gotchas
+
+### `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
+not found." Use `bunx` instead, run from outside any workspace, or
+`npm install -g`.
+
+Doesn't affect MCP-client launches (the client controls the launched
+process's CWD).
+
+### Schema-version banner in the web UI
+
+If you upgrade `@cerefox/memory` but haven't redeployed the schema, the
+v0.3.0+ schema-version-mismatch banner fires. Run
+`uv run python scripts/db_deploy.py` to sync.
+
+This isn't unique to v0.5 — it's the same banner v0.3.0 introduced.
+
+---
+
+## Where to go next
+
+- `cerefox docs --list` — bundled docs, offline.
+- `cerefox doctor` — see what's missing / configured.
+- [`docs/guides/connect-agents.md`](connect-agents.md) — full MCP client guide.
+- [`docs/guides/cli.md`](cli.md) — every command and flag, in detail.
+- [`CHANGELOG.md`](../../CHANGELOG.md) — what shipped in v0.5.0.

package/docs/guides/operational-cost.md

@@ -0,0 +1,113 @@
+# Operational Cost
+
+Cerefox is designed to be cheap to run. This page explains what you will (and won't) pay for,
+and gives rough estimates for two common deployment scenarios.
+
+> **Disclaimer**: Pricing for third-party services (Supabase, OpenAI, GCP) changes over time
+> and varies by region and usage pattern. Treat the figures here as order-of-magnitude guidance
+> for a typical single-user personal knowledge base, not as a billing guarantee. Check each
+> provider's current pricing page before committing to a setup.
+
+---
+
+## What costs money
+
+| Component | Cost driver |
+|-----------|-------------|
+| **Supabase** | Database storage and API calls. The free tier is generous and covers a typical personal knowledge base indefinitely. |
+| **OpenAI embeddings** | Charged per token when ingesting content or running searches. The default model (`text-embedding-3-small`) is among the cheapest available. |
+| **Cloud Run** (optional) | Compute for the web UI if you deploy it to GCP rather than running it locally. |
+| **Artifact Registry** (optional) | Docker image storage on GCP, if you deploy to Cloud Run. |
+
+---
+
+## Scenario A — Local webapp (lean setup)
+
+The web UI and CLI run on your own machine. Supabase is the only cloud service.
+
+```
+Your machine
+├── cerefox CLI + web UI  (free — runs locally)
+└── Supabase (cloud)      (free tier)
+    └── PostgreSQL + pgvector
+        Embeddings via OpenAI API  (pay-per-use)
+```
+
+**Typical cost for personal use**: a few cents to a couple of dollars per month, almost entirely
+from OpenAI embedding calls. Light users (a few hundred documents ingested and searched
+occasionally) will see costs well under a dollar a month. Heavier usage — thousands of documents
+with frequent AI agent queries — might reach a few dollars a month.
+
+You only pay for embeddings when:
+- Ingesting new or updated content (one embedding call per chunk, typically a few hundred tokens)
+- Searching via `cerefox mcp` or the CLI (one embedding call per query)
+
+The web UI's built-in search bar and document browser make no embedding calls.
+
+### Supabase free tier limits
+
+Supabase's free tier is sufficient for a personal knowledge base. Key limits as of early 2026:
+
+- 500 MB database storage (text + vectors; a typical knowledge base is well under this)
+- 50,000 API calls/month (for queries via supabase-py)
+- 2 active projects
+
+If you exceed these limits, Supabase's Pro plan is the next step — check
+[supabase.com/pricing](https://supabase.com/pricing) for current rates.
+
+---
+
+## Scenario B — Cloud Run webapp
+
+The web UI is deployed to Google Cloud Run so it's accessible from any browser without keeping
+your laptop on. Everything else is the same as Scenario A.
+
+```
+Your machine / any browser
+└── Cloud Run (GCP)       (free tier; small charge if exceeded)
+    └── cerefox web UI
+Supabase (cloud)          (free tier)
+└── PostgreSQL + pgvector
+    Embeddings via OpenAI API  (pay-per-use)
+```
+
+**Typical cost for personal use**: similar to Scenario A for embeddings, plus a small amount
+for Cloud Run and image storage. Cloud Run has a generous always-free tier (2 million requests
+and 360,000 vCPU-seconds per month) that easily covers low-traffic personal use. Docker image
+storage in Artifact Registry costs a small amount per GB per month.
+
+In practice, most single users running Cerefox on Cloud Run pay roughly the same as Scenario A
+— a few cents to a couple of dollars per month in total.
+
+### GCP free tier limits
+
+Cloud Run's free tier limits as of early 2026:
+
+- 2 million requests/month
+- 360,000 GB-seconds of memory/month
+- 180,000 vCPU-seconds/month
+
+These limits comfortably cover personal-use traffic. Check
+[cloud.google.com/run/pricing](https://cloud.google.com/run/pricing) for current rates.
+
+---
+
+## Controlling embedding costs
+
+If you want to keep costs as low as possible:
+
+- **Fireworks AI** is an OpenAI-compatible alternative that offers competitive embedding prices.
+  See `docs/guides/configuration.md` for how to switch.
+- **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 reindex`**: Re-embeds all existing chunks if you switch embedders. Run this once
+  after switching, not repeatedly.
+
+---
+
+## What is always free
+
+- The Cerefox application itself (Apache 2.0 open source, no license fees)
+- Local CLI and web UI (runs on your machine)
+- All search RPCs and FTS queries (Supabase free tier covers personal-scale usage)
+- Backups and restores (JSON snapshots, no cloud storage required)