MoltMind

Persistent semantic memory and session continuity for AI agents. One install, zero config, runs 100% locally.

MoltMind is an MCP server that gives your AI agent long-term memory across sessions — storing learnings, decisions, error fixes, and handoff context using local SQLite and embeddings. No API keys, no cloud, no accounts needed.

Why MoltMind?

Every time your AI agent starts a new conversation, it forgets everything. It spends 1-2 minutes re-reading your files, re-learning your architecture, and re-discovering decisions you already made. MoltMind gives it memory — your agent picks up right where it left off in seconds.

| | Without MoltMind | With MoltMind | |--|-----------------|---------------| | Model used | Claude Opus 4.6 ($5/$25 per 1M tokens) | | | Time per session | 1-2 min re-exploring | Seconds to resume | | Cost per session | ~$0.09 | ~$0.009 | | 20 sessions | $1.80 | $0.18 | | Daily use (1 year) | $32.85 | $3.29 | | Time saved (1 year) | — | ~6 hours | | Money saved (1 year) | — | ~$30 |

Assumes ~8,000 input + ~2,000 output tokens per cold start, ~825 input + ~200 output per resume. Savings scale with usage — power users save more.

Quick Start

Claude Code

claude mcp add moltmind -- npx -y moltmind

Restart Claude Code, then run /mcp to verify.

With moltbook social features:

claude mcp add moltmind -- npx -y moltmind --moltbook

See moltbook.com for the agent social network.

Other Clients

Add to your client's MCP config file:

{
  "mcpServers": {
    "moltmind": {
      "command": "npx",
      "args": ["-y", "moltmind"]
    }
  }
}

With moltbook: "args": ["-y", "moltmind", "--moltbook"]

| Client | Config file | Key | |--------|------------|-----| | Cursor | ~/.cursor/mcp.json or .cursor/mcp.json | mcpServers | | Windsurf | ~/.codeium/windsurf/mcp_config.json | mcpServers | | VS Code (Copilot) | .vscode/mcp.json | servers | | Cline | Settings > MCP Servers > Edit Config | mcpServers | | Codex CLI | ~/.codex/config.json | mcpServers | | Any MCP client | Varies | mcpServers |

Note: VS Code uses "servers" instead of "mcpServers" as the top-level key.

Upgrading

npx -y moltmind always fetches the latest version. If you have a stale global install:

npm uninstall -g moltmind   # then let npx handle it

Tools

14 core tools by default, 21 with --moltbook:

| Tool | Description | |------|-------------| | mm_store | Store a memory (learning, error fix, decision, plan, or raw note) | | mm_recall | Search memories — hybrid semantic + keyword search | | mm_read | Read a specific memory by ID | | mm_update | Update an existing memory | | mm_delete | Archive a memory (soft delete) | | mm_status | Server health dashboard | | mm_init | Create a project-local memory vault | | mm_handoff_create | Structured handoff for agent-to-agent context transfer | | mm_handoff_load | Load the most recent handoff | | mm_session_save | Save session summary and where you left off | | mm_session_resume | Restore context from recent sessions | | mm_session_history | Browse past sessions with tool call stats | | mm_feedback | Report bugs or request features | | mm_metrics | Adoption and health metrics dashboard |

How It Works

Memory & Search — Your agent stores memories in a local database. When it needs to find something, MoltMind searches by meaning (not just keywords) — so searching for "API port" finds a memory about "our server runs on port 8080". If the search model isn't downloaded yet, it falls back to keyword matching.

Sessions & Handoffs — Sessions are auto-created on startup and auto-paused on shutdown. Your agent saves where it left off and picks up seamlessly next time. Handoffs let one agent pass context to another with structured goal/state/next-action documents.

Diagnostics — Every tool call is logged locally with timing and success/failure. mm_status shows health, mm_metrics shows usage stats and token savings. All data stays on your machine.

What It Costs (Tokens)

Every MCP tool adds a small overhead to each request because the AI needs to know what tools are available. Here's what MoltMind costs — and what it saves you:

| | Cost per request | In dollars | |--|-----------------|------------| | MoltMind overhead (14 tools) | ~500 tokens | ~$0.0015 | | With prompt caching | ~50 tokens | ~$0.00015 | | Session resume (saves you) | ~7,675 tokens | ~$0.023 |

Bottom line: MoltMind pays for itself after a single session resume. Every conversation after that is pure savings.

Free vs Pro

| | Free | Pro ($9 one-time) | |--|------|-----| | Stores per day | 20 | Unlimited | | Total memories | 200 | Unlimited | | Search | Unlimited | Unlimited | | Session tools | Unlimited | Unlimited | | Vector search | Brute-force | Zvec ANN (auto) |

Upgrade to Pro

From your terminal

macOS / Linux:

npx moltmind --upgrade

Windows (Command Prompt or PowerShell):

npx moltmind --upgrade

Same command on all platforms. A checkout page opens in your browser, you pay $9, and the terminal waits up to 5 minutes for payment. Once confirmed, your license activates automatically — no copy-pasting keys, no config files.

Prerequisite: You must have run MoltMind at least once before upgrading (so your machine ID exists at ~/.moltmind/instance_id). If you just installed, open your AI client, let MoltMind start, then come back and run --upgrade.

From inside your AI agent

If you're already in a conversation with an agent that has MoltMind installed, just say:

"Upgrade MoltMind to Pro"

Your agent will run npx moltmind --upgrade for you, the checkout page opens, and the license activates after payment. Works in Claude Code, Cursor, Windsurf, Cline, Codex CLI — any client where MoltMind is installed.

After payment

• License is written to ~/.moltmind/license.key
• Zvec ANN search auto-enables on next startup
• mm_status shows "Pro" tier
• Restart your MCP client to pick up the change

Machine lock and migration

Pro licenses are tied to one machine (your instance_id). A daily heartbeat check enforces this.

• Switching machines? Run npx moltmind --upgrade on the new one. Your old machine reverts to free within 24 hours.
• Offline? A 7-day grace period keeps Pro active while you're disconnected.
• All data stays local. The heartbeat only sends your machine ID and license prefix — no memory content ever leaves your machine.

Search Performance (Pro)

Pro tier uses Zvec ANN for fast memory search. Here's what that means in practice:

Accuracy — At 1,000 memories (a typical heavy user), Zvec finds 98% of the exact same results as an exhaustive search. Your agent gets the right answer almost every time.

Speed — Search takes under 1ms at 1,000 memories. At 10,000 memories, it's still under 5ms. Your agent won't notice any delay.

Reliability — Handles 330+ searches per second with zero latency spikes. Deleted memories never come back. Results are deterministic.

See BENCHMARK_RESULTS.md for the full report, or RUNBOOK.md for how to run benchmarks yourself.

Data Storage

| Path | Purpose | |------|---------| | ~/.moltmind/memory.db | Global memory vault | | ./.moltmind/memory.db | Project-local vault (via mm_init) | | ~/.moltmind/models/ | Cached embedding model (~22MB) | | ~/.moltmind/instance_id | Anonymous instance identifier | | ~/.moltmind/license.key | Pro license (after upgrade) |

Requirements

• Node.js 18+
• No API keys required
• No internet after first embedding model download

License

MIT