MCP Server

The Memsy MCP server is drop-in memory infrastructure that learns at the role, team, and org level — so your AI app gets smarter as more agents and humans use it. One server, every host.

What you get

13 tools your AI agent can call:

Plus 4 resources — memsy://memories/recent, actor/current, session/current, profile/current — and 4 prompts — recall-context, setup-defaults, proactive-mode, summarize-and-store.

Quickstart

claude mcp add memsy --scope user \
  -e MEMSY_API_KEY=msy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -- npx -y @memsy-io/mcp

{
  "mcpServers": {
    "memsy": {
      "command": "npx",
      "args": ["-y", "@memsy-io/mcp"],
      "env": {
        "MEMSY_API_KEY": "msy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "memsy": {
      "command": "npx",
      "args": ["-y", "@memsy-io/mcp"],
      "env": {
        "MEMSY_API_KEY": "msy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

code --add-mcp '{"name":"memsy","command":"npx","args":["-y","@memsy-io/mcp"],"env":{"MEMSY_API_KEY":"msy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}}'

{
  "servers": {
    "memsy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@memsy-io/mcp"],
      "env": {
        "MEMSY_API_KEY": "msy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

{
  "memsy": {
    "command": "npx",
    "args": ["-y", "@memsy-io/mcp"],
    "env": {
      "MEMSY_API_KEY": "msy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}

mcpServers:
  memsy:
    command: npx
    args: ["-y", "@memsy-io/mcp"]
    env:
      MEMSY_API_KEY: msy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "context_servers": {
    "memsy": {
      "command": {
        "path": "npx",
        "args": ["-y", "@memsy-io/mcp"]
      },
      "env": {
        "MEMSY_API_KEY": "msy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

"env": {
  "MEMSY_API_KEY": "msy_...",
  "MEMSY_ACTOR_ID": "claude-code"   // or "cursor", "vscode", "coder-agent", or your handle
}

{ "status": "ok", "version": "...", "base_url": "https://api.memsy.io/v1" }

Using it day-to-day

Talk to your agent naturally — it picks which tool to call. The phrasing patterns below are the ones the tool descriptions are tuned for. You don't need to remember tool names.

First-time setup

Run these once when you start a new Memsy account or want to configure a fresh project.

Recalling — getting context back

The wider the question, the more results. Be specific when you want precision.

Tips for better recall:

• Use the same nouns and verbs you used when you originally stored the memory. Memsy is semantic, but lexical overlap helps.
• If a search returns nothing, try a shorter / simpler query before assuming the memory isn't there.
• "Show me everything I've stored about X" triggers memsy_list_memories (paginated browse) instead of memsy_search — useful when semantic search is too narrow.

Storing — committing things to long-term memory

Use trigger verbs: remember, note, save, store.

What gets auto-tagged: if you've set a default role/team, every ingest is automatically attributed to it. You see applied_default_role_id / applied_default_team_id in the response so you know.

What NOT to do — these usually waste memory:

• ❌ "Remember everything we just talked about." — too vague; the extractor will store low-quality "context" memories.
• ❌ "Remember this code: <paste 200 lines>." — code lives in git. Store the decision about the code, not the code itself.
• ❌ Storing transient state ("Remember I'm currently debugging the login flow") — by the time you need it, it's stale.

Browsing and inspecting

Switching contexts (multi-org)

If you have multiple Memsy profiles configured:

Adjusting defaults mid-session

Diagnostics

Always-on proactive mode

By default, Memsy fires only when you ask. If you want decision-triggered store + context-aware recall for the rest of the session, invoke the proactive-mode prompt once:

"Enable proactive Memsy mode." (or type / and pick the proactive-mode prompt directly)

After invocation, Claude will:

• Call memsy_search BEFORE answering whenever you mention a project / decision / component / past topic — and cite the results inline.
• Call memsy_ingest AFTER explicit decisions, stated preferences, multi-turn conclusions, or confirmed fixes — and tell you it stored.
• Skip storing typos, aborted experiments, raw code, and transient state.

This is the closest you can get to always-on Memsy from inside the MCP alone. (True session-wide automation needs a Claude Code skill — see roadmap.)

Power patterns

Combine tools in one turn for richer flows:

• "Search memsy for everything about Q3, then summarize the top 5 findings and store the summary." — search → analyze → store.
• "Before suggesting a new fix, check if we already discussed this bug. If so, cite the prior memory." — recall-first pattern.
• "List my last 20 ingests and tell me which ones look low-quality." — periodic memory hygiene.
• "Switch to the work profile, search for the launch checklist, then switch back." — multi-context lookup.

Multi-org setup

If you work across multiple Memsy orgs (personal + work, multiple clients), use a config file with named profiles instead of putting the key in env.

{
  "active_profile": "personal",
  "profiles": {
    "personal": {
      "api_key": "msy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "base_url": "https://api.memsy.io/v1",
      "org_label": "Personal",
      "actor_id": "alex-dev"            // optional — pin identity for this profile (see Identity model)
    },
    "work": {
      "api_key": "msy_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
      "base_url": "https://api.memsy.io/v1",
      "org_label": "Work",
      "default_role_ids": ["senior"],   // optional — applied as default search filter
      "default_team_ids": ["platform"]  // optional — applied as default search filter
    }
  }
}

chmod 600 ~/.memsy/config.json

{
  "mcpServers": {
    "memsy": {
      "command": "npx",
      "args": ["-y", "@memsy-io/mcp"]
    }
  }
}

Configuration reference

Environment variables

CLI flags

npx @memsy-io/mcp --profile work
npx @memsy-io/mcp --api-key msy_... --base-url https://staging.memsy.io/v1
npx @memsy-io/mcp --config /path/to/config.json

CLI flags beat env vars beat config-file active_profile.

Resolution order

• API key: --api-key → MEMSY_API_KEY → active profile's api_key
• Profile name: --profile → MEMSY_PROFILE → config's active_profile → default
• Config file path: --config → ./.memsy/config.json → ~/.memsy/config.json

Identity model

actor_id scopes who memories belong to. The server resolves it at startup from one of four sources, in precedence order — the first one set wins:

The derived fallback ships no PII to the server — just a deterministic hash so the same developer in the same repo lands on the same actor_id across sessions. But it's only the fallback — most users want option 2 or 3.

Resolved value applies to:

• Ingest — every new event is tagged with the resolved actor_id (no matter which source it came from).
• Search — org-wide by default; the resolved actor_id is not used as a filter. Pass actor_id explicitly to scope down. So pinning your identity for ingest doesn't hide memories from earlier channels (dashboard, SDK, other hosts).

Pinning a stable identity

Three options, in order of convenience:

1. memsy_set_defaults (recommended — conversational) — ask Claude "tag my memories as <value> from now on" and it calls memsy_set_defaults { actor_id: "<value>", persist: "global" }, writing the field into ~/.memsy/config.json for you. Source becomes profile.
2. Profile config (manual) — hand-edit ~/.memsy/config.json and add "actor_id": "<value>" to the active profile. Stable across every MCP host (Claude Code, Cursor, VS Code, etc.) that reads the same file.
3. Per-host env var (highest precedence — overrides #1 and #2) — set MEMSY_ACTOR_ID=<value> in the host's MCP config env block. Useful when you want each host to have a distinct identity (e.g. claude-code in Claude Code's config, cursor in Cursor's) so you can later filter "what did I save via Claude Code last week?". Source becomes env.

Suggested values: an agent identifier (claude-code, cursor, vscode, zed, cline, coder-agent) or a personal handle (alex-dev). Whatever you pick, search stays org-wide by default so existing memories remain findable.

See Actors and Sessions for the broader concept.

Troubleshooting

MemsyAuthError or 401

API key missing, malformed, or revoked. Check:

• MEMSY_API_KEY is in the host's MCP env block (not just your shell — the host doesn't inherit shell env).
• Key starts with msy_ and has 32 hex chars.
• Key is active in app.memsy.io → API Keys.

MemsyAPIError 404

Wrong base_url. Production hot-path is https://api.memsy.io/v1 — the /v1 suffix is required. The server defaults to it; override only for staging or self-hosted.

memsy_search returns count: 0 but memories exist

The query may not semantically match. Try:

• Broader terms / single keyword.
• memsy_list_memories (no args) to see what's actually stored.
• threshold: 0 (the default — anything stricter hides weak matches).

Search is org-wide by default, so prior-channel memories are findable without setting actor_id.

Server doesn't start / host shows "memsy: disconnected"

Run the server manually to see the error:

MEMSY_API_KEY=msy_... npx -y @memsy-io/mcp

Common causes:

• No key + no config file → "No Memsy profile resolved"
• Config file is invalid JSON → parse error on stderr
• Node 17 or older → upgrade to 18+

Profile switch doesn't persist across sessions

memsy_use_org swaps the active profile in the current MCP process only. Each host spawns a fresh process per chat. To change the default at startup, set MEMSY_PROFILE in the host's MCP env, or update active_profile in the config file.

Security notes

• The config file stores API keys in plain text. chmod 600 is enforced via stderr warning. Use a passworded keychain manager if your threat model demands it.
• API keys are held in process memory and sent only to your configured base_url over HTTPS. They are never logged.
• memsy_list_orgs and memsy://profile/current never return the API key — only metadata.

See also

• Quickstart — using the Python / Node SDKs directly
• Actors and Sessions — the identity model
• Searching Memory — query patterns + thresholds
• Source code on GitHub