Summary

The "Tools don't appear in my editor" troubleshooting step in Getting Started and MCP Clients told users to run uvx --from memtomem memtomem-server in a terminal and check it "starts without errors". That guidance is actively wrong in two ways — it paints the terminal with scary ERROR output on a healthy install, and it silently provisions ~/.memtomem/. Replace it with two side-effect-free checks that actually help the user diagnose.

2 files, +8 / −2.

Closes #381.

Problem 1 — "starts without errors" is false

memtomem-server speaks JSON-RPC on stdin. When launched bare in a TTY, the terminal sends prompt noise / \n, the server rejects it as invalid JSON, and logs:

[04/22/26 23:20:49] ERROR    Received exception from stream: 1
                             validation error for JSONRPCMessage
                               Invalid JSON: EOF while parsing a value
                             at line 2 column 0 [type=json_invalid,
                             input_value='\n', input_type=str]

The server is working correctly. The user following the docs reasonably concludes it isn't.

Problem 2 — hidden side effect

memtomem-server initializes ~/.memtomem/ (creates memtomem.db + .server.pid) at startup, even if the user has never run mm init. A user who reads "should start without errors" and runs the command to check has quietly provisioned a state dir, and the docs give no signal that this happened.

This problem is broader than the verify command (see the follow-up discussion on #381: every MCP client connection triggers the same init path). The full fix is server-side lazy DB init; this PR handles the docs layer.

Proposed replacement

1. Restart your editor after configuring MCP
2. Check that `memtomem-server` (not `memtomem`) is in your MCP config
3. Verify the install is reachable: `mm --version` (or `uvx --from memtomem mm --version` for uvx-only setups) — side-effect-free, no state dir is touched
4. From inside the editor, ask it to call the `mem_status` tool — a successful response confirms the MCP handshake reached the server

> Don't run `uvx --from memtomem memtomem-server` in a terminal to test — it expects JSON-RPC on stdin, so TTY noise triggers `ERROR` lines that don't reflect install health, and the startup itself provisions `~/.memtomem/` even on a fresh machine.

Steps 3 and 4 together cover what step 3 alone was trying to do — "can the user reach the install" + "does the MCP handshake actually work". The "Don't" blockquote is there because old docs do circulate via search results / copies, and the silent side effect means quietly re-adopting it has real cost.

Fanout

Both files had the identical step, so both were updated consistently:

• docs/guides/getting-started.md — "Tools don't appear in my editor" section under Troubleshooting
• docs/guides/mcp-clients.md — same section heading under MCP Clients' Troubleshooting

No other copies of this guidance in public docs (grep -rn 'should start without errors' README.md packages/memtomem/README.md docs/ returns only these two lines).

Out of scope — tracked as follow-up

• Server-side fix: defer ~/.memtomem/ provisioning until the first tool call that actually needs SQLite. This is option (1) from the issue's follow-up comment and is the principled fix — the initialize / tools/list MCP handshake doesn't require a DB. Worth its own server-side PR; design surface includes where to hoist the lazy-open gate and how to avoid a race between two clients both creating the DB on first call.
• Log hygiene: downgrade the TTY-origin "Invalid JSON" ERROR to DEBUG so bare-TTY runs don't paint the terminal red. Separate, smaller, and independent of the lazy-init work.
• memtomem-server --version flag: mentioned in the issue as an option. Not needed for this PR since mm --version / uvx --from memtomem mm --version cover the same ground, but worth considering as a DX polish later.

Test plan

• mm --version verified side-effect-free on a fresh install (no ~/.memtomem/ created).
• uvx --from memtomem mm --version verified on a fresh uvx-only context.
• mem_status is a real MCP tool (exists in the core-9, see packages/memtomem/src/memtomem/server/__init__.py).
• Grep confirms no other public-doc copies of the misleading guidance.
• No code changes, so no lint/test runs affected.
• Reviewer: sanity-check the blockquote reads as an instruction to avoid, not an invitation.

🤖 Generated with Claude Code