MCP Integration Guide
The smart-memory-mcp package is an MCP server that exposes SmartMemory operations to MCP-compatible clients (Claude Desktop, Cursor, Maya, custom agents). It is a separate package from smart-memory-core and ships its own tool catalogue.
For the full tool catalogue with signatures, see api/tools.md.
Install
pip install smartmemory-mcpThe console script is smartmemory-mcp (registered in pyproject.toml):
smartmemory-mcp # stdio transport (default)
smartmemory-mcp --http # HTTP transport on 0.0.0.0:8011
smartmemory-mcp --http --port 9100 # custom HTTP portYou can also invoke the module directly: python -m smartmemory_mcp.
Backends
The server can route every tool call to one of two backends; the choice is independent of the tier model.
| Backend | When | How it's selected |
|---|---|---|
| Local | You have smartmemory installed locally. No FalkorDB or Redis needed. | Default. Uses the in-process Lite SmartMemory (SQLite graph, embedded vector index), see Lite Mode. |
| Remote | You want to talk to the managed SmartMemory Service. | smartmemory setup --mode remote (from the desktop app), or set SMARTMEMORY_API_KEY and ensure smartmemory_app config has mode=remote. |
whoami() reports the active backend.
Tiers
Tools are registered into three tiers at server startup. Restarting the server is required after any tier-changing event (login, env var change).
| Tier | Tools (cumulative) | Unlock |
|---|---|---|
| FREE | 26 | Default — no auth required |
| PRO | 58 (+32) | login(api_key) (or SMARTMEMORY_API_KEY env) |
| PRO+ | 89 (+31) | PRO and SMARTMEMORY_MCP_FULL_TOOLS=true |
FREE
login, whoami, switch_workspace, memory_save, memory_search, memory_recall (deprecated), get_working_context, memory_get, memory_export, memory_import, memory_migrate, memory_auto, memory_feedback, and the full decisions suite (decision_create, decision_get, decision_list, decision_search, decision_supersede, decision_retract, decision_reinforce, decision_contradict, decision_provenance, decision_find_conflicts, decision_create_pending, decision_resolve_requirement, decision_try_activate). Decisions need no API key, the same as the Python SDK.
PRO
PRO unlocks PRO-tier memory_* (CRUD: memory_update, memory_delete, memory_clear, memory_list, memory_stats, memory_save_conversation, memory_search_advanced, memory_search_by_metadata) and the code indexing, anchors, plans / failure recall, agent profiles, and document save (memory_save_document) suites.
PRO+
PRO+ adds reasoning, evolution, insights, dev workflow, and zettelkasten suites.
See api/tools.md for the complete per-tier list with signatures.
Authentication
Three sources are checked in order — the first non-empty value wins:
SMARTMEMORY_API_KEYenvironment variable.- The
smartmemory_appdesktop keyring (if installed). - The fallback file
~/.config/smartmemory/.api_key(written by thelogintool).
Calling the login tool stores the key into the file fallback and validates it against the API. The server only re-reads credentials at startup, so:
restart the MCP server after login()is mandatory.
switch_workspace(workspace) takes a workspace id or name and switches the current session at once, with no restart. The next request uses the new workspace, and the service still checks that you are a member. A refused switch tells you which workspace is still in use. Pass save_as_default=True to also write it into the smartmemory_app config for new sessions. Without the desktop app installed, set SMARTMEMORY_WORKSPACE_ID instead. In local mode the only workspace is default.
Listing your workspaces needs an API key with the read:teams scope. If your key lacks it, switch_workspace says so and leaves you in your current workspace. Create a key with Read teams enabled and use it instead.
A new session starts in the first workspace that is set, in this order:
SMARTMEMORY_WORKSPACE_IDSMARTMEMORY_TEAM_ID(the older name, still supported)- The workspace saved with
save_as_default=True - Your account's default workspace
The order is the same with or without the smartmemory package installed. If both variables are set to different workspaces, the server logs one warning that names both. An environment variable wins over a saved default, so save_as_default=True tells you when one is set.
whoami shows your user, tenant and workspace. Your tenant comes from your credential and is never a tool argument.
Deprecated: switch_team(team_id) still works for one more release as an alias of switch_workspace. It never saves a default.
Client configuration
Claude Desktop / Cursor
In the MCP client's config file (e.g. claude_desktop_config.json):
{
"mcpServers": {
"smartmemory": {
"command": "smartmemory-mcp",
"env": {
"SMARTMEMORY_API_KEY": "sm_live_...",
"SMARTMEMORY_MCP_FULL_TOOLS": "true"
}
}
}
}HTTP transport
For multi-process deployments or browser clients, run in HTTP mode:
smartmemory-mcp --http --port 8011Then point your MCP client at http://localhost:8011.
Calling a tool
Standard MCP tools/call:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "memory_search",
"arguments": { "query": "auth caching", "top_k": 5, "multi_hop": true }
}
}All tools return strings, except get_working_context which returns a structured surfacing-response dict.
Hosted MCP
For the managed SmartMemory Service there is also a hosted MCP server at https://mcp.smartmemory.ai/mcp. You run nothing yourself: each call is authenticated with OAuth through your SmartMemory account or with a SmartMemory API key, and runs as that caller. It exposes a fixed allowlist of tools rather than the full local tool catalogue. See Hosted MCP Server for setup.
Troubleshooting
- PRO tools missing after
login— restart the MCP server. Tier is resolved once at startup. whoamireportsBackend: remote (smartmemory package not installed)— installsmartmemoryfor local backend, or this is expected if you intend remote-only.- Tools time out: with the local backend, the first call can wait on loading the local models. Run
sm warmonce to preload them. With the remote backend, confirm the API URL is reachable. - Permission warning on
~/.config/smartmemory/.api_key— the loader logs a warning if the file is group/other-readable.chmod 600it.
See also
- MCP Tools API — every tool with its signature.
- SmartMemory API — Python API the tools wrap.