# MCP‑Server for Agent Memory Management

A lightweight FastAPI server that stores and retrieves memory snippets for an AI agent using **Qdrant** as a vector database and **OpenAI embeddings** to encode text.

> **TL;DR** – Run the server, add memory items via `/memory`, query them with `/query`, and let your agent fetch relevant context automatically.

---

## Table of Contents

- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Running the Server](#running-the-server)
- [API Endpoints](#api-endpoints)
  - `POST /memory`
  - `GET /query`
- [Example Usage](#example-usage)
- [Testing with cURL](#testing-with-curl)
- [License](#license)

---

## Features

| Feature | Description |
|---------|-------------|
| **Vector Search** | Stores embeddings in Qdrant and performs similarity search. |
| **OpenAI Embeddings** | Uses `text-embedding-ada-002` (or any OpenAI model) to encode text. |
| **FastAPI** | Simple, async API with automatic docs (`/docs`). |
| **Conversation Buffer Memory** | Optional integration with LangChain for conversational context. |

---

## Prerequisites

| Component | Minimum Version | How to Install |
|-----------|-----------------|----------------|
| Python | 3.10+ | `python -m venv .venv && source .venv/bin/activate` |
| Qdrant | 1.x (Docker) | `docker run -p 6333:6333 qdrant/qdrant` |
| OpenAI API Key | – | Sign up at https://platform.openai.com and copy your key. |

> **Tip:** The server uses the default Qdrant port `6333`. If you change it, update `QDRANT_PORT` in `solution.py`.

---

## Installation

```bash
# 1️⃣ Clone the repo (or download solution.py)
git clone https://github.com/your-username/mcp-agent-memory.git
cd mcp-agent-memory

# 2️⃣ Create a virtual environment and activate it
python -m venv .venv
source .venv/bin/activate   # On Windows: .venv\Scripts\activate

# 3️⃣ Install dependencies
pip install --upgrade pip
pip install fastapi uvicorn httpx qdrant-client langchain openai pydantic
```

> **Optional** – If you want to use the built‑in LangChain memory, also install:
> ```bash
> pip install langchain[all]
> ```

---

## Configuration

Edit `solution.py` and set:

```python
OPENAI_API_KEY = "YOUR_OPENAI_API_KEY"   # <-- Replace with your key
QDRANT_HOST = "localhost"
QDRANT_PORT = 6333
COLLECTION_NAME = "agent_memory"
```

If you run Qdrant on a different host/port, adjust `QDRANT_HOST` and `QDRANT_PORT`.

---

## Running the Server

```bash
uvicorn solution:app --reload
```

- The server will start at `http://127.0.0.1:8000`.
- OpenAPI docs are available at `http://127.0.0.1:8000/docs`.

> **Note:** The first request to `/memory` will create the Qdrant collection automatically.

---

## API Endpoints

| Method | Path   | Description |
|--------|--------|-------------|
| `POST` | `/memory` | Add a new memory snippet. |
| `GET`  | `/query`  | Retrieve top‑k similar snippets for a query string. |

### POST /memory

```json
{
  "text": "The quick brown fox jumps over the lazy dog.",
  "metadata": {
    "source": "example.txt",
    "timestamp": "2024-05-28T12:34:56Z"
  }
}
```

**Response**

```json
{
  "id": 42,
  "text": "...",
  "metadata": { ... }
}
```

### GET /query

Query parameters:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query`   | str  | –       | Search string. |
| `top_k`   | int  | 5       | Number of results to return. |

**Example**

```
GET /query?query=quick%20fox&top_k=3
```

**Response**

```json
[
  {
    "id": 42,
    "text": "...",
    "metadata": { ... },
    "score": 0.87
  },
  ...
]
```

---

## Example Usage

Below is a quick Python script that demonstrates adding memory and querying it.

```python
import httpx

BASE_URL = "http://127.0.0.1:8000"

# 1️⃣ Add a memory snippet
payload = {
    "text": "The quick brown fox jumps over the lazy dog.",
    "metadata": {"source": "example.txt"}
}
resp = httpx.post(f"{BASE_URL}/memory", json=payload)
print("Added:", resp.json())

# 2️⃣ Query for similar snippets
params = {"query": "quick fox", "top_k": 3}
resp = httpx.get(f"{BASE_URL}/query", params=params)
print("Query results:")
for item in resp.json():
    print(item["text"], "(score:", item["score"] + ")")
```

Run the script after starting the server:

```bash
python example.py
```

---

## Testing with cURL

Add memory:

```bash
curl -X POST http://127.0.0.1:8000/memory \
     -H "Content-Type: application/json" \
     -d '{"text":"Hello world","metadata":{"source":"greeting"}}'
```

Query:

```bash
curl "http://127.0.0.1:8000/query?query=hello&top_k=2"
```

---

## License

MIT © 2024

---