214 lines
4.6 KiB
Markdown
214 lines
4.6 KiB
Markdown
# 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
|
||
|
||
--- |