diff --git a/ README.md b/ README.md
new file mode 100644
index 0000000..b023400
--- /dev/null
+++ b/ README.md	
@@ -0,0 +1,125 @@
+# 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
+
+---
\ No newline at end of file