# MCP‑Memory Server

A lightweight **Model Context Protocol (MCP)** server that exposes a simple API for storing and retrieving agent memory.  
The project is built on top of the `fastmcp` framework and uses `pydantic` for data validation and `python-dotenv` to load configuration from `.env`.

> **TL;DR** – Run the server, then use `memory_client.py` (or any MCP‑compatible client) to store and fetch memory chunks.

---

## Table of Contents

- [What is this?](#what-is-this)
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Running the Server](#running-the-server)
- [Using the Client](#using-the-client)
- [Example Workflow](#example-workflow)
- [License](#license)

---

## What is this?

The **MCP‑Memory Server** is a minimal, self‑contained service that:

1. Accepts `PUT` and `GET` requests over MCP.
2. Stores memory entries in JSON files under a namespace hierarchy.
3. Supports simple pattern matching (`fnmatch`) for bulk retrieval.

It’s ideal for prototyping multi‑agent systems where each agent can read/write to a shared knowledge base without worrying about the underlying storage format.

---

## Features

| Feature | Description |
|---------|-------------|
| **Namespace support** | Organize memory by logical groups (e.g., `agents/alpha`, `world/events`). |
| **Pattern matching** | Retrieve multiple entries with glob patterns (`*`, `?`). |
| **FastI/O** | Uses `fastmcp` for low‑latency communication. |
| **Configurable via `.env`** | Set the listening port, storage directory, and other options without code changes. |
| **Simple API** | Two endpoints: `/memory/{namespace}` (PUT) and `/memory/{namespace}/{key}` (GET). |

---

## Prerequisites

- Python 3.10 or newer
- `pip` (or any compatible package manager)

The project relies on the following libraries:

```bash
fastmcp==0.1.2   # MCP framework
pydantic==2.5    # Data validation
python-dotenv==1.0 # Environment variable loader
```

---

## Installation

```bash
# 1️⃣ Clone the repo (or copy the files)
git clone https://github.com/your-org/mcp-memory-server.git
cd mcp-memory-server

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

# 3️⃣ Install dependencies
pip install -r requirements.txt
```

> **Tip** – If you don’t have a `requirements.txt`, create one with the packages listed above.

---

## Running the Server

The server reads configuration from a `.env` file. Create it in the project root:

```dotenv
# .env
MCP_PORT=8000          # Port to listen on
STORAGE_DIR=data/memory  # Directory where JSON files are stored
```

Then start the server:

```bash
python memory_server.py
```

You should see something like:

```
[INFO] Memory-Server listening on http://localhost:8000
```

The server will automatically create `data/memory` if it doesn’t exist.

---

## Using the Client

A minimal client is provided in `memory_client.py`. It demonstrates how to:

1. Store a memory chunk.
2. Retrieve a single entry.
3. List entries with pattern matching.

```bash
python memory_client.py
```

The script will output the results of each operation, e.g.:

```
Stored: {'key': 'greeting', 'value': 'Hello, world!'}
Fetched: {'key': 'greeting', 'value': 'Hello, world!'}
All greetings: [{'key': 'greeting', 'value': 'Hello, world!'}]
```

---

## Example Workflow

Below is a quick walkthrough of how an agent might interact with the server.

```python
# 1️⃣ Import the client helper (or use any MCP library)
from memory_client import MemoryClient

client = MemoryClient(host="localhost", port=8000)

# 2️⃣ Store some facts under the "agents/alpha" namespace
client.put("agents/alpha", {"key": "location", "value": "office"})
client.put("agents/alpha", {"key": "mood", "value": "curious"})

# 3️⃣ Retrieve a specific fact
fact = client.get("agents/alpha/location")
print(fact)   # {'key': 'location', 'value': 'office'}

# 4️⃣ List all facts for the agent
all_facts = client.list("agents/alpha/*")
print(all_facts)
```

The server will persist these entries in:

```
data/memory/
└── agents/
    └── alpha.json   # contains [{"key":"location","value":"office"}, {"key":"mood","value":"curious"}]
```

---

## License

MIT © 2026 Your Name  
Feel free to fork, modify, and use this project in your own multi‑agent systems.

---