MCP clients (Claude Code, Claude Desktop) surface the cold-load of the
ONNX/CoreML embedder + HNSW segment as -32000 "Internal tool error"
without a recoverable trace, because the first chromadb-touching tool
call after a fresh mempalace-mcp boot can exceed the client timeout.
Two opt-in env vars, both default off, both fail-soft:
- MEMPALACE_LOG_FILE: append-mode FileHandler so the server-side
traceback that the MCP client never surfaces stays diagnosable. Invalid
path falls back to stderr-only with a warning naming the env var, so
it cannot itself become a server-start failure. basicConfig uses
force=True so the FileHandler is not silently dropped when something
already configured root logging. (OSError, ValueError) catch covers
Windows NUL-byte paths in addition to POSIX missing-dir / EPERM.
- MEMPALACE_EAGER_WARMUP: pre-loads embedder + HNSW segment at the end
of main() startup via _get_collection(create=False).query(...) — a
single call drives ONNX _download_model_if_not_exists +
InferenceSession AND HNSW data_level0.bin segment load (HNSW chunks
are read lazily on the first chromadb collection op). Fresh-install
pre-check on os.path.isfile(palace/chroma.sqlite3) skips the warmup
before any chromadb client call so the chromadb constructor cannot
materialize the palace scaffold before `mempalace init` (preserves
CLAUDE.md "Incremental only" invariant). Truthy 1/true/yes/on; falsy
0/false/no/off and empty are silent; unrecognized values warn so
typos like "tru" do not silently disable the feature. All failure
paths (collection-open-raise, returned-None, query-raise) log with
palace path + device + error class so ops can disambiguate.
Empirical evidence (Linux, CPU-only ONNX, ~1k drawers): first
diary_write t_handoff = 7.60s baseline vs 0.17s with warmup
(-7.4s shifted off the first-call window into startup). CoreML cold-load
on macOS is reported at 5-30s in the issue's empirical record
(paideia#114); the CPU baseline above is the floor.
Tests (24 cases) cover both env vars across set/unset/empty/invalid/
garbage paths, warmup truthy/falsy/garbage parsing, fresh-install (real
integration, no monkeypatch — pins zero on-disk side effect),
collection-open-raise / returned-None / query-raise fail modes, and
two regression pins: warning-before-banner ordering (guards delay=True
regression) + truthy path actually invokes col.query (guards no-op
warmup regression). Probe text is a sentinel so it cannot semantically
match real drawer content.
Co-Authored-By: StarshipSuperjam <33380501+StarshipSuperjam@users.noreply.github.com>