@cerefox/memory 0.5.1 → 0.5.2

package/dist/bin/cerefox.js

@@ -7179,7 +7179,7 @@ var exports_meta = {};
 __export(exports_meta, {
   PKG_VERSION: () => PKG_VERSION
 });
-var PKG_VERSION = "0.5.1";
+var PKG_VERSION = "0.5.2";
 var init_meta = () => {};
 
 // ../../node_modules/.bun/tslib@2.8.1/node_modules/tslib/tslib.js

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

@@ -24,9 +24,14 @@ the canonical configuration recipe per MCP client.
   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.
+- **`cerefox mcp` (Python CLI)** starts the in-tree Python MCP server.
+  (v0.4–v0.5.1 advertised a "soft wrapper" that tried to delegate to the
+  npm package's TS MCP server via npx, but the probe was unreliable
+  under `uv run`-launched MCP-client contexts and caused infinite
+  recursion. v0.5.2 stripped the wrapper; the Python path is now
+  always the Python server, and the npm/TS path is configured
+  explicitly. See `docs/guides/migration-v0.5.md` § "v0.5.2 fixed the
+  soft wrapper" for the migration story.)
 
 ## The optional one-time upgrade
 
@@ -38,11 +43,18 @@ npm install -g @cerefox/memory
 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).
+After this, the npm `cerefox` is on your PATH. To actually have your
+MCP client use the TS server, you need to **update your MCP client
+config explicitly** — v0.5.2 removed the auto-delegation. The
+canonical config invokes the npm bin directly; see the next section.
 
-You can also point your MCP client directly at `cerefox-mcp` (the bin
-shipped by the package) and bypass the Python wrapper entirely:
+(v0.4–v0.5.1 *thought* it had auto-delegation, but the soft wrapper
+was unreliable under `uv run`-launched contexts and caused infinite
+recursion when the MCP client launched it. v0.5.2 took the simpler
+"each path is explicit" stance.)
+
+You can also point your MCP client directly at `cerefox mcp` (the
+TS-CLI subcommand) and bypass the Python path entirely:
 
 ### Claude Code
 

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

@@ -149,6 +149,53 @@ cerefox configure-agent --tool claude-code              # apply
 
 ---
 
+## v0.5.2 fixed the soft wrapper
+
+v0.4.0 through v0.5.1 advertised that `cerefox mcp` (the Python CLI's
+subcommand, used by configs of the form `uv run --directory /path/to/cerefox cerefox mcp`)
+was a "soft wrapper": it would try to delegate to the npm package's
+TS MCP server via `npx --no-install --package=@cerefox/memory cerefox`
+and fall back to the in-tree Python server otherwise.
+
+**The probe was unreliable under `uv run`-launched MCP-client contexts.**
+`uv run` puts the project's `.venv/bin/` first on PATH. When the npm
+cache only has v0.4.x (which doesn't ship a `cerefox` bin name), npx
+falls back to PATH and finds `.venv/bin/cerefox` — the Python CLI
+itself — making the probe report success. The execvp then PATH-falls
+back to the same `.venv/bin/cerefox`, which calls `_run_mcp()` again
+→ infinite recursion → MCP client times out with "Could not attach
+to MCP server cerefox."
+
+**v0.5.2 stripped the wrapper.** `cerefox mcp` always starts the
+in-tree Python MCP server. To use the TS MCP server, configure your
+client to invoke it explicitly:
+
+```json
+"command": "npx",
+"args": ["-y", "--package=@cerefox/memory", "cerefox", "mcp"]
+```
+
+or, if you have `@cerefox/memory` installed globally:
+
+```json
+"command": "cerefox",
+"args": ["mcp"]
+```
+
+The two paths (Python via `uv run`, TS via `cerefox mcp` on PATH or
+via `npx`) are functionally equivalent — same 10 MCP tools, same wire
+shapes. Pick whichever fits your environment, but the choice is now
+explicit instead of "magic delegation".
+
+> **Affected configs**: if your Claude Desktop / Claude Code / Cursor
+> config invokes `uv run … cerefox mcp` AND you saw "Could not attach
+> to MCP server cerefox" after restarting your client on
+> @cerefox/memory v0.5.1 or earlier, this is the bug. Upgrade to
+> v0.5.2+ (pull `main` and `uv sync`) — the Python MCP server boots
+> directly and your existing config works again.
+
+---
+
 ## Known gotchas
 
 ### `npx` from inside an npm workspace

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "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",