# Memory MCP Server

A hybrid long-term memory server for AI assistants built using the Model Context Protocol (MCP).

The server combines:

- PostgreSQL for structured storage
- ChromaDB for semantic retrieval
- OpenAI Embeddings for vector search
- MCP tools for interacting with memory

---

# Features

✅ Long-term memory storage

✅ Semantic search

✅ Memory updates

✅ Structured memory models

✅ Separate memory types

- User Facts
- Memories
- Chat History
- Tasks
- Reminders

---

# Architecture

```
                User
                  │
                  ▼
            MCP Client
                  │
                  ▼
          Memory MCP Server
                  │
     ┌────────────┴────────────┐
     │                         │
     ▼                         ▼
PostgreSQL                ChromaDB
Structured Data      Vector Embeddings
```

---

# Memory Types

The server supports five different memory categories.

## User Facts

Persistent user information.

Examples:

- Preferred IDE
- Name
- Job
- Location

---

## Memories

General knowledge.

Examples:

- Project documentation
- Architecture decisions
- Workflows

---

## Chat History

Important conversations worth preserving.

---

## Tasks

Long-term tasks.

---

## Reminders

Time-based reminders.

---

# Available MCP Tools

## Create

- remember_memory
- remember_user_fact
- remember_chat_history
- remember_task
- remember_reminder

---

## Search

```
search(query, top_k)
```

Performs semantic search over stored memories.

---

## Update

- update_memory
- update_user_fact
- update_chat_history
- update_task
- update_reminder

---

# How it Works

## Storing Memory

```
User
  │
  ▼
remember_*
  │
  ▼
Insert into PostgreSQL
  │
  ▼
Generate Embedding
  │
  ▼
Store in ChromaDB
```

---

## Searching

```
Query
  │
  ▼
Embedding
  │
  ▼
Chroma Similarity Search
  │
  ▼
Retrieve PostgreSQL Records
```

---

## Updating

```
Search Existing Memory
          │
          ▼
Update PostgreSQL
          │
          ▼
Update Chroma Embedding
```

---

# Installation

Clone the repository.

```bash
git clone https://github.com/<username>/memory-mcp-server.git
```

Install dependencies.

```bash
pip install -r requirements.txt
```

Create a `.env` file.

```env
OPENAI_API_KEY=YOUR_KEY
```

Start PostgreSQL.

Create a Chroma database directory.

Run the server.

```bash
python server.py
```

---

# Example Workflow

Store memory

```
remember_user_fact()

↓

PostgreSQL
↓

ChromaDB
```

Search

```
search("What IDE do I use?")
```

Update

```
search()

↓

update_user_fact()
```

---

# Tech Stack

- Python
- MCP
- PostgreSQL
- ChromaDB
- OpenAI Embeddings
- Pydantic

---

# Future Improvements

- Delete memories
- Memory scoring
- Multi-user support
- Memory expiration
- Redis caching
- Hybrid keyword + semantic search
- Memory graph relationships
- Multiple embedding providers
- Local embedding support

---

# License

MIT