@momenttttt/pi-zcode-memory 0.0.0-stage → 0.1.1

package/src/list.ts

@@ -0,0 +1,100 @@
+/**
+ * 扫记忆目录里的"事实文件"。
+ *
+ * 候选与排序都是对外承诺的一部分：递归扫 `.md`、排除索引自身；不递归进目录符号链接，
+ * 但指向文件的符号链接算候选；单个文件读不了只跳过它自己，不牵连其它条目；结果按 mtime
+ * 倒序（最近改动的排在前面）。不设条数上限——事实文件本来就不多，`memory_list` 给的是完整列表。
+ */
+import { closeSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { basename, join, relative, sep } from "node:path";
+
+import { MEMORY_INDEX_FILENAME, type MemoryType } from "./paths.ts";
+import { parseMemoryFrontmatter } from "./frontmatter.ts";
+
+export interface MemoryListEntry {
+  /** 相对记忆目录的路径，统一 `/` 分隔。 */
+  filename: string;
+  name?: string;
+  description?: string;
+  type?: MemoryType;
+  mtimeMs: number;
+  /** frontmatter 坏了：记成"无描述条目"，不抛错。 */
+  malformed: boolean;
+}
+
+/** 单个事实文件最多读这么多字节来解析 frontmatter；防止误把大文件整份读进来。 */
+const FRONTMATTER_READ_BYTES = 64 * 1024;
+
+export function listMemoryFiles(root: string): MemoryListEntry[] {
+  const entries: MemoryListEntry[] = [];
+  collect(root, root, entries);
+  return entries.sort((left, right) => right.mtimeMs - left.mtimeMs);
+}
+
+function collect(root: string, directory: string, out: MemoryListEntry[]): void {
+  let dirents;
+  try {
+    dirents = readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const dirent of dirents) {
+    const path = join(directory, dirent.name);
+    if (dirent.isDirectory()) {
+      // 不递归进目录符号链接；指向文件的链接在下面单独判。
+      if (!dirent.isSymbolicLink()) collect(root, path, out);
+      continue;
+    }
+    let isFile = dirent.isFile();
+    if (dirent.isSymbolicLink()) {
+      try {
+        isFile = statSync(path).isFile();
+      } catch {
+        // 失效链接与"读不了的事实文件"一样，跳过即可
+        isFile = false;
+      }
+    }
+    if (!isFile) continue;
+    if (!isMemoryCandidate(dirent.name)) continue;
+    const entry = readEntry(root, path);
+    if (entry) out.push(entry);
+  }
+}
+
+function isMemoryCandidate(filename: string): boolean {
+  return filename.endsWith(".md") && basename(filename) !== MEMORY_INDEX_FILENAME;
+}
+
+function readEntry(root: string, path: string): MemoryListEntry | undefined {
+  let stat;
+  let head: string;
+  try {
+    stat = statSync(path);
+    head = readHead(path);
+  } catch {
+    // 单个文件读不了不影响其它条目
+    return undefined;
+  }
+  const frontmatter = parseMemoryFrontmatter(head);
+  const filename = relative(root, path).split(sep).join("/");
+  return {
+    filename,
+    mtimeMs: Math.trunc(stat.mtimeMs),
+    malformed: frontmatter.malformed,
+    ...(frontmatter.name === undefined ? {} : { name: frontmatter.name }),
+    ...(frontmatter.description === undefined ? {} : { description: frontmatter.description }),
+    ...(frontmatter.type === undefined ? {} : { type: frontmatter.type }),
+  };
+}
+
+/** 只读文件头这么多字节：frontmatter 只需前 30 行。 */
+function readHead(path: string): string {
+  const buffer = Buffer.allocUnsafe(FRONTMATTER_READ_BYTES);
+  const fd = openSync(path, "r");
+  try {
+    const bytesRead = readSync(fd, buffer, 0, buffer.length, 0);
+    return buffer.subarray(0, bytesRead).toString("utf8");
+  } finally {
+    closeSync(fd);
+  }
+}

package/src/paths.ts

@@ -0,0 +1,95 @@
+/**
+ * 共享记忆目录的路径算法（纯函数，不 import pi）。
+ *
+ * 规则：
+ *   - 存储根：`<home>/.zcode`，basename 已是 `cli` 就不再追加
+ *   - 项目目录：`memories/projects/<slug>-<hash16>/memory`
+ *   - hash 输入：工作区标识（远程/托管工作区才有），否则 `resolve(cwd)`；**仅 win32** 折叠大小写
+ *   - slug：小写、非 `[a-z0-9._-]` 换 `-`、去首尾 `-`、截 48、空则 `project`
+ *
+ * **`platform` 是参数而不是读 `process.platform`**：路径语义（分隔符、盘符、大小写）本身就是
+ * 这条算法的一部分，必须在**任何机器上**都能被单测覆盖两种语义——CI 跑在 Linux 上，
+ * 如果绑运行时平台，win32 分支（也就是用户实际在用的那套）永远测不到。
+ */
+import { createHash } from "node:crypto";
+import { posix, win32 } from "node:path";
+
+/** 记忆目录里索引文件的名字。 */
+export const MEMORY_INDEX_FILENAME = "MEMORY.md";
+
+/** 事实文件 frontmatter 允许的 `type`。 */
+export const MEMORY_TYPES = ["user", "feedback", "project", "reference"] as const;
+export type MemoryType = (typeof MEMORY_TYPES)[number];
+
+export interface MemoryDirInput {
+  /** 工作目录（会话的工作区路径）。 */
+  cwd: string;
+  /** CLI 存储根：`<home>/.zcode/cli`。 */
+  storageRoot: string;
+  /**
+   * 外部工作区标识（远程/托管工作区才有）。
+   * 独立 CLI 与桌面普通项目都是 undefined，此时 slug 取 basename、hash 取路径。
+   */
+  workspaceIdentity?: string;
+  /** 用哪套路径语义。默认当前平台；只有 win32 才折叠 keySource 的大小写。 */
+  platform?: NodeJS.Platform;
+}
+
+export interface ProjectDirParts {
+  /** 目录名里的 slug 段（identity 存在时固定为 `project`）。 */
+  slug: string;
+  /** 16 个 hex 字符。 */
+  hash: string;
+  /** `<slug>-<hash>`。 */
+  dirName: string;
+}
+
+/** 按平台挑 path 实现：win32 一套，其余走 POSIX。 */
+export function pathImpl(platform: NodeJS.Platform | undefined) {
+  return (platform ?? process.platform) === "win32" ? win32 : posix;
+}
+
+/** 存储根归一化：basename 已是 `cli` 就不再追加。 */
+export function ensureCliStorageRoot(storageRoot: string, platform?: NodeJS.Platform): string {
+  const impl = pathImpl(platform);
+  return impl.basename(storageRoot) === "cli" ? storageRoot : impl.join(storageRoot, "cli");
+}
+
+/** 由 home 推导存储根：`<home>/.zcode` 再归一化。 */
+export function resolveZcodeStorageRoot(homeDir: string, platform?: NodeJS.Platform): string {
+  const impl = pathImpl(platform);
+  return ensureCliStorageRoot(impl.join(homeDir, ".zcode"), platform);
+}
+
+/** slug 清洗：小写 → 非 `[a-z0-9._-]` 换 `-` → 去首尾 `-` → 截 48 → 空则 `project`。 */
+export function sanitizeProjectSlug(value: string): string {
+  const slug = value
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+  return slug.length > 0 ? slug : "project";
+}
+
+/** 目录名（`<slug>-<hash16>`）与它的输入。 */
+export function computeProjectDirParts(input: MemoryDirInput): ProjectDirParts {
+  const impl = pathImpl(input.platform);
+  const identity = input.workspaceIdentity?.trim();
+  const resolvedCwd = impl.resolve(input.cwd);
+  const keySource =
+    identity || ((input.platform ?? process.platform) === "win32" ? resolvedCwd.toLowerCase() : resolvedCwd);
+  const hash = createHash("sha256").update(keySource).digest("hex").slice(0, 16);
+  const slug = identity ? "project" : sanitizeProjectSlug(impl.basename(resolvedCwd) || "project");
+  return { slug, hash, dirName: `${slug}-${hash}` };
+}
+
+/** `memories/projects/` 根：三级回退第 3 步扫描的目录。 */
+export function projectsRootOf(storageRoot: string, platform?: NodeJS.Platform): string {
+  return pathImpl(platform).join(storageRoot, "memories", "projects");
+}
+
+/** `<storageRoot>/memories/projects/<slug>-<hash>/memory`。 */
+export function computeMemoryDir(input: MemoryDirInput): string {
+  const parts = computeProjectDirParts(input);
+  return pathImpl(input.platform).join(projectsRootOf(input.storageRoot, input.platform), parts.dirName, "memory");
+}

package/src/read.ts

@@ -0,0 +1,175 @@
+/**
+ * `memory_read` 的定位与读取。
+ *
+ * - 定位：按 frontmatter `name`、或按文件名（相对记忆目录，支持子目录）精确匹配；
+ *   多处命中时报错而不是猜一个。
+ * - 正文上限：先取前 200 行，再按 4096 字节截断到完整行的边界；任一超限都算截断。
+ *   这两个数就是一条记忆在会话里实际可用的量——读到上限的内容不该被当成全文。
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, isAbsolute, relative, resolve } from "node:path";
+
+import { hashMemoryContent } from "./bridge.ts";
+import { normalizeMemoryText, parseMemoryDocument, type MemoryFrontmatter } from "./frontmatter.ts";
+import { listMemoryFiles } from "./list.ts";
+
+export const MEMORY_BODY_LINE_LIMIT = 200;
+export const MEMORY_BODY_BYTE_LIMIT = 4096;
+
+export interface LocatedMemory {
+  /** 相对记忆目录的路径，统一 `/` 分隔。 */
+  filename: string;
+  absolutePath: string;
+  sizeBytes: number;
+  mtimeMs: number;
+  /** sha256(磁盘上的原始 utf8 文本)，与 read-guard 的 `hashContent` 同构。 */
+  contentHash: string;
+  frontmatter: MemoryFrontmatter;
+  body: string;
+}
+
+export interface LocateError {
+  code: "not_found" | "ambiguous" | "outside_root" | "unreadable";
+  message: string;
+}
+
+export type LocateResult = { ok: true; value: LocatedMemory } | { ok: false; error: LocateError };
+
+/** 把引用折成记忆目录内的绝对路径；越界返回 undefined。 */
+export function resolveUnderRoot(root: string, reference: string): string | undefined {
+  const cleaned = reference.trim().replace(/\\/gu, "/").replace(/^(?:\.\/)+/u, "");
+  if (cleaned.length === 0) return undefined;
+  if (cleaned.startsWith("/") || /^[A-Za-z]:/u.test(cleaned)) return undefined;
+  const absolute = resolve(root, cleaned);
+  const rel = relative(root, absolute);
+  if (rel.length === 0 || rel.startsWith("..") || isAbsolute(rel)) return undefined;
+  return absolute;
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function locateMemory(root: string, reference: string): LocateResult {
+  const ref = reference.trim().replace(/\\/gu, "/").replace(/^(?:\.\/)+/u, "");
+  if (ref.length === 0) {
+    return { ok: false, error: { code: "not_found", message: "The reference is empty: pass the memory's name or filename." } };
+  }
+
+  // 1) 直接当相对路径试：`foo.md`、`sub/foo.md`，以及（允许的）MEMORY.md
+  const direct = resolveUnderRoot(root, ref);
+  if (direct !== undefined && isFile(direct)) {
+    const located = readLocated(root, direct);
+    if (located.ok) return located;
+  }
+  // 2) 没有 `.md` 后缀时补一次
+  if (!ref.endsWith(".md")) {
+    const withSuffix = resolveUnderRoot(root, `${ref}.md`);
+    if (withSuffix !== undefined && isFile(withSuffix)) {
+      const located = readLocated(root, withSuffix);
+      if (located.ok) return located;
+    }
+  }
+
+  // 3) 扫目录按 name / 文件名匹配
+  const matches = new Map<string, string>();
+  for (const entry of listMemoryFiles(root)) {
+    const withoutExtension = entry.filename.replace(/\.md$/iu, "");
+    const filenameBase = basename(withoutExtension);
+    if (entry.name === ref || entry.filename === ref || withoutExtension === ref || filenameBase === ref) {
+      matches.set(entry.filename, entry.filename);
+    }
+  }
+  if (matches.size === 1) {
+    const filename = [...matches.keys()][0]!;
+    const absolute = resolve(root, filename);
+    const located = readLocated(root, absolute);
+    if (located.ok) return located;
+  }
+  if (matches.size > 1) {
+    return {
+      ok: false,
+      error: {
+        code: "ambiguous",
+        message: `"${reference}" matches more than one memory; pass the filename instead: ${[...matches.keys()].join(", ")}`,
+      },
+    };
+  }
+  return {
+    ok: false,
+    error: {
+      code: "not_found",
+      message: `No memory "${reference}" in the memory directory. Use memory_list first to see which memories exist.`,
+    },
+  };
+}
+
+function readLocated(root: string, absolutePath: string): LocateResult {
+  let stat;
+  let content: string;
+  try {
+    stat = statSync(absolutePath);
+    content = readFileSync(absolutePath, "utf8");
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        code: "unreadable",
+        message: `Read failed: ${absolutePath} (${error instanceof Error ? error.message : String(error)})`,
+      },
+    };
+  }
+  const normalized = normalizeMemoryText(content);
+  const document = parseMemoryDocument(normalized);
+  return {
+    ok: true,
+    value: {
+      filename: relative(root, absolutePath).split("\\").join("/"),
+      absolutePath,
+      sizeBytes: stat.size,
+      mtimeMs: Math.trunc(stat.mtimeMs),
+      contentHash: hashMemoryContent(content),
+      frontmatter: document.frontmatter,
+      body: document.body,
+    },
+  };
+}
+
+export interface TruncatedBody {
+  text: string;
+  truncated: boolean;
+  /** 截断原因，用于提示文案；未截断时 undefined。 */
+  reason?: "lines" | "bytes" | "both";
+}
+
+export function truncateMemoryBody(body: string): TruncatedBody {
+  const lines = body === "" ? [""] : body.split("\n");
+  const lineTruncated = lines.length > MEMORY_BODY_LINE_LIMIT;
+  const lineLimited = lineTruncated ? lines.slice(0, MEMORY_BODY_LINE_LIMIT).join("\n") : body;
+
+  const selected: string[] = [];
+  let selectedBytes = 0;
+  let byteTruncated = false;
+  for (const line of lineLimited.split("\n")) {
+    const separatorBytes = selected.length > 0 ? 1 : 0;
+    const nextBytes = selectedBytes + separatorBytes + Buffer.byteLength(line, "utf8");
+    if (nextBytes > MEMORY_BODY_BYTE_LIMIT) {
+      byteTruncated = true;
+      break;
+    }
+    selected.push(line);
+    selectedBytes = nextBytes;
+  }
+
+  const reason: TruncatedBody["reason"] =
+    lineTruncated && byteTruncated ? "both" : lineTruncated ? "lines" : byteTruncated ? "bytes" : undefined;
+  return {
+    text: selected.join("\n"),
+    truncated: lineTruncated || byteTruncated,
+    ...(reason === undefined ? {} : { reason }),
+  };
+}

package/src/resolve.ts

@@ -0,0 +1,130 @@
+/**
+ * 记忆目录定位的三级回退（设计文档 §5.1）：
+ *
+ *   1. 配置里的 `dir`（最高优先级，任何异常场景的兜底）
+ *   2. 按路径算法算出的目录**存在** → 用它
+ *   3. 计算路径不存在时，`memories/projects/` 下若恰好一个 `<slug>-*` 目录 → 用它并警告
+ *      都没有 → 视为"该项目尚无记忆"，不创建目录
+ *   4. 第 3 步失败但存在 `project-*` 目录 → 提示目录可能是按 workspace identity 建的
+ *      （slug 固定为 `project`，hash 输入不是工作区路径）
+ *
+ * 只做字符串路径判定，不做 realpath / `~` 展开：hash 的输入就是 `resolve(cwd)` 这个字符串，
+ * realpath 会把符号链接、短路径折成另一种写法，算出来的目录反而对不上。
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import {
+  computeMemoryDir,
+  computeProjectDirParts,
+  projectsRootOf,
+  resolveZcodeStorageRoot,
+  type MemoryDirInput,
+} from "./paths.ts";
+
+export type MemoryDirSource = "config" | "computed" | "fallback" | "none";
+
+export interface MemoryDirResolution {
+  /** 最终使用的记忆目录；`none` 时为 undefined。 */
+  dir: string | undefined;
+  source: MemoryDirSource;
+  /** 按算法算出的目录（`memory_write` 在 `none` 时按它创建）。 */
+  computedDir: string;
+  /** `<storageRoot>/memories/projects`，回退扫描与提示用。 */
+  projectsRoot: string;
+  /** 计算路径与账户目录不一致时为什么。 */
+  warnings: string[];
+}
+
+export interface ResolveMemoryDirOptions {
+  cwd: string;
+  /** 显式配置的目录。 */
+  configDir?: string;
+  /** 覆盖 home（测试用）。默认 `homedir()`。 */
+  homeDir?: string;
+  /** 覆盖存储根（测试用）；给了就不再由 homeDir 推导。 */
+  storageRoot?: string;
+  workspaceIdentity?: string;
+  platform?: NodeJS.Platform;
+  /** 注入文件系统判定（测试用）。默认真实 fs。 */
+  pathExists?: (path: string) => boolean;
+  listDirNames?: (path: string) => string[];
+}
+
+export function resolveMemoryDir(options: ResolveMemoryDirOptions): MemoryDirResolution {
+  const storageRoot =
+    options.storageRoot ?? resolveZcodeStorageRoot(options.homeDir ?? homedir(), options.platform);
+  const dirInput: MemoryDirInput = {
+    cwd: options.cwd,
+    storageRoot,
+    ...(options.workspaceIdentity === undefined ? {} : { workspaceIdentity: options.workspaceIdentity }),
+    ...(options.platform === undefined ? {} : { platform: options.platform }),
+  };
+  const parts = computeProjectDirParts(dirInput);
+  const projectsRoot = projectsRootOf(storageRoot, options.platform);
+  const computedDir = computeMemoryDir(dirInput);
+  const exists = options.pathExists ?? isDirectory;
+  const listNames = options.listDirNames ?? listDirectoryNames;
+
+  if (options.configDir !== undefined) {
+    // 配置是显式覆盖：不要求目录已存在（memory_write 会创建它）。
+    return { dir: options.configDir, source: "config", computedDir, projectsRoot, warnings: [] };
+  }
+
+  if (exists(computedDir)) {
+    return { dir: computedDir, source: "computed", computedDir, projectsRoot, warnings: [] };
+  }
+
+  const candidates = listNames(projectsRoot).filter((name) => name.startsWith(`${parts.slug}-`));
+  if (candidates.length === 1) {
+    const dir = join(projectsRoot, candidates[0]!, "memory");
+    return {
+      dir,
+      source: "fallback",
+      computedDir,
+      projectsRoot,
+      warnings: [
+        `The computed memory directory does not exist: ${computedDir}; using the only candidate with the same slug instead: ${dir}. ` +
+          `Different hashes on the two sides usually mean the workspace path is written differently from the one the memory directory was computed from; set dir explicitly in the config.`,
+      ],
+    };
+  }
+
+  const warnings: string[] = [];
+  if (candidates.length > 1) {
+    warnings.push(
+      `The computed memory directory does not exist, and ${projectsRoot} holds ${candidates.length} directories starting with ${parts.slug}-, so there is no way to tell which one to use.`,
+    );
+  } else {
+    warnings.push(`This project has no ZCode memory yet (the computed directory does not exist: ${computedDir}).`);
+  }
+
+  if (listNames(projectsRoot).some((name) => name.startsWith("project-"))) {
+    warnings.push(
+      "Found memory directories with the project- prefix: a workspace identity may be in use (slug fixed to project, hash input not the workspace path). " +
+        "Set dir explicitly in this package's config.",
+    );
+  }
+
+  return { dir: undefined, source: "none", computedDir, projectsRoot, warnings };
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function listDirectoryNames(path: string): string[] {
+  try {
+    return readdirSync(path, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+}

package/src/status.ts

@@ -0,0 +1,111 @@
+/**
+ * `/memory` 的状态与索引体检。
+ *
+ * 索引体检只做两件确定的事：索引行指向的文件不存在（孤儿行）、磁盘上的事实文件没出现在
+ * 索引里（未入索引）。索引可能被模型写坏（重复、失效链接），`memory_list` 走文件系统兜底。
+ */
+import { INDEX_CHARACTER_LIMIT, INDEX_LINE_LIMIT } from "./index-content.ts";
+import { INDEX_FILENAME } from "./index-file.ts";
+import type { MemoryListEntry } from "./list.ts";
+import type { MemoryDirResolution } from "./resolve.ts";
+
+export interface IndexHealth {
+  indexLineCount: number;
+  /** 索引里的链接目标（相对记忆目录，`/` 分隔）。 */
+  linkTargets: string[];
+  /** 指向不存在文件的索引行。 */
+  orphanIndexLines: string[];
+  /** 磁盘上有、但索引里没有链接的事实文件。 */
+  unindexedFiles: string[];
+}
+
+const LINK_TARGET_PATTERN = /\]\(\s*([^)\s]+)\s*\)/gu;
+
+/** 抽出索引里的相对 `.md` 链接目标。 */
+export function extractIndexTargets(indexContent: string): string[] {
+  const targets: string[] = [];
+  for (const match of indexContent.matchAll(LINK_TARGET_PATTERN)) {
+    const target = match[1]!.replace(/\\/gu, "/").replace(/^(?:\.\/)+/u, "");
+    if (target.startsWith("http://") || target.startsWith("https://")) continue;
+    if (!target.endsWith(".md")) continue;
+    if (target.split("/").pop() === INDEX_FILENAME) continue;
+    targets.push(target);
+  }
+  return targets;
+}
+
+/** 文件内容的"实际行数"：末尾换行不算一行。 */
+function countLines(content: string): number {
+  if (content.length === 0) return 0;
+  const lines = content.replace(/\r\n/gu, "\n").split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  return lines.length;
+}
+
+export function inspectMemoryIndex(input: {
+  indexContent: string | undefined;
+  files: readonly MemoryListEntry[];
+}): IndexHealth {
+  const indexContent = input.indexContent ?? "";
+  const linkTargets = extractIndexTargets(indexContent);
+  const fileNames = new Set(input.files.map((entry) => entry.filename));
+  const targetNames = new Set(linkTargets);
+  return {
+    indexLineCount: countLines(indexContent),
+    linkTargets,
+    orphanIndexLines: [...new Set(linkTargets)].filter((target) => !fileNames.has(target)),
+    unindexedFiles: input.files.map((entry) => entry.filename).filter((filename) => !targetNames.has(filename)),
+  };
+}
+
+export interface MemoryStatusInput {
+  resolution: MemoryDirResolution;
+  /** `MEMORY.md` 的内容；不存在/读不了时 undefined。 */
+  indexContent: string | undefined;
+  files: readonly MemoryListEntry[];
+  /** 由扩展算出的注入状态描述。 */
+  injectionLabel: string;
+}
+
+function sourceLabel(source: MemoryDirResolution["source"]): string {
+  switch (source) {
+    case "config":
+      return "配置指定";
+    case "computed":
+      return "按算法计算（路径存在）";
+    case "fallback":
+      return "同 slug 唯一候选回退";
+    case "none":
+      return "尚无记忆";
+  }
+}
+
+function preview(values: readonly string[], limit = 10): string {
+  if (values.length === 0) return "无";
+  const shown = values.slice(0, limit).join("、");
+  return values.length > limit ? `${shown} 等 ${values.length} 项` : shown;
+}
+
+export function formatMemoryStatus(input: MemoryStatusInput): string {
+  const { resolution, files } = input;
+  const health = inspectMemoryIndex({ indexContent: input.indexContent, files });
+  const lines: string[] = [];
+  lines.push(`记忆目录：${resolution.dir ?? "未解析到"}`);
+  lines.push(`来源：${sourceLabel(resolution.source)}`);
+  if (resolution.dir === undefined || resolution.source !== "computed") {
+    lines.push(`计算路径：${resolution.computedDir}`);
+  }
+  lines.push(
+    input.indexContent === undefined
+      ? `索引 ${INDEX_FILENAME}：不存在（注入会跳过；memory_write 会创建它）`
+      : `索引 ${INDEX_FILENAME}：${health.indexLineCount} 行（注入上限 ${INDEX_LINE_LIMIT} 行 / ${INDEX_CHARACTER_LIMIT} 字符）`,
+  );
+  lines.push(`事实文件：${files.length} 个`);
+  lines.push(
+    `索引体检：孤儿索引行 ${health.orphanIndexLines.length} 条（${preview(health.orphanIndexLines)}）；` +
+      `未入索引的文件 ${health.unindexedFiles.length} 个（${preview(health.unindexedFiles)}）`,
+  );
+  lines.push(`索引注入：${input.injectionLabel}`);
+  for (const warning of resolution.warnings) lines.push(`注意：${warning}`);
+  return lines.join("\n");
+}