pi-ssh-remote 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -18,6 +18,37 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Rel
 
 - None.
 
+## [0.1.12] - 2026-08-25
+
+### Added
+
+- None.
+
+### Changed
+
+- Simplified the server-memory documentation to focus on adding, listing, updating, and deleting entries without exposing implementation details.
+
+### Fixed
+
+- Prevented follow-up SSH client errors during a connection loss before handshake from becoming an uncaught exception that exits Pi.
+
+## [0.1.11] - 2026-08-16
+
+### Added
+
+- Added per-`user@host` server-memory JSON files with stable `id` and `content` entries, plus automatic migration from legacy string memories.
+- Added a local-path exception so Pi's normal `read`, `edit`, and `write` tools can manage the active server's memory file while other operations remain routed over SSH.
+- Added `/remote memory` to display the current server's memory entries, IDs, and JSON file path.
+
+### Changed
+
+- Replaced agent-side append/clear memory mutations with prompt-guided entry-level CRUD on the JSON file. Deletion instructions now require an explicit user request, an exact entry ID, and preservation of unrelated entries.
+- Removed `/remote config memory`; the dedicated `/remote memory` command now handles display, while the `remote` tool's `memory` action locates and inspects the JSON file.
+
+### Fixed
+
+- None.
+
 ## [0.1.10] - 2026-08-16
 
 ### Added
@@ -189,7 +220,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.10...HEAD
+[Unreleased]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.12...HEAD
+[0.1.12]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.11...v0.1.12
+[0.1.11]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.10...v0.1.11
 [0.1.10]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.9...v0.1.10
 [0.1.9]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.8...v0.1.9
 [0.1.8]: https://github.com/petrichor20211/pi-ssh-remote/compare/v0.1.7...v0.1.8

package/README.md

@@ -31,7 +31,7 @@ The extension exposes `remote` for the agent and `/remote` for the user. You can
 
 ### Stateful endpoints instead of disposable SSH commands
 
-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.
+Each `user@host:port` endpoint remembers its remote working directory, note, 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.
 
 ### Resilient and bounded by default
 
@@ -66,7 +66,6 @@ Requires Node.js 20+. The remote server must provide Bash, SFTP, and GNU `timeou
 /remote ssh root@gpu-box.example.com -p 2202
 /remote cd /srv/project
 /remote config note H100 training server
-/remote config memory Use /opt/conda/bin/python and never stop shared jobs.
 /remote status
 ```
 
@@ -82,6 +81,29 @@ Return to local tools with:
 /remote off
 ```
 
+### Server memory
+
+Tell Pi what to remember for the current server:
+
+```text
+Remember for this server: use /opt/conda/bin/python and never stop shared jobs.
+```
+
+List saved entries and their IDs:
+
+```text
+/remote memory
+```
+
+Use an ID to update or delete an entry:
+
+```text
+Update memory deploy-command to use /opt/deploy/v2/run.sh.
+Delete memory obsolete-proxy-rule.
+```
+
+Pi automatically applies saved memory when you work on that server. Deletion only happens when you explicitly request it.
+
 ### Private key authentication
 
 Pass an explicit local private key with `-i`:
@@ -131,7 +153,7 @@ The default foreground timeout prevents an accidental long-running command from
 /remote
 ```
 
-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.
+Endpoint notes and working directories survive Pi restarts and remain separate for each saved endpoint.
 
 ### 4. Expose a remote service while editing locally
 
@@ -164,8 +186,6 @@ 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 `remote` tool; slash commands are optional. For safety, calling its `memory` action without a `memory` argument only reads the current server memory. Non-empty text is appended to the existing memory instead of replacing it; retrying the same final entry is a no-op. Clearing still requires the explicit `--clear` value.
-
 ## Command reference
 
 | Command | Purpose |
@@ -176,8 +196,7 @@ These requests are handled through the agent-facing `remote` tool; slash command
 | `/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 for the current `user@host`, shared across ports |
-| `/remote config memory --clear` | Clear the current `user@host` memory |
+| `/remote memory` | List the current server's memory entries and IDs |
 | `/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` |
@@ -205,7 +224,7 @@ Endpoint configuration is stored locally in:
 ~/.pi/agent/ssh-remote-config.json
 ```
 
-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.
+Saved global values include endpoints, active endpoint, notes, 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. 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.
 
@@ -215,13 +234,13 @@ The extension currently supports direct SSH commands with `-p`, `-l`, and `-i`.
 
 ## Releases
 
-Latest release: [v0.1.10](https://github.com/petrichor20211/pi-ssh-remote/releases/tag/v0.1.10)
+Latest release: [v0.1.12](https://github.com/petrichor20211/pi-ssh-remote/releases/tag/v0.1.12)
 
 | Version | Date | Highlights |
 |---|---|---|
+| [0.1.12](CHANGELOG.md#0112---2026-08-25) | 2026-08-25 | Safe handling of repeated SSH errors when a connection is lost during handshake |
+| [0.1.11](CHANGELOG.md#0111---2026-08-16) | 2026-08-16 | JSON memory entries, prompt-guided CRUD, and `/remote memory` listing |
 | [0.1.10](CHANGELOG.md#0110---2026-08-16) | 2026-08-16 | Safe inspect-by-default and append-only agent updates for server memory |
-| [0.1.9](CHANGELOG.md#019---2026-08-12) | 2026-08-12 | Stable deduplicated server-memory context and shorter footer labels |
-| [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 |
 
 See [CHANGELOG.md](CHANGELOG.md) for the complete release history, including additions, behavior changes, and bug fixes.
 

package/README.zh-CN.md

@@ -54,7 +54,7 @@ H100 训练机 (root@gpu-box.example.com:2202):/srv/project
 - 服务器特定记忆；
 - 端口转发配置。
 
-例如可以把几台机器分别备注为 `8xH100 训练机`、`预发布环境`、`线上只读机`。服务器记忆按 `user@host` 保存，例如指定 Python 环境、共享任务保护规则或部署约定；同一用户和主机即使通过不同 SSH 端口连接，也会使用同一份记忆。连接匹配的 endpoint 并启用远端工具路由后，这段记忆会自动注入模型上下文；断开连接或切换到纯隧道模式后，后续请求不再注入。所有配置保存在本地，重启 Pi 后仍然存在。
+例如可以把几台机器分别备注为 `8xH100 训练机`、`预发布环境`、`线上只读机`。这些配置保存在本地，重启 Pi 后仍然存在。
 
 ### 断线后可以自动恢复
 
@@ -107,7 +107,6 @@ pi install npm:pi-ssh-remote
 ```text
 /remote cd /srv/project
 /remote config note H100 训练机
-/remote config memory 使用 /opt/conda/bin/python，不要停止其他用户的共享任务。
 ```
 
 查看当前状态：
@@ -124,6 +123,29 @@ pi install npm:pi-ssh-remote
 /remote off
 ```
 
+### 服务器记忆
+
+直接告诉 Pi 要为当前服务器记住什么：
+
+```text
+记住这台服务器使用 /opt/conda/bin/python，不要停止共享任务。
+```
+
+查看已有记忆和 ID：
+
+```text
+/remote memory
+```
+
+通过 ID 修改或删除：
+
+```text
+把记忆 deploy-command 改为使用 /opt/deploy/v2/run.sh。
+删除记忆 obsolete-proxy-rule。
+```
+
+以后连接这台服务器时，Pi 会自动使用这些记忆。只有明确要求删除时才会删除。
+
 ### 使用私钥文件登录
 
 通过 `-i` 指定本地私钥：
@@ -183,7 +205,7 @@ pi install npm:pi-ssh-remote
 /remote
 ```
 
-备注和默认目录会按 `user@host:port` 分别保存，不会互相覆盖；服务器记忆则按 `user@host` 共享，不受端口影响。
+备注和默认目录会按 `user@host:port` 分别保存，不会互相覆盖。
 
 ### 4. 远端启动模型，本地开发界面
 
@@ -218,8 +240,6 @@ pi install npm:pi-ssh-remote
 把远端 8000 端口转发到本地 8000，但代码工具继续留在本地。
 ```
 
-Pi 会通过插件提供的 `remote` 工具完成这些操作。为防止误删，调用 `memory` action 但不传 `memory` 参数时只会读取当前服务器记忆；传入非空内容时会追加到现有记忆，而不是覆盖，重复提交相同的末尾内容不会再次追加；清除时仍必须显式传入 `--clear`。
-
 ## 命令说明
 
 | 命令 | 作用 |
@@ -230,8 +250,7 @@ Pi 会通过插件提供的 `remote` 工具完成这些操作。为防止误删
 | `/remote use USER@HOST:PORT` | 切换到指定服务器 |
 | `/remote config note TEXT` | 给当前服务器添加或修改备注 |
 | `/remote config note --clear` | 清除当前服务器备注 |
-| `/remote config memory TEXT` | 保存当前 `user@host` 的记忆，并在不同端口间共享 |
-| `/remote config memory --clear` | 清除当前 `user@host` 的记忆 |
+| `/remote memory` | 展示当前服务器的记忆条目和 ID |
 | `/remote config cwd PATH` | 设置默认远程工作目录 |
 | `/remote cd PATH` | 切换当前远程目录并保存 |
 | `/remote config forward MAPPING...` | 保存端口转发配置，例如 `7860:127.0.0.1:7860` |
@@ -264,14 +283,13 @@ Pi 会通过插件提供的 `remote` 工具完成这些操作。为防止误删
 - 已保存的服务器；
 - 当前选中的服务器；
 - 服务器备注；
-- 服务器特定记忆；
 - 默认远程目录；
 - 端口转发配置；
 - 私钥文件路径；
 - 命令预览设置；
 - 模型输出预算。
 
-此外，每个 Pi session 都会记录不含凭据的 SSH 工作区元数据，用于在 `/resume` 时恢复该历史 session 对应的服务器环境。服务器记忆按 `user@host` 识别，不受 SSH 端口影响。它是由用户在本地配置的可信上下文，不会从远程服务器自动读取；仅当匹配的 endpoint 作为远端工作区启用时才会加入每次模型请求。
+此外，每个 Pi session 都会记录不含凭据的 SSH 工作区元数据，用于在 `/resume` 时恢复该历史 session 对应的服务器环境。
 
 私钥内容、密码和密钥 passphrase 都不会写入配置文件。插件仅在连接时从本地读取私钥；手动输入的密码和 passphrase 只会缓存在当前 Pi 进程的内存中。
 
@@ -294,13 +312,13 @@ Pi 会通过插件提供的 `remote` 工具完成这些操作。为防止误删
 
 ## 版本发布
 
-最新版本：[v0.1.10](https://github.com/petrichor20211/pi-ssh-remote/releases/tag/v0.1.10)
+最新版本：[v0.1.12](https://github.com/petrichor20211/pi-ssh-remote/releases/tag/v0.1.12)
 
 | 版本 | 日期 | 主要内容 |
 |---|---|---|
+| [0.1.12](CHANGELOG.md#0112---2026-08-25) | 2026-08-25 | 安全处理 SSH 握手期间断线所触发的连续错误 |
+| [0.1.11](CHANGELOG.md#0111---2026-08-16) | 2026-08-16 | JSON 记忆条目、Prompt 引导增删查改与 `/remote memory` 展示命令 |
 | [0.1.10](CHANGELOG.md#0110---2026-08-16) | 2026-08-16 | 默认安全读取且仅追加的服务器记忆 agent 更新逻辑 |
-| [0.1.9](CHANGELOG.md#019---2026-08-12) | 2026-08-12 | 稳定且去重的服务器记忆上下文与更短的状态栏标签 |
-| [0.1.8](CHANGELOG.md#018---2026-08-10) | 2026-08-10 | 显式私钥登录、跨端口服务器记忆与更短的 `remote` 工具名 |
 
 完整的新增内容、行为变更和 Bug 修复记录请查看 [CHANGELOG.md](CHANGELOG.md)。
 

package/index.ts

@@ -7,8 +7,8 @@
  */
 
 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 { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
 import { createServer, type Server, type Socket } from "node:net";
 import { tmpdir } from "node:os";
 import { Type } from "typebox";
@@ -64,9 +64,20 @@ interface RemoteEndpointConfig {
   memory?: string;
 }
 
+interface ServerMemoryEntry {
+  id: string;
+  content: string;
+}
+
+interface ServerMemoryFile {
+  server: string;
+  entries: ServerMemoryEntry[];
+}
+
 interface RemoteConfig {
   activeEndpoint?: string;
   endpoints?: Record<string, RemoteEndpointConfig>;
+  /** Legacy values migrated into per-server JSON files at extension startup. */
   serverMemories?: Record<string, string>;
   displayLines?: number;
   readMaxLines?: number;
@@ -98,6 +109,7 @@ interface SessionRemoteState {
 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");
+const SERVER_MEMORY_DIR = join(AGENT_DIR, "ssh-remote-memories");
 const FALLBACK_REMOTE_CWD = "~";
 const DEFAULT_DISPLAY_LINES = 5;
 const MAX_DISPLAY_LINES = 50;
@@ -412,21 +424,103 @@ function endpointDisplayLabel(endpoint: ParsedSsh, config = loadRemoteConfig()):
   return note ? `${note} (${endpoint.label})` : endpoint.label;
 }
 
-function endpointMemory(endpoint: ParsedSsh, config = loadRemoteConfig()): string | undefined {
-  return config.serverMemories?.[serverMemoryId(endpoint)]?.trim() || undefined;
+function serverMemoryFilePath(endpoint: ParsedSsh | string): string {
+  const server = typeof endpoint === "string" ? endpoint : serverMemoryId(endpoint);
+  return join(SERVER_MEMORY_DIR, `${Buffer.from(server, "utf8").toString("base64url")}.json`);
+}
+
+function legacyMemoryEntries(memory: string): ServerMemoryEntry[] {
+  return memory
+    .trim()
+    .split(/\n\s*\n/)
+    .map((content) => content.trim())
+    .filter(Boolean)
+    .map((content, index) => ({ id: `legacy-${String(index + 1).padStart(3, "0")}`, content }));
+}
+
+function writeServerMemoryFile(path: string, memory: ServerMemoryFile): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(memory, null, 2) + "\n", { mode: 0o600 });
+}
+
+function migrateLegacyServerMemories(): void {
+  const config = loadRemoteConfig();
+  const legacy = config.serverMemories ?? {};
+  if (!Object.keys(legacy).length) {
+    mkdirSync(SERVER_MEMORY_DIR, { recursive: true });
+    return;
+  }
+
+  const remaining = { ...legacy };
+  let changed = false;
+  for (const [server, content] of Object.entries(legacy)) {
+    const path = serverMemoryFilePath(server);
+    try {
+      if (!existsSync(path)) {
+        writeServerMemoryFile(path, { server, entries: legacyMemoryEntries(content) });
+      }
+      delete remaining[server];
+      changed = true;
+    } catch {}
+  }
+  if (changed) saveRemoteConfig({ ...config, serverMemories: remaining });
+}
+
+function ensureServerMemoryFile(endpoint: ParsedSsh): string {
+  const path = serverMemoryFilePath(endpoint);
+  if (!existsSync(path)) writeServerMemoryFile(path, { server: serverMemoryId(endpoint), entries: [] });
+  return path;
+}
+
+function loadServerMemory(endpoint: ParsedSsh): ServerMemoryFile | undefined {
+  const path = serverMemoryFilePath(endpoint);
+  if (!existsSync(path)) return undefined;
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<ServerMemoryFile>;
+  if (parsed.server !== serverMemoryId(endpoint) || !Array.isArray(parsed.entries)) {
+    throw new Error("expected an object with the matching server and an entries array");
+  }
+  const ids = new Set<string>();
+  const entries = parsed.entries.map((entry, index) => {
+    if (!entry || typeof entry.id !== "string" || !entry.id.trim() || typeof entry.content !== "string" || !entry.content.trim()) {
+      throw new Error(`entry ${index + 1} must contain non-empty string id and content fields`);
+    }
+    const id = entry.id.trim();
+    if (ids.has(id)) throw new Error(`duplicate entry id: ${id}`);
+    ids.add(id);
+    return { id, content: entry.content.trim() };
+  });
+  return { server: parsed.server, entries };
+}
+
+function formatServerMemoryEntries(memory: ServerMemoryFile | undefined): string {
+  if (!memory?.entries.length) return "No entries.";
+  return memory.entries.map((entry) => `[${entry.id}]\n${entry.content}`).join("\n\n");
+}
+
+function memoryManagementPrompt(remote: RemoteState): string {
+  let path = serverMemoryFilePath(remote);
+  try { path = ensureServerMemoryFile(remote); }
+  catch {}
+  return `Persistent memory for this SSH server is a local JSON file at ${path}. This exact path is always handled by Pi's local read, write, and edit tools even while other tools are routed over SSH. The file schema is {"server":"${serverMemoryId(remote)}","entries":[{"id":"stable-unique-id","content":"memory text"}]}. If the file does not exist, create it with that server value and an empty entries array. Read the file before changing it and preserve valid JSON plus all unrelated entries. Add by appending one object with a unique stable id; query by reading the file; update by editing only the matching id. DELETE SAFETY: delete an entry only when the user explicitly asks to delete, remove, or forget server memory. Before deleting, read the file and identify the exact id; if the target is ambiguous, ask the user. Use edit to remove only that exact object and preserve every other entry. Never treat a correction or replacement request as permission to delete, and never delete all entries unless the user explicitly requests deletion of all server memory.`;
 }
 
 function remoteSystemPrompt(systemPrompt: string, localCwd: string, remote: RemoteState): string {
-  return systemPrompt.replace(
+  const workspacePrompt = 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 remote 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, except for the explicitly identified local server-memory JSON file. Use remote with action disconnect to return to the local environment when requested.`,
   );
+  return `${workspacePrompt}\n\n${memoryManagementPrompt(remote)}`;
 }
 
 function serverMemoryContext(remote: RemoteState): string | undefined {
-  const memory = endpointMemory(remote);
-  if (!memory) return undefined;
-  return `<ssh_remote_server_memory endpoint="${remote.label}">\nThe following is user-configured, persistent memory specific to this SSH server. Apply it while working on this server:\n${memory}\n</ssh_remote_server_memory>`;
+  const path = serverMemoryFilePath(remote);
+  let memory: ServerMemoryFile | undefined;
+  try { memory = loadServerMemory(remote); }
+  catch (error) {
+    return `<ssh_remote_server_memory endpoint="${remote.label}" path="${path}">\nThe server-memory JSON file is invalid and must not be applied until repaired: ${(error as Error).message}\n</ssh_remote_server_memory>`;
+  }
+  if (!memory?.entries.length) return undefined;
+  return `<ssh_remote_server_memory endpoint="${remote.label}" path="${path}">\nThe following user-configured JSON entries are persistent memory specific to this SSH server. Apply their content while working on this server:\n${JSON.stringify(memory.entries, null, 2)}\n</ssh_remote_server_memory>`;
 }
 
 function saveEndpointConfig(command: string, updates: RemoteEndpointConfig, makeActive = false): void {
@@ -442,23 +536,6 @@ 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")); }
@@ -649,7 +726,11 @@ function connect(config: ParsedSsh, authentication: SshAuthentication, fingerpri
       hostVerifier: (hash) => hash === fingerprint,
     };
     client.once("ready", () => resolve(client));
-    client.once("error", reject);
+    // ssh2 may emit a socket error followed by a protocol error while a
+    // connection is lost during handshake. Keep consuming client errors after
+    // the first one so EventEmitter does not turn the follow-up into an
+    // uncaught exception; rejecting an already-settled promise is a no-op.
+    client.on("error", reject);
     client.connect(options);
   });
 }
@@ -782,6 +863,8 @@ async function askPassword(ctx: any): Promise<string | null> {
 }
 
 export default function sshRemoteExtension(pi: ExtensionAPI) {
+  migrateLegacyServerMemories();
+
   const localCwd = process.cwd();
   let remote: RemoteState | null = null;
   let routeRemoteTools = false;
@@ -1270,16 +1353,20 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
   const localWrite = createWriteTool(localCwd);
   const localEdit = createEditTool(localCwd);
   const localBash = createBashTool(localCwd);
+  const targetsLocalServerMemory = (path: unknown): boolean => {
+    if (!remote || typeof path !== "string") return false;
+    return resolve(path.replace(/^@/, "")) === serverMemoryFilePath(remote);
+  };
   pi.registerTool({
     ...localRead,
     description: `Read file contents. Remote text reads fetch only the requested range and return at most ${DEFAULT_READ_MAX_LINES} lines or ${formatSize(DEFAULT_READ_MAX_BYTES)} by default; use offset/limit to continue.`,
     promptGuidelines: ["Use read with offset/limit for remote code and logs; inspect large files in focused chunks instead of reading them wholesale."],
-    execute: (id, params, signal, update) => remote && routeRemoteTools
+    execute: (id, params, signal, update) => remote && routeRemoteTools && !targetsLocalServerMemory(params.path)
       ? executeRemoteRead(id, params, signal, update)
       : localRead.execute(id, params, signal, update),
   });
-  pi.registerTool({ ...localWrite, execute: (id, params, signal, update) => remote && routeRemoteTools ? createWriteTool(localCwd, { operations: remoteWriteOps() }).execute(id, params, signal, update) : localWrite.execute(id, params, signal, update) });
-  pi.registerTool({ ...localEdit, execute: (id, params, signal, update) => remote && routeRemoteTools ? createEditTool(localCwd, { operations: remoteEditOps() }).execute(id, params, signal, update) : localEdit.execute(id, params, signal, update) });
+  pi.registerTool({ ...localWrite, execute: (id, params, signal, update) => remote && routeRemoteTools && !targetsLocalServerMemory(params.path) ? createWriteTool(localCwd, { operations: remoteWriteOps() }).execute(id, params, signal, update) : localWrite.execute(id, params, signal, update) });
+  pi.registerTool({ ...localEdit, execute: (id, params, signal, update) => remote && routeRemoteTools && !targetsLocalServerMemory(params.path) ? createEditTool(localCwd, { operations: remoteEditOps() }).execute(id, params, signal, update) : localEdit.execute(id, params, signal, update) });
   pi.registerTool({
     ...localBash,
     description: `Execute a shell command. Remote model-facing output returns at most the last ${DEFAULT_EXEC_MAX_LINES} lines or ${formatSize(DEFAULT_EXEC_MAX_BYTES)} by default; complete oversized output is saved locally.`,
@@ -1294,12 +1381,13 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
   pi.registerTool({
     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",
+    description: "Connect, reconnect, annotate endpoints, locate server-specific memory, change the persistent remote working directory, inspect, forward ports, run remote SSH commands, or disconnect the configured SSH environment. Server memory is managed as JSON entries with Pi's read, write, and edit tools. 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 location, working directory, and local port forwarding",
     promptGuidelines: [
       "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.",
-      "Use remote with action memory and no memory argument to inspect server memory. Non-empty memory text appends to the existing memory; clear it only by passing --clear explicitly.",
+      "Use remote with action memory to locate and inspect the current server-memory JSON file, then use read/edit/write on that exact local path for entry-level changes.",
+      "Delete a server-memory JSON entry only after an explicit user request to delete, remove, or forget it. Read the file first, identify the exact entry id, and remove only that object with edit; ask the user if the target is ambiguous and never infer deletion from an update request.",
       `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.",
@@ -1308,7 +1396,6 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       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 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 context shared by the endpoint's user@host across SSH ports; omit to inspect, provide non-empty text to append without overwriting existing memory, or use --clear to clear explicitly" })),
       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" })),
@@ -1357,47 +1444,29 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       if (params.action === "note" || params.action === "memory") {
         const command = params.command || lastCommand || activeSshCommand();
         if (!command) throw new Error("No SSH endpoint configured; connect or select an endpoint first");
-        const label = parseSshCommand(command).label;
+        const parsed = parseSshCommand(command);
+        const label = parsed.label;
         if (params.action === "note") {
           const note = params.note?.trim() || undefined;
           saveEndpointConfig(command, { note });
-          if (remote && cacheId(remote) === cacheId(parseSshCommand(command)) && currentCtx) status(currentCtx);
+          if (remote && cacheId(remote) === cacheId(parsed) && currentCtx) status(currentCtx);
           return {
             content: [{ type: "text", text: note ? `SSH remote note updated (${label}): ${note}` : `SSH remote note cleared (${label})` }],
             details: { endpoint: label, note },
           };
         }
-        const parsed = parseSshCommand(command);
-        const server = serverMemoryId(parsed);
-        if (params.memory === undefined) {
-          const memory = endpointMemory(parsed);
-          return {
-            content: [{ type: "text", text: memory ? `SSH remote server memory (${server}):\n${memory}` : `No SSH remote server memory is configured (${server}).` }],
-            details: { endpoint: label, server, memory },
-          };
+        const path = ensureServerMemoryFile(parsed);
+        let memory: ServerMemoryFile | undefined;
+        try { memory = loadServerMemory(parsed); }
+        catch (error) {
+          throw new Error(`Invalid server-memory JSON at ${path}: ${(error as Error).message}`);
         }
-        const addition = params.memory.trim();
-        if (!addition) throw new Error("memory must contain text; omit it to inspect the current memory or use --clear to clear it explicitly");
-        if (addition.toLowerCase() === "--clear") {
-          saveServerMemory(command, undefined);
-          return {
-            content: [{ type: "text", text: `SSH remote server memory cleared (${server}).` }],
-            details: { endpoint: label, server, memory: undefined },
-          };
-        }
-        const currentMemory = endpointMemory(parsed);
-        const duplicate = currentMemory === addition || currentMemory?.endsWith(`\n\n${addition}`);
-        if (duplicate) {
-          return {
-            content: [{ type: "text", text: `SSH remote server memory already ends with this content (${server}); nothing was changed.` }],
-            details: { endpoint: label, server, memory: currentMemory, addedMemory: addition, changed: false },
-          };
-        }
-        const memory = currentMemory ? `${currentMemory}\n\n${addition}` : addition;
-        saveServerMemory(command, memory);
+        const text = memory?.entries.length
+          ? `SSH remote server memory (${serverMemoryId(parsed)}) is stored at ${path}:\n${JSON.stringify(memory.entries, null, 2)}`
+          : `No server-memory entries are configured for ${serverMemoryId(parsed)}. Use write to create ${path} with schema {"server":"${serverMemoryId(parsed)}","entries":[]}, then use edit for entry-level changes.`;
         return {
-          content: [{ type: "text", text: `SSH remote server memory appended (${server}). It applies to every port for this user and host.` }],
-          details: { endpoint: label, server, memory, addedMemory: addition, changed: true },
+          content: [{ type: "text", text }],
+          details: { endpoint: label, server: serverMemoryId(parsed), path, entries: memory?.entries ?? [] },
         };
       }
       if (params.action === "exec") {
@@ -1444,7 +1513,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
   });
 
   pi.registerCommand("remote", {
-    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",
+    description: "Connect over SSH and manage endpoints: /remote | ssh USER@HOST [-p PORT] [-i KEY] | memory | config | use USER@HOST:PORT | config note 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();
@@ -1453,8 +1522,18 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
         const rows = Object.entries(config.endpoints ?? {}).map(([key, endpoint]) => {
           const active = key === config.activeEndpoint ? "*" : " ";
           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"}`;
+          let memory = "none";
+          if (command) {
+            const parsed = parseSshCommand(command);
+            const path = serverMemoryFilePath(parsed);
+            try {
+              const entries = loadServerMemory(parsed)?.entries ?? [];
+              memory = `${entries.length} JSON entr${entries.length === 1 ? "y" : "ies"} (${path})`;
+            } catch (error) {
+              memory = `invalid JSON (${path}: ${(error as Error).message})`;
+            }
+          }
+          return `${active} ${key}\n    note: ${endpoint.note || "none"}\n    memory: ${memory}\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");
@@ -1508,15 +1587,19 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
         ctx.ui.notify(note ? `SSH remote note updated (${parseSshCommand(command).label}): ${note}` : `SSH remote note cleared (${parseSshCommand(command).label})`, "info");
         return;
       }
-      if (/^config\s+memory(?:\s+|$)/i.test(input)) {
-        const value = input.replace(/^config\s+memory\s*/i, "").trim();
-        if (!value) { ctx.ui.notify("Use /remote config memory TEXT or /remote config memory --clear", "error"); return; }
-        const command = lastCommand || activeSshCommand();
+      if (action === "memory") {
+        const command = remote?.command || lastCommand || activeSshCommand();
         if (!command) { ctx.ui.notify("Configure an SSH endpoint first", "error"); return; }
-        const memory = value.toLowerCase() === "--clear" ? undefined : value;
-        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");
+        const parsed = parseSshCommand(command);
+        let path: string;
+        try { path = ensureServerMemoryFile(parsed); }
+        catch (error) { ctx.ui.notify(`Could not initialize server-memory JSON: ${(error as Error).message}`, "error"); return; }
+        try {
+          const memory = loadServerMemory(parsed);
+          ctx.ui.notify(`SSH remote server memory (${serverMemoryId(parsed)})\nFile: ${path}\n\n${formatServerMemoryEntries(memory)}`, "info");
+        } catch (error) {
+          ctx.ui.notify(`Invalid server-memory JSON at ${path}: ${(error as Error).message}`, "error");
+        }
         return;
       }
       if (/^config\s+display-lines\s+/i.test(input)) {

package/package.json

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