Memstate AI - MCP

Versioned memory for AI agents. Store facts, detect conflicts, and track how decisions change over time — exposed as a hosted MCP server.

Dashboard · Docs · Pricing

Why Memstate?

| | RAG (most other memory systems) | Memstate AI | |---|---|---| | Token usage per conversation | ~7,500 | ~1,500 | | Agent visibility | Black box | Full transparency | | Memory versioning | None | Full history | | Token growth as memories scale | O(n) | O(1) | | Infrastructure required | Yes | None — hosted SaaS |

Other memory systems dump everything into your context window and hope for the best. Memstate gives your agent a structured, versioned knowledge base it navigates precisely — load only what you need, know what changed, know when facts conflict.

Benchmarks

We built an open-source benchmark suite that tests what actually matters for agent memory: can your system store facts, recall them accurately across sessions, detect conflicts when things change, and maintain context as a project evolves?

Head-to-Head: Memstate AI vs Mem0

Both systems were tested under identical conditions using the same agent (Claude Sonnet 4.6, temperature 0), the same scenarios, and the same scoring rubric.

| Metric | Memstate AI | Mem0 | Winner | |--------|:-----------:|:----:|--------| | Overall Score | 69.1 | 15.4 | Memstate | | Accuracy (fact recall) | 74.1 | 12.6 | Memstate | | Conflict Detection | 85.5 | 19.0 | Memstate | | Context Continuity | 63.7 | 10.1 | Memstate | | Token Efficiency | 22.3 | 30.6 | Mem0 |

Scoring weights: Accuracy 40%, Conflict Detection 25%, Context Continuity 25%, Token Efficiency 10%.

Per-Scenario Breakdown

The benchmark runs five real-world scenarios that simulate multi-session agent workflows:

| Scenario | Memstate AI | Mem0 | |----------|:-----------:|:----:| | Web App Architecture Evolution | 43.2 | 55.6 | | Auth System Migration | 66.2 | 10.2 | | Database Schema Evolution | 72.7 | 7.0 | | API Versioning Conflicts | 86.5 | 0.9 | | Team Decision Reversal | 77.2 | 3.3 |

Mem0 won the first scenario (simple architecture tracking), but struggled severely on scenarios requiring contradiction handling, cross-session context, and decision reversal tracking — scoring near zero on three of five scenarios.

Why Memstate Wins

The benchmark reveals a fundamental architectural difference:

Mem0 uses embedding-based semantic search. Facts are chunked, embedded, and retrieved by similarity. This works for simple lookups but breaks down when:

• Facts contradict earlier facts (the system can't distinguish current vs. outdated)
• Precise recall is needed (embeddings return "similar" results, not exact ones)
• Write-to-read latency matters (new memories take seconds to become searchable)

Memstate uses structured, versioned key-value storage. Every fact lives at an explicit keypath with a full version history. This means:

• Conflict detection is built in — when a new fact contradicts an old one, the system knows and preserves both versions
• Recall is deterministic — you get back exactly what was stored, not an approximate match
• Cross-session continuity is reliable — the agent navigates a structured tree rather than hoping semantic search surfaces the right context
• Token cost stays O(1) — the agent loads summaries first and drills into detail only when needed, instead of dumping all potentially-relevant embeddings into the context window

Fairness Notes

• Both systems used the same agent model, temperature, and evaluation rubric
• Mem0 was given a 10-second ingestion delay between writes and reads to account for its async embedding pipeline
• Mem0 scores higher on token efficiency, but this metric should be read in context — lower token usage can simply reflect less information being returned. A system that retrieves incomplete or incorrect facts uses fewer tokens per response but may require more follow-up calls, ultimately costing more tokens to reach the same answer
• The benchmark source code is included in this repository for full reproducibility
• Mem0 may perform differently with custom configuration or a different embedding model

Quick Start

Get your API key at memstate.ai/dashboard, then add to your MCP client config:

{
  "mcpServers": {
    "memstate": {
      "command": "npx",
      "args": ["-y", "@memstate/mcp"],
      "env": {
        "MEMSTATE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

No Docker. No database. No infrastructure. Running in 60 seconds.

Client Setup

Claude Desktop

Config location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "memstate": {
      "command": "npx",
      "args": ["-y", "@memstate/mcp"],
      "env": { "MEMSTATE_API_KEY": "YOUR_API_KEY_HERE" }
    }
  }
}

Claude Code

claude mcp add memstate npx @memstate/mcp -e MEMSTATE_API_KEY=YOUR_API_KEY_HERE

Cursor

In Cursor Settings → MCP → Add Server — same JSON format as Claude Desktop above.

Cline / Windsurf / Kilo Code / Roo Code

All support the same stdio MCP config format. Add to your client's MCP settings file.

Core Tools

| Tool | When to use | |------|-------------| | memstate_remember | Store markdown, task summaries, decisions. Server extracts keypaths and detects conflicts automatically. Use for most writes. | | memstate_set | Set a single keypath to a short value (e.g. config.port = 8080). Not for prose. | | memstate_get | Browse all memories for a project or subtree. Use at the start of every task. | | memstate_search | Semantic search by meaning when you don't know the exact keypath. | | memstate_history | See how a piece of knowledge changed over time — full version chain. | | memstate_delete | Soft-delete a keypath. Creates a tombstone; full history is preserved. | | memstate_delete_project | Soft-delete an entire project and all its memories. |

How keypaths work

Memories are organized in hierarchical dot-notation:

project.my_app.database.schema
project.my_app.auth.provider
project.my_app.deploy.environment

Keypaths are auto-prefixed: keypath="database" with project_id="my_app" → project.my_app.database. Your agent can drill into exactly what it needs — no full-context dumps.

How It Works

Agent: memstate_remember(project_id="my_app", content="## Auth\nUsing SuperTokens...")
         ↓
Server extracts keypaths:  [project.my_app.auth.provider, ...]
         ↓
Conflict detection:  compare against existing memories at those keypaths
         ↓
New version stored — old version preserved in history chain
         ↓
Next session: memstate_get(project_id="my_app") → structured summaries only
         ↓
Agent drills into project.my_app.auth only when it needs auth details

Token cost stays constant regardless of how many total memories exist.

Add to Your Agent Instructions

Copy into your AGENTS.md or system prompt:

## Memory (Memstate MCP)

### Before each task
- memstate_get(project_id="my_project") — browse existing knowledge
- memstate_search(query="topic", project_id="my_project") — find by meaning

### After each task
- memstate_remember(project_id="my_project", content="## Summary\n- ...", source="agent")

### Tool guide
- memstate_remember — markdown summaries, decisions, task results (preferred)
- memstate_set — single short values only (config flags, status)
- memstate_get — browse/retrieve before tasks
- memstate_search — semantic lookup when keypath unknown
- memstate_history — audit how knowledge evolved
- memstate_delete — remove outdated memories (history preserved)

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | MEMSTATE_API_KEY | (required) | API key from memstate.ai/dashboard | | MEMSTATE_MCP_URL | https://mcp.memstate.ai | Override for self-hosted deployments |

Verify Your Connection

MEMSTATE_API_KEY=your_key npx @memstate/mcp --test

Prints all available tools and confirms your API key works.

Built for AI agents that deserve to know what they know.