# MCP‑Memory Server

A lightweight **Model Context Protocol (MCP)** server that exposes a simple key/value memory store to any agent or client via the `fastmcp` protocol.

The project contains two scripts:

| File | Purpose |
|------|---------|
| `memory_server.py` | The MCP server – runs as an independent process and listens for requests. |
| `memory_client.py` | A demo client that connects to the server, stores data and retrieves it. |

> **Why MCP?**  
> In a multi‑agent system agents often need to share state (e.g., user profiles, conversation history).  Running a dedicated memory service decouples this shared state from individual agent processes, enabling easier scaling, persistence, and cross‑agent coordination.

---

## Features

- **Namespace support** – store data under arbitrary namespaces (`default`, `session_1234`, …).
- **Simple CRUD API** – `save_with_namespace`, `load_from_namespace`, `delete_from_namespace`.
- **FastMCP integration** – uses the `fastmcp` library for lightweight, async communication.
- **Zero‑configuration** – no external database required; data is kept in memory (restart loses state).

---

## Prerequisites

| Component | Minimum version |
|-----------|-----------------|
| Python | 3.10+ |
| pip | latest |

> No external services are needed – the server keeps all data in RAM.

---

## Installation

```bash
# Clone the repo
git clone https://github.com/your-org/mcp-memory-server.git
cd mcp-memory-server

# Create a virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

`requirements.txt` contains:

```text
fastmcp>=0.2.0
pydantic>=1.10.0
python-dotenv>=1.0.0
```

---

## Running the Server

The server is a simple Python script that can be started directly or via `subprocess`.  
It listens on an internal IPC channel (via `fastmcp`), so no network port is exposed.

```bash
# Direct execution
python memory_server.py
```

You should see:

```
[INFO] MCP Server listening...
```

---

## Running the Demo Client

The client demonstrates how to connect to the server, store a value, and retrieve it.

```bash
python memory_client.py
```

Output example:

```
Сохранено: {'status': 'ok'}
Загружено: {'value': 'Алексей', 'namespace': 'default'}
```

---

## API Reference

The server exposes three tools via MCP:

| Tool | Parameters | Returns |
|------|------------|---------|
| `save_with_namespace` | `{key, value, namespace}` | `{'status': 'ok'}` |
| `load_from_namespace` | `{key, namespace}` | `{'value': <value>, 'namespace': <ns>}` |
| `delete_from_namespace` | `{key, namespace}` | `{'status': 'deleted'}` |

All calls are asynchronous and return JSON‑serializable dictionaries.

---

## Example Usage in an Agent

```python
from fastmcp import Client
import asyncio

async def agent_logic():
    client = Client("python memory_server.py")
    await client.connect()

    # Store a user ID
    await client.call_tool(
        "save_with_namespace",
        {"key": "user_id", "value": 42, "namespace": "session_123"}
    )

    # Later retrieve it
    res = await client.call_tool(
        "load_from_namespace",
        {"key": "user_id", "namespace": "session_123"}
    )
    print(res["value"])   # -> 42

asyncio.run(agent_logic())
```

---

## Extending the Server

- **Persistence** – wrap the in‑memory store with a simple file or Redis backend.
- **Authentication** – add token checks to `Client` before processing requests.
- **Metrics** – expose Prometheus metrics for request counts and latency.

Feel free to fork, improve, and contribute!