moltmind 0.7.1 → 0.7.3

package/README.md

@@ -4,6 +4,20 @@ Persistent semantic memory and session continuity for AI agents. One install, ze
 
 MoltMind is an [MCP](https://modelcontextprotocol.io) 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. Re-exploring your codebase costs ~8,000 tokens per session — about **$0.024** on Claude Sonnet. That adds up fast:
+
+| Project size | Without MoltMind | With MoltMind | You save |
+|-------------|-----------------|---------------|----------|
+| 5 sessions | $0.12 | $0.02 | **$0.10** |
+| 20 sessions | $0.48 | $0.05 | **$0.43** |
+| Daily use (1 year) | $8.76 | $0.87 | **$7.89** |
+
+MoltMind restores your agent's context in ~325 tokens ($0.001) instead of re-exploring from scratch. Your agent picks up right where it left off — same project knowledge, same decisions, same learnings.
+
+> Dollar estimates based on Claude Sonnet 4.5 input pricing ($3/1M tokens). Actual savings vary by model and usage.
+
 ## Quick Start
 
 ### Claude Code
@@ -12,7 +26,15 @@ MoltMind is an [MCP](https://modelcontextprotocol.io) server that gives your AI
 claude mcp add moltmind -- npx -y moltmind
 ```
 
-Restart Claude Code, then run `/mcp` to verify. Add `--moltbook` for social features ([moltbook.com](https://moltbook.com)).
+Restart Claude Code, then run `/mcp` to verify.
+
+With moltbook social features:
+
+```bash
+claude mcp add moltmind -- npx -y moltmind --moltbook
+```
+
+See [moltbook.com](https://moltbook.com) for the agent social network.
 
 ### Other Clients
 
@@ -73,11 +95,23 @@ npm uninstall -g moltmind   # then let npx handle it
 
 ## How It Works
 
-**Memory & Search** — Memories are stored in local SQLite with FTS5. Each has a type (`learning`, `error`, `decision`, `plan`, `raw`), tags, and a tier (`hot`, `warm`, `cold`, `archived`). `mm_recall` runs hybrid search: semantic similarity (0.7 weight) via a local [MiniLM-L6-v2](https://huggingface.co/Xenova/all-MiniLM-L6-v2) embedding model plus FTS5 keyword matching (0.3 weight). If the embedding model isn't available, it falls back to keyword-only.
+**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.
 
-**Sessions & Handoffs** — Sessions are auto-created on startup and auto-paused on shutdown. `mm_session_save` captures what happened and where you left off; `mm_session_resume` restores full context. `mm_handoff_create` structures goal/state/next-action for agent-to-agent transfers. All tool calls are tagged with session IDs for traceability.
+## What It Costs (Tokens)
 
-**Diagnostics** — Every tool call is logged locally with latency and success/failure. `mm_status` shows health score, `mm_metrics` shows per-tool usage stats, error rates, and token savings. All data stays on your machine.
+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
 
@@ -91,27 +125,17 @@ npm uninstall -g moltmind   # then let npx handle it
 
 Upgrade: `npx moltmind --upgrade`
 
-## Token Cost
-
-MCP tools add overhead because descriptions are sent with every request. MoltMind pays for itself quickly:
+## Search Performance (Pro)
 
-| Mode | Overhead per request |
-|------|---------------------|
-| Default (14 tools) | ~500 tokens |
-| + Moltbook (21 tools) | ~1,000 tokens |
-| With prompt caching | ~50 tokens |
+Pro tier uses [Zvec ANN](https://github.com/ariv14/zvec-native) for fast memory search. Here's what that means in practice:
 
-### Session resume vs cold start
+**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.
 
-Without MoltMind, re-exploring a codebase costs ~8,000 tokens per session. `mm_session_resume` restores context in ~325 tokens.
+**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.
 
-| Scenario | Without | With MoltMind | Savings |
-|----------|---------|---------------|---------|
-| Single resume | ~8,000 | ~825 | 90% |
-| 5-session project | ~40,000 | ~7,500 | 81% |
-| 20-session project | ~160,000 | ~40,200 | 75% |
+**Reliability** — Handles **330+ searches per second** with zero latency spikes. Deleted memories never come back. Results are deterministic.
 
-Run `npm run benchmark` for latency measurements and projected savings. See [RUNBOOK.md](RUNBOOK.md) for detailed results.
+See [BENCHMARK_RESULTS.md](BENCHMARK_RESULTS.md) for the full report, or [RUNBOOK.md](RUNBOOK.md) for how to run benchmarks yourself.
 
 ## Data Storage
 

package/dist/index.js

@@ -25,7 +25,7 @@ const moltbookInstructions = isMoltbookEnabled()
     : "";
 const server = new McpServer({
     name: "moltmind",
-    version: "0.7.1",
+    version: "0.7.3",
 }, {
     instructions: `MoltMind provides persistent memory and session continuity. On startup, call mm_session_resume to restore context from previous sessions. Before disconnecting or when a task is complete, call mm_session_save to preserve session state. Use mm_handoff_create to checkpoint progress during long tasks.${moltbookInstructions}`,
 });

package/dist/tools/mm_status.js

@@ -9,7 +9,7 @@ export async function handleMmStatus() {
     const uptimeSeconds = Math.floor((Date.now() - startTime) / 1000);
     return {
         success: true,
-        version: "0.7.1",
+        version: "0.7.3",
         tier: isProTier() ? "pro" : "free",
         usage: checkStoreLimits().message,
         db_stats: stats,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moltmind",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Agent Memory MCP Server — persistent semantic memory and session continuity for AI agents",
   "type": "module",
   "bin": {
@@ -43,7 +43,7 @@
     "@xenova/transformers": "^2.17.0"
   },
   "optionalDependencies": {
-    "@moltmind/zvec-native": "^0.1.0"
+    "@moltmind/zvec-native": "^0.1.1"
   },
   "devDependencies": {
     "typescript": "^5.5.0",