smart-memory-mcp

Unified SmartMemory MCP (Model Context Protocol) server — tiered tools, local + remote backends.

mcp-name: ai.smartmemory/smartmemory-mcp

Overview

MCP server exposing SmartMemory operations to MCP-compatible clients (Claude Desktop, Cursor, etc.). Implements the full memory toolset (add, search, recall, decisions, plans, anchors, code-index) and routes to either a local SmartMemory instance or a remote smart-memory-service API endpoint.

Status

Version: 0.2.1

Quick start

pip install -e .

# Run the server
smartmemory-mcp        # or python -m smartmemory_mcp

Tests:

pytest tests/ -v

Hosted mode

--hosted serves the multi-tenant, OAuth-protected endpoint that runs at mcp.smartmemory.ai. It is a different server from the stdio and --http modes: every request carries its own credential, and the tool call is executed as that caller against smart-memory-service. The process holds no shared API key and no core SmartMemory instance.

Hosted search and recall ask the service to exclude speculative-derived memories server-side, while retaining client-side tier filtering as defence in depth.

SMARTMEMORY_MCP_MODE=hosted smartmemory-mcp
# or
smartmemory-mcp --hosted

Install with the extra, which adds the Redis-backed OAuth state store:

pip install "smartmemory-mcp[hosted]"

Modes

--http has no per-request authentication, so every caller of it acts as whoever the process's API key belongs to. It therefore binds 127.0.0.1 and logs a warning if asked for anything else. Set SMARTMEMORY_MCP_ALLOW_UNAUTH_HTTP=true to override that deliberately. Use --hosted if what you want is a server on the network.

Environment

All of these are required in hosted mode. A missing one raises at startup, naming the variable.

Optional:

Set MCP_JWT_SIGNING_KEY explicitly. Left unset, the signing key is derived from the Clerk client secret, which ties rotating that secret to invalidating every token already issued.

Tools

Local code_index indexes Python, JavaScript, TypeScript, JSX and TSX through core CodeIndexer. Standalone remote installations without core use the bundled Python parser and report a warning that TS/JS/TSX/JSX indexing and shared cross-file resolution require pip install smartmemory-core. A hard parse error refuses replacement and retains the prior index. Recoverable grammar partials travel with visible diagnostics. Hosted code_upload publishes a client-parsed bundle containing repo, entities, relations and optional commit_hash and parse_summary. It accepts up to 10,000 source files and 64 MiB per bundle. Destination workspace comes from the authenticated session. The hosted tool accepts no checkout path.

Code indexing reports clean, partial and failed file counts plus acceptance, staging and publication outcomes. Every hosted response derives counts from uploaded file evidence. Uncomputable evidence and missing server counts are displayed as unknown. Localized grammar partials with usable extraction can publish with visible spans and byte coverage. Hard collection or parse failures retain the prior index. Partial 1.x acceptance does not prove G16 complete-generation publication. Successful file extraction checkpoints are stored under SMARTMEMORY_CODE_CHECKPOINT_DIR (default ~/.cache/smartmemory/code-parse) and reused when source, configuration and parser versions match. Remote code indexing preserves the server diagnostic counts and publication outcome on HTTP failures. Transport loss reports an unconfirmed server outcome.

Local code_effects(directory, repo_name=None) scans Python effects through the shared engine without opening a memory store. Hosted code_effects(repo, source_snapshot, limit=20, offset=0) reads uploaded fa_snapshot records in the selected workspace. It accepts no filesystem path. Upload the engine's snapshot_record payload through existing declared-record ingestion first. Repository rules belong in the scanned checkout's .smartmemory-effects.json.

Hosted mode advertises 27 tools, an explicit allowlist rather than a tier:

memory_ingest memory_search memory_recall read_around memory_get memory_explain memory_recall_pack memory_policy_bundle memory_add memory_update memory_delete memory_list memory_stats memory_distill memory_ingest_conversation memory_search_by_metadata memory_feedback code_search code_dead_code code_dependencies code_upload code_effects agent_set_recall_profile agent_get_recall_profile reasoning_query_traces whoami switch_team

Everything else is hidden, and hidden is the default, so a tool added to a shared module does not appear here until it is added to the allowlist. Three kinds of tool are excluded on purpose:

• Anything that reads or writes a filesystem path. The container's disk is shared by every tenant, so memory_export, memory_import, code_index, code_blame and the rest are out.
• Anything that needs a local SmartMemory instance. Tools reaching for backend._mem or the core graph cannot work against a REST backend.
• Destructive bulk operations, such as memory_clear.

Two tools have options that cannot work here and refuse them rather than quietly ignoring the request:

• memory_search(cite=True) — citation formatting lives in the smartmemory core package, which the hosted server does not ship.
• memory_recall(session_id=…) and memory_recall(cite=True) — the alternative recall path builds a working context through the core activation scorer.

switch_team changes the workspace for the current session only. It validates membership against the API and never leaks into another user's calls.

Client configuration

Claude Code:

claude mcp add --transport http smartmemory https://mcp.smartmemory.ai/mcp

The first tool call opens a browser for consent. Claude Code registers itself through client id metadata, so nothing needs to be created in advance.

Claude.ai custom connector: add a connector with the URL https://mcp.smartmemory.ai/mcp and complete the OAuth prompt.

Grok web: add a connector with the same URL. Grok asks for a client id rather than registering dynamically, so paste the SmartMemory MCP OAuth application client id when prompted.

xAI API and Grok Build take a static bearer token instead of an OAuth flow, so give them a SmartMemory API key:

{
  "type": "mcp",
  "server_url": "https://mcp.smartmemory.ai/mcp",
  "authorization": "sm_live_your_key_here"
}

An API key skips the OAuth flow entirely and acts as its owner in that owner's default workspace. Legacy sk_ keys are accepted.

Documentation

Full SmartMemory documentation: https://docs.smartmemory.ai

Part of SmartMemory

This is one component of the SmartMemory ecosystem. See the main repo for the broader project.

Lexical search migration

Search uses lexical with default weight 0.8. Replace removed contains and keyword-bm25 channel weights explicitly. A zero weight disables lexical, and omission preserves the existing default/profile behavior. Required lexical unavailability fails the whole search. Service callers receive 400 for query/name validation and 503 for unavailable indexes.

Local tools, hosted search and the remote backend validate the same names. Failed search returns an MCP error result, including connection failure.

Quiesce old writers before first-open indexing. Verify the engine capability pin and use sm rebuild --lexical for recovery. Migration, targets and measured limitations.

Company project alongside local memory

Keep your existing local smartmemory connection. Add claude mcp add --transport http smartmemory-company https://mcp.smartmemory.ai/mcp and authenticate with your own company-org login. Check whoami for the expected tenant, use switch_team with the project's paired Workspace ID, then check again. Recheck after reconnect because selection is session-scoped. The owner and Kyle authenticate separately. No local-memory upload or local backend switch is needed. Hosted Team responses use team_id. Independent Workspace selection is outside this change. Live OAuth and two-user access acceptance remain required.