# MCP‑Memory Server

A lightweight **FastMCP** based key/value store for agent memory with support for namespaces.

- **Server** – `memory_server.py`
- **Client** – `memory_client.py`

The server exposes the following tools:

| Tool | Description |
|------|-------------|
| `save` | Store a value by key. |
| `get` | Retrieve a value by key. |
| `delete` | Remove a key/value pair. |
| `list_keys` | List all stored keys. |
| `save_with_namespace` | Store a value under a namespace and key. |
| `get_by_namespace` | Retrieve a value from a specific namespace/key. |

---

## 📦 Installation

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

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

# Install dependencies
pip install fastmcp
```

> **Tip:** If you want to run the client and server on different machines, make sure the host machine is reachable from the client.

---

## 🚀 Running the Server

```bash
python memory_server.py
```

The server starts listening on `localhost:8000` by default.  
You can change the port or host by editing the `MCPServer` initialization in `memory_server.py`.

---

## 🧩 Using the Client

```bash
python memory_client.py
```

The client script demonstrates how to call each tool:

1. **Save a key/value pair**  
   ```python
   result = await client.call("save", {"key": "name", "value": "Alice"})
   print(result)  # → "Значение сохранено под ключом 'name'."
   ```

2. **Retrieve the value**  
   ```python
   value = await client.call("get", {"key": "name"})
   print(value)  # → "Alice"
   ```

3. **List all keys**  
   ```python
   keys = await client.call("list_keys")
   print(keys)  # → {"keys": ["name"]}
   ```

4. **Delete a key**  
   ```python
   result = await client.call("delete", {"key": "name"})
   print(result)  # → "Ключ 'name' удалён."
   ```

5. **Namespace operations**  
   ```python
   await client.call("save_with_namespace", {"namespace": "user1", "key": "age", "value": 30})
   age = await client.call("get_by_namespace", {"namespace": "user1", "key": "age"})
   print(age)  # → 30
   ```

Feel free to modify `memory_client.py` or write your own scripts that use the same RPC pattern.

---

## 📚 Example Workflow

```bash
# Terminal 1 – start server
$ python memory_server.py
Server listening on http://localhost:8000

# Terminal 2 – run client demo
$ python memory_client.py
Значение сохранено под ключом 'name'.
Alice
{'keys': ['name']}
Ключ 'name' удалён.
```

---

## 🔧 Troubleshooting

| Issue | Fix |
|-------|-----|
| `ModuleNotFoundError: No module named 'fastmcp'` | Ensure you installed the package in the active virtual environment. Run `pip install fastmcp`. |
| Connection refused | Verify that the server is running and listening on the correct host/port. |
| Unexpected RPC errors | Check that the tool names match exactly (`save`, `get`, etc.). |

---

## 📄 License

MIT © 2026

---