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?
• Features
• Prerequisites
• Installation
• Running the Server
• Using the Client
• Example Workflow
• 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:

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

---

Installation

# 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:

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

Then start the server:

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.

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.

# 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.

---