Spomory MCP server

<!-- mcp-name: io.github.lyf-wxy/spomory -->

Spomory

English | 中文

Spomory gives Claude Desktop, Cursor, and Codex CLI a memory that persists across sessions — and is shared between all three. Tell one of them something once (a project detail, a preference, a fact about yourself) and any of them can recall it later, without you repeating yourself.

It runs as an MCP server, either locally on your own machine (free, nothing leaves your computer) or as a hosted cloud service (free signup, memory follows you across devices). The rest of this README covers the local path; for the cloud path see spomory.yliuai.com/get-started/remote.

Curious what it looks like before installing anything? There's a no-signup demo at spomory.yliuai.com — paste in some text, see the entities and relations it extracts.

Get started

Requires Python 3.11+.

1. Install

pip install "spomory[llm,embedding,mcp]"

2. Give it an LLM. Spomory uses an LLM to turn what you tell it into structured facts. Any OpenAI-compatible API works — OpenAI, DeepSeek, Qwen, etc.:

export LLM_API_KEY=sk-...
export LLM_BASE_URL=https://api.deepseek.com   # optional, defaults to OpenAI
export LLM_MODEL=deepseek-chat                 # optional, defaults to gpt-4o-mini

3. Connect it to your client. Claude Desktop, Cursor, and Codex CLI each need a few lines added to a config file, pointing at the spomory-mcp command. The exact steps, a config file example for each client, and a real gotcha we hit (macOS blocking a venv that lives under ~/Documents) are in docs/mcp_quickstart.en.md.

The one thing that trips people up: the config needs the **absolute

path** to spomory-mcp (run which spomory-mcp to find it) — the

client doesn't necessarily launch it with your shell's PATH set.

That's it. Data lives locally in ~/.memory-core/ by default (override with MEMORYCOREDATA_DIR). A Dockerfile is also included, for MCP directories/hosts that deploy from a container image instead.

Want the LLM calls local too, instead of a cloud API? Point LLMBASEURL at any local OpenAI-compatible server — vLLM, Ollama, llama.cpp, or MLX all work — and set EMBEDDINGPROVIDER=openaicompatible to route embedding the same way instead of the local sentence-transformers model, dropping the torch dependency entirely. Details and per-engine examples in docs/mcp_quickstart.en.md.

What it can do

Once connected, six tools become available inside the client:

All six are verified working end-to-end against real Claude Desktop, Cursor, and Codex CLI sessions, both local and remote — see docs/mcp_quickstart.en.md for what "verified" means for each client.

How it works, for the curious

You don't need any of this to use Spomory — it's here for people who want to know what's actually happening underneath.

Shortened. The full README is on GitHub.