io.github.n24q02m/mnemo-mcp

Mnemo MCP Server

mcp-name: io.github.n24q02m/mnemo-mcp

Persistent AI memory with hybrid search and embedded sync. Open, free, unlimited.

Features

• Hybrid search -- FTS5 full-text + sqlite-vec semantic + reranking for precision
• Knowledge graph -- Automatic entity extraction and relation tracking across memories
• Importance scoring -- LLM-scored 0.0-1.0 per memory for smarter retrieval
• Auto-archive -- Configurable age + importance threshold to keep memory clean
• STM-to-LTM consolidation -- LLM summarization of related memories in a category
• Duplicate detection -- Warns before adding semantically similar memories
• Zero config -- Built-in local Qwen3 embedding + reranking, no API keys needed. Optional cloud providers (Jina AI, Gemini, OpenAI, Cohere)
• Multi-machine sync -- JSONL-based merge sync via embedded rclone (Google Drive, S3, Dropbox)
• Proactive memory -- Tool descriptions guide AI to save preferences, decisions, facts

Quick Start

Claude Code Plugin (Recommended)

Via marketplace (includes skills: /session-handoff, /knowledge-audit):

/plugin marketplace add n24q02m/claude-plugins
/plugin install mnemo-mcp@claude-plugins

Or install this plugin only:

/plugin marketplace add n24q02m/mnemo-mcp
/plugin install mnemo-mcp

Configure env vars in ~/.claude/settings.local.json or shell profile. See Environment Variables.

MCP Server

Option 1: uvx

{
  "mcpServers": {
    "mnemo": {
      "command": "uvx",
      "args": ["--python", "3.13", "mnemo-mcp@latest"]
    }
  }
}

// Cursor (~/.cursor/mcp.json), Windsurf, Cline, Amp, OpenCode
{
  "mcpServers": {
    "mnemo": {
      "command": "uvx",
      "args": ["--python", "3.13", "mnemo-mcp@latest"]
    }
  }
}

# Codex (~/.codex/config.toml)
[mcp_servers.mnemo]
command = "uvx"
args = ["--python", "3.13", "mnemo-mcp@latest"]

Option 2: Docker

{
  "mcpServers": {
    "mnemo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--name", "mcp-mnemo",
        "-v", "mnemo-data:/data",
        "-e", "API_KEYS",
        "-e", "SYNC_ENABLED",
        "n24q02m/mnemo-mcp:latest"
      ]
    }
  }
}

Configure env vars in ~/.claude/settings.local.json or your shell profile. See Environment Variables below.

Pre-install (optional)

Pre-download the embedding model (~570 MB) to avoid first-run delays. Use the setup MCP tool after connecting:

setup(action="warmup")

Sync setup

Sync is fully automatic. Just set SYNC_ENABLED=true and the server handles everything:

1. First sync: rclone is auto-downloaded, a browser opens for OAuth authentication
2. Token saved: OAuth token is stored locally at ~/.mnemo-mcp/tokens/ (600 permissions)
3. Subsequent runs: Token is loaded automatically -- no manual steps needed

For non-Google Drive providers, set SYNC_PROVIDER and SYNC_REMOTE:

{
  "SYNC_ENABLED": "true",
  "SYNC_PROVIDER": "dropbox",
  "SYNC_REMOTE": "dropbox"
}

Tools

MCP Resources

MCP Prompts

Configuration

Embedding & Reranking

Both embedding and reranking are always available -- local models are built-in and require no configuration.

• Jina AI (recommended): A single JINA_AI_API_KEY enables both embedding and reranking
• Embedding priority: Jina AI > Gemini > OpenAI > Cohere. Local Qwen3 fallback always available
• Reranking priority: Jina AI > Cohere. Local Qwen3 fallback always available
• GPU auto-detection: CUDA/DirectML auto-detected, uses GGUF models for better performance
• All embeddings stored at 768 dims. Switching providers never breaks the vector table

Security

• Graceful fallbacks -- Cloud → Local embedding, no cross-mode fallback
• Sync token security -- OAuth tokens stored at ~/.mnemo-mcp/tokens/ with 600 permissions
• Input validation -- Sync provider, folder, remote validated against allowlists
• Error sanitization -- No credentials in error messages

Build from Source

git clone https://github.com/n24q02m/mnemo-mcp.git
cd mnemo-mcp
uv sync
uv run mnemo-mcp

Compatible With

Also by n24q02m

Contributing

See CONTRIBUTING.md.

License

MIT -- See LICENSE.