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.

---

🚀 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:

Tool	Description
add_memory	Ingests a new fact, rule, or preference into the persistent database.
search_memories	Retrieves historical context. Supports semantic, hybrid, and spreading modes.
create_entity	Creates a strict named node in the Neo4j knowledge graph.
create_relation	Links two entities with a specific relationship type (e.g., DEPENDS_ON).
get_context	Fetches the aggregated agent state and active working memory.
compression_stats	Retrieves real-time telemetry on the ProMem engine's token reduction.

---

🛠 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.