README.md•3.95 kB
# MCP Memory Server
This server implements long-term memory capabilities for AI assistants using mem0 principles, powered by PostgreSQL with pgvector for efficient vector similarity search.
## Features
- PostgreSQL with pgvector for vector similarity search
- Automatic embedding generation using BERT
- RESTful API for memory operations
- Semantic search capabilities
- Support for different types of memories (learnings, experiences, etc.)
- Tag-based memory retrieval
- Confidence scoring for memories
- Server-Sent Events (SSE) for real-time updates
- Cursor MCP protocol compatible
## Prerequisites
1. PostgreSQL 14+ with pgvector extension installed:
```bash
# In your PostgreSQL instance:
CREATE EXTENSION vector;
```
2. Node.js 16+
## Setup
1. Install dependencies:
```bash
npm install
```
2. Configure environment variables:
Copy `.env.sample` to `.env` and adjust the values:
```bash
cp .env.sample .env
```
Example `.env` configurations:
```bash
# With username/password
DATABASE_URL="postgresql://username:password@localhost:5432/mcp_memory"
PORT=3333
# Local development with peer authentication
DATABASE_URL="postgresql:///mcp_memory"
PORT=3333
```
3. Initialize the database:
```bash
npm run prisma:migrate
```
4. Start the server:
```bash
npm start
```
For development with auto-reload:
```bash
npm run dev
```
## Using with Cursor
### Adding the MCP Server in Cursor
To add the memory server to Cursor, you need to modify your MCP configuration file located at `~/.cursor/mcp.json`. Add the following configuration to the `mcpServers` object:
```json
{
"mcpServers": {
"memory": {
"command": "node",
"args": [
"/path/to/your/memory/src/server.js"
]
}
}
}
```
Replace `/path/to/your/memory` with the actual path to your memory server installation.
For example, if you cloned the repository to `/Users/username/workspace/memory`, your configuration would look like:
```json
{
"mcpServers": {
"memory": {
"command": "node",
"args": [
"/Users/username/workspace/memory/src/server.js"
]
}
}
}
```
The server will be automatically started by Cursor when needed. You can verify it's working by:
1. Opening Cursor
2. The memory server will be started automatically when Cursor launches
3. You can check the server status by visiting `http://localhost:3333/mcp/v1/health`
### Available MCP Endpoints
#### SSE Connection
- **Endpoint**: `GET /mcp/v1/sse`
- **Query Parameters**:
- `subscribe`: Comma-separated list of events to subscribe to (optional)
- **Events**:
- `connected`: Sent on initial connection
- `memory.created`: Sent when new memories are created
- `memory.updated`: Sent when existing memories are updated
#### Memory Operations
1. **Create Memory**
```http
POST /mcp/v1/memory
Content-Type: application/json
{
"type": "learning",
"content": {
"topic": "Express.js",
"details": "Express.js is a web application framework for Node.js"
},
"source": "documentation",
"tags": ["nodejs", "web-framework"],
"confidence": 0.95
}
```
2. **Search Memories**
```http
GET /mcp/v1/memory/search?query=web+frameworks&type=learning&tags=nodejs
```
3. **List Memories**
```http
GET /mcp/v1/memory?type=learning&tags=nodejs,web-framework
```
### Health Check
```http
GET /mcp/v1/health
```
### Response Format
All API responses follow the standard MCP format:
```json
{
"status": "success",
"data": {
// Response data
}
}
```
Or for errors:
```json
{
"status": "error",
"error": "Error message"
}
```
## Memory Schema
- id: Unique identifier
- type: Type of memory (learning, experience, etc.)
- content: Actual memory content (JSON)
- source: Where the memory came from
- embedding: Vector representation of the content (384 dimensions)
- tags: Array of relevant tags
- confidence: Confidence score (0-1)
- createdAt: When the memory was created
- updatedAt: When the memory was last updated