Setup guide for AI assistants

Purpose

• Give users a repeatable, correct Memstate MCP installation.
• Send humans to agent-specific docs when file paths or UIs differ.
• Avoid inventing CLI flags, env var names, or config keys—use only what appears below or in linked docs.
• Use a stable logical project name (project_id) for everything you store or retrieve—see below.

Project ID: top-level namespace

In Memstate, the project is the top-level isolation boundary. Every memstate_* call takes a project_id (short string). Memories in one project do not mix with another.

Open-source MCP reference implementation: github.com/memstate-ai/memstate-mcp. Align naming with the repo or product the user is actually working on, not with Memstate's own org unless that is the workspace.

Keypath hierarchy

Below the project, memories live at hierarchical keypaths: dot-separated segments, like a logical file tree. Examples: auth.oauth.provider, database.migrations.status, api.rate_limit.policy.

• When you pass project_id, Memstate auto-prefixes keypaths under that project (e.g. short key database becomes a namespaced path under the project).
• Deeper paths group related facts so agents can browse, search, and fetch subtree context deterministically—not only by vector similarity.

Full tool semantics: MCP tools reference.

Prerequisites

1. Node.js available on the user's machine (for npx).
2. A Memstate API key. Create one at https://memstate.ai/dashboard/api-keys (requires sign-in). Never embed a real key in shared configs or screenshots.
3. An MCP-capable client (Claude Desktop, Cursor, Cline, Windsurf, Gemini CLI, Kilo Code, Copilot, etc.).

Recommended: automated setup

When the user is comfortable running a terminal command, this is the fastest path. It detects installed agents, writes MCP config where appropriate, and can open the browser for API key creation.

npx @memstate/mcp setup

After setup, the user may still need to restart their app (e.g. quit Claude Desktop fully on macOS). See the agent-specific guide for restart and verification.

Manual: universal MCP server block

Merge this object into the client's existing mcpServers (or equivalent) configuration. Replace the placeholder with the user's API key.

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

Agent-specific guides (authoritative paths)

When the user names a product, open the matching page for exact config locations, screenshots context, and verification prompts.

After connection: writes, reads, and ingestion

Once Memstate is connected, the agent typically has MCP tools such as memstate_get, memstate_remember, memstate_set, memstate_search, memstate_history, and delete helpers. Full parameters and examples: MCP tools reference →

Simple get / set (exact keypaths)

When you already know the exact keypath and need a single value or a direct read, use memstate_get / memstate_set (MCP) or the equivalent REST API operations. That path is appropriate for config-like flags, ports, or fetching a known atom—no unstructured text ingestion.

Default for tasks and sessions: memstate_remember

For most real-world writes—after coding task completion, meeting notes, architecture decisions, multi-step summaries, or end-of-session wrap-ups—use memstate_remember with markdown or plain text. Do not try to manually shard that content into dozens of memstate_set calls unless the user explicitly wants raw key-value control.

memstate_remember sends your content through Memstate's ingestion pipeline: specialized models extract structured keypaths and facts, reconcile conflicts, and create versioned memory updates. That typically completes in seconds—faster than hand-authoring a tree of keys and less error-prone than guessing paths from prose.

REST API and other integrations

• REST API overview — programmatic memory for backends and custom apps; use it for simple get/set of known keypaths when MCP is not in the loop. Prefer memstate_remember-style ingestion via MCP (or the Remember API) when storing rich text that should be structured automatically.
• LangChain & LangGraph — langchain-memstate.
• MCP server overview and MCP setup & installation.

Verification checklist

1. Config file saved in the path given in the agent-specific guide (OS may vary).
2. MEMSTATE_API_KEY set in env for the MCP process (or substituted per client docs).
3. Host application fully restarted if required (especially Claude Desktop).
4. User can list MCP tools or run a trivial memstate_get / project list call.