MCP Server

The SharedMemory MCP server lets any MCP-compatible AI assistant (Claude Desktop, Cursor, Windsurf, VS Code Copilot) access persistent memory.

Use any valid Bearer sm_… secret. Examples assume sm_org_rw_… / sm_proj_rw_… from Settings → API Keys; sm_agent_… and sm_live_… (sm login) equally work.

Quick Install (Recommended)

The fastest way to get started — one command, no JSON editing:

# Interactive — picks your client, asks for your API key
npx -y @sharedmemory/mcp-server install

# Or specify everything inline
npx -y @sharedmemory/mcp-server install --cursor --api-key sm_org_rw_... --volume your-volume-id

# Install for all supported clients at once
npx -y @sharedmemory/mcp-server install --all --api-key sm_org_rw_...

Supported clients: --claude-code, --claude, --cursor, --vscode, --windsurf, --all

Manual Setup

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "sharedmemory": {
      "command": "npx",
      "args": ["-y", "@sharedmemory/mcp-server"],
      "env": {
        "SHAREDMEMORY_API_KEY": "sm_org_rw_...",
        "SHAREDMEMORY_API_URL": "https://api.sharedmemory.ai",
        "SHAREDMEMORY_VOLUME_ID": "your-volume-id"
      }
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "sharedmemory": {
      "command": "npx",
      "args": ["-y", "@sharedmemory/mcp-server"],
      "env": {
        "SHAREDMEMORY_API_KEY": "sm_org_rw_...",
        "SHAREDMEMORY_API_URL": "https://api.sharedmemory.ai",
        "SHAREDMEMORY_VOLUME_ID": "your-volume-id"
      }
    }
  }
}

VS Code Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "sharedmemory": {
      "command": "npx",
      "args": ["-y", "@sharedmemory/mcp-server"],
      "env": {
        "SHAREDMEMORY_API_KEY": "sm_org_rw_...",
        "SHAREDMEMORY_API_URL": "https://api.sharedmemory.ai",
        "SHAREDMEMORY_VOLUME_ID": "your-volume-id"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "sharedmemory": {
      "command": "npx",
      "args": ["-y", "@sharedmemory/mcp-server"],
      "env": {
        "SHAREDMEMORY_API_KEY": "sm_org_rw_...",
        "SHAREDMEMORY_API_URL": "https://api.sharedmemory.ai",
        "SHAREDMEMORY_VOLUME_ID": "your-volume-id"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
SHAREDMEMORY_API_KEY	Yes	Bearer sm_… secret (sm_org_rw_… from API Keys by default)
SHAREDMEMORY_API_URL	No	API base URL (default: https://api.sharedmemory.ai)
SHAREDMEMORY_VOLUME_ID	No	Default project (volume) ID for all operations

Tools

The MCP server exposes 15 tools to the AI assistant:

remember

Store a fact, note, or piece of information. The memory pipeline handles classification, conflict checking, entity extraction, and graph building automatically.

Parameters:

Name	Type	Required	Description
content	string	Yes	The information to remember
volume_id	string	No	Volume ID (uses default)
memory_type	enum	No	factual, preference, event, relationship, technical

query

Retrieve context BEFORE answering. Searches memories by semantic similarity. Returns matching memories plus knowledge graph facts.

Parameters:

Name	Type	Required	Description
query	string	Yes	What to search for
volume_id	string	No	Volume ID
limit	number	No	Max results (1–50, default: 10)

get_entity

Get everything known about a specific entity (person, project, concept). Returns summary, facts, and relationships.

Parameters:

Name	Type	Required	Description
name	string	Yes	Name of the entity
volume_id	string	No	Volume ID

search_entities

Search for entities in the knowledge graph by name.

Parameters:

Name	Type	Required	Description
query	string	Yes	Search term
volume_id	string	No	Volume ID
limit	number	No	Max results (1–50, default: 20)

get_graph

Overview of the entire knowledge graph — all entities and relationships.

Parameters:

Name	Type	Required	Description
volume_id	string	No	Volume ID
limit	number	No	Max entities (1–200, default: 50)

list_volumes

List all memory projects (volumes) accessible to this agent. No parameters.

delete_memory

Delete a memory by ID.

Parameters:

Name	Type	Required	Description
memory_id	string	Yes	UUID of the memory to delete
volume_id	string	No	Volume ID (uses default)

update_memory

Update an existing memory's content.

Parameters:

Name	Type	Required	Description
memory_id	string	Yes	UUID of the memory to update
content	string	Yes	New content for the memory
volume_id	string	No	Volume ID (uses default)

feedback

Submit feedback on a memory's relevance or quality.

Parameters:

Name	Type	Required	Description
memory_id	string	Yes	UUID of the memory
feedback	enum	Yes	positive or negative
reason	string	No	Reason for the feedback
volume_id	string	No	Volume ID (uses default)

batch_remember

Store multiple facts at once. More efficient than calling remember in a loop.

Parameters:

Name	Type	Required	Description
memories	array	Yes	Array of { content, memory_type? } objects (1–100)
volume_id	string	No	Volume ID (uses default)

get_memory

Retrieve a specific memory by its ID. Useful for viewing full details of a memory found via query.

Parameters:

Name	Type	Required	Description
memory_id	string	Yes	UUID of the memory

get_profile

Get an auto-generated user profile based on stored memories. Returns stable facts, recent activity, relationships, and a summary.

Parameters:

Name	Type	Required	Description
user_id	string	Yes	The user ID to generate a profile for
volume_id	string	No	Volume ID (uses default)

get_context

Get a context block from stored memories. Returns a pre-formatted context string ready to inject into system prompts.

Parameters:

Name	Type	Required	Description
volume_id	string	No	Volume ID (uses default)
user_id	string	No	User ID for personalized context
max_tokens	number	No	Max tokens for context block (default: 2000)

list_documents

List all documents that have been uploaded and processed for a volume.

Parameters:

Name	Type	Required	Description
volume_id	string	No	Volume ID (uses default)

Resources

URI	Description
memory://graph	JSON representation of the knowledge graph for the default volume

Prompts

summarize-knowledge

Generates a comprehensive summary of all knowledge in a volume. Useful as a conversation starter.

what-do-you-know-about

Asks the AI to synthesize everything SharedMemory knows about a specific topic, combining entity data, memories, and graph facts.

Usage Examples

Once configured, just talk to your AI naturally:

"Remember that our quarterly meeting is on March 15th"

"What do you know about the React migration project?"

"Show me everyone who works on the backend team"

"What did I tell you about deployment procedures?"

The MCP server handles the API calls behind the scenes.