167 lines
4.3 KiB
Markdown
167 lines
4.3 KiB
Markdown
# 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.
|
||
|
||
--- |