diff --git a/README.md b/README.md
new file mode 100644
index 0000000..90a0121
--- /dev/null
+++ b/README.md
@@ -0,0 +1,60 @@
+# MCP Memory Server
+
+## Overview
+This repository contains a simple **MCP (Model Context Protocol)** server that provides basic key‑value memory operations with optional namespace support. The server is built on top of the `fastmcp` framework and stores data in a JSON file.
+
+The project also includes a small client script demonstrating how to interact with the server via MCP stdio transport.
+
+## File Structure
+- **memory_server.py** – Implements the MCP server with tools: `save`, `get`, `delete`, `list_keys`, `save_with_namespace`, `get_by_namespace`.
+- **memory_client.py** – Example client that connects to the server and performs a few operations.
+- **requirements.txt** – Python dependencies.
+- **README.md** – Project documentation.
+
+## Installation
+```bash
+pip install -r requirements.txt
+```
+
+## Running the Server
+```bash
+python memory_server.py
+```
+The server listens on stdio transport and can be used by any MCP client.
+
+## Using the Client
+```bash
+python memory_client.py
+```
+This script demonstrates:
+1. Saving a value with namespace `default`.
+2. Retrieving all items in that namespace.
+3. Listing keys matching a pattern.
+
+The expected output is similar to:
+```
+Сохранено: True
+Данные namespace 'default':
+  username: Алексей
+Ключи с 'name': ['default:user_name']
+```
+
+## MCP Tool Details
+| Tool | Purpose |
+|------|---------|
+| `save` | Store a value under a key. |
+| `get` | Retrieve the stored item for a key. |
+| `delete` | Remove a key from storage. |
+| `list_keys` | List all keys with optional glob pattern. |
+| `save_with_namespace` | Store a value under ``namespace:key``. |
+| `get_by_namespace` | Return all items belonging to a namespace. |
+
+## Notes
+- Data is persisted in `memory_data.json` located next to the script.
+- Timestamps are stored in UTC ISO format.
+- The server uses atomic writes for safety.
+- Wildcard patterns use Unix shell syntax via `fnmatch`.
+
+---
+
+Feel free to extend or adapt this example for your own multi‑agent systems.