pi-ssh-remote 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -18,6 +18,23 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Rel
 
 - None.
 
+## [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 +206,8 @@ 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.11...HEAD
+[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. Server memory is a per-`user@host` JSON file containing stable `{ "id", "content" }` entries, so another SSH port for the same user and host uses the same entries. Pi is told the exact local file path and can use its normal `read`, `edit`, and `write` tools for entry-level CRUD even while other tools are routed remotely. 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. Valid server-memory entries are automatically injected into the model context whenever a matching endpoint is connected as the active remote workspace.
 
 ### Resilient and bounded by default
 
@@ -66,8 +66,9 @@ 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
+
+You: Add a server-memory entry saying to use /opt/conda/bin/python and never stop shared jobs.
 ```
 
 From this point, normal Pi operations target `/srv/project` on the remote server. The footer makes that routing explicit:
@@ -131,7 +132,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 in the local remote configuration. `user@host`-specific memory survives in a separate local JSON file under `~/.pi/agent/ssh-remote-memories/`; each entry has a stable `id` and `content`. When Pi connects to an endpoint, valid entries matching its user and host are added to the model 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 them from subsequent model requests.
 
 ### 4. Expose a remote service while editing locally
 
@@ -164,7 +165,24 @@ 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.
+```text
+Add a server-memory entry that says deployments must use /opt/deploy/run.sh.
+```
+
+List the current server's entries and IDs before referring to one:
+
+```text
+/remote memory
+```
+
+Then update or delete by the displayed ID:
+
+```text
+Update the entry with ID deploy-command to use /opt/deploy/v2/run.sh.
+Delete the server-memory entry with ID obsolete-proxy-rule.
+```
+
+These requests are handled through the agent-facing `remote` tool; slash commands are optional. The `memory` action locates and inspects the matching JSON file, while Pi's normal `read`, `edit`, and `write` tools perform entry-level add, query, update, and delete operations. The injected instructions make deletion deliberately strict: Pi must first read the file, identify the exact entry ID, and delete only that object—and only after the user explicitly asks to delete, remove, or forget memory. Ambiguous targets require clarification, update requests do not imply deletion, and deleting all entries requires an explicit request to delete all server memory.
 
 ## Command reference
 
@@ -176,8 +194,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, IDs, and JSON file path |
 | `/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 +222,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. Server-memory entries are stored separately under `~/.pi/agent/ssh-remote-memories/` as `{ "server", "entries": [{ "id", "content" }] }`; legacy string memories are migrated automatically. 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. The current server's exact memory path is the only local path that the routed `read`, `edit`, and `write` tools special-case. Private key contents, passwords, and key passphrases are **never written to these files**. 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 +232,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.11](https://github.com/petrichor20211/pi-ssh-remote/releases/tag/v0.1.11)
 
 | Version | Date | Highlights |
 |---|---|---|
+| [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 训练机`、`预发布环境`、`线上只读机`。服务器记忆按 `user@host` 保存为 JSON 文件，每条记忆都是稳定的 `{ "id", "content" }` 对象；同一用户和主机即使通过不同 SSH 端口连接，也会使用同一组条目。插件会把精确的本地文件路径告诉 Pi，因此即使其他工具已路由到远端，Pi 仍能用普通 `read`、`edit`、`write` 工具对记忆条目增删查改。连接匹配的 endpoint 并启用远端工具路由后，有效条目会自动注入模型上下文；断开连接或切换到纯隧道模式后，后续请求不再注入。所有配置保存在本地，重启 Pi 后仍然存在。
 
 ### 断线后可以自动恢复
 
@@ -107,7 +107,12 @@ pi install npm:pi-ssh-remote
 ```text
 /remote cd /srv/project
 /remote config note H100 训练机
-/remote config memory 使用 /opt/conda/bin/python，不要停止其他用户的共享任务。
+```
+
+然后直接告诉 Pi：
+
+```text
+添加一条服务器记忆：使用 /opt/conda/bin/python，不要停止其他用户的共享任务。
 ```
 
 查看当前状态：
@@ -183,7 +188,7 @@ pi install npm:pi-ssh-remote
 /remote
 ```
 
-备注和默认目录会按 `user@host:port` 分别保存，不会互相覆盖；服务器记忆则按 `user@host` 共享，不受端口影响。
+备注和默认目录会按 `user@host:port` 分别保存，不会互相覆盖；服务器记忆则按 `user@host` 保存为独立 JSON 文件并跨端口共享。
 
 ### 4. 远端启动模型，本地开发界面
 
@@ -218,7 +223,24 @@ pi install npm:pi-ssh-remote
 把远端 8000 端口转发到本地 8000，但代码工具继续留在本地。
 ```
 
-Pi 会通过插件提供的 `remote` 工具完成这些操作。为防止误删，调用 `memory` action 但不传 `memory` 参数时只会读取当前服务器记忆；传入非空内容时会追加到现有记忆，而不是覆盖，重复提交相同的末尾内容不会再次追加；清除时仍必须显式传入 `--clear`。
+```text
+添加一条服务器记忆：部署必须使用 /opt/deploy/run.sh。
+```
+
+更新或删除前，可以先展示当前服务器的全部记忆和 ID：
+
+```text
+/remote memory
+```
+
+然后使用展示出的 ID：
+
+```text
+把 ID 为 deploy-command 的记忆更新为使用 /opt/deploy/v2/run.sh。
+删除 ID 为 obsolete-proxy-rule 的服务器记忆。
+```
+
+Pi 会通过插件提供的 `remote` 工具完成这些操作。`memory` action 只负责定位和查看匹配的 JSON 文件，实际增删查改使用 Pi 自带的 `read`、`edit`、`write`。删除规则会明确注入给 Agent：只有用户明确要求“删除／移除／忘记”服务器记忆时，Pi 才能先读取文件、确认准确条目 ID，再只删除该对象；目标不明确时必须询问，修改请求不等于删除授权，删除全部条目也必须由用户明确提出。
 
 ## 命令说明
 
@@ -230,8 +252,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 和 JSON 文件路径 |
 | `/remote config cwd PATH` | 设置默认远程工作目录 |
 | `/remote cd PATH` | 切换当前远程目录并保存 |
 | `/remote config forward MAPPING...` | 保存端口转发配置，例如 `7860:127.0.0.1:7860` |
@@ -264,16 +285,21 @@ Pi 会通过插件提供的 `remote` 工具完成这些操作。为防止误删
 - 已保存的服务器；
 - 当前选中的服务器；
 - 服务器备注；
-- 服务器特定记忆；
 - 默认远程目录；
 - 端口转发配置；
 - 私钥文件路径；
 - 命令预览设置；
 - 模型输出预算。
 
-此外，每个 Pi session 都会记录不含凭据的 SSH 工作区元数据，用于在 `/resume` 时恢复该历史 session 对应的服务器环境。服务器记忆按 `user@host` 识别，不受 SSH 端口影响。它是由用户在本地配置的可信上下文，不会从远程服务器自动读取；仅当匹配的 endpoint 作为远端工作区启用时才会加入每次模型请求。
+服务器记忆单独保存在：
+
+```text
+~/.pi/agent/ssh-remote-memories/
+```
+
+文件结构为 `{ "server", "entries": [{ "id", "content" }] }`，旧版字符串记忆会自动迁移为 JSON 条目。此外，每个 Pi session 都会记录不含凭据的 SSH 工作区元数据，用于在 `/resume` 时恢复该历史 session 对应的服务器环境。服务器记忆按 `user@host` 识别，不受 SSH 端口影响。它是由用户在本地配置的可信上下文，不会从远程服务器自动读取；仅当匹配的 endpoint 作为远端工作区启用时才会加入每次模型请求。远端路由启用时，只有当前服务器对应的精确记忆文件路径会被 `read`、`edit`、`write` 特殊处理为本地文件。
 
-私钥内容、密码和密钥 passphrase 都不会写入配置文件。插件仅在连接时从本地读取私钥；手动输入的密码和 passphrase 只会缓存在当前 Pi 进程的内存中。
+私钥内容、密码和密钥 passphrase 都不会写入这些配置文件。插件仅在连接时从本地读取私钥；手动输入的密码和 passphrase 只会缓存在当前 Pi 进程的内存中。
 
 ## 安全与输出限制
 
@@ -294,13 +320,13 @@ Pi 会通过插件提供的 `remote` 工具完成这些操作。为防止误删
 
 ## 版本发布
 
-最新版本：[v0.1.10](https://github.com/petrichor20211/pi-ssh-remote/releases/tag/v0.1.10)
+最新版本：[v0.1.11](https://github.com/petrichor20211/pi-ssh-remote/releases/tag/v0.1.11)
 
 | 版本 | 日期 | 主要内容 |
 |---|---|---|
+| [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")); }
@@ -782,6 +859,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 +1349,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 +1377,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 +1392,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 +1440,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 +1509,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 +1518,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 +1583,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.11",
   "description": "Persistent remote SSH workspaces for Pi.",
   "type": "module",
   "author": "Yutong Bian",