Local, free, and private

This is the default recommended way to use Spomory: no registration, your memory graph never leaves your machine, encrypted at rest by default. It runs as a stdio MCP server that Claude Desktop or Cursor spawn as a subprocess.

1. Install

Requires Python 3.11+. Using uv (recommended):

uv pip install "memory-core[llm,embedding,mcp] @ git+https://github.com/yliuai/spomory.git"
# or, for local development from a cloned repo:
uv pip install -e ".[llm,embedding,mcp]"

2. Configure

Set these environment variables. Defaults to OpenAI; swap LLM_BASE_URL / LLM_MODEL for any other OpenAI-compatible provider (DeepSeek, Qwen, etc.):

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

3. Run

memory-core-mcp

⚠️ On macOS, don't install the runtime under ~/Documents (or Desktop/Downloads)

A real gotcha we actually hit: if the command path points inside ~/Documents/<project>/.venv/..., Claude Desktop's MCP server subprocess fails with "Server disconnected." The real error, in ~/Library/Logs/Claude/mcp-server-<name>.log, is a PermissionError reading the venv's own pyvenv.cfg. The cause is macOS's TCC privacy protection: ~/Documents, ~/Desktop, and ~/Downloads are protected by default against apps (and their subprocesses) without explicit Full Disk Access — this has nothing to do with the code or where the repo lives, it's an OS-level restriction on those specific folders.

The fix: Install the virtual environment actually used to run the MCP server somewhere outside ~/Documents (e.g. ~/mcp-servers/), non-editable:

mkdir -p ~/mcp-servers
uv venv --python 3.11 ~/mcp-servers/memory-core-venv
uv pip install "/path/to/memory-core[llm,embedding,mcp]" \
    --python ~/mcp-servers/memory-core-venv/bin/python

4. Configure Claude Desktop / Cursor

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 the absolute path of memory-core-mcp inside the non-Documents virtual environment from step above:

{
  "mcpServers": {
    "Spomory": {
      "command": "/Users/<you>/mcp-servers/memory-core-venv/bin/memory-core-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.

Cursor

Same JSON shape, in ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project). Restart Cursor after editing. This path is inferred from Cursor's official MCP docs and hasn't been tested against a real Cursor install — please verify with the steps below after connecting.

Where your data lives

Local SQLite files (graph data + usage stats) live in ~/.memory-core/ by default (override with MEMORY_CORE_DATA_DIR) — deliberately outside Documents/Desktop/Downloads. Every entity and relation is stored as ciphertext, not plaintext: the first startup generates an encryption.key file (mode 600) next to the database, and reuses it on every later run. Upgrading from an older, unencrypted database migrates it automatically on first launch (the original file is backed up, not deleted).

Verify it works (should take under 10 minutes)

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

Troubleshooting

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 — that's exactly how the TCC issue above gets diagnosed.

The five tools

add_memory	Extracts facts from text and writes them into the graph.
search_memory	Matches the query against triples, expands via personalized PageRank, returns a natural-language context.
forget_memory	Finds the single best-matching relation and physically deletes it, cleaning up orphaned entities and logging the deletion.
get_graph	Returns the subgraph around an entity, as JSON.
export_memory	Exports the entire graph as a memory passport.

Full quickstart doc on GitHub (includes more detail) →