<div align="center">
  <h1>🧠 Hystersis MCP Server</h1>
  <p><strong>The Model Context Protocol (MCP) server for the Hystersis Persistent Memory Engine.</strong></p>
  
  [![npm version](https://img.shields.io/npm/v/hystersis-mcp.svg?style=flat-square)](https://www.npmjs.com/package/hystersis-mcp)
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
  [![Protocol: MCP](https://img.shields.io/badge/Protocol-MCP%20v1.0-purple.svg?style=flat-square)](https://modelcontextprotocol.io/)
</div>

<br />

**Hystersis MCP Server** acts as the universal bridge connecting your local or cloud-hosted [Hystersis](https://github.com/Himan-D/agent-memory) 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:
```bash
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`):

```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:
```json
{
  "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**
   ```bash
   git clone https://github.com/Himan-D/hystersis-mcp.git
   cd hystersis-mcp
   npm install
   ```

2. **Build**
   ```bash
   npm run build
   ```

3. **Test the MCP Output Manually**
   ```bash
   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npm start
   ```

---

## 📝 License

This project is licensed under the **MIT License**.