Hystersis MCP Server

Hystersis MCP Server acts as the universal bridge connecting your local or cloud-hosted Hystersis backend to any MCP-compatible AI assistant (e.g., Claude Desktop, Cursor, Windsurf, Cline).

By attaching this server to your coding assistant, your AI instantly gains long-term, persistent memory, a Neo4j knowledge graph, and ProMem-style extraction across all your chats and workspaces.

✨ Features

• Long-Term Context: AI assistants remember coding preferences, architecture rules, and past bugs across completely different chats and workspaces.

• Graph Knowledge Base: Exposes tools for the AI to explicitly create entities and relationships, building an architectural map of your systems as it works.

• Multi-Hop Spreading Activation: Search through memories not just by vector similarity, but through associative graph propagation (Neo4j + Qdrant).

• Plug-and-Play: Installs globally via NPM and connects to Claude or Cursor with three lines of JSON.

Related MCP server: Neo4j Memory Server

🚀 Quick Start

1. Prerequisites

Ensure your core Hystersis engine is running. You can start it locally via Docker:

git clone https://github.com/Himan-D/agent-memory.git
cd agent-memory
docker-compose up -d

(By default, the Hystersis API runs on http://localhost:8080)

2. Client Integrations

You don't need to clone this repository to use the server. You can execute it directly via npx hystersis-mcp in your assistant's configuration.

🤖 Claude Desktop

Add the following to your claude_desktop_config.json (Mac: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "hystersis": {
      "command": "npx",
      "args": [
        "-y",
        "hystersis-mcp"
      ],
      "env": {
        "HYSTERSIS_API_URL": "http://localhost:8080",
        "HYSTERSIS_API_KEY": "default-key"
      }
    }
  }
}

💻 Cursor IDE

1. Go to Cursor Settings > Features > MCP.

2. Click + Add new MCP server.

3. Set the name to Hystersis.

4. Set the type to command.

5. Set the command to: npx -y hystersis-mcp

6. (If your API requires a specific key or URL, you may need to export it in your environment or wrap the command in a bash script).

🛠 Cline / RooCode (VS Code Extensions)

Add to your MCP settings file:

{
  "mcpServers": {
    "hystersis": {
      "command": "npx",
      "args": ["-y", "hystersis-mcp"],
      "env": {
        "HYSTERSIS_API_URL": "http://localhost:8080"
      }
    }
  }
}

🧰 Available Tools (Exposed to AI)

When connected, the AI assistant automatically discovers and can independently utilize the following tools:

🛠 Local Development

If you wish to modify the MCP server or contribute:

1. Clone & Install

   git clone https://github.com/Himan-D/hystersis-mcp.git
   cd hystersis-mcp
   npm install

2. Build

   npm run build

3. Test the MCP Output Manually

   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npm start

📝 License

This project is licensed under the MIT License.