[FEATURE] Support running multiple Basic Memory MCP servers concurrently (dev + prod, local + cloud)

[groksrc]

Summary

When developing against basic-memory-cloud locally, I have to swap my Claude.ai connector between the production Basic Memory Cloud endpoint and the dev endpoint. I can't run both at once productively — connecting both surfaces duplicate tool names (e.g. two write_note, two search_notes, etc.) and the model gets confused about which instance to call.

This makes day-to-day dev painful and also blocks useful workflows like moving notes between dev and production for testing.

Current behavior

• One connector configured → can only use that environment.
• Two connectors configured (prod + dev) → tools are duplicated under identical names; model picks unpredictably; no way to say "use the dev one" without manually re-reading tool descriptions.
• No supported pattern for running, e.g., a local-only instance alongside a cloud instance.

Desired behavior

A first-class way to run 2+ Basic Memory MCP servers concurrently without tool-name collisions or model confusion. Some directions worth considering:

1. Tool name prefixing / namespacing. Allow each server instance to declare a short prefix (e.g. prod_, dev_, local_) that gets applied to all exposed tool names. The model then sees prod_write_note vs dev_write_note and can disambiguate from the name alone.
2. Instance label surfaced in tool descriptions. Even without renaming tools, every tool's description could lead with the configured instance label so the model has clear context when picking.
3. Cross-instance operations. Once multiple instances are addressable, expose a way to copy/move notes between them (e.g. transfer_note(source="dev", target="prod", permalink=...)) — useful for promoting test notes to prod or seeding dev from prod.
4. Mixed local + cloud configuration. Support a setup where one configured instance is local-only (filesystem-backed) and another is cloud, both available in the same Claude session.

Use cases

• Active dev on basic-memory-cloud while still using prod for real work in the same Claude session.
• Promoting / copying notes from a dev workspace to prod after testing.
• Running a local-only scratch instance alongside a synced cloud instance.

Notes

Happy to help refine the design or prototype the prefixing approach if useful.

[claude]

Claude finished @groksrc's task in 2m 12s —— View job

---

Issue Triage

• Gather context and read issue
• Check for duplicate issues
• Classify issue type, priority, component, complexity
• Add appropriate labels
• Provide triage summary

---

Thanks for the detailed write-up, @groksrc! Here's the triage:

Type: Enhancement / Feature Request
Priority: Medium — developer productivity improvement; not blocking core functionality for most users
Component: MCP tools, Cloud
Complexity: Complex — requires architectural changes at the FastMCP/server layer
Labels added: enhancement, cloud
Duplicates: None found

---

Analysis

The root cause is a limitation of how MCP clients handle multiple servers exposing identically-named tools — the model sees flat tool lists with no namespace signal, making disambiguation impossible. Basic Memory already has per-project routing (get_project_client() in mcp/project_context.py) that handles local vs. cloud for a single server, but that's orthogonal to running two separate MCP server processes with unique tool names.

Feasibility of each proposed approach:

1. Tool name prefixing — Most impactful. FastMCP supports tool naming at registration time, so a configurable --prefix flag on the MCP server (e.g. basic-memory mcp --prefix dev_) that wraps all tool names is architecturally sound. This is the recommended path. Tradeoff: requires clients to know the prefix upfront.

2. Instance label in tool descriptions — Low effort, partial win. Every tool description could include [Instance: dev] at the top if a --label flag is passed. This helps the model disambiguate via reasoning but doesn't prevent the tool list from being noisy.

3. Cross-instance operations — Additive on top of Pre release #1. Once two instances are addressable via distinct tool names, a transfer_note tool could be implemented. Higher complexity but valuable for the dev→prod promotion workflow.

4. Mixed local + cloud in one session — Already partially supported via per-project cloud routing (project set-cloud). The remaining gap is using this alongside a separately-connected MCP server, which Pre release #1 would unblock.

Recommended Implementation Path

1. Add --prefix (and optionally --label) flags to basic-memory mcp CLI
2. Pass the prefix through to the FastMCP app at startup so all tool names are registered as {prefix}{tool_name}
3. Surface the label in tool descriptions when set
4. Document a sample Claude Desktop config for running dev + prod side-by-side

This would make this a medium complexity change in practice — mostly contained to cli/, mcp/server.py, and mcp/tools/ registration, with no schema migrations needed.

Happy to review a prototype if you want to take a first pass at the --prefix flag approach!