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
Use the hosted server. Nothing to install:
claude mcp add --transport http smartmemory https://mcp.smartmemory.ai/mcp
The first tool call opens a browser for consent. Other clients (Claude.ai, Grok, xAI API) are under Client configuration.
Run it yourself instead (pip install, stdio):
pip install smartmemory-mcp # or, from a checkout: pip install -e .
# Run the server
smartmemory-mcp # or python -m smartmemory_mcp
Tests:
pytest tests/ -v
Backend: REST by default, in-process only on opt-in
The stdio and --http servers talk to a SmartMemory service over REST
(SMARTMEMORY_API_URL, SMARTMEMORY_API_KEY, SMARTMEMORY_WORKSPACE_ID; the older
SMARTMEMORY_TEAM_ID still works). A new session starts on the first of these that
is set: SMARTMEMORY_WORKSPACE_ID, then SMARTMEMORY_TEAM_ID, then the workspace
saved in the smartmemory config (switch_workspace(..., save_as_default=True)), then
your account's default workspace. The order is the same with or without the
smartmemory package installed, and one WARNING names both variables when they are
set to different workspaces. A live switch_workspace overrides all of them for the
rest of the session. Having the
smartmemory package importable does not switch them to an in-process store
any more (MCP-PERF-1): that loaded the embedding model, spaCy and the reranker into
every MCP process, 1.6-4 GB per Claude Code session.
SMARTMEMORY_MCP_MODE |
Backend |
|---|---|
unset or remote |
REST. A service that does not answer is logged once at WARNING with its URL, and tools return a clear error; nothing falls back to an in-process store. |
local |
In-process store (pip install smartmemory), models load on first use. Also warms the transcript-search models at boot. |
hosted |
the multi-tenant server below |
| anything else | one WARNING, then REST |
The smartmemory CLI config's mode = "local" is not an opt-in for the MCP; it is
logged once. The transcript tools (transcript_search and friends) read a local
store, so they still open it in-process on first use, with a WARNING.
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
| Mode | Command | Authentication | Tenancy |
|---|---|---|---|
| stdio | smartmemory-mcp |
none, local process | single identity |
| http | smartmemory-mcp --http |
none | single identity, loopback by default |
| hosted | smartmemory-mcp --hosted |
Clerk OAuth or a SmartMemory API key | per request |
--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.
| Variable | Meaning |
|---|---|
SMARTMEMORY_API_URL |
Base URL of smart-memory-service |
MCP_PUBLIC_BASE_URL |
Public URL of this server, e.g. https://mcp.smartmemory.ai |
CLERK_DOMAIN |
Clerk instance domain |
CLERK_OAUTH_CLIENT_ID |
Clerk OAuth application client id |
CLERK_OAUTH_CLIENT_SECRET |
Clerk OAuth application client secret |
MCP_JWT_SIGNING_KEY |
Signs the reference tokens issued to MCP clients |
MCP_STATE_ENCRYPTION_KEY |
Fernet key encrypting all stored OAuth state |
MCP_REDIS_URL |
Redis holding OAuth state, ideally its own instance |
Optional:
| Variable | Default | Meaning |
|---|---|---|
MCP_ALLOWED_CLIENT_REDIRECTS |
the six built-in patterns | Comma-separated client callback allowlist |
SMARTMEMORY_WEB_URL |
https://www.smartmemory.ai |
Web app URL shown when an invited beta user must accept the agreement |
MCP_HOSTED_PORT |
8012 |
Port to bind |
MCP_TRUST_PROXY |
false |
Honour X-Forwarded-For for rate limiting. Only true behind our own reverse proxy |
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 31 tools, an explicit allowlist rather than a tier:
memory_ingest memory_search memory_recall memory_ask read_around memory_get
memory_explain memory_recall_pack memory_policy_bundle memory_add
memory_update memory_supersede 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 list_workspaces switch_workspace
memory_update edits in place and keeps no history; to change or reverse a rule use memory_supersede(item_id, content, reason, valid_from=...), and ask memory_search(query, valid_at="2026-04-10") which rule was in force on a date (1.5.25).
Deprecated: switch_team (an alias of switch_workspace, removed in the next
release).
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_blameand the rest are out. - Anything that needs a local SmartMemory instance. Tools reaching for
backend._memor 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 thesmartmemorycore package, which the hosted server does not ship.memory_recall(session_id=…)andmemory_recall(cite=True)— the alternative recall path builds a working context through the core activation scorer.
list_workspaces() lists the workspaces you can use (GET /memory/workspaces).
switch_workspace(workspace) changes the workspace by id or name, with no
restart. The switch is saved server-side for you and this MCP client (1.5.24),
so it survives a reconnect or a restart of the hosted server and lapses after a
day without writes. It validates membership against the API and never leaks into
another user's calls. A refused switch names the workspace still in use. Every
write result ends with the line Workspace: <name> (<id>), routed by <lever>. Listing your workspaces needs an API key with the read:teams
scope (a key with only read:memories is told so and keeps its workspace).
whoami shows the user, tenant and workspace. The tenant comes from
your credential and is never a tool argument.
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_workspace 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.
memory_ask(question, limit=5, reasoning=True) uses the web app's Answer mode and returns the answer, evidence, reasoning, and relations.
A lost add receipt reports an unconfirmed write outcome. The memory may already exist. Check search or the memory list before retrying. Adds allow 120 seconds for the extraction pipeline, matching ingestion.
Metadata
Release files for smartmemory-mcp 1.5.28
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| smartmemory_mcp-1.5.28-py3-none-any.whl | Python 3 | none | any | Details for smartmemory_mcp-1.5.28-py3-none-any.whl |
Release files / smartmemory_mcp-1.5.28-py3-none-any.whl
| Download URL | smartmemory_mcp-1.5.28-py3-none-any.whl |
|---|---|
| Size | 170.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
caa8479972d3a0400f85cad039caaf0d7f361c6e05aa1b8fce948d8fd77259a1
|
|
BLAKE2b-256 checksum How to use checksums |
8813c07c8700636a25abd5e8c20ca307e29ece43172545d3b9d239486d5db827
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.7
|
Security for smartmemory-mcp 1.5.28
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.