Setup & Installation

Get Memstate connected to your AI agent in 2 simple steps.

1

Add MCP Configuration

Add this to your MCP client configuration file. Replace YOUR_API_KEY_HERE with your API key from the dashboard.

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

Where does this go? (Mac)

Add the config to your agent's MCP config file, then restart the agent.

  • Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
  • Cursor — .cursor/mcp.json in your project root
  • Cline — cline_mcp_settings.json in VS Code settings
  • Windsurf — ~/.codeium/windsurf/mcp_config.json
2

Add Instructions to Your Agent File

Copy this into your project's AGENTS.md (recommended), CLAUDE.md, or GEMINI.md. These files tell your AI agent how to use Memstate; AGENTS.md is the most common.

Agent instructions (paste into AGENTS.md, CLAUDE.md, or GEMINI.md)
# Memstate MCP - Memory Storage

This project uses Memstate MCP for versioned memory. Keypaths are hierarchical (e.g. `project.myapp.database`). Memstate handles versioning and conflict detection.

## Which tool when

- **memstate_remember** — PREFERRED for markdown, task summaries, meeting notes. Server extracts keypaths and creates structured memories. Use after tasks.
- **memstate_set** — Only for one keypath = one short value (e.g. config.port, status). Not for summaries.
- **memstate_get** — Browse project, fetch existing knowledge before tasks.
- **memstate_search** — Find by meaning when you don't know the keypath.
- **memstate_history** — View version history of a keypath or memory.

## Before each task

Check what already exists: `memstate_get(project_id="myproject")` or `memstate_search(query="topic", project_id="myproject")`

## After each task

**Preferred — save markdown with remember:**
```
memstate_remember(project_id="myproject", content="## Task Summary\n- What was done\n- Key changes\n- Files modified", source="agent")
```

**Only for a single value:** `memstate_set(project_id="myproject", keypath="config.port", value="8080")`

Keypaths are auto-prefixed: `keypath="database"` → `project.myproject.database`. Use short project_id: `myapp`, `memstate`, etc.

Why this matters

These instructions ensure your AI agent:

  • Looks up memories before tasks to avoid duplicate work and understand existing decisions
  • Saves summaries after tasks to maintain session state across conversations
  • Stays current with structured facts that are automatically versioned
  • Gets precise context without falling out of date, thanks to automatic versioning

Verify the Connection

After configuring your agent, test the connection:

Test in your agent
Ask your agent: "Use memstate_get() to list all projects and verify Memstate is connected."

You should see a response showing available projects and memories.

You're all set!

Your agent now has access to structured, versioned memory. It will automatically lookup existing knowledge before tasks and save summaries after completion, keeping your project context current and organized.

Tools Reference View Dashboard

Alternative: Install as an Agent Skill

If you use Claude Code, Cline, or Cursor, you can also install Memstate as an Agent Skill. Skills are loaded automatically by your agent without requiring manual instruction files. This is an alternative to the AGENTS.md approach above — both work, skills are just more portable.

Terminal
npx @memstate/skills setup

This installs the Memstate skill to the correct location for your agent(s) and optionally updates your instruction files. See the Skills documentation for more details.