diff --git a/README.md b/README.md
index 3c74f4e..a6cd797 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,167 @@
-# mcp-server-dlya-upravleniya-pamyatyu-agenta
+# MCP‑Memory Server
 
-Решение: MCP-сервер для управления памятью агента
\ No newline at end of file
+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?](#what-is-this)
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Running the Server](#running-the-server)
+- [Using the Client](#using-the-client)
+- [Example Workflow](#example-workflow)
+- [License](#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:
+
+```bash
+fastmcp==0.1.2   # MCP framework
+pydantic==2.5    # Data validation
+python-dotenv==1.0 # Environment variable loader
+```
+
+---
+
+## Installation
+
+```bash
+# 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:
+
+```dotenv
+# .env
+MCP_PORT=8000          # Port to listen on
+STORAGE_DIR=data/memory  # Directory where JSON files are stored
+```
+
+Then start the server:
+
+```bash
+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.
+
+```bash
+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.
+
+```python
+# 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.
+
+---
\ No newline at end of file