diff --git a/.memory/project.md b/.memory/project.md
new file mode 100644
index 0000000..54c84f3
--- /dev/null
+++ b/.memory/project.md
@@ -0,0 +1,10 @@
+# Project Memory
+
+- Project: mtm-ssh-menu
+- Type: Bash SSH target picker using `fzf` and YAML config.
+- Main entry point: `mtm-ssh-menu`
+- Configuration: `~/.config/mtm-ssh-menu/global.yaml` and `hosts/*.yaml` by default.
+- Dependencies: `bash`, `ssh`, `fzf`, `jq`, `yq`.
+- Sample config is stored in `sample-config/`.
+- Documentation language: English.
+- Current task focus: keep README aligned with the working script and sample configuration.
diff --git a/README.md b/README.md
index 8f91eab..fdca782 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,88 @@
 # mtm-ssh-menu
 
+A small Bash utility to browse SSH targets from YAML configuration and connect to them with `fzf`.
+
+## Features
+
+- Interactive selection with `fzf`
+- Global defaults for SSH user, port, and jump hosts
+- Per-host overrides in grouped YAML files
+- Support for jump hosts via named aliases
+- Simple, dependency-light Bash script
+
+## Requirements
+
+- `bash`
+- `ssh`
+- `fzf`
+- `jq`
+- `yq`
+
+## Usage
+
+```bash
+./mtm-ssh-menu [--config-dir DIR]
+```
+
+Options:
+
+- `--help`: show help
+- `--config-dir DIR`: use a custom configuration directory
+
+By default, the script reads configuration from:
+
+- `~/.config/mtm-ssh-menu/global.yaml`
+- `~/.config/mtm-ssh-menu/hosts/*.yaml`
+
+## Configuration format
+
+### `global.yaml`
+
+```yaml
+ssh:
+  default_user: root
+  default_port: 22
+  default_options: ""
+  jump_hosts:
+    office: "user@192.168.10.11"
+```
+
+### `hosts/dev.yaml`
+
+```yaml
+group: dev
+servers:
+  - name: api-1
+    aliases:
+      - api
+      - backend
+    host: 192.168.10.11
+    user: dev
+    port: 2222
+```
+
+Each host entry can define:
+
+- `name`
+- `aliases`
+- `host`
+- `user`
+- `port`
+- `jump_host`
+
+## Example workflow
+
+1. Create the config directory.
+2. Add `global.yaml` and one or more files under `hosts/`.
+3. Run the script.
+4. Select a target in the menu and connect.
+
+## Sample configuration
+
+A complete sample configuration is available in `sample-config/`.
+
+## Notes
+
+- The script requires `yq`, `jq`, `ssh`, and `fzf` to be installed.
+- Jump hosts are resolved by name from `global.yaml`.
+- If a host does not define a user or port, global defaults are used.