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?

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.

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:

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

How keypaths work

Memories are organized in hierarchical dot-notation:

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

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

How It Works

Agent: memstate_remember(project_id="myapp", content="## Auth\nUsing SuperTokens...")
         ↓
Server extracts keypaths:  [project.myapp.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="myapp") → structured summaries only
         ↓
Agent drills into project.myapp.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="myproject") — browse existing knowledge
- memstate_search(query="topic", project_id="myproject") — find by meaning

### After each task
- memstate_remember(project_id="myproject", 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

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.