pi-ssh-remote 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -18,6 +18,37 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Rel
 
 - None.
 
+## [0.1.8] - 2026-08-10
+
+### Added
+
+- Added explicit private-key authentication through `ssh -i KEY`, including passphrase-protected keys and in-memory passphrase caching for reconnects.
+
+### Changed
+
+- Renamed the agent-facing `ssh_remote_control` tool to the shorter `remote` name, matching the `/remote` command.
+- Server memory is now keyed by `user@host` and shared across SSH ports; existing endpoint memories are migrated automatically.
+- `/remote forget` now clears cached private-key passphrases as well as passwords.
+
+### Fixed
+
+- None.
+
+## [0.1.7] - 2026-08-05
+
+### Added
+
+- Added non-secret, session-scoped SSH workspace state for endpoint, remote directory, tool-routing mode, and port forwards.
+
+### Changed
+
+- `/new` now inherits the active SSH workspace, forks and clones retain their source workspace, and `/resume` restores the selected historical session's recorded workspace.
+- Session changes close the previous transport cleanly and reconnect the target workspace without storing passwords or other credentials in session files.
+
+### Fixed
+
+- None.
+
 ## [0.1.6] - 2026-08-05
 
 ### Added
@@ -130,7 +161,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Rel
 
 - None.
 
-[Unreleased]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.6...HEAD
+[Unreleased]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.8...HEAD
+[0.1.8]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.7...v0.1.8
+[0.1.7]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/petrichor20211/pi-ssh-remote/releases/tag/v0.1.4

package/README.md

@@ -27,15 +27,15 @@ Once connected, Pi's file tools, shell tool, and `!` user shell commands are tra
 
 ### Agent control plane, human control plane
 
-The extension exposes `ssh_remote_control` for the agent and `/remote` for the user. You can ask Pi to connect, inspect status, change directory, add a server note, execute a command, create a tunnel, or return to local work in natural language—and still take direct control whenever you want.
+The extension exposes `remote` for the agent and `/remote` for the user. You can ask Pi to connect, inspect status, change directory, add a server note, execute a command, create a tunnel, or return to local work in natural language—and still take direct control whenever you want.
 
 ### Stateful endpoints instead of disposable SSH commands
 
-Each `user@host:port` endpoint remembers its remote working directory, note, server-specific memory, and port-forward configuration locally. Notes such as `H100 training`, `staging`, or `customer demo` appear in configuration, status messages, and Pi's footer, so the active execution environment stays visible. Server memory is automatically injected into the model context whenever that endpoint is connected as the active remote workspace.
+Each `user@host:port` endpoint remembers its remote working directory, note, and port-forward configuration locally. Server memory is shared by `user@host`, so connecting as the same user to the same host through another port uses the same memory. Notes such as `H100 training`, `staging`, or `customer demo` appear in configuration, status messages, and Pi's footer, so the active execution environment stays visible. Server memory is automatically injected into the model context whenever a matching endpoint is connected as the active remote workspace.
 
 ### Resilient and bounded by default
 
-Dropped connections are automatically re-established during the active session. Remote commands have a 30-second default timeout. Remote text reads fetch focused ranges instead of downloading complete files, command output is streamed through bounded buffers, and a 32 KB per-turn budget prevents parallel tools from flooding model context. Complete oversized command output is preserved in a permission-restricted temporary file.
+Dropped connections are automatically re-established during the active session. SSH workspace state is also session-aware: `/new` inherits the current workspace, forks and clones retain their source workspace, and `/resume` restores the selected session's recorded endpoint, remote directory, routing mode, and forwards. Remote commands have a 30-second default timeout. Remote text reads fetch focused ranges instead of downloading complete files, command output is streamed through bounded buffers, and a 32 KB per-turn budget prevents parallel tools from flooding model context. Complete oversized command output is preserved in a permission-restricted temporary file.
 
 ### Hybrid local/remote workflows
 
@@ -82,6 +82,16 @@ Return to local tools with:
 /remote off
 ```
 
+### Private key authentication
+
+Pass an explicit local private key with `-i`:
+
+```text
+/remote ssh -i ~/.ssh/id_ed25519 root@gpu-box.example.com -p 2202
+```
+
+Identity paths must be absolute or start with `~/`. Unencrypted and passphrase-protected private keys are supported. Pi prompts for an encrypted key's passphrase and caches it only in the current process for reconnects; `/remote forget` clears it. When `-i` is present, that key is used exclusively instead of silently falling back to SSH agent or password authentication. Commands without `-i` keep the existing SSH agent and password flow unchanged.
+
 ## Examples
 
 ### 1. Let the agent investigate and repair a remote failure
@@ -121,7 +131,7 @@ The default foreground timeout prevents an accidental long-running command from
 /remote
 ```
 
-Endpoint notes, working directories, and server-specific memories survive Pi restarts because they are stored in the local remote configuration. When Pi connects to an endpoint, its memory is added to the system context on every agent run while remote tool routing remains active. Disconnecting or switching to tunnel-only mode removes it from subsequent model requests.
+Endpoint notes and working directories, plus `user@host`-specific server memories, survive Pi restarts because they are stored in the local remote configuration. When Pi connects to an endpoint, the memory matching its user and host is added to the system context on every agent run while remote tool routing remains active; the SSH port does not affect memory selection. Disconnecting or switching to tunnel-only mode removes it from subsequent model requests.
 
 ### 4. Expose a remote service while editing locally
 
@@ -154,20 +164,20 @@ Forward the remote service on port 8000 to localhost:8000, but keep my coding
 tools on the local repository.
 ```
 
-These requests are handled through the agent-facing `ssh_remote_control` tool; slash commands are optional.
+These requests are handled through the agent-facing `remote` tool; slash commands are optional.
 
 ## Command reference
 
 | Command | Purpose |
 |---|---|
-| `/remote ssh USER@HOST -p PORT` | Save, select, and connect to an endpoint |
+| `/remote ssh USER@HOST -p PORT [-i KEY]` | Save, select, and connect using agent/password or an explicit private key |
 | `/remote` | Connect to the selected endpoint or prompt for one |
 | `/remote config` | List saved endpoints and settings |
 | `/remote use USER@HOST:PORT` | Select a saved endpoint |
 | `/remote config note TEXT` | Persist a note for the selected endpoint |
 | `/remote config note --clear` | Clear its note |
-| `/remote config memory TEXT` | Persist context that is injected while working on this endpoint |
-| `/remote config memory --clear` | Clear its server-specific memory |
+| `/remote config memory TEXT` | Persist context for the current `user@host`, shared across ports |
+| `/remote config memory --clear` | Clear the current `user@host` memory |
 | `/remote config cwd PATH` | Persist its default remote working directory |
 | `/remote cd PATH` | Change the connected remote cwd and persist it |
 | `/remote config forward MAPPING...` | Persist port forwards such as `7860:127.0.0.1:7860` |
@@ -185,7 +195,7 @@ These requests are handled through the agent-facing `ssh_remote_control` tool; s
 | `/remote status` | Show the active workspace |
 | `/remote reload` | Reconnect the active workspace |
 | `/remote off` | Disconnect and return tools to local execution |
-| `/remote forget` | Disconnect and clear the in-memory password |
+| `/remote forget` | Disconnect and clear cached passwords and key passphrases |
 
 ## Persistence, output, and security
 
@@ -195,23 +205,23 @@ Endpoint configuration is stored locally in:
 ~/.pi/agent/ssh-remote-config.json
 ```
 
-Saved values include endpoints, active endpoint, notes, server-specific memories, remote working directories, forwards, preview settings, and model-output budgets. Server memory is user-configured trusted context and is inserted into each model request only while that endpoint is the active remote workspace; it is not read from the remote server. Passwords are **never written to this file**: SSH agent authentication is preferred, and prompted passwords remain only in process memory.
+Saved global values include endpoints, active endpoint, notes, `user@host`-specific server memories, remote working directories, forwards, identity file paths, preview settings, and model-output budgets. Each Pi session also stores non-secret SSH workspace metadata so `/resume` can restore the server associated with that session. Server memory is user-configured trusted context and is inserted into each model request only while a matching endpoint is the active remote workspace; it is not read from the remote server. Private key contents, passwords, and key passphrases are **never written to this file**. Private keys are read locally only when connecting; prompted passwords and passphrases remain only in process memory.
 
 New or changed host keys require interactive confirmation and are stored separately from OpenSSH. By default, remote text reads return at most 400 lines or 16 KB, remote command results return the last 200 lines or 8 KB, and all remote tools in one agent turn share a 32 KB output budget. Text reads support `offset`/`limit` continuation without downloading the complete remote file. Oversized command output is streamed to a permission-restricted temporary local file rather than accumulated in memory. Configured limits may be raised only to the extension's hard safety ceilings. Preview-line settings affect only the collapsed UI and never increase model output.
 
 ## Current SSH scope
 
-The extension currently supports direct SSH commands with `-p` and `-l`. It does not yet consume `~/.ssh/config`, `IdentityFile`, or ProxyJump settings.
+The extension currently supports direct SSH commands with `-p`, `-l`, and `-i`. It does not yet consume `~/.ssh/config` or ProxyJump settings; use `-i` explicitly instead of relying on an `IdentityFile` entry.
 
 ## Releases
 
-Latest release: [v0.1.6](https://github.com/petrichor20211/pi-ssh-remote/releases/tag/v0.1.6)
+Latest release: [v0.1.8](https://github.com/petrichor20211/pi-ssh-remote/releases/tag/v0.1.8)
 
 | Version | Date | Highlights |
 |---|---|---|
+| [0.1.8](CHANGELOG.md#018---2026-08-10) | 2026-08-10 | Explicit private-key login, cross-port server memory, and the shorter `remote` tool name |
+| [0.1.7](CHANGELOG.md#017---2026-08-05) | 2026-08-05 | Session-aware SSH workspace restoration for new, forked, and resumed sessions |
 | [0.1.6](CHANGELOG.md#016---2026-08-05) | 2026-08-05 | Bounded remote reads, streamed command output, and per-turn output budgets |
-| [0.1.5](CHANGELOG.md#015---2026-08-04) | 2026-08-04 | Endpoint-specific server memory and automatic context injection |
-| [0.1.4](CHANGELOG.md#014---2026-07-31) | 2026-07-31 | Endpoint notes and enforced remote command timeouts |
 
 See [CHANGELOG.md](CHANGELOG.md) for the complete release history, including additions, behavior changes, and bug fixes.
 

package/README.zh-CN.md

@@ -54,11 +54,11 @@ SSH remote H100 训练机 (root@gpu-box.example.com:2202):/srv/project
 - 服务器特定记忆；
 - 端口转发配置。
 
-例如可以把几台机器分别备注为 `8xH100 训练机`、`预发布环境`、`线上只读机`。还可以为每个 `user@host:port` 保存独立记忆，例如指定 Python 环境、共享任务保护规则或部署约定。连接该 endpoint 并启用远端工具路由后，这段记忆会自动注入模型上下文；断开连接或切换到纯隧道模式后，后续请求不再注入。所有配置保存在本地，重启 Pi 后仍然存在。
+例如可以把几台机器分别备注为 `8xH100 训练机`、`预发布环境`、`线上只读机`。服务器记忆按 `user@host` 保存，例如指定 Python 环境、共享任务保护规则或部署约定；同一用户和主机即使通过不同 SSH 端口连接，也会使用同一份记忆。连接匹配的 endpoint 并启用远端工具路由后，这段记忆会自动注入模型上下文；断开连接或切换到纯隧道模式后，后续请求不再注入。所有配置保存在本地，重启 Pi 后仍然存在。
 
 ### 断线后可以自动恢复
 
-当前会话中如果 SSH 连接意外断开，插件会尝试自动重连，不需要 Agent 从头建立工作环境。
+当前会话中如果 SSH 连接意外断开，插件会尝试自动重连，不需要 Agent 从头建立工作环境。SSH 工作区状态也会跟随 Pi session：`/new` 继承当前工作区，`/fork` 和 `/clone` 保留来源工作区，`/resume` 恢复目标历史 session 记录的服务器、远程目录、路由模式和端口转发。
 
 ### 对 Agent 上下文更友好
 
@@ -124,6 +124,16 @@ pi install npm:pi-ssh-remote
 /remote off
 ```
 
+### 使用私钥文件登录
+
+通过 `-i` 指定本地私钥：
+
+```text
+/remote ssh -i ~/.ssh/id_ed25519 root@gpu-box.example.com -p 2202
+```
+
+密钥路径必须是绝对路径或以 `~/` 开头。插件支持未加密私钥和带 passphrase 的私钥；对于加密私钥，Pi 会以遮罩方式询问 passphrase，并仅在当前进程内缓存以便自动重连，`/remote forget` 会清除它。指定 `-i` 后只使用该私钥，不会静默回退到 SSH Agent 或密码；不带 `-i` 的旧命令仍保持原有的 SSH Agent 和密码登录流程。
+
 ## 常见用法
 
 ### 1. 让 Pi 直接排查远程服务故障
@@ -173,7 +183,7 @@ pi install npm:pi-ssh-remote
 /remote
 ```
 
-备注和默认目录会按 `user@host:port` 分别保存，不会互相覆盖。
+备注和默认目录会按 `user@host:port` 分别保存，不会互相覆盖；服务器记忆则按 `user@host` 共享，不受端口影响。
 
 ### 4. 远端启动模型，本地开发界面
 
@@ -208,20 +218,20 @@ pi install npm:pi-ssh-remote
 把远端 8000 端口转发到本地 8000，但代码工具继续留在本地。
 ```
 
-Pi 会通过插件提供的 `ssh_remote_control` 工具完成这些操作。
+Pi 会通过插件提供的 `remote` 工具完成这些操作。
 
 ## 命令说明
 
 | 命令 | 作用 |
 |---|---|
-| `/remote ssh USER@HOST -p PORT` | 保存并连接服务器 |
+| `/remote ssh USER@HOST -p PORT [-i KEY]` | 保存并使用 Agent／密码或指定私钥连接服务器 |
 | `/remote` | 连接当前选中的服务器，或提示输入 SSH 地址 |
 | `/remote config` | 查看已保存的服务器和配置 |
 | `/remote use USER@HOST:PORT` | 切换到指定服务器 |
 | `/remote config note TEXT` | 给当前服务器添加或修改备注 |
 | `/remote config note --clear` | 清除当前服务器备注 |
-| `/remote config memory TEXT` | 保存连接该服务器时自动注入上下文的记忆 |
-| `/remote config memory --clear` | 清除当前服务器的特定记忆 |
+| `/remote config memory TEXT` | 保存当前 `user@host` 的记忆，并在不同端口间共享 |
+| `/remote config memory --clear` | 清除当前 `user@host` 的记忆 |
 | `/remote config cwd PATH` | 设置默认远程工作目录 |
 | `/remote cd PATH` | 切换当前远程目录并保存 |
 | `/remote config forward MAPPING...` | 保存端口转发配置，例如 `7860:127.0.0.1:7860` |
@@ -239,7 +249,7 @@ Pi 会通过插件提供的 `ssh_remote_control` 工具完成这些操作。
 | `/remote status` | 查看当前连接和工作目录 |
 | `/remote reload` | 重新连接当前服务器 |
 | `/remote off` | 断开连接并返回本地 |
-| `/remote forget` | 断开连接并清除内存中的密码 |
+| `/remote forget` | 断开连接并清除内存中的密码和密钥 passphrase |
 
 ## 配置保存在哪里
 
@@ -249,7 +259,7 @@ Pi 会通过插件提供的 `ssh_remote_control` 工具完成这些操作。
 ~/.pi/agent/ssh-remote-config.json
 ```
 
-其中包括：
+全局配置包括：
 
 - 已保存的服务器；
 - 当前选中的服务器；
@@ -257,12 +267,13 @@ Pi 会通过插件提供的 `ssh_remote_control` 工具完成这些操作。
 - 服务器特定记忆；
 - 默认远程目录；
 - 端口转发配置；
+- 私钥文件路径；
 - 命令预览设置；
 - 模型输出预算。
 
-服务器记忆是由用户在本地配置的可信上下文，不会从远程服务器自动读取；仅当对应 endpoint 作为远端工作区启用时才会加入每次模型请求。
+此外，每个 Pi session 都会记录不含凭据的 SSH 工作区元数据，用于在 `/resume` 时恢复该历史 session 对应的服务器环境。服务器记忆按 `user@host` 识别，不受 SSH 端口影响。它是由用户在本地配置的可信上下文，不会从远程服务器自动读取；仅当匹配的 endpoint 作为远端工作区启用时才会加入每次模型请求。
 
-密码不会写入配置文件。插件会优先使用 SSH agent；如果需要手动输入密码，密码只会缓存在当前 Pi 进程的内存中。
+私钥内容、密码和密钥 passphrase 都不会写入配置文件。插件仅在连接时从本地读取私钥；手动输入的密码和 passphrase 只会缓存在当前 Pi 进程的内存中。
 
 ## 安全与输出限制
 
@@ -279,17 +290,17 @@ Pi 会通过插件提供的 `ssh_remote_control` 工具完成这些操作。
 
 ## 当前限制
 
-目前只支持 SSH 直连，以及 `-p`、`-l` 参数。暂不读取 `~/.ssh/config`，也不支持 `IdentityFile` 和 ProxyJump。
+目前只支持 SSH 直连，以及 `-p`、`-l`、`-i` 参数。暂不读取 `~/.ssh/config` 或 ProxyJump；如需指定私钥，请显式使用 `-i`，不要依赖 SSH config 中的 `IdentityFile`。
 
 ## 版本发布
 
-最新版本：[v0.1.6](https://github.com/petrichor20211/pi-ssh-remote/releases/tag/v0.1.6)
+最新版本：[v0.1.8](https://github.com/petrichor20211/pi-ssh-remote/releases/tag/v0.1.8)
 
 | 版本 | 日期 | 主要内容 |
 |---|---|---|
+| [0.1.8](CHANGELOG.md#018---2026-08-10) | 2026-08-10 | 显式私钥登录、跨端口服务器记忆与更短的 `remote` 工具名 |
+| [0.1.7](CHANGELOG.md#017---2026-08-05) | 2026-08-05 | 新建、分叉和恢复 session 时自动恢复对应 SSH 工作区 |
 | [0.1.6](CHANGELOG.md#016---2026-08-05) | 2026-08-05 | 有界远端读取、流式命令输出与每轮输出预算 |
-| [0.1.5](CHANGELOG.md#015---2026-08-04) | 2026-08-04 | endpoint 级服务器记忆与自动上下文注入 |
-| [0.1.4](CHANGELOG.md#014---2026-07-31) | 2026-07-31 | endpoint 备注与远程命令强制超时 |
 
 完整的新增内容、行为变更和 Bug 修复记录请查看 [CHANGELOG.md](CHANGELOG.md)。
 

package/index.ts

@@ -6,9 +6,9 @@
  * credentials, remote working directories, reconnection, and TCP forwarding.
  */
 
-import { Client, type ClientChannel, type ConnectConfig, type SFTPWrapper } from "ssh2";
-import { closeSync, mkdirSync, mkdtempSync, openSync, readFileSync, writeFileSync, writeSync } from "node:fs";
-import { dirname, join, posix, relative, sep } from "node:path";
+import ssh2, { type Client as SshClient, type ClientChannel, type ConnectConfig, type SFTPWrapper } from "ssh2";
+import { closeSync, mkdirSync, mkdtempSync, openSync, readFileSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { dirname, isAbsolute, join, posix, relative, sep } from "node:path";
 import { createServer, type Server, type Socket } from "node:net";
 import { tmpdir } from "node:os";
 import { Type } from "typebox";
@@ -33,22 +33,26 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { CURSOR_MARKER, Key, Text, matchesKey, truncateToWidth, type Component, type Focusable } from "@earendil-works/pi-tui";
 
+const { Client, utils: ssh2Utils } = ssh2;
+
 interface ParsedSsh {
   host: string;
   port: number;
   username: string;
+  identityFile?: string;
   label: string;
   command: string;
 }
 
 interface RemoteState extends ParsedSsh {
-  client: Client;
+  client: SshClient;
   cwd: string;
 }
 
 interface CredentialCache {
   passwords: Map<string, string>;
-  resume?: { command: string; cwd: string };
+  keyPassphrases: Map<string, string>;
+  resume?: { command: string; cwd: string; routeRemoteTools: boolean; forwards?: string[] };
 }
 
 interface RemoteEndpointConfig {
@@ -56,12 +60,14 @@ interface RemoteEndpointConfig {
   remoteCwd?: string;
   forwards?: string[];
   note?: string;
+  /** Legacy field migrated into serverMemories on the next config write. */
   memory?: string;
 }
 
 interface RemoteConfig {
   activeEndpoint?: string;
   endpoints?: Record<string, RemoteEndpointConfig>;
+  serverMemories?: Record<string, string>;
   displayLines?: number;
   readMaxLines?: number;
   readMaxBytes?: number;
@@ -80,6 +86,15 @@ interface ForwardSpec {
   remotePort: number;
 }
 
+interface SessionRemoteState {
+  version: 1;
+  connected: boolean;
+  command?: string;
+  cwd?: string;
+  routeRemoteTools?: boolean;
+  forwards?: string[];
+}
+
 const AGENT_DIR = join(process.env.HOME || ".", CONFIG_DIR_NAME, "agent");
 const KNOWN_HOSTS_FILE = join(AGENT_DIR, "ssh-remote-known-hosts.json");
 const REMOTE_CONFIG_FILE = join(AGENT_DIR, "ssh-remote-config.json");
@@ -95,9 +110,12 @@ const MIN_MODEL_OUTPUT_BYTES = 1024;
 const OUTPUT_FOOTER_RESERVE_BYTES = 512;
 const DEFAULT_REMOTE_TIMEOUT_SECONDS = 30;
 const MAX_REMOTE_TIMEOUT_SECONDS = 2_147_483_647 / 1000;
+const MAX_PRIVATE_KEY_BYTES = 1024 * 1024;
+const SESSION_STATE_ENTRY_TYPE = "pi-ssh-remote-state";
 const CACHE_KEY = "__piHpcCredentialCacheV1";
 const cacheHost = globalThis as typeof globalThis & { [CACHE_KEY]?: CredentialCache };
-const credentialCache = cacheHost[CACHE_KEY] ??= { passwords: new Map<string, string>() };
+const credentialCache = cacheHost[CACHE_KEY] ??= { passwords: new Map<string, string>(), keyPassphrases: new Map<string, string>() };
+credentialCache.keyPassphrases ??= new Map<string, string>();
 
 function shellWords(input: string): string[] {
   const words: string[] = [];
@@ -122,28 +140,47 @@ function parseSshCommand(command: string): ParsedSsh {
   if (args[0] !== "ssh") throw new Error("Command must start with ssh, for example: ssh root@host -p 22");
   let port = 22;
   let username = process.env.USER || "root";
+  let identityFile: string | undefined;
   let target: string | undefined;
   for (let i = 1; i < args.length; i++) {
     const arg = args[i]!;
     if (arg === "-p") { port = Number(args[++i]); continue; }
     if (arg.startsWith("-p") && arg.length > 2) { port = Number(arg.slice(2)); continue; }
     if (arg === "-l") { username = args[++i] || username; continue; }
-    if (arg.startsWith("-")) throw new Error(`Unsupported SSH option ${arg}; only -p and -l are currently supported`);
+    if (arg === "-i") {
+      if (identityFile !== undefined) throw new Error("Only one SSH identity file may be specified");
+      identityFile = args[++i];
+      if (!identityFile) throw new Error("SSH option -i requires a private key path");
+      continue;
+    }
+    if (arg.startsWith("-i") && arg.length > 2) {
+      if (identityFile !== undefined) throw new Error("Only one SSH identity file may be specified");
+      identityFile = arg.slice(2);
+      continue;
+    }
+    if (arg.startsWith("-")) throw new Error(`Unsupported SSH option ${arg}; only -p, -l, and -i are currently supported`);
     if (!target) target = arg;
     else throw new Error("Unexpected extra argument in SSH command");
   }
   if (!target || !Number.isInteger(port) || port < 1 || port > 65535) throw new Error("Invalid SSH host or port");
+  if (identityFile && identityFile !== "~" && !identityFile.startsWith("~/") && !isAbsolute(identityFile)) {
+    throw new Error("SSH identity file must use an absolute path or ~/...");
+  }
   const at = target.lastIndexOf("@");
   const host = at >= 0 ? target.slice(at + 1) : target;
   if (at >= 0) username = target.slice(0, at);
   if (!host || !username) throw new Error("Invalid SSH username or host");
-  return { host, port, username, label: `${username}@${host}:${port}`, command };
+  return { host, port, username, ...(identityFile ? { identityFile } : {}), label: `${username}@${host}:${port}`, command };
 }
 
 function cacheId(config: ParsedSsh): string {
   return `${config.username}@${config.host}:${config.port}`;
 }
 
+function serverMemoryId(config: ParsedSsh): string {
+  return `${config.username}@${config.host}`;
+}
+
 function getCachedPassword(config: ParsedSsh): string | undefined {
   return credentialCache.passwords.get(cacheId(config));
 }
@@ -156,6 +193,60 @@ function deleteCachedPassword(config: ParsedSsh): void {
   credentialCache.passwords.delete(cacheId(config));
 }
 
+function resolveIdentityPath(config: ParsedSsh): string {
+  if (!config.identityFile) throw new Error("No SSH identity file is configured");
+  if (config.identityFile === "~" || config.identityFile.startsWith("~/")) {
+    const home = process.env.HOME;
+    if (!home) throw new Error("Cannot expand SSH identity path because HOME is not set");
+    return config.identityFile === "~" ? home : join(home, config.identityFile.slice(2));
+  }
+  return config.identityFile;
+}
+
+function keyPassphraseId(config: ParsedSsh): string {
+  return `${cacheId(config)}|${resolveIdentityPath(config)}`;
+}
+
+function getCachedKeyPassphrase(config: ParsedSsh): string | undefined {
+  return credentialCache.keyPassphrases.get(keyPassphraseId(config));
+}
+
+function setCachedKeyPassphrase(config: ParsedSsh, passphrase: string): void {
+  credentialCache.keyPassphrases.set(keyPassphraseId(config), passphrase);
+}
+
+function deleteCachedKeyPassphrase(config: ParsedSsh): void {
+  if (config.identityFile) credentialCache.keyPassphrases.delete(keyPassphraseId(config));
+}
+
+function readPrivateKey(config: ParsedSsh): Buffer {
+  const path = resolveIdentityPath(config);
+  let stat;
+  try { stat = statSync(path); }
+  catch (error) { throw new Error(`Cannot access SSH private key ${path}: ${(error as Error).message}`); }
+  if (!stat.isFile()) throw new Error(`SSH private key is not a regular file: ${path}`);
+  if (stat.size > MAX_PRIVATE_KEY_BYTES) throw new Error(`SSH private key exceeds the ${MAX_PRIVATE_KEY_BYTES}-byte limit: ${path}`);
+  try { return readFileSync(path); }
+  catch (error) { throw new Error(`Cannot read SSH private key ${path}: ${(error as Error).message}`); }
+}
+
+function parsePrivateKey(keyData: Buffer, passphrase?: string): any | Error {
+  let parsed: any;
+  try { parsed = ssh2Utils.parseKey(keyData, passphrase); }
+  catch (error) { return error as Error; }
+  if (parsed instanceof Error) return parsed;
+  const keys = Array.isArray(parsed) ? parsed : [parsed];
+  const privateKeys = keys.filter((key) => key?.isPrivateKey?.());
+  if (privateKeys.length !== 1) {
+    return new Error(privateKeys.length ? "SSH identity files containing multiple private keys are not supported" : "SSH identity file does not contain a private key");
+  }
+  return privateKeys[0];
+}
+
+function isPassphraseError(error: Error): boolean {
+  return /passphrase|encrypted private/i.test(error.message);
+}
+
 function parseForwardSpec(value: string): ForwardSpec {
   const match = value.match(/^(\d+):([^:]+):(\d+)$/);
   if (!match) throw new Error(`Invalid port-forward specification: ${value}; expected LOCAL_PORT:REMOTE_HOST:REMOTE_PORT`);
@@ -231,11 +322,25 @@ function commandFromEndpointKey(key: string): string | undefined {
 
 function normalizeRemoteConfig(config: RemoteConfig): RemoteConfig {
   const endpoints = { ...(config.endpoints ?? {}) };
-  for (const [key, endpoint] of Object.entries(endpoints)) {
+  const serverMemories = Object.fromEntries(
+    Object.entries(config.serverMemories ?? {})
+      .filter((entry): entry is [string, string] => typeof entry[1] === "string" && Boolean(entry[1].trim()))
+      .map(([key, memory]) => [key, memory.trim()]),
+  );
+  const endpointEntries = Object.entries(endpoints).sort(([left], [right]) =>
+    left === config.activeEndpoint ? -1 : right === config.activeEndpoint ? 1 : 0,
+  );
+  for (const [key, endpoint] of endpointEntries) {
+    const command = endpoint.sshCommand || commandFromEndpointKey(key);
+    const { memory: legacyMemory, ...endpointWithoutMemory } = endpoint;
     endpoints[key] = {
-      ...endpoint,
-      ...(endpoint.sshCommand ? {} : { sshCommand: commandFromEndpointKey(key) }),
+      ...endpointWithoutMemory,
+      ...(command ? { sshCommand: command } : {}),
     };
+    if (legacyMemory?.trim() && command) {
+      try { serverMemories[serverMemoryId(parseSshCommand(command))] ??= legacyMemory.trim(); }
+      catch {}
+    }
   }
 
   let activeEndpoint = config.activeEndpoint;
@@ -269,6 +374,7 @@ function normalizeRemoteConfig(config: RemoteConfig): RemoteConfig {
   return {
     ...(activeEndpoint ? { activeEndpoint } : {}),
     ...(Object.keys(endpoints).length ? { endpoints } : {}),
+    ...(Object.keys(serverMemories).length ? { serverMemories } : {}),
     ...(displayLines !== undefined ? { displayLines } : {}),
     ...(readMaxLines !== undefined ? { readMaxLines } : {}),
     ...(readMaxBytes !== undefined ? { readMaxBytes } : {}),
@@ -307,13 +413,13 @@ function endpointDisplayLabel(endpoint: ParsedSsh, config = loadRemoteConfig()):
 }
 
 function endpointMemory(endpoint: ParsedSsh, config = loadRemoteConfig()): string | undefined {
-  return endpointConfig(config, endpoint.command).memory?.trim() || undefined;
+  return config.serverMemories?.[serverMemoryId(endpoint)]?.trim() || undefined;
 }
 
 function remoteSystemPrompt(systemPrompt: string, localCwd: string, remote: RemoteState): string {
   return systemPrompt.replace(
     `Current working directory: ${localCwd}`,
-    `Current working directory: ${remote.cwd} (via SSH ${endpointDisplayLabel(remote)}). All read, write, edit, bash, and user shell operations run on this remote server. Use ssh_remote_control with action disconnect to return to the local environment when requested.`,
+    `Current working directory: ${remote.cwd} (via SSH ${endpointDisplayLabel(remote)}). All read, write, edit, bash, and user shell operations run on this remote server. Use remote with action disconnect to return to the local environment when requested.`,
   );
 }
 
@@ -336,6 +442,24 @@ function saveEndpointConfig(command: string, updates: RemoteEndpointConfig, make
   });
 }
 
+function saveServerMemory(command: string, memory: string | undefined): void {
+  const config = loadRemoteConfig();
+  const parsed = parseSshCommand(command);
+  const endpointKey = cacheId(parsed);
+  const memoryKey = serverMemoryId(parsed);
+  const serverMemories = { ...(config.serverMemories ?? {}) };
+  if (memory) serverMemories[memoryKey] = memory;
+  else delete serverMemories[memoryKey];
+  saveRemoteConfig({
+    ...config,
+    serverMemories,
+    endpoints: {
+      ...(config.endpoints ?? {}),
+      [endpointKey]: { ...endpointConfig(config, command), sshCommand: command },
+    },
+  });
+}
+
 function loadKnownHosts(): Record<string, string> {
   try { return JSON.parse(readFileSync(KNOWN_HOSTS_FILE, "utf8")); }
   catch { return {}; }
@@ -508,15 +632,16 @@ function probeFingerprint(config: ParsedSsh): Promise<string> {
   });
 }
 
-function connect(config: ParsedSsh, password: string | undefined, fingerprint: string): Promise<Client> {
+type SshAuthentication = Partial<Pick<ConnectConfig, "password" | "privateKey" | "passphrase" | "agent">>;
+
+function connect(config: ParsedSsh, authentication: SshAuthentication, fingerprint: string): Promise<SshClient> {
   return new Promise((resolve, reject) => {
     const client = new Client();
     const options: ConnectConfig = {
       host: config.host,
       port: config.port,
       username: config.username,
-      ...(password ? { password } : {}),
-      ...(process.env.SSH_AUTH_SOCK ? { agent: process.env.SSH_AUTH_SOCK } : {}),
+      ...authentication,
       readyTimeout: 12000,
       keepaliveInterval: 15000,
       keepaliveCountMax: 3,
@@ -530,7 +655,7 @@ function connect(config: ParsedSsh, password: string | undefined, fingerprint: s
 }
 
 function execRemote(
-  client: Client,
+  client: SshClient,
   command: string,
   allowFailure = false,
   timeoutSeconds = DEFAULT_REMOTE_TIMEOUT_SECONDS,
@@ -564,7 +689,7 @@ function execRemote(
 }
 
 function execRemoteLimited(
-  client: Client,
+  client: SshClient,
   command: string,
   timeoutSeconds: number,
   maxLines: number,
@@ -610,11 +735,11 @@ function execRemoteLimited(
   });
 }
 
-function getSftp(client: Client): Promise<SFTPWrapper> {
+function getSftp(client: SshClient): Promise<SFTPWrapper> {
   return new Promise((resolve, reject) => client.sftp((error, sftp) => error ? reject(error) : resolve(sftp)));
 }
 
-async function withSftp<T>(client: Client, operation: (sftp: SFTPWrapper) => Promise<T>): Promise<T> {
+async function withSftp<T>(client: SshClient, operation: (sftp: SFTPWrapper) => Promise<T>): Promise<T> {
   const sftp = await getSftp(client);
   try { return await operation(sftp); }
   finally { sftp.end(); }
@@ -625,10 +750,10 @@ function isReconnectable(error: unknown): boolean {
   return /channel open failure|open failed|not connected|no response|econnreset|econnrefused|etimedout|ehostunreach|epipe|connection (?:lost|closed)|socket.*closed|client is not connected/i.test(message);
 }
 
-class PasswordInput implements Component, Focusable {
+class SecretInput implements Component, Focusable {
   focused = false;
   private value = "";
-  constructor(private done: (value: string | null) => void, private renderNow: () => void) {}
+  constructor(private label: string, private done: (value: string | null) => void, private renderNow: () => void) {}
   handleInput(data: string): void {
     if (matchesKey(data, Key.enter)) return this.done(this.value);
     if (matchesKey(data, Key.escape)) return this.done(null);
@@ -641,15 +766,19 @@ class PasswordInput implements Component, Focusable {
     this.renderNow();
   }
   render(width: number): string[] {
-    return [truncateToWidth(`SSH password: ${"•".repeat([...this.value].length)}${this.focused ? CURSOR_MARKER : ""}\x1b[7m \x1b[27m`, width, "")];
+    return [truncateToWidth(`${this.label}: ${"•".repeat([...this.value].length)}${this.focused ? CURSOR_MARKER : ""}\x1b[7m \x1b[27m`, width, "")];
   }
   invalidate(): void {}
 }
 
-async function askPassword(ctx: any): Promise<string | null> {
-  if (ctx.mode !== "tui") return (await ctx.ui.input("SSH password:", "password")) ?? null;
+async function askSecret(ctx: any, label: string, placeholder: string): Promise<string | null> {
+  if (ctx.mode !== "tui") return (await ctx.ui.input(`${label}:`, placeholder)) ?? null;
   return ctx.ui.custom<string | null>((tui: any, _theme: any, _keys: any, done: (value: string | null) => void) =>
-    new PasswordInput(done, () => tui.requestRender()));
+    new SecretInput(label, done, () => tui.requestRender()));
+}
+
+async function askPassword(ctx: any): Promise<string | null> {
+  return askSecret(ctx, "SSH password", "password");
 }
 
 export default function sshRemoteExtension(pi: ExtensionAPI) {
@@ -659,6 +788,9 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
   let currentCtx: any;
   let reconnectPromise: Promise<RemoteState> | null = null;
   const forwardServers = new Map<number, Server>();
+  const forwardSpecs = new Map<number, ForwardSpec>();
+  let sessionReady = false;
+  let restoringSessionState = false;
   let lastConnectionError: string | undefined;
   let lastCommand = credentialCache.resume?.command ?? activeSshCommand() ?? "";
   let turnOutputBytes = 0;
@@ -669,6 +801,33 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
   const configuredForwards = (command: string): string[] =>
     endpointConfig(loadRemoteConfig(), command).forwards ?? [];
 
+  const standardAuthentication = (password?: string): SshAuthentication => ({
+    ...(password ? { password } : {}),
+    ...(process.env.SSH_AUTH_SOCK ? { agent: process.env.SSH_AUTH_SOCK } : {}),
+  });
+
+  const privateKeyAuthentication = async (parsed: ParsedSsh, ctx?: any): Promise<SshAuthentication> => {
+    const keyData = readPrivateKey(parsed);
+    let passphrase = getCachedKeyPassphrase(parsed);
+    let privateKey = parsePrivateKey(keyData, passphrase);
+    if (privateKey instanceof Error && isPassphraseError(privateKey)) {
+      if (passphrase) deleteCachedKeyPassphrase(parsed);
+      if (!ctx) throw new Error(`SSH private key ${resolveIdentityPath(parsed)} requires its passphrase again; reconnect interactively`);
+      passphrase = await askSecret(ctx, `Passphrase for ${parsed.identityFile}`, "private key passphrase") ?? undefined;
+      if (!passphrase) throw new Error("No SSH private key passphrase was provided");
+      privateKey = parsePrivateKey(keyData, passphrase);
+      if (privateKey instanceof Error) {
+        deleteCachedKeyPassphrase(parsed);
+        throw new Error(`Could not unlock SSH private key ${resolveIdentityPath(parsed)}: ${privateKey.message}`);
+      }
+      setCachedKeyPassphrase(parsed, passphrase);
+    }
+    if (privateKey instanceof Error) {
+      throw new Error(`Invalid SSH private key ${resolveIdentityPath(parsed)}: ${privateKey.message}`);
+    }
+    return { privateKey: keyData, ...(passphrase ? { passphrase } : {}) };
+  };
+
   const mapPath = (path: string): string => {
     if (!remote) return path;
     if (path === localCwd) return remote.cwd;
@@ -684,6 +843,42 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
     return posix.join(remote.cwd, normalized);
   };
 
+  const serializeForward = (spec: ForwardSpec): string => `${spec.localPort}:${spec.remoteHost}:${spec.remotePort}`;
+
+  const currentSessionRemoteState = (): SessionRemoteState => remote ? {
+    version: 1,
+    connected: true,
+    command: remote.command,
+    cwd: remote.cwd,
+    routeRemoteTools,
+    forwards: [...forwardSpecs.values()].map(serializeForward),
+  } : { version: 1, connected: false };
+
+  const persistSessionRemoteState = (): void => {
+    if (!sessionReady || restoringSessionState) return;
+    pi.appendEntry(SESSION_STATE_ENTRY_TYPE, currentSessionRemoteState());
+  };
+
+  const loadSessionRemoteState = (ctx: any): SessionRemoteState | undefined => {
+    const branch = ctx.sessionManager.getBranch();
+    for (let index = branch.length - 1; index >= 0; index--) {
+      const entry = branch[index] as any;
+      if (entry.type !== "custom" || entry.customType !== SESSION_STATE_ENTRY_TYPE) continue;
+      const data = entry.data as Partial<SessionRemoteState> | undefined;
+      if (!data || data.version !== 1 || typeof data.connected !== "boolean") return undefined;
+      if (data.connected && (typeof data.command !== "string" || typeof data.cwd !== "string")) return undefined;
+      return {
+        version: 1,
+        connected: data.connected,
+        ...(data.command ? { command: data.command } : {}),
+        ...(data.cwd ? { cwd: data.cwd } : {}),
+        ...(typeof data.routeRemoteTools === "boolean" ? { routeRemoteTools: data.routeRemoteTools } : {}),
+        ...(Array.isArray(data.forwards) ? { forwards: data.forwards.filter((value): value is string => typeof value === "string") } : {}),
+      };
+    }
+    return undefined;
+  };
+
   const limitRemoteToolResult = (result: any, kind: "read" | "exec", startLine = 1, requestedMaxLines?: number) => {
     const limits = configuredOutputLimits();
     const configuredMaxBytes = kind === "read" ? limits.readMaxBytes : limits.execMaxBytes;
@@ -753,11 +948,11 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
     });
   };
 
-  const establish = async (parsed: ParsedSsh, password: string | undefined, cwd: string): Promise<RemoteState> => {
+  const establish = async (parsed: ParsedSsh, authentication: SshAuthentication, cwd: string): Promise<RemoteState> => {
     const key = `${parsed.host}:${parsed.port}`;
     const fingerprint = loadKnownHosts()[key];
     if (!fingerprint) throw new Error(`Host ${key} is not trusted; connect interactively with /remote first`);
-    const client = await connect(parsed, password, fingerprint);
+    const client = await connect(parsed, authentication, fingerprint);
     try {
       const cdCommand = cwd === FALLBACK_REMOTE_CWD ? "cd -- ~" : `cd -- ${quote(cwd)}`;
       const resolved = (await execRemote(client, `${cdCommand} && pwd -P`)).toString().trim();
@@ -772,15 +967,20 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
 
   async function reconnectRemote(): Promise<RemoteState> {
     if (reconnectPromise) return reconnectPromise;
+    const resumeRouting = remote ? routeRemoteTools : (credentialCache.resume?.routeRemoteTools ?? true);
     const source = remote ?? (credentialCache.resume ? { ...parseSshCommand(credentialCache.resume.command), cwd: credentialCache.resume.cwd } : null);
     if (!source) throw new Error("No SSH remote connection is available to reconnect");
     const parsed = parseSshCommand(source.command);
     const password = getCachedPassword(parsed);
     reconnectPromise = (async () => {
+      const authentication = parsed.identityFile
+        ? await privateKeyAuthentication(parsed)
+        : standardAuthentication(password);
       const oldClient = remote?.client;
-      const next = await establish(parsed, password, source.cwd);
+      const next = await establish(parsed, authentication, source.cwd);
       remote = next;
-      credentialCache.resume = { command: parsed.command, cwd: next.cwd };
+      routeRemoteTools = resumeRouting;
+      credentialCache.resume = { command: parsed.command, cwd: next.cwd, routeRemoteTools, forwards: credentialCache.resume?.forwards };
       oldClient?.end();
       if (currentCtx) {
         status(currentCtx);
@@ -791,7 +991,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
     return reconnectPromise;
   }
 
-  const withReconnect = async <T>(operation: (client: Client) => Promise<T>): Promise<T> => {
+  const withReconnect = async <T>(operation: (client: SshClient) => Promise<T>): Promise<T> => {
     if (!remote) throw new Error("SSH remote is not connected");
     try { return await operation(remote.client); }
     catch (error) {
@@ -810,9 +1010,10 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       `cd -- ${quote(remote!.cwd)} && ${targetCommand} && pwd -P`,
     ))).toString().trim();
     remote.cwd = resolved;
-    credentialCache.resume = { command: remote.command, cwd: resolved };
+    credentialCache.resume = { command: remote.command, cwd: resolved, routeRemoteTools, forwards: [...forwardSpecs.values()].map(serializeForward) };
     saveEndpointConfig(remote.command, { remoteCwd: resolved }, true);
     status(ctx);
+    persistSessionRemoteState();
     return resolved;
   };
 
@@ -856,33 +1057,38 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
     let password = getCachedPassword(parsed);
     ctx.ui.setStatus("ssh-remote", ctx.ui.theme.fg("warning", `SSH remote connecting ${endpointDisplayLabel(parsed)}…`));
     try {
+      let authentication = parsed.identityFile
+        ? await privateKeyAuthentication(parsed, ctx)
+        : standardAuthentication(password);
       let next: RemoteState;
       try {
-        next = await establish(parsed, password, cwd ?? configuredCwd(command));
+        next = await establish(parsed, authentication, cwd ?? configuredCwd(command));
       } catch (error) {
-        if (!/authentication methods failed|authentication failure/i.test((error as Error).message)) throw error;
+        if (parsed.identityFile || !/authentication methods failed|authentication failure/i.test((error as Error).message)) throw error;
         password = await askPassword(ctx) ?? undefined;
         if (!password) {
           lastConnectionError = "No SSH password was provided and SSH agent authentication failed";
           status(ctx);
           return null;
         }
-        next = await establish(parsed, password, cwd ?? configuredCwd(command));
+        authentication = standardAuthentication(password);
+        next = await establish(parsed, authentication, cwd ?? configuredCwd(command));
       }
       const previous = remote?.client;
       remote = next;
       routeRemoteTools = true;
       previous?.end();
-      if (password) setCachedPassword(parsed, password);
-      credentialCache.resume = { command, cwd: next.cwd };
+      if (!parsed.identityFile && password) setCachedPassword(parsed, password);
+      credentialCache.resume = { command, cwd: next.cwd, routeRemoteTools, forwards: [] };
       lastCommand = command;
       lastConnectionError = undefined;
       saveEndpointConfig(command, { remoteCwd: next.cwd }, true);
       status(ctx);
+      persistSessionRemoteState();
       ctx.ui.notify(`SSH remote connected: ${endpointDisplayLabel(next)}:${next.cwd}`, "info");
       return next;
     } catch (error) {
-      deleteCachedPassword(parsed);
+      if (!parsed.identityFile) deleteCachedPassword(parsed);
       remote = null;
       lastConnectionError = (error as Error).message;
       status(ctx);
@@ -895,7 +1101,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
     if (remote) return remote;
     if (credentialCache.resume) return reconnectRemote();
     const command = lastCommand || activeSshCommand();
-    if (!command) throw new Error("No SSH endpoint configured; use /remote ssh USER@HOST -p PORT");
+    if (!command) throw new Error("No SSH endpoint configured; use /remote ssh USER@HOST -p PORT [-i KEY]");
     const state = await connectInteractive(command, ctx, configuredCwd(command));
     if (!state) throw new Error("SSH remote connection was cancelled or failed");
     return state;
@@ -922,33 +1128,54 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       });
     });
     forwardServers.set(spec.localPort, server);
+    forwardSpecs.set(spec.localPort, spec);
   };
 
   const stopForwards = async (): Promise<void> => {
     const servers = [...forwardServers.values()];
     forwardServers.clear();
+    forwardSpecs.clear();
     await Promise.all(servers.map((server) => new Promise<void>((resolve) => server.close(() => resolve()))));
   };
 
-  const disconnect = (ctx: any, forgetPassword = false) => {
+  const restoreSessionRemoteState = async (saved: SessionRemoteState, ctx: any): Promise<void> => {
+    if (!saved.connected) {
+      credentialCache.resume = undefined;
+      status(ctx);
+      return;
+    }
+    const command = saved.command!;
+    const next = await connectInteractive(command, ctx, saved.cwd);
+    if (!next) throw new Error(lastConnectionError || "SSH remote session restore was cancelled or failed");
+    routeRemoteTools = saved.routeRemoteTools ?? true;
+    const specs = (saved.forwards ?? []).map(parseForwardSpec);
+    for (const spec of specs) await startForward(spec);
+    credentialCache.resume = { command, cwd: next.cwd, routeRemoteTools, forwards: [...forwardSpecs.values()].map(serializeForward) };
+    status(ctx);
+  };
+
+  const disconnect = (ctx: any, forgetCredentials = false) => {
     const previous = remote;
     remote = null;
     routeRemoteTools = false;
     reconnectPromise = null;
     credentialCache.resume = undefined;
     void stopForwards();
-    if (forgetPassword) {
-      if (previous) deleteCachedPassword(previous);
-      else {
-        const configured = activeSshCommand();
-        if (configured) {
-          try { deleteCachedPassword(parseSshCommand(configured)); } catch {}
-        }
+    if (forgetCredentials) {
+      const configured = previous ?? (() => {
+        const command = activeSshCommand();
+        if (!command) return undefined;
+        try { return parseSshCommand(command); } catch { return undefined; }
+      })();
+      if (configured) {
+        deleteCachedPassword(configured);
+        deleteCachedKeyPassphrase(configured);
       }
     }
     previous?.client.end();
     status(ctx);
-    ctx.ui.notify(forgetPassword ? "SSH remote disconnected and cached password cleared" : "SSH remote mode disabled (password remains cached in memory only)", "info");
+    persistSessionRemoteState();
+    ctx.ui.notify(forgetCredentials ? "SSH remote disconnected and cached credentials cleared" : "SSH remote mode disabled (credentials remain cached in memory only)", "info");
   };
 
   const detectRemoteMimeType = async (path: string): Promise<string | undefined> => {
@@ -1065,22 +1292,22 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
   });
 
   pi.registerTool({
-    name: "ssh_remote_control",
-    label: "SSH Remote Control",
-    description: "Connect, reconnect, annotate endpoints, manage server-specific memory, change the persistent remote working directory, inspect, forward ports, run remote SSH commands, or disconnect the configured SSH environment. Exec output is streamed to bounded buffers; model output defaults to the last 200 lines or 8KB, while complete oversized output is saved locally. Passwords are never accepted as arguments and are cached only in process memory.",
+    name: "remote",
+    label: "Remote",
+    description: "Connect, reconnect, annotate endpoints, manage server-specific memory, change the persistent remote working directory, inspect, forward ports, run remote SSH commands, or disconnect the configured SSH environment. Connections support SSH agent, password, or an explicit local private key with -i. Exec output is streamed to bounded buffers; model output defaults to the last 200 lines or 8KB, while complete oversized output is saved locally. Passwords and key passphrases are never accepted as arguments and are cached only in process memory.",
     promptSnippet: "Control the configured remote SSH connection, endpoint note and memory, working directory, and local port forwarding",
     promptGuidelines: [
-      "Use ssh_remote_control when the user asks the agent to enter, reconnect, inspect, or leave a remote SSH environment.",
-      "Use ssh_remote_control with action chdir when the user asks to change the remote working directory; do not emulate a persistent directory change with action exec and a one-command cwd.",
-      `Always set timeout for ssh_remote_control remote exec commands; it defaults to ${DEFAULT_REMOTE_TIMEOUT_SECONDS} seconds when omitted.`,
-      "Keep ssh_remote_control exec output narrow with tail, sed, rg limits, or similarly bounded commands; never cat large logs or emit broad file listings.",
-      "Use ssh_remote_control with action disconnect after remote work when the user asks to return to the local environment.",
+      "Use remote when the user asks the agent to enter, reconnect, inspect, or leave a remote SSH environment.",
+      "Use remote with action chdir when the user asks to change the remote working directory; do not emulate a persistent directory change with action exec and a one-command cwd.",
+      `Always set timeout for remote exec commands; it defaults to ${DEFAULT_REMOTE_TIMEOUT_SECONDS} seconds when omitted.`,
+      "Keep remote exec output narrow with tail, sed, rg limits, or similarly bounded commands; never cat large logs or emit broad file listings.",
+      "Use remote with action disconnect after remote work when the user asks to return to the local environment.",
     ],
     parameters: Type.Object({
       action: StringEnum(["connect", "reconnect", "status", "disconnect", "forget", "forward", "unforward", "exec", "chdir", "note", "memory"] as const),
-      command: Type.Optional(Type.String({ description: "SSH command for connect, such as ssh root@host -p 22; optionally selects the endpoint for note or memory" })),
+      command: Type.Optional(Type.String({ description: "SSH command for connect, such as ssh root@host -p 22 or ssh -i ~/.ssh/id_ed25519 root@host; optionally selects the endpoint for note or memory" })),
       note: Type.Optional(Type.String({ description: "Endpoint note for the note action; omit or use an empty string to clear it" })),
-      memory: Type.Optional(Type.String({ description: "Persistent server-specific context for the memory action; omit or use an empty string to clear it" })),
+      memory: Type.Optional(Type.String({ description: "Persistent context shared by the endpoint's user@host across SSH ports; omit or use an empty string to clear it" })),
       cwd: Type.Optional(Type.String({ description: "Remote working directory; required for chdir, and a one-command override for exec" })),
       forwards: Type.Optional(Type.String({ description: "Space-separated LOCAL_PORT:REMOTE_HOST:REMOTE_PORT mappings; defaults to ssh-remote-config.json" })),
       remoteCommand: Type.Optional(Type.String({ description: "Remote shell command for the exec action" })),
@@ -1095,7 +1322,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       }
       if (params.action === "disconnect" || params.action === "forget") {
         disconnect(ctx, params.action === "forget");
-        return { content: [{ type: "text", text: params.action === "forget" ? "Disconnected and forgot the cached password." : "Disconnected from SSH remote and returned to local tools." }], details: { connected: false } };
+        return { content: [{ type: "text", text: params.action === "forget" ? "Disconnected and forgot the cached credentials." : "Disconnected from SSH remote and returned to local tools." }], details: { connected: false } };
       }
       if (params.action === "reconnect") {
         if (!remote && !credentialCache.resume) throw new Error("No SSH remote connection is available to reconnect");
@@ -1104,6 +1331,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       }
       if (params.action === "unforward") {
         await stopForwards();
+        persistSessionRemoteState();
         return { content: [{ type: "text", text: "Closed all extension-managed SSH port forwards." }], details: { forwardedPorts: [] } };
       }
       if (params.action === "forward") {
@@ -1113,7 +1341,9 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
         const specs = values.map(parseForwardSpec);
         for (const spec of specs) await startForward(spec);
         routeRemoteTools = false;
+        credentialCache.resume = { command: state.command, cwd: state.cwd, routeRemoteTools, forwards: [...forwardSpecs.values()].map(serializeForward) };
         if (currentCtx) status(currentCtx);
+        persistSessionRemoteState();
         const ports = specs.map((spec) => spec.localPort);
         return { content: [{ type: "text", text: `Forwarded local ports: ${ports.join(", ")}; tools remain local.` }], details: { toolRouting: "local", forwardedPorts: ports } };
       }
@@ -1137,10 +1367,11 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
           };
         }
         const memory = params.memory?.trim() || undefined;
-        saveEndpointConfig(command, { memory });
+        const server = serverMemoryId(parseSshCommand(command));
+        saveServerMemory(command, memory);
         return {
-          content: [{ type: "text", text: memory ? `SSH remote server memory updated (${label}). It will be injected while this endpoint is the active remote workspace.` : `SSH remote server memory cleared (${label}).` }],
-          details: { endpoint: label, memory },
+          content: [{ type: "text", text: memory ? `SSH remote server memory updated (${server}). It applies to every port for this user and host.` : `SSH remote server memory cleared (${server}).` }],
+          details: { endpoint: label, server, memory },
         };
       }
       if (params.action === "exec") {
@@ -1187,7 +1418,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
   });
 
   pi.registerCommand("remote", {
-    description: "Connect over SSH and manage endpoints: /remote | ssh USER@HOST [-p PORT] | config | use USER@HOST:PORT | config note TEXT|--clear | config memory TEXT|--clear | config cwd PATH | config display-lines N | config read-max-lines|read-max-bytes|exec-max-lines|exec-max-bytes|turn-max-bytes N | forward [MAPPINGS] | unforward | exec [--timeout SECONDS] [--lines N] COMMAND | cd PATH | status | reload | off | forget",
+    description: "Connect over SSH and manage endpoints: /remote | ssh USER@HOST [-p PORT] [-i KEY] | config | use USER@HOST:PORT | config note TEXT|--clear | config memory TEXT|--clear | config cwd PATH | config display-lines N | config read-max-lines|read-max-bytes|exec-max-lines|exec-max-bytes|turn-max-bytes N | forward [MAPPINGS] | unforward | exec [--timeout SECONDS] [--lines N] COMMAND | cd PATH | status | reload | off | forget",
     handler: async (args, ctx) => {
       const input = args.trim().replace(/^\/?remote(?:\s+|$)/i, "").trim();
       const action = input.toLowerCase();
@@ -1195,7 +1426,9 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
         const config = loadRemoteConfig();
         const rows = Object.entries(config.endpoints ?? {}).map(([key, endpoint]) => {
           const active = key === config.activeEndpoint ? "*" : " ";
-          return `${active} ${key}\n    note: ${endpoint.note || "none"}\n    memory: ${endpoint.memory || "none"}\n    SSH: ${endpoint.sshCommand}\n    cwd: ${endpoint.remoteCwd || FALLBACK_REMOTE_CWD}\n    forward: ${endpoint.forwards?.join(", ") || "none"}`;
+          const command = endpoint.sshCommand || commandFromEndpointKey(key);
+          const memory = command ? endpointMemory(parseSshCommand(command), config) : undefined;
+          return `${active} ${key}\n    note: ${endpoint.note || "none"}\n    memory: ${memory || "none"}\n    SSH: ${endpoint.sshCommand}\n    cwd: ${endpoint.remoteCwd || FALLBACK_REMOTE_CWD}\n    forward: ${endpoint.forwards?.join(", ") || "none"}`;
         });
         const limits = configuredOutputLimits(config);
         ctx.ui.notify(`SSH remote configuration: ${REMOTE_CONFIG_FILE}\nDisplay lines: ${configuredDisplayLines(config)}\nRead output: ${limits.readMaxLines} lines / ${formatSize(limits.readMaxBytes)}\nExec output: ${limits.execMaxLines} lines / ${formatSize(limits.execMaxBytes)}\nPer-turn output: ${formatSize(limits.turnMaxBytes)}\n${rows.join("\n") || "No saved endpoints"}`, "info");
@@ -1231,6 +1464,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
           previous.client.end();
           await stopForwards();
           status(ctx);
+          persistSessionRemoteState();
         }
         saveRemoteConfig({ ...config, activeEndpoint: key });
         lastCommand = command;
@@ -1254,8 +1488,9 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
         const command = lastCommand || activeSshCommand();
         if (!command) { ctx.ui.notify("Configure an SSH endpoint first", "error"); return; }
         const memory = value.toLowerCase() === "--clear" ? undefined : value;
-        saveEndpointConfig(command, { memory });
-        ctx.ui.notify(memory ? `SSH remote server memory updated (${parseSshCommand(command).label}); it will be injected while connected` : `SSH remote server memory cleared (${parseSshCommand(command).label})`, "info");
+        const server = serverMemoryId(parseSshCommand(command));
+        saveServerMemory(command, memory);
+        ctx.ui.notify(memory ? `SSH remote server memory updated (${server}); it applies to every port` : `SSH remote server memory cleared (${server})`, "info");
         return;
       }
       if (/^config\s+display-lines\s+/i.test(input)) {
@@ -1309,13 +1544,16 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
           const specs = values.map(parseForwardSpec);
           for (const spec of specs) await startForward(spec);
           routeRemoteTools = false;
+          credentialCache.resume = { command: state.command, cwd: state.cwd, routeRemoteTools, forwards: [...forwardSpecs.values()].map(serializeForward) };
           status(ctx);
+          persistSessionRemoteState();
           ctx.ui.notify(`SSH remote port forwarding started; tools remain local in ${localCwd}: ${specs.map((spec) => `127.0.0.1:${spec.localPort}`).join(", ")}`, "info");
         } catch (error) { ctx.ui.notify(`SSH remote port forwarding failed: ${(error as Error).message}`, "error"); }
         return;
       }
       if (action === "unforward") {
         await stopForwards();
+        persistSessionRemoteState();
         ctx.ui.notify("Closed all extension-managed SSH remote port forwards", "info");
         return;
       }
@@ -1378,19 +1616,50 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
   pi.on("turn_start", () => { turnOutputBytes = 0; });
   pi.on("session_start", async (event, ctx) => {
     currentCtx = ctx;
+    sessionReady = true;
     status(ctx);
-    if (event.reason === "reload" && credentialCache.resume) {
-      try { await reconnectRemote(); }
-      catch (error) { ctx.ui.notify(`SSH remote automatic login after reload failed: ${(error as Error).message}`, "error"); }
+    const saved = loadSessionRemoteState(ctx);
+    const canInheritCurrent = event.reason === "reload" || event.reason === "new" || event.reason === "fork";
+    const inherited = !saved && canInheritCurrent && credentialCache.resume ? credentialCache.resume : undefined;
+    const target: SessionRemoteState | undefined = saved ?? (inherited ? {
+      version: 1,
+      connected: true,
+      command: inherited.command,
+      cwd: inherited.cwd,
+      routeRemoteTools: inherited.routeRemoteTools,
+      forwards: inherited.forwards ?? [],
+    } : undefined);
+    if (!target) {
+      credentialCache.resume = undefined;
+      return;
+    }
+    restoringSessionState = true;
+    try {
+      await restoreSessionRemoteState(target, ctx);
+    } catch (error) {
+      ctx.ui.notify(`SSH remote session restore failed: ${(error as Error).message}`, "error");
+    } finally {
+      restoringSessionState = false;
     }
+    if (inherited && remote) persistSessionRemoteState();
   });
-  pi.on("session_shutdown", (event) => {
+  pi.on("session_shutdown", async (event) => {
+    sessionReady = false;
     const previous = remote;
+    const preserveConnection = event.reason === "reload" || event.reason === "new" || event.reason === "fork";
+    if (previous && preserveConnection) {
+      credentialCache.resume = {
+        command: previous.command,
+        cwd: previous.cwd,
+        routeRemoteTools,
+        forwards: [...forwardSpecs.values()].map(serializeForward),
+      };
+    }
     remote = null;
     routeRemoteTools = false;
-    void stopForwards();
+    await stopForwards();
     previous?.client.end();
-    if (event.reason !== "reload") credentialCache.resume = undefined;
+    if (!preserveConnection) credentialCache.resume = undefined;
   });
   pi.on("user_bash", async (event, ctx) => {
     if (!remote || !routeRemoteTools) return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ssh-remote",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Persistent remote SSH workspaces for Pi.",
   "type": "module",
   "author": "Yutong Bian",