@xmem.space/mcp

MCP (Model Context Protocol) Server for xmem – persistent, graph-based memory for AI agents.

Provides tools, resources and a context prompt for storing, searching, and managing memories through any MCP-compatible client — over stdio (Claude Desktop / Claude Code / Cursor) or StreamableHTTP.

Install

npm install -g @xmem.space/mcp

Configuration

Environment Variables

Variable	Description	Default
XMEM_API_URL	xmem server URL	http://localhost:18800
XMEM_API_KEY	API key for authentication	(none)
MEMTAP_AGENT_ID	Default agent identifier	main
XMEM_MODE	core = only remember/recall/whoami (less tool-sprawl); full = complete toolset	full
XMEM_LEGACY_ALIASES	Also register deprecated memtap_* tool names	true
XMEM_TRANSPORT	stdio (default) or http (StreamableHTTP server)	stdio
XMEM_HTTP_HOST	Bind host for http transport	127.0.0.1
XMEM_HTTP_PORT	Bind port for http transport	8787

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "xmem": {
      "command": "xmem-mcp",
      "env": {
        "XMEM_API_URL": "https://api.xmem.space",
        "XMEM_API_KEY": "xm_live_...",
        "MEMTAP_AGENT_ID": "main"
      }
    }
  }
}

Or with npx (no global install needed):

{
  "mcpServers": {
    "xmem": {
      "command": "npx",
      "args": ["-y", "@xmem.space/mcp"],
      "env": {
        "XMEM_API_URL": "https://api.xmem.space",
        "XMEM_API_KEY": "xm_live_...",
        "MEMTAP_AGENT_ID": "main"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "xmem": {
      "command": "npx",
      "args": ["-y", "@xmem.space/mcp"],
      "env": {
        "XMEM_API_URL": "https://api.xmem.space",
        "XMEM_API_KEY": "xm_live_...",
        "MEMTAP_AGENT_ID": "main"
      }
    }
  }
}

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "xmem": {
      "command": "npx",
      "args": ["-y", "@xmem.space/mcp"],
      "env": {
        "XMEM_API_URL": "https://api.xmem.space",
        "XMEM_API_KEY": "xm_live_...",
        "MEMTAP_AGENT_ID": "main"
      }
    }
  }
}

claude.ai Connector (remote, no install)

The hosted xmem server already exposes a remote MCP endpoint with OAuth discovery — you do not need this npm package for the web/mobile connector. Just add a custom connector pointing at:

https://api.xmem.space/mcp

OAuth discovery is served at /.well-known/oauth-protected-resource.

Self-hosted HTTP transport

To run this package as a local StreamableHTTP server (e.g. behind your own reverse proxy):

XMEM_TRANSPORT=http XMEM_HTTP_PORT=8787 xmem-mcp
# → xmem MCP (StreamableHTTP) listening on http://127.0.0.1:8787/mcp

Tool Reference

All tools use the canonical xmem_* names. The legacy memtap_* names remain registered as deprecated aliases unless XMEM_LEGACY_ALIASES=false.

Tool	Description
xmem_whoami	Verify connection: authenticated space, tier, agent, API-key status
xmem_remember	Store a new memory (fact, decision, preference, event, etc.)
xmem_recall	Full-text search across memories
xmem_bulletin	Context-aware memory retrieval
xmem_graphrag	Deep search with multi-hop graph traversal
xmem_graph	Graph operations: traverse, connections, gaps, clusters, overview
xmem_decide	Create, list, resolve, or defer decisions
xmem_memory	Get, update, or delete a specific memory
xmem_entities	List entities, get linked memories, merge duplicates
xmem_edges	Create relationships between memories
xmem_health	Check server health status
xmem_maintenance	Run maintenance: decay report, contradictions, dedup scan
xmem_consolidate	Full maintenance consolidation in one call
xmem_export	Export memory statistics
xmem_profile	Get memory profile for an agent
xmem_categories	List memory categories with counts

In XMEM_MODE=core, only xmem_remember, xmem_recall and xmem_whoami are exposed.

Prompts

Prompt	Description
context	Loads the agent-self + user-identity profile facts as a priming system message. Call at session start so the assistant knows who it is and who the user is.

Resources

URI	Description
xmem://health	Server health status
xmem://stats	Memory statistics
xmem://profile	Agent-self + user-identity profile facts (profile scope)
xmem://profile/{agentId}	Agent memory profile
xmem://graph	Knowledge-graph snapshot (overview + top entities/edges)

Development

npm install
npm run build
npm start

License

MIT