Spomory
← All platforms

Claude Desktop

A JSON config file for local, OAuth 2.1 for cloud — both verified end-to-end.

Spomory connects to Claude Desktop two ways: a local stdio server (free, private, runs on your machine) or the hosted cloud endpoint over OAuth 2.1 (memory follows you across devices). Both expose the same six tools.

Local (stdio)

Add this to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json). The key under mcpServers is what shows up in the client UI — rename it if you like, but keep the log filename note below in sync. Point command at uvx — it downloads and runs Spomory on demand, no install step, and it sidesteps macOS's ~/Documents subprocess-blocking gotcha entirely:

{
  "mcpServers": {
    "Spomory": {
      "command": "uvx",
      "args": ["--from", "spomory[llm,embedding,mcp]", "spomory-mcp"],
      "env": {
        "LLM_API_KEY": "...",
        "LLM_BASE_URL": "https://api.deepseek.com",
        "LLM_MODEL": "deepseek-v4-flash"
      }
    }
  }
}

If this file already has other keys, only add mcpServers — don't touch anything else, and back up the file first. Fully quit and reopen Claude Desktop for the change to take effect.

Prefer a fixed, pinned install over uvx's on-demand cache? Install into a virtual environment outside ~/Documents (pip install 'spomory[llm,embedding,mcp]'), then point command at that venv's bin/memory-core-mcp directly.

Verify it works (should take under 10 minutes)

  1. Open Claude Desktop, start a new conversation, and confirm the Connectors/MCP tools list shows Spomory connected.
  2. Have Claude call add_memory: "Please call Spomory's add_memory tool to remember: I work as a backend engineer at Some Company."
  3. Start a new conversation and have Claude call search_memory: "Where do I work?" — confirm it retrieves what you just wrote.
  4. Have Claude call forget_memory to remove it, then repeat the search — confirm the memory is gone.

If Claude Desktop shows "Server disconnected," the real error is in ~/Library/Logs/Claude/mcp-server-Spomory.log (filename follows whatever key you used under mcpServers). Check that file first.

Where do these environment variables come from?

LLM_API_KEY is your key for whichever OpenAI-compatible provider you use for extraction — OpenAI, DeepSeek, Qwen, and others all work. LLM_BASE_URL and LLM_MODEL default to OpenAI if you leave them out; swap them to point at DeepSeek, Qwen, or any other OpenAI-compatible provider, or a fully local server (Ollama, vLLM, llama.cpp, MLX):

export LLM_API_KEY=...
export LLM_BASE_URL=https://api.deepseek.com   # optional, defaults to OpenAI
export LLM_MODEL=deepseek-v4-flash             # optional, defaults to gpt-4o-mini
export EMBEDDING_MODEL=BAAI/bge-m3             # optional, defaults to bge-m3
Full local setup guide, including the macOS ~/Documents gotcha →

Full local setup guide on GitHub →

Cloud (OAuth 2.1)

Uses OAuth. Settings → Connectors → Add custom connector — name it anything, URL https://api.yliuai.com/mcp. It'll redirect you through an authorization flow; sign-in is a magic link — enter your email, click the link you receive, and you're redirected back to Claude, now connected.

Verified end-to-end: connecting, and all six tools (including forget_all_memory) showing up with correct per-tool approval settings in Claude Desktop's Connector tools list.

Full remote-access guide on GitHub →

Make it actually get used

Connecting the tools doesn't mean your client reaches for them on its own — it needs to be told to call search_memory before answering and add_memory after you share something worth keeping. SKILL.md is a short instructions file that does that. How you load it is specific to each client: some auto-discover a skills folder the same way Claude Code does, others only have a custom-instructions or system-prompt field instead. Verified for this one:

Claude Desktop doesn't scan a local folder for this — its Skills feature is account-level: Settings → Capabilities → Skills → upload SKILL.md as a folder or .zip. It then syncs to every Claude surface tied to your account.

SKILL.md on GitHub →