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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Momenttttt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# @momenttttt/pi-zcode-memory
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+让 pi 与 ZCode 共用同一份项目记忆。
+
+- 三个工具：`memory_list`、`memory_read`、`memory_write`
+- 会话开始时只把 `MEMORY.md` 索引注入一次；正文永不自动注入，按需读
+- 目录算法、索引格式、事实文件 frontmatter 逐条对齐 ZCode，两边读写同一批文件
+- `/memory` 查看状态与索引体检，`/memory reload` 强制下一次运行重新注入
+
+## 安装
+
+```bash
+pi install npm:@momenttttt/pi-zcode-memory
+```
+
+本地开发：
+
+```bash
+pi -e ./packages/pi-zcode-memory/extensions/zcode-memory.ts
+```
+
+## 记忆目录怎么定位
+
+按共享记忆目录的路径算法计算：
+
+```
+~/.zcode -> 追加 cli（basename 已是 cli 则不追加）
+<storageRoot>/memories/projects/<slug>-<hash16>/memory/
+hash16 = sha256(win32 ? resolve(cwd).toLowerCase() : resolve(cwd)).slice(0, 16)
+slug   = 小写、非 [a-z0-9._-] 换 -、去首尾 -、截 48、空则 project
+```
+
+实际使用时有三级回退：
+
+1. 配置里的 `dir`（最高优先级；路径算法对不上时用它，例如工作区标识或路径写法差异）
+2. 算法算出的路径存在 → 用它
+3. 不存在时，`memories/projects/` 下恰好一个 `<slug>-*` 目录 → 用它并警告；
+   否则视为"该项目尚无 ZCode 记忆"（不创建目录；`memory_write` 时才按计算路径创建）
+
+检测到 `project-` 前缀目录时会提示：ZCode 可能用了 workspace identity（slug 固定为 `project`，
+hash 输入不是路径）。独立 CLI 与普通桌面项目不会出现这种情况。
+
+## 配置
+
+两个位置，深合并，项目覆盖全局：
+
+- 全局：`<agent-dir>/extensions/zcode-memory.json`（默认 `~/.pi/agent/extensions/zcode-memory.json`）
+- 项目：`<cwd>/.pi/zcode-memory.json`
+
+```json
+{
+  "enabled": true,
+  "dir": "D:/zcode/cli/memories/projects/chat-ace14747b286680c/memory",
+  "injectIndex": true
+}
+```
+
+| 项 | 默认 | 说明 |
+| --- | --- | --- |
+| `enabled` | `true` | 关掉后工具仍注册，但不注入索引（工具本身仍可用） |
+| `dir` | 无 | 显式记忆目录。任意异常场景的兜底 |
+| `injectIndex` | `true` | 是否做索引注入 |
+
+配置解析失败（文件坏了、JSON 不合法）不会让插件崩，退回默认值。
+
+## 工具
+
+| 工具 | 行为 |
+| --- | --- |
+| `memory_list` | 递归扫记忆目录（排除 `MEMORY.md`、不跟随目录符号链接），返回文件名 / name / description / type / mtime。坏 frontmatter 降级成"无描述条目"，不抛错 |
+| `memory_read` | 按 name 或文件名定位；返回 frontmatter 摘要 + 正文。正文按 ZCode 召回上限截断（前 200 行 / 4096 字节）并提示去哪里读全文 |
+| `memory_write` | `name` / `description` / `type` / `body` / `mode: create\|upsert`。原子写事实文件 + 维护 `MEMORY.md` 索引行 |
+
+写入的 frontmatter 只有四个键：
+
+```yaml
+---
+name: <kebab-case-slug>
+description: <一行描述>
+metadata:
+  node_type: memory
+  type: user | feedback | project | reference
+---
+```
+
+**不写** `originSessionId`（那是读文件的一方在缺失时自己补的惰性字段，我们不伪造不属于自己的
+会话 id），也不在 `metadata` 里加自定义键。
+
+## 设计取舍
+
+**为什么索引只注入一次，而不是每轮重注？**
+只有 `MEMORY.md` 进上下文，正文按需读。注入形态是 `before_agent_start` 返回的
+一条 `display: false` custom 消息（不是塞进 system prompt）。之后用
+`pi.appendEntry("zcode-memory/injected", { indexHash })` 记标记；`session_start`
+（new / resume / fork）按当前会话投影重建标记。重新注入只有三种情况：索引内容 hash 变化、
+注入消息被压缩摘要掉（不在保留尾部里）、`/memory reload`。`messageType === "custom"`
+的运行（`pi.sendMessage(..., { triggerTurn: true })` 起的）直接跳过。
+
+**为什么 `memory_write` 走 `withFileMutationQueue` + revision 重试，而不是做跨进程锁？**
+ZCode 的前台写本来就没有跨进程锁（后台整理进程除外），它靠 revision
+（`mtime:<截断毫秒>:size:<字节>`）发现并发。我们走同一条自愈路径：进程内用 pi 的写队列
+串行；`MEMORY.md` 写前比对 revision，不一致就重读重试一次，再失败就报错让模型重试——
+**不静默覆盖**。代价是 ZCode 下一次写会撞上 revision 冲突，它重读索引后即可继续。
+
+**为什么 `memory_read` 后要发读态事件？**
+用 `memory_read` 读过的记忆，紧接着用内置 `edit` 修改时不应该再被
+[pi-read-guard](https://github.com/Momenttttt/pi-extension-suite) 要求"先读"。两个包通过
+`pi.events` 共享总线互通（频道 `read-guard/file-read`）：发布方只 `emit`，接收方只 `on`，
+任一方缺席时静默降级，没有 import 依赖。相比"配置声明的读态提供方"，少一层配置形状与
+解析规则，收益相同。截断读发布 `kind: "truncated"` 且不带内容 hash —— 截断读不能成为
+写水位，和内置 `read` 的 `details.truncation` 是同一条规则。
+
+**为什么正文读取要有截断上限？**
+`memory_read` 返回的就是"会话里实际可用的量"：一条记忆被召回时最多取前 200 行 /
+4096 字节，完整内容始终可以用内置 `read` 读。这样模型不会误以为工具给了全文。
+
+**为什么目录算法不做 `~` 展开、不做 realpath？**
+hash 的输入就是 `resolve(cwd)` 这个路径字符串。realpath 会把符号链接/短路径折成另一个
+字符串，反而算错目录。win32 折叠大小写也是同一个目的：让同一目录的不同写法落到同一个 hash。
+
+## 边界与已知限制
+
+- **与 ZCode 是最终一致，不是实时同步。** ZCode 的 `MEMORY.md` **整个运行期只读一次**，
+  刷新点只有首次上下文初始化、冷恢复、`/clear`。**压缩不是刷新点**——陈旧索引会活过压缩。
+  所以 pi 写完记忆后，ZCode 那个正在跑的会话看不到，要到新会话/冷恢复才可见；事实文件正文
+  不被缓存，比索引新鲜。
+- **ZCode 的 `Write` 是整体覆盖。** 它拿着旧快照写 `MEMORY.md` 时，我们的外部改动会被
+  整份盖掉（它不会合并）。缓解只有"每次写前读一次"和"不要在 ZCode 正主动写记忆时批量写"。
+- **索引可能被模型写坏。** `memory_list` 走文件系统兜底；`/memory` 给出孤儿索引行与
+  未入索引文件的体检，但**不自动修正**索引。
+- **frontmatter 只在前 30 行内解析。** 闭合行更靠后的文件，读它的一方同样会当成
+  "无描述条目"——所以写文件时 frontmatter 必须短。
+- **写入拒绝跟随符号链接。** 目标是符号链接时报错，要求传真实路径。
+- **`memory_read` 截断读不会成为写水位**：接着用内置 `edit` 改同一文件仍会被
+  pi-read-guard 要求重读（先读后写约束的预期行为）。
+- **没有删除工具、没有自动抽取。** v1 需要"忘记"时用内置 `bash rm`；提炼记忆走显式
+  工具调用，不在后台跑模型。
+- **索引是 `custom_message`**，不在 pi-context-guard 微压缩的可清理白名单里，不会被清理。
+
+## 开发
+
+```bash
+npm install
+npm run check        # typecheck + test + 文档交叉引用
+git config core.hooksPath .githooks   # 提交身份与提交信息格式钩子
+```
+
+测试分两层：纯函数单测（目录算法、frontmatter、解析/截断、索引行、注入决策），以及
+"进程内真实会话 + 桩 provider"的端到端测试（工具输出、索引注入、与 read-guard 的互通）。
+
+## License
+
+MIT

package/extensions/zcode-memory.ts

@@ -0,0 +1,476 @@
+/**
+ * 扩展入口：让 pi 与 ZCode 共用同一份项目记忆。
+ *
+ * 互通是这个包存在的理由，也是唯一一条外部约束：目录布局、索引格式、事实文件 frontmatter
+ * 必须与 ZCode 读写的那一套一致，因为那些文件由它创建、也由它召回。除此之外本包不依赖它，
+ * 代码里也不复述它的内部实现。
+ *
+ * 分层（越靠下越纯，纯层不 import pi，便于 S1 单测）：
+ *   - `src/paths.ts`        目录算法
+ *   - `src/resolve.ts`      三级回退
+ *   - `src/config.ts`       全局 + 项目配置深合并
+ *   - `src/frontmatter.ts`  事实文件 frontmatter 解析与生成
+ *   - `src/list.ts` / `src/read.ts`   memory_list / memory_read 的落盘逻辑
+ *   - `src/atomic.ts` / `src/index-file.ts` / `src/write.ts`   memory_write
+ *   - `src/index-content.ts` / `src/injection.ts` / `src/status.ts`   索引注入与 /memory
+ *   - 本文件               事件与工具接线
+ *
+ * 并发：所有写入都走 pi 的 `withFileMutationQueue(root, ...)` 串行；跨进程的部分不做锁，
+ * 靠写前 revision 比对 + 重读重试自愈——**不**静默覆盖别人的改动。
+ */
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionFactory,
+} from "@earendil-works/pi-coding-agent";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+
+import { buildReadStatePayload, READ_STATE_EVENT } from "../src/bridge.ts";
+import { loadConfig, type ZcodeMemoryConfig } from "../src/config.ts";
+import { MemoryWriteError, type MemoryWriteErrorCode } from "../src/errors.ts";
+import { INDEX_MESSAGE_TYPE, INJECTED_ENTRY_TYPE, decideInjection, rebuildInjectedHash } from "../src/injection.ts";
+import { formatMemoryIndexForInjection, memoryIndexHash } from "../src/index-content.ts";
+import { listMemoryFiles, type MemoryListEntry } from "../src/list.ts";
+import { MEMORY_TYPES } from "../src/paths.ts";
+import { locateMemory, truncateMemoryBody } from "../src/read.ts";
+import { resolveMemoryDir, type MemoryDirResolution } from "../src/resolve.ts";
+import { formatMemoryStatus } from "../src/status.ts";
+import { writeMemory } from "../src/write.ts";
+
+const INDEX_FILENAME = "MEMORY.md";
+
+/** 工具结果详情：给脚本/后续扩展判断用，模型看不到（除 content 外）。 */
+interface MemoryToolDetails {
+  dir?: string;
+  filename?: string;
+  absolutePath?: string;
+  /** 失败原因码：写入失败是 `MemoryWriteErrorCode`，读取失败是定位错误码。 */
+  code?: string;
+}
+
+const zcodeMemory: ExtensionFactory = (pi: ExtensionAPI): void => {
+  /** 当前上下文投影里仍存活的注入 hash；`session_start` 起重建，压缩/切分支后失效重算。 */
+  let injectedHash: string | undefined;
+  /** `/memory reload` 置位：下一次运行强制重新注入。 */
+  let forceInject = false;
+  let missingDirWarned = false;
+
+  const resolveFor = (ctx: ExtensionContext): { config: ZcodeMemoryConfig; resolution: MemoryDirResolution } => {
+    const config = loadConfig(ctx.cwd);
+    // 配置里的相对路径按会话 cwd 解析，避免受进程启动目录影响
+    const configuredDir =
+      config.dir === undefined ? undefined : isAbsolute(config.dir) ? config.dir : resolve(ctx.cwd, config.dir);
+    const resolution = resolveMemoryDir({
+      cwd: ctx.cwd,
+      ...(configuredDir === undefined ? {} : { configDir: configuredDir }),
+    });
+    return { config, resolution };
+  };
+
+  const rebuildInjectionState = (ctx: ExtensionContext): void => {
+    // 会话投影只包含压缩后的保留尾部：注入消息被摘要掉后这里就找不到它了
+    const projection = ctx.sessionManager.buildSessionProjection();
+    injectedHash = rebuildInjectedHash(projection.entries.map((entry) => entry.sourceEntry));
+  };
+
+  pi.on("session_start", (_event, ctx) => {
+    forceInject = false;
+    missingDirWarned = false;
+    rebuildInjectionState(ctx);
+  });
+
+  pi.on("session_compact", (_event, ctx) => rebuildInjectionState(ctx));
+  pi.on("session_tree", (_event, ctx) => rebuildInjectionState(ctx));
+  pi.on("session_shutdown", () => {
+    injectedHash = undefined;
+    forceInject = false;
+  });
+
+  // ---------------------------------------------------------------------------
+  // 工具：memory_list / memory_read / memory_write
+  // ---------------------------------------------------------------------------
+
+  pi.registerTool({
+    name: "memory_list",
+    label: "Memory List",
+    description:
+      "List the fact files in the project memory directory shared with ZCode (filename / name / description / type / modified time). " +
+      "Memories are long-term facts, not a to-do list; use memory_read to see a body and memory_write to store a new fact. " +
+      "This list comes from the files on disk, so it does not depend on the MEMORY.md index being intact.",
+    promptSnippet: "List project memories shared with ZCode (long-term facts)",
+    parameters: Type.Object({}),
+    exposure: "direct",
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const { resolution } = resolveFor(ctx);
+      const text = formatMemoryListResult(resolution);
+      return { content: [{ type: "text", text }], details: detailsOf(resolution) };
+    },
+  });
+
+  const memoryReadParams = Type.Object({
+    name: Type.String({
+      description:
+        "The memory's name (the name in its frontmatter) or its filename, for example user-api-preference or user-api-preference.md; filenames in subdirectories work too.",
+    }),
+  });
+
+  pi.registerTool({
+    name: "memory_read",
+    label: "Memory Read",
+    description:
+      "Read one project memory's frontmatter summary and body. The parameter is the memory's name or filename. " +
+      "A body longer than 200 lines or 4096 bytes is truncated at the same limit ZCode uses when it recalls a memory, " +
+      "and the result says where to read the full text — so what you see here is what is actually usable in a session.",
+    promptSnippet: "Read the body of one project memory",
+    parameters: memoryReadParams,
+    exposure: "direct",
+    async execute(_toolCallId, params: Static<typeof memoryReadParams>, _signal, _onUpdate, ctx) {
+      const { resolution } = resolveFor(ctx);
+      const dir = resolution.dir;
+      if (dir === undefined) {
+        return {
+          content: [{ type: "text", text: noMemoryDirText(resolution) }],
+          details: detailsOf(resolution),
+          isError: true,
+        };
+      }
+      const located = locateMemory(dir, params.name);
+      if (!located.ok) {
+        return {
+          content: [{ type: "text", text: `Failed to read memory: ${located.error.message}` }],
+          details: { dir, code: located.error.code } satisfies MemoryToolDetails,
+          isError: true,
+        };
+      }
+      const memory = located.value;
+      const truncated = truncateMemoryBody(memory.body);
+      const text = formatMemoryReadResult(memory, truncated);
+      // 读态互通（票据 08）：在共享事件总线上登记"这个记忆文件刚被读成什么程度"。
+      // 没有安装 pi-read-guard 时总线上没有订阅者，emit 是 no-op——双方都不需要硬依赖。
+      // 截断读发布 kind: "truncated" 且不带 hash，read-guard 不会放行后续 edit。
+      pi.events.emit(
+        READ_STATE_EVENT,
+        buildReadStatePayload({
+          absolutePath: memory.absolutePath,
+          mtimeMs: memory.mtimeMs,
+          sizeBytes: memory.sizeBytes,
+          contentHash: memory.contentHash,
+          truncated: truncated.truncated,
+        }),
+      );
+      return {
+        content: [{ type: "text", text }],
+        details: {
+          dir,
+          filename: memory.filename,
+          absolutePath: memory.absolutePath,
+        } satisfies MemoryToolDetails,
+      };
+    },
+  });
+
+  const memoryWriteParams = Type.Object({
+    name: Type.String({
+      description:
+        "The memory's name, also used as its filename (.md optional); by convention a kebab-case slug of 3-4 words, for example user-api-preference.",
+    }),
+    description: Type.String({
+      description:
+        "One sentence describing what this memory is; it goes into the frontmatter and the MEMORY.md index line, and it is what ZCode uses to judge relevance when recalling memories.",
+    }),
+    type: Type.Union(
+      MEMORY_TYPES.map((value) => Type.Literal(value)),
+      {
+        description:
+          "user (who the user is) / feedback (working-style feedback the user gave) / project (ongoing project facts) / reference (where an external resource lives).",
+      },
+    ),
+    body: Type.String({
+      description:
+        "The memory body: one fact per file. For feedback / project memories the convention is **Why:** and **How to apply:**; link related memories with [[name]].",
+    }),
+    mode: Type.Union([Type.Literal("create"), Type.Literal("upsert")], {
+      description: "create errors when a memory with that name exists; upsert overwrites it and updates the index line.",
+    }),
+  });
+
+  pi.registerTool({
+    name: "memory_write",
+    label: "Memory Write",
+    description:
+      "Write one long-term fact into the project memory directory shared with ZCode, and maintain its MEMORY.md index line. " +
+      "Memories are long-term facts (user preferences, working-style feedback the user gave, project constraints, external resources), **not a to-do list**, " +
+      "and not temporary state that ends with the conversation; do not write down information that the repository code, git history, or this task already answers. " +
+      "Before writing, work out whether an existing memory covers the same thing: if so, upsert it rather than creating a duplicate entry.",
+    promptSnippet: "Write a long-term fact into the project memory shared with ZCode (not a to-do)",
+    parameters: memoryWriteParams,
+    exposure: "direct",
+    async execute(_toolCallId, params: Static<typeof memoryWriteParams>, _signal, _onUpdate, ctx) {
+      const { resolution } = resolveFor(ctx);
+      // 尚无记忆时按计算路径创建（三级回退第 3 步）；配置给了目录就以配置为准
+      const dir = resolution.dir ?? resolution.computedDir;
+      try {
+        // 全部写入串行化：同一记忆目录下的读-改-写不会互相踩
+        const outcome = await withFileMutationQueue(dir, () =>
+          writeMemory({
+            root: dir,
+            name: params.name,
+            description: params.description,
+            type: params.type,
+            body: params.body,
+            mode: params.mode,
+          }),
+        );
+        const action = outcome.fileAction === "created" ? "Created" : "Overwrote";
+        const indexAction =
+          outcome.indexAction === "inserted"
+            ? "index line added"
+            : outcome.indexAction === "updated"
+              ? "index line updated"
+              : "index line unchanged";
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `${action} memory ${outcome.filename}; MEMORY.md ${indexAction}.\n` +
+                `Memory directory: ${dir}\n` +
+                `ZCode sees this change only after it re-reads the index (new session / cold resume / /clear); that is a sync delay, not a failed write.`,
+            },
+          ],
+          details: {
+            dir,
+            filename: outcome.filename,
+            absolutePath: outcome.absolutePath,
+          } satisfies MemoryToolDetails,
+        };
+      } catch (error) {
+        if (error instanceof MemoryWriteError) {
+          const hint = error.hint === undefined ? "" : `\n${error.hint}`;
+          return {
+            content: [{ type: "text", text: `Failed to write memory: ${error.message}${hint}` }],
+            details: { dir, code: error.code } satisfies MemoryToolDetails,
+            isError: true,
+          };
+        }
+        throw error;
+      }
+    },
+  });
+
+  // ---------------------------------------------------------------------------
+  // 索引注入：一次注入 + 标记；hash 变化 / 被压缩掉 / /memory reload 时重注
+  // ---------------------------------------------------------------------------
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    // `pi.sendMessage(..., { triggerTurn: true })` 起的运行不算用户轮
+    if (event.messageType === "custom") return undefined;
+    const { config, resolution } = resolveFor(ctx);
+    if (!config.enabled || !config.injectIndex) return undefined;
+    const dir = resolution.dir;
+    if (dir === undefined) {
+      warnMissingMemoryDir(ctx, resolution);
+      return undefined;
+    }
+    const indexPath = join(dir, INDEX_FILENAME);
+    let raw: string;
+    try {
+      raw = await readFile(indexPath, "utf8");
+    } catch {
+      // 没有索引（或读不了）就不注入；清掉状态，等索引出现后重新注入
+      injectedHash = undefined;
+      return undefined;
+    }
+    const formatted = formatMemoryIndexForInjection(raw);
+    if (formatted.text.length === 0) return undefined;
+    const hash = memoryIndexHash(formatted.text);
+    const decision = decideInjection({
+      messageType: event.messageType,
+      enabled: config.enabled,
+      injectIndex: config.injectIndex,
+      indexPresent: true,
+      indexHash: hash,
+      injectedHash,
+      force: forceInject,
+    });
+    if (!decision.inject) return undefined;
+
+    injectedHash = hash;
+    forceInject = false;
+    pi.appendEntry(INJECTED_ENTRY_TYPE, { indexHash: hash });
+    return {
+      message: {
+        customType: INDEX_MESSAGE_TYPE,
+        content: buildInjectionText(dir, formatted.text, formatted.truncated),
+        display: false,
+        details: { indexHash: hash },
+      },
+    };
+  });
+
+  // ---------------------------------------------------------------------------
+  // /memory：状态 + 索引体检；/memory reload 强制下次运行重新注入
+  // ---------------------------------------------------------------------------
+
+  pi.registerCommand("memory", {
+    description: "查看共享记忆目录状态与索引体检；/memory reload 让下一次运行重新注入索引",
+    handler: async (args, ctx) => {
+      const subcommand = args.trim().toLowerCase();
+      if (subcommand === "reload") {
+        forceInject = true;
+        notify(ctx, "memory：下一次运行会重新注入 MEMORY.md 索引。", "info");
+        return;
+      }
+      if (subcommand.length > 0 && subcommand !== "status") {
+        notify(ctx, "memory：用法是 /memory（状态）或 /memory reload（强制重新注入）。", "warning");
+        return;
+      }
+      const { resolution } = resolveFor(ctx);
+      const dir = resolution.dir;
+      let indexContent: string | undefined;
+      if (dir !== undefined) {
+        try {
+          indexContent = await readFile(join(dir, INDEX_FILENAME), "utf8");
+        } catch {
+          indexContent = undefined;
+        }
+      }
+      const files: MemoryListEntry[] = dir === undefined ? [] : listMemoryFiles(dir);
+      const text = formatMemoryStatus({
+        resolution,
+        indexContent,
+        files,
+        injectionLabel: injectionLabel(resolution, indexContent, injectedHash, forceInject),
+      });
+      notify(ctx, text, "info");
+    },
+  });
+
+  function warnMissingMemoryDir(ctx: ExtensionContext, resolution: MemoryDirResolution): void {
+    if (missingDirWarned) return;
+    missingDirWarned = true;
+    const hint = resolution.warnings.length > 0 ? ` ${resolution.warnings[resolution.warnings.length - 1]}` : "";
+    notify(ctx, `memory：这次没有注入记忆索引——该项目尚无 ZCode 记忆。${hint}`, "warning");
+  }
+};
+
+function detailsOf(resolution: MemoryDirResolution): MemoryToolDetails {
+  return resolution.dir === undefined ? {} : { dir: resolution.dir };
+}
+
+function noMemoryDirText(resolution: MemoryDirResolution): string {
+  const warnings = resolution.warnings.map((warning) => `\nNote: ${warning}`).join("");
+  return (
+    `This project has no ZCode memory yet: the computed directory does not exist (${resolution.computedDir}). ` +
+    `memory_write creates it; if ZCode really has written memories for this project, set dir in the config to point at that directory. ` +
+    `${warnings}`
+  );
+}
+
+function formatMemoryListResult(resolution: MemoryDirResolution): string {
+  const dir = resolution.dir;
+  if (dir === undefined) return noMemoryDirText(resolution);
+  const entries = listMemoryFiles(dir);
+  const warnings = resolution.warnings.map((warning) => `Note: ${warning}`).join("\n");
+  const header = `Memory directory: ${dir}\nFact files: ${entries.length}`;
+  const body =
+    entries.length === 0
+      ? "(no fact files)"
+      : entries
+          .map((entry) => {
+            const mtime = new Date(entry.mtimeMs).toISOString();
+            if (entry.malformed) {
+              return `- ${entry.filename} (frontmatter cannot be parsed: treated as an entry with no description; modified ${mtime})`;
+            }
+            const type = entry.type === undefined ? "" : ` [${entry.type}]`;
+            const description = entry.description === undefined ? "" : ` — ${entry.description}`;
+            const name = entry.name === undefined ? "" : ` ${entry.name}`;
+            return `- ${entry.filename}${type}${name}${description} (modified ${mtime})`;
+          })
+          .join("\n");
+  return warnings.length === 0 ? `${header}\n${body}` : `${warnings}\n${header}\n${body}`;
+}
+
+function formatMemoryReadResult(
+  memory: {
+    filename: string;
+    absolutePath: string;
+    sizeBytes: number;
+    mtimeMs: number;
+    frontmatter: { name?: string; description?: string; type?: string; malformed: boolean };
+  },
+  truncated: { text: string; truncated: boolean; reason?: "lines" | "bytes" | "both" },
+): string {
+  const frontmatter = memory.frontmatter;
+  const lines: string[] = [];
+  lines.push(`File: ${memory.filename}`);
+  lines.push(
+    frontmatter.malformed
+      ? "frontmatter: cannot be parsed (treated as an entry with no description)"
+      : `name: ${frontmatter.name ?? "(none)"}; description: ${frontmatter.description ?? "(no description)"}; type: ${frontmatter.type ?? "(not set)"}`,
+  );
+  lines.push(`Size: ${memory.sizeBytes} bytes; modified: ${new Date(memory.mtimeMs).toISOString()}`);
+  lines.push("");
+  lines.push(truncated.text.length === 0 ? "(body is empty)" : truncated.text);
+  if (truncated.truncated) {
+    const why =
+      truncated.reason === "lines"
+        ? "the first 200 lines"
+        : truncated.reason === "bytes"
+          ? "4096 bytes"
+          : "the first 200 lines / 4096 bytes";
+    lines.push("");
+    lines.push(
+      `(body truncated: at most ${why} is read here, the same limit ZCode uses when recalling a memory. Use the built-in read tool to read the full content at ${memory.absolutePath}.)`,
+    );
+  }
+  return lines.join("\n");
+}
+
+function buildInjectionText(dir: string, indexText: string, truncated: boolean): string {
+  const lines = [
+    "Below is the cross-session automatic memory index for this project. It records long-term facts (who the user is, working-style feedback they gave, what the project is doing, where external resources live), not a to-do list for this turn.",
+    "",
+    `Memory directory: ${dir}`,
+    `Index: ${join(dir, INDEX_FILENAME)} (only the index appears in context; read bodies on demand with memory_read, and do not infer a body's content from its index line)`,
+  ];
+  if (truncated) lines.push("The index injected this time is a truncated excerpt (see the WARNING at the end).");
+  lines.push("", indexText);
+  return lines.join("\n");
+}
+
+function injectionLabel(
+  resolution: MemoryDirResolution,
+  indexContent: string | undefined,
+  injectedHash: string | undefined,
+  force: boolean,
+): string {
+  if (resolution.dir === undefined) return "未注入（尚无记忆目录）";
+  if (indexContent === undefined) return "未注入（索引不存在）";
+  if (force) return "已排队：下一次运行重新注入";
+  if (injectedHash === undefined) return "未注入（下一次运行会注入）";
+  return `已注入（hash ${injectedHash.slice(0, 12)}…）`;
+}
+
+/**
+ * 按设计共同约定 7：所有 UI 交互先看 `ctx.hasUI`。
+ *
+ * 非交互模式（print / json）没有 UI；显式守一道不是为了防崩，而是让"这里依赖渲染"
+ * 在代码里看得见——真实运行里 `ctx.ui` 的无操作实现会吞掉内容，静默通过很难被发现。
+ */
+function notify(
+  ctx: { hasUI: boolean; ui: { notify(message: string, kind?: "info" | "warning" | "error"): void } },
+  message: string,
+  kind?: "info" | "warning" | "error",
+): void {
+  if (!ctx.hasUI) return;
+  ctx.ui.notify(message, kind);
+}
+
+export default zcodeMemory;
+export { zcodeMemory as zcodeMemoryFactory };
+export type { ZcodeMemoryConfig };