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