dsh-continual-evolve 0.11.0 → 0.12.1

package/lib/index.js

@@ -1,127 +1,38 @@
 /**
- * dsh-continual-evolve — plugin entry (Phase 2: auto review gate).
+ * dsh-continual-evolve — plugin entry.
  *
- * Mounts the evolution engine, registers the model-facing evolve_* tools,
- * the human-facing /evolve command, the system-prompt guidance section, and
- * the dedicated Memory Agent listener. The listener is always registered so
- * an install works without profile edits; `autoReview` only supplies the
- * initial default when `evolve/runtime.json` does not exist yet, and
- * `/evolve pause|resume` own it afterwards. Generic review/planner/fate are
- * not reachable from this listener.
+ * After the 2026-10-04 ZCode-alignment teardown the plugin is one thing: a
+ * session-start system-prompt section that injects the workspace memory
+ * index (`<cwd>/.evolve/memory/MEMORY.md`), hands out the store path, and
+ * teaches the when-to-save guide. The model reads and writes the markdown
+ * files with its native tools; there are no plugin tools, no commands, no
+ * background extraction, and no governance. See
+ * .agents/notes/implemented/architecture/2026-10-04-zcode-alignment-teardown.md.
  *
- * evolve v2 registers a third section (`evolve:memory-index`) that injects
- * memory content plus the when_to_save guide, frozen per session — see
- * memory-index.ts.
+ * The 2026-10-04 plugin-management card adds a read-only surface: the
+ * workspace roots the section has served feed an in-memory allowlist, and a
+ * `webServer` route pair projects any known workspace's store for the card
+ * in the official plugin manager (`plugins.bundle.config`, client bundle in
+ * client/client.js). The card is a viewer — see
+ * .agents/notes/implemented/feature/2026-10-04-plugin-management-card.md.
+ *
+ * The host API surface is declared locally (the minimal shape this plugin
+ * touches) instead of importing the DSH type packages — the section call is
+ * the same one every prior release used, verified in production.
  */
-import { join } from "node:path";
 import z from "@deepseek-ai/schemastery";
-import { expandHomePath, resolveDshHome } from "@deepseek-ai/dsh-home-paths";
-import { createEvolutionEngine } from "./service.js";
-import { registerEvolveTools } from "./tool.js";
-import { registerEvolveCommand } from "./command.js";
-import { registerAutoReview } from "./listener.js";
-import { syncSkillsFromResult } from "./skill.js";
-import { entriesSectionText } from "./inject.js";
-import { createFrozenMemorySection, DEFAULT_MEMORY_INDEX_MAX_CHARS, DEFAULT_MEMORY_SECTION_ORDER, MEMORY_SECTION_NAME, memoryIndexSectionText, } from "./memory-index.js";
-import { resolveRubricKey } from "./rubric.js";
-import { restoreMounted } from "./mount.js";
-import { registerFileLogger } from "./logfile.js";
-import { resolvePromotionPolicy } from "./promotion.js";
+import { mountCardRoutes } from "./card-routes.js";
+import { createKnownWorkspaces } from "./known-workspaces.js";
+import { createFrozenMemorySection, cwdOf, DEFAULT_MAX_CHARS, DEFAULT_MEMORY_SECTION_ORDER, MEMORY_SECTION_NAME, memorySectionText, } from "./memory-section.js";
 export const name = "continual-evolve";
-/** Service key under which the evolution engine is published. */
-export const EVOLUTION_SERVICE = "evolution";
-export const inject = ["tools", "commands", "systemPrompt", "llm", "sessionQuery", "agents", "userQuestions", "subagents"];
+export const inject = ["systemPrompt"];
 export const Config = z.object({
-    /** Root for evolution stores; defaults to the resolved DSH home. */
-    baseDir: z.string(),
-    /** System-prompt section order for the evolution guidance. */
-    sectionOrder: z.natural().default(118),
-    /** Initial Memory Agent default when no `evolve/runtime.json` exists; not a registration gate. */
-    autoReview: z.boolean().default(false),
-    /** ZCode-style minimum lexical words in one direct user text part. */
-    memoryMinUserWords: z.natural().default(3),
-    /**
-     * Session-close bounded drain for in-flight extraction, in milliseconds.
-     * Absent → 15s; 0 restores the legacy immediate abort on dispose.
-     */
-    sessionCloseDrainMs: z.natural().default(15000),
-    /** Trajectory slice handed to the extractor, in characters. */
-    maxReviewInputChars: z.natural().default(40000),
-    /** Output budget for the cheap gate call. */
-    reviewBudgetTokens: z.natural().default(4096),
-    /**
-     * Planner prefix-cache routing for the gate and planner inputs: `auto`
-     * prepends a session-derived message prefix when the session shows
-     * cache-read evidence (dropping the redundant flat trajectory text),
-     * `session` always prefixes, `off` keeps the legacy flat-text input.
-     */
-    plannerPrefixCache: z.union([z.const("auto"), z.const("session"), z.const("off")]).default("auto"),
-    /** Session-prefix budget for Route A planning inputs, in characters. */
-    plannerPrefixMaxChars: z.natural().default(12000),
-    /** After an approved gate run with applied edits, queue a visible follow-up notice. */
-    notifyOnAutoReview: z.boolean().default(true),
-    /** Cross-session (global) edits require an explicit human approval. */
-    requireGlobalApproval: z.boolean().default(true),
-    /**
-     * Authoring language for evolution records (refinement summaries,
-     * rationales, entry titles/content, review and wrap-up verdicts).
-     * `auto` follows the DSH client language (durable `locale.preference`,
-     * then trajectory detection, then `en`); `zh`/`en` pin it.
-     */
-    recordLanguage: z.union([z.const("auto"), z.const("zh"), z.const("en")]).default("auto"),
-    /** Skills root for materialized skill entries; defaults to <dshHome>/skills. */
-    skillsDir: z.string(),
-    /** Passphrase for rubric encryption; falls back to DSH_EVOLVE_RUBRIC_KEY, then a local key file. */
-    rubricKey: z.string(),
-    /** Write all cordis log messages to <baseDir>/evolve/plugin.log (JSONL). */
-    logToFile: z.boolean().default(true),
-    /** File log level: 0=error, 1=info, 2=warn, 3=debug. */
-    logLevel: z.natural().default(1),
-    /** Rotate the file log when it exceeds this many bytes. */
-    logMaxBytes: z.natural().default(5 * 1024 * 1024),
-    /** After a benchmark decision rejects a candidate, roll the refinement back automatically. */
-    autoRollbackOnReject: z.boolean().default(true),
-    /**
-     * P1 auto-case capture: failed evolution attempts (benchmark-rejected
-     * candidates, gate proposals without consent) land as draft cases in the
-     * auto-regression container benchmark, seeding the regression loop.
-     */
-    autoCase: z.boolean().default(true),
-    /**
-     * Optional model override for the memory extractor (cheaper model).
-     * Format: "provider/model" or just "model" (same provider as the agent).
-     * When absent, the extractor uses the agent's own provider/model.
-     */
-    reviewModel: z.string(),
-    /**
-     * Goal-blocked moment: after this many CONSECUTIVE idle probes that
-     * observe the session goal in phase "blocked", run one memory extraction
-     * so the stuck encounter is distilled. 0 disables.
-     */
-    goalBlockedWrapupTurns: z.natural().min(0).default(3),
-    /**
-     * Promotion policy (2026-08-22): regex sources whose match in a
-     * candidate's title/content marks it project-scoped — such entries are
-     * never promoted to the cross-session global store. Replaces the built-in
-     * defaults when set.
-     */
     /**
-     * Promotion policy (2026-08-22): regex sources whose match in a
-     * candidate's title/content marks it project-scoped — such entries are
-     * never promoted to the cross-session global store. Replaces the built-in
-     * defaults when set.
-     */
-    promotionBlockPatterns: z.array(z.string()),
-    /** Whole promotions below this content length stay local (chars). */
-    promotionMinChars: z.natural().default(100),
-    /** Entry-directory lines injected per build before folding into a counter. */
-    injectionDirectoryLines: z.natural().default(15),
-    /**
-     * evolve v2 memory index: the section that injects memory CONTENT (not just
-     * an id/title directory) at session start, frozen per session to keep the
-     * system prompt byte-stable (prompt cache). `enabled`/`guide`/`order`/
-     * `maxChars` default to true/true/400/6000; with `guide` off and an empty
-     * store the section renders to "" and costs no tokens.
+     * The memory section: injects the workspace memory index at session
+     * start, frozen per session to keep the system prompt byte-stable
+     * (prompt cache). `enabled`/`guide`/`order`/`maxChars` default to
+     * true/true/400/6000; with `guide` off and an empty store the section
+     * renders to "" and costs no tokens.
      */
     memoryIndex: z.object({
         enabled: z.boolean(),
@@ -130,130 +41,59 @@ export const Config = z.object({
         maxChars: z.natural(),
     }),
     /**
-     * Storage hygiene (#20): how much append-only past each write keeps.
-     * `snapshots` = full-state copies per store, `refinements` = tail lines
-     * per store history, `reviews` = tail lines of the shared audit trail,
-     * `tokenUsage` = tail lines of the direct-call token ledger.
-     * Absent fields fall back to the store defaults (20 / 500 / 500 / 500) —
-     * rollback needs recent snapshots, readers need a recent window.
+     * The read-only memory card in the official plugin manager
+     * (`plugins.bundle.config`). Defaults to on; hosts without the
+     * `webServer` service or the `plugins.bundle.config` slot degrade to no
+     * card, with the memory section unaffected.
      */
-    historyRetain: z.object({
-        snapshots: z.natural(),
-        refinements: z.natural(),
-        reviews: z.natural(),
-        tokenUsage: z.natural(),
+    memoryCard: z.object({
+        enabled: z.boolean(),
     }),
 });
-export function apply(ctx, config) {
-    const baseDir = resolveDshHome(config.baseDir);
-    const skillsRoot = config.skillsDir ? expandHomePath(config.skillsDir) : join(baseDir, "skills");
-    const engine = createEvolutionEngine(baseDir, {
-        onApplied: (result) => {
-            try {
-                const warnings = syncSkillsFromResult(skillsRoot, result);
-                for (const warning of warnings) {
-                    ctx.logger("continual-evolve").warn(warning);
-                }
-            }
-            catch (cause) {
-                ctx
-                    .logger("continual-evolve")
-                    .warn(`skill materialization failed for ${result.id}: ${cause instanceof Error ? cause.message : String(cause)}`);
-            }
-        },
-    }, config.historyRetain ? { historyRetain: { ...config.historyRetain } } : {});
-    ctx.provide(EVOLUTION_SERVICE, { engine, baseDir });
-    ctx.systemPrompt.section({
-        name: "tool:continual-evolve",
-        order: config.sectionOrder ?? 118,
-        text: "You have a continual harness: versioned, persistent prompt notes, memories, skills, and subagent specs. Memories are ONE FACT per entry, typed user/feedback/project/reference (feedback = pitfall + Why + How to apply). Stores: local (this session's staging), project (this project's cross-session store), global (cross-project). Prompt notes and delegation specs are injected below; use evolve_list for the full state. Create an entry (evolve_add) after a repeated failure, a reusable tactic, a durable fact or preference, a repeated procedure, or a repeated delegation role. Keep edits small and evidence-backed; prefer local scope, use project for repo-specific lessons, global: true only for stable cross-project lessons. Update or delete (evolve_update / evolve_delete) when an entry is wrong or obsolete; roll back faulty refinements with evolve_rollback. Every edit is snapshotted, versioned, and recorded — no edit can be silently lost.",
-    });
-    // Phase 2: make prompt entries real system-prompt content and subagent
-    // entries real delegation specs. The text is a provider evaluated at every
-    // assembly with the assembling agent; a store without prompt/subagent
-    // entries renders to "" and the prompt renderer drops the section.
-    //
-    // evolve v2: when the memory index section carries memory content, the
-    // directory stops listing memories so the same entries are never paid for
-    // twice (one fact, one home).
-    const memoryIndexEnabled = config.memoryIndex?.enabled ?? true;
-    ctx.systemPrompt.section({
-        name: "tool:continual-evolve:entries",
-        order: (config.sectionOrder ?? 118) + 1,
-        text: (context) => entriesSectionText(engine, context.agent, undefined, {
-            directoryLines: config.injectionDirectoryLines ?? 15,
-            includeMemoryDirectory: !memoryIndexEnabled,
-        }),
-    });
-    // evolve v2 passive read path: memory content in the prompt at session
-    // start, frozen per session (see memory-index.ts) so the whole system
-    // prompt stays byte-stable within a session and prompt-cache reads keep
-    // hitting. Registered in the empty 1–499 order slot — the two sections
-    // above sit at 118/119, upstream's named slots start at PLAN_POLICY=500.
-    if (memoryIndexEnabled) {
-        const frozenMemories = createFrozenMemorySection();
-        const memoryIndexOrder = config.memoryIndex?.order ?? DEFAULT_MEMORY_SECTION_ORDER;
-        const memoryIndexMaxChars = config.memoryIndex?.maxChars ?? DEFAULT_MEMORY_INDEX_MAX_CHARS;
-        const memoryIndexGuide = config.memoryIndex?.guide ?? true;
-        ctx.systemPrompt.section({
-            name: MEMORY_SECTION_NAME,
-            order: memoryIndexOrder,
-            text: (context) => frozenMemories.textFor(context.agent, (agent) => memoryIndexSectionText(engine, agent, { maxChars: memoryIndexMaxChars, guide: memoryIndexGuide })),
-        });
+/**
+ * Mount the card routes on the host web server through a nested inject, so
+ * the plugin stays mountable on hosts without that service. Called only when
+ * the card is enabled.
+ */
+function mountCardWhenAvailable(host, workspaces) {
+    const nested = host;
+    if (typeof nested.inject !== "function") {
+        host.logger("continual-evolve").warn("host context exposes no inject — memory card routes not mounted (memory section unaffected)");
+        return;
     }
-    const gate = {
-        requireGlobalApproval: config.requireGlobalApproval ?? true,
-        ...(config.recordLanguage !== undefined ? { recordLanguage: config.recordLanguage } : {}),
-    };
-    const promotionPolicy = resolvePromotionPolicy({
-        blockPatterns: config.promotionBlockPatterns,
-        minPromoteChars: config.promotionMinChars,
-    });
-    registerEvolveTools(ctx, engine, gate);
-    const rubricKey = resolveRubricKey(baseDir, config.rubricKey, process.env, (m) => ctx.logger("continual-evolve").warn(m));
-    registerEvolveCommand(ctx, engine, gate, {
-        rubricKey,
-        autoRollbackOnReject: config.autoRollbackOnReject ?? true,
-        autoCase: config.autoCase ?? true,
-        promotionPolicy,
-        autoReview: config.autoReview ?? false,
-        ...(config.recordLanguage !== undefined ? { recordLanguage: config.recordLanguage } : {}),
+    nested.inject(["webServer"], (scoped) => {
+        const webServer = scoped.webServer;
+        if (webServer === undefined) {
+            host.logger("continual-evolve").warn("webServer service present but empty — memory card routes not mounted (memory section unaffected)");
+            return;
+        }
+        mountCardRoutes(webServer, workspaces);
     });
-    // Plugin-owned file logging: every cordis log message lands in
-    // <baseDir>/evolve/plugin.log regardless of how dsh web was launched —
-    // no extra component to install, no startup-script dependency.
-    if (config.logToFile !== false) {
-        registerFileLogger(ctx, baseDir, {
-            logLevel: config.logLevel ?? 1,
-            ...(config.logMaxBytes !== undefined ? { logMaxBytes: config.logMaxBytes } : {}),
-        });
+}
+export function apply(host, config) {
+    if (config.memoryIndex?.enabled === false) {
+        return;
     }
-    // v2 optional: restore hot-mounted skill plugins after a restart.
-    void restoreMounted(ctx, baseDir).catch((cause) => {
-        ctx.logger("continual-evolve").warn(`mount restore failed: ${cause instanceof Error ? cause.message : String(cause)}`);
-    });
-    // The memory extraction listener is always registered: an install must
-    // work without profile edits, so `autoReview` is only the initial default
-    // when no `evolve/runtime.json` exists yet — `/evolve pause|resume` own
-    // the switch afterwards. Extraction is moment-driven: compaction,
-    // goal-blocked streaks, the session-close drain, and manual
-    // `/evolve wrapup` — successful turns never cost an LLM call.
-    registerAutoReview(ctx, engine, {
-        enabledByDefault: config.autoReview ?? false,
-        memoryMinUserWords: config.memoryMinUserWords ?? 3,
-        sessionCloseDrainMs: config.sessionCloseDrainMs ?? 15000,
-        maxInputChars: config.maxReviewInputChars ?? 40000,
-        budgetTokens: config.reviewBudgetTokens ?? 4096,
-        notifyOnAutoReview: config.notifyOnAutoReview ?? true,
-        goalBlockedWrapupTurns: config.goalBlockedWrapupTurns ?? 3,
-        ...(config.historyRetain?.reviews !== undefined ? { reviewsRetain: config.historyRetain.reviews } : {}),
-        ...(config.reviewModel ? { reviewModel: config.reviewModel } : {}),
-        requireGlobalApproval: config.requireGlobalApproval ?? true,
-        ...(config.plannerPrefixCache ? { prefixCacheMode: config.plannerPrefixCache } : {}),
-        ...(config.plannerPrefixMaxChars !== undefined ? { prefixMaxChars: config.plannerPrefixMaxChars } : {}),
-        ...(config.recordLanguage !== undefined ? { recordLanguage: config.recordLanguage } : {}),
+    const workspaces = createKnownWorkspaces();
+    const frozen = createFrozenMemorySection();
+    host.systemPrompt.section({
+        name: MEMORY_SECTION_NAME,
+        order: config.memoryIndex?.order ?? DEFAULT_MEMORY_SECTION_ORDER,
+        text: (context) => {
+            const cwd = cwdOf(context.agent);
+            if (cwd !== undefined) {
+                workspaces.remember(cwd);
+            }
+            return frozen.textFor(context.agent, (agent) => memorySectionText(agent, {
+                maxChars: config.memoryIndex?.maxChars ?? DEFAULT_MAX_CHARS,
+                guide: config.memoryIndex?.guide ?? true,
+            }));
+        },
     });
-    ctx.logger("continual-evolve").info("continual-evolve moment-driven memory extraction listener registered (compaction / goal-blocked / session-close drain; manual wrapup via /evolve wrapup)");
-    ctx.logger("continual-evolve").info(`continual-evolve mounted (baseDir=${baseDir})`);
+    host.logger("continual-evolve").info("continual-evolve memory section registered (workspace .evolve/memory, native file read/write)");
+    if (config.memoryCard?.enabled === false) {
+        return;
+    }
+    mountCardWhenAvailable(host, workspaces);
 }
 //# sourceMappingURL=index.js.map

package/lib/known-workspaces.d.ts

@@ -0,0 +1,22 @@
+/** One known workspace: the resolved root and when it was last served. */
+export interface KnownWorkspace {
+    root: string;
+    /** ISO timestamp of the most recent section assembly seen for this root. */
+    lastSeen: string;
+}
+/** The allowlist the card routes read through. */
+export interface KnownWorkspaces {
+    /**
+     * Record (or refresh) a workspace root. A relative or blank cwd is a
+     * silent no-op — the caller is the injection path, where a bad cwd
+     * already renders an empty section and must not turn into a throw.
+     */
+    remember(cwd: string): void;
+    /** Known roots, most recently served first. */
+    list(): KnownWorkspace[];
+}
+/** How many recent workspaces the card tracks. */
+export declare const DEFAULT_KNOWN_WORKSPACE_LIMIT = 8;
+/** Create the in-memory allowlist; `limit` is the LRU bound. */
+export declare function createKnownWorkspaces(limit?: number): KnownWorkspaces;
+//# sourceMappingURL=known-workspaces.d.ts.map

package/lib/known-workspaces.js

@@ -0,0 +1,42 @@
+/**
+ * The workspace roots the card may look at, in memory only.
+ *
+ * Populated as a side effect of section assembly (the plugin already knows
+ * each session's cwd there), this list is the card's read allowlist: the
+ * memory API refuses any root the running process has not served a session
+ * in, so the endpoint cannot be used to probe the filesystem. Bounded LRU,
+ * never persisted — a restart starts empty and one session in a workspace
+ * puts it back. No second store on disk.
+ */
+import { isAbsolute, resolve } from "node:path";
+/** How many recent workspaces the card tracks. */
+export const DEFAULT_KNOWN_WORKSPACE_LIMIT = 8;
+/** Create the in-memory allowlist; `limit` is the LRU bound. */
+export function createKnownWorkspaces(limit = DEFAULT_KNOWN_WORKSPACE_LIMIT) {
+    const max = Math.max(1, limit);
+    // Insertion order encodes recency: the most recently served root is last.
+    const recent = new Map();
+    return {
+        remember(cwd) {
+            const trimmed = cwd.trim();
+            if (trimmed.length === 0 || !isAbsolute(trimmed)) {
+                return;
+            }
+            recent.delete(resolve(trimmed));
+            recent.set(resolve(trimmed), new Date().toISOString());
+            while (recent.size > max) {
+                const oldest = recent.keys().next();
+                if (oldest.done === true) {
+                    break;
+                }
+                recent.delete(oldest.value);
+            }
+        },
+        list() {
+            return [...recent.entries()]
+                .reverse()
+                .map(([root, lastSeen]) => ({ root, lastSeen }));
+        },
+    };
+}
+//# sourceMappingURL=known-workspaces.js.map

package/lib/memory-guide.d.ts

@@ -1,19 +1,18 @@
 /**
- * The persistent-memory guide injected as part of the `evolve:memory-index`
- * system-prompt section (evolve v2, change two).
+ * The persistent-memory guide injected as part of the memory section.
  *
- * This text is the write-path half of the v2 plan: it teaches the model when a
- * durable memory is worth creating, which recall type it belongs to, what body
- * structure each type owes, and that the main session may write directly with
- * `evolve_add` instead of waiting for the background pipeline.
+ * This text is the write-path half of the ZCode-aligned design: it teaches
+ * the model when a durable memory is worth creating, which type it belongs
+ * to, what body structure each type owes, and that memories are plain
+ * markdown files written directly with the native file tools — the plugin
+ * registers no tools and no commands.
  *
- * Provenance: `docs/research/evolve-v2-passive-read-write-plan.md` §改动二
- * (Chinese full text, adapted from ZCode's persistent-memory prompt). Kept in
- * its own module so the wording is a single home — `memory-index.ts` only
- * composes it with the `<memories>` block.
+ * Provenance: the when_to_save taxonomy is adapted from ZCode's persistent-
+ * memory prompt (introduced here in evolve v2); the write-path wording now
+ * targets native file operations on `<workspace>/.evolve/memory/`.
  */
-/** Heading and framing before the `<memories>` block. */
-export declare const MEMORY_GUIDE_INTRO = "# \u6301\u4E45\u8BB0\u5FC6\n\n\u4F60\u6709\u4E00\u4E2A\u8DE8\u4F1A\u8BDD\u7684\u6301\u4E45\u8BB0\u5FC6\u7CFB\u7EDF\u3002\u4EE5\u4E0B\u662F\u5F53\u524D\u8BB0\u5FC6\uFF08\u5DF2\u76F4\u63A5\u6CE8\u5165\uFF0C\u65E0\u9700\u67E5\u8BE2\u5373\u53EF\u4F7F\u7528\uFF1B\u9700\u8981\u68C0\u7D22\u5B8C\u6574\u5185\u5BB9\u6216\u786E\u8BA4\u662F\u5426\u6709\u76F8\u5173\u8BB0\u5FC6\u65F6\uFF0C\u8C03\u7528 evolve_recall\uFF09\u3002\u672C\u4F1A\u8BDD\u5185\u53EF\u4EE5\u76F4\u63A5\u7528 evolve_add \u843D\u76D8\uFF0C\u4E0D\u5FC5\u7B49\u540E\u53F0\u6D41\u7A0B\u2014\u2014\u9ED8\u8BA4\u5199 local\uFF0C\u53EA\u6709\u7A33\u5B9A\u7684\u8DE8\u9879\u76EE\u6559\u8BAD\u624D\u5199 global\uFF08global \u5199\u5165\u4F1A\u5F39\u4EBA\u5DE5\u6279\u51C6\uFF09\u3002";
-/** The when_to_save / how_to_use rules and maintenance discipline. */
-export declare const MEMORY_GUIDE_RULES = "## \u4F55\u65F6\u5199\u5165\u8BB0\u5FC6\n\n\u7528\u6237\u660E\u786E\u8981\u6C42\u8BB0\u4F4F\u65F6\uFF0C\u7ACB\u5373\u5B58\u4E3A\u6700\u5408\u9002\u7684\u7C7B\u578B\uFF1B\u8981\u6C42\u5FD8\u8BB0\u65F6\uFF0C\u627E\u5230\u5E76\u5220\u9664\u76F8\u5173\u6761\u76EE\u3002\n\u9664\u6B64\u4E4B\u5916\uFF0C\u5728\u5BF9\u8BDD\u4E2D\u81EA\u7136\u9047\u5230\u4EE5\u4E0B\u4FE1\u53F7\u65F6\u4E3B\u52A8\u5199\u5165\u3002\u5B58\u4E4B\u524D\u5148\u8FC7\u4E00\u9053\u7B5B\u5B50\uFF1A\n**\u80FD\u4ECE\u4EE3\u7801\u3001git \u5386\u53F2\u3001\u4ED3\u5E93\u6587\u4EF6\u91CC\u91CD\u65B0\u63A8\u5BFC\u51FA\u6765\u7684\u4E8B\u5B9E\u4E0D\u5B58**\u2014\u2014\u53EA\u5B58\u91CD\u63A8\u5BFC\u4E0D\u51FA\u6765\u7684\n\u80CC\u666F\u3001\u51B3\u7B56\u548C\u504F\u597D\u3002\u76F8\u5BF9\u65E5\u671F\u4E00\u5F8B\u8F6C\u6210\u7EDD\u5BF9\u65E5\u671F\uFF08\"\u5468\u56DB\"\u2192\"2026-10-08\"\uFF09\uFF0C\u5426\u5219\u672A\u6765\n\u7684\u4F1A\u8BDD\u65E0\u6CD5\u89E3\u8BFB\u3002\u4E00\u6761\u4E8B\u5B9E\u4E00\u4E2A\u6761\u76EE\uFF1B\u4E0D\u786E\u5B9A\u503C\u4E0D\u503C\u5F97\u5B58\u65F6\uFF0C\u95EE\u81EA\u5DF1\"\u8FD9\u6761\u7684\u4FE1\u606F\u91CF\n\u662F\u5426\u5728'\u4E3A\u4EC0\u4E48'\u91CC\uFF0C\u800C\u4E0D\u5728'\u662F\u4EC0\u4E48'\u91CC\"\u3002\n\n<type name=\"user\">\n  <when_to_save>\u5F97\u77E5\u7528\u6237\u7684\u89D2\u8272\u3001\u6280\u672F\u6808\u3001\u7ECF\u9A8C\u6C34\u5E73\u3001\u504F\u597D\u6216\u77E5\u8BC6\u80CC\u666F\u7684\u4EFB\u4F55\u7EC6\u8282\u65F6\u3002\n  \u4F8B\u5982\u7528\u6237\u81EA\u8FF0\"\u6211\u662F\u6570\u636E\u79D1\u5B66\u5BB6\uFF0C\u5728\u67E5\u65E5\u5FD7\u7CFB\u7EDF\"\u2014\u2014\u5B58\uFF1A\u7528\u6237\u662F\u6570\u636E\u79D1\u5B66\u5BB6\uFF0C\n  \u5F53\u524D\u5173\u6CE8\u53EF\u89C2\u6D4B\u6027/\u65E5\u5FD7\u3002</when_to_save>\n  <how_to_use>\u540E\u7EED\u89E3\u91CA\u548C\u5EFA\u8BAE\u6309\u7528\u6237\u7684\u80CC\u666F\u5B9A\u5236\u6DF1\u6D45\u4E0E\u7C7B\u6BD4\uFF1B\u5BF9\u8D44\u6DF1\u5DE5\u7A0B\u5E08\n  \u4E0D\u89E3\u91CA\u57FA\u7840\u6982\u5FF5\uFF0C\u5BF9\u67D0\u9886\u57DF\u7684\u65B0\u624B\u7528\u5176\u719F\u6089\u9886\u57DF\u7684\u7C7B\u6BD4\u5207\u5165\u3002</how_to_use>\n</type>\n\n<type name=\"feedback\">\n  <when_to_save>\u4E24\u6761\u4FE1\u53F7\uFF0C\u7F3A\u4E00\u4E0D\u53EF\uFF1A\n  \uFF081\uFF09\u7EA0\u6B63\u2014\u2014\u7528\u6237\u8BF4\"\u4E0D\u662F\u8FD9\u6837\"\"\u522B\"\"\u505C\u4E0B\"\u65F6\uFF0C\u5B58\u88AB\u7EA0\u6B63\u7684\u505A\u6CD5\u4E0E\u6B63\u786E\u505A\u6CD5\uFF1B\n  \uFF082\uFF09\u786E\u8BA4\u2014\u2014\u8FD9\u662F\u66F4\u5B89\u9759\u3001\u66F4\u5BB9\u6613\u6F0F\u7684\u4FE1\u53F7\uFF1A\u7528\u6237\u63A5\u53D7\u4E86\u4F60\u4E0D\u5BFB\u5E38\u7684\u9009\u62E9\u800C\u6CA1\u6709\u5F02\u8BAE\uFF0C\n  \u6216\u660E\u786E\u8BF4\"\u5BF9\uFF0C\u5C31\u8FD9\u6837\"\"\u4FDD\u6301\u8FD9\u6837\"\u3002\u786E\u8BA4\u8FC7\u7684\u5224\u65AD\u662F\u5DF2\u9A8C\u8BC1\u7684\u65B9\u6CD5\u8BBA\uFF0C\u53EA\u5B58\u7EA0\u9519\n  \u4F1A\u8BA9\u4F60\u7684\u884C\u4E3A\u8D8A\u6765\u8D8A\u4FDD\u5B88\u3001\u504F\u79BB\u7528\u6237\u5DF2\u8BA4\u53EF\u7684\u8DEF\u3002\n  \u4F8B\uFF1A\"\u6D4B\u8BD5\u522B mock \u6570\u636E\u5E93\uFF0C\u4E0A\u6B21 mock \u8FC7\u4E86\u7EBF\u4E0A\u8FC1\u79FB\u6302\u4E86\"\u2014\u2014\u5B58\u89C4\u5219\u5E76\u5E26\u4E0A\u4E8B\u6545\u539F\u56E0\u3002\n  \u4F8B\uFF1A\"\u7ED3\u5C3E\u4E0D\u7528\u603B\u7ED3\uFF0Cdiff \u6211\u81EA\u5DF1\u4F1A\u770B\"\u2014\u2014\u5B58\uFF1A\u8BE5\u7528\u6237\u4E0D\u8981\u5C3E\u968F\u6027\u603B\u7ED3\u3002</when_to_save>\n  <how_to_use>\u8BA9\u7528\u6237\u4E0D\u5FC5\u628A\u540C\u4E00\u6761\u6307\u5BFC\u8BF4\u7B2C\u4E8C\u904D\u3002</how_to_use>\n  <body_structure>\u89C4\u5219\u5148\u884C\uFF0C\u968F\u540E\u5FC5\u5E26\u4E24\u884C\uFF1A**Why:**\uFF08\u7528\u6237\u7ED9\u7684\u7406\u7531\uFF0C\u5E38\u662F\u67D0\u6B21\n  \u4E8B\u6545\u6216\u5F3A\u504F\u597D\u2014\u2014\u77E5\u9053\u4E3A\u4EC0\u4E48\u624D\u80FD\u5224\u65AD\u8FB9\u7F18\u60C5\u51B5\u8BE5\u4E0D\u8BE5\u7834\u4F8B\uFF09\u548C **How to apply:**\n  \uFF08\u4F55\u65F6\u4F55\u5730\u751F\u6548\uFF09\u3002feedback \u7C7B\u578B\u7F3A\u8FD9\u4E24\u884C\u89C6\u4E3A\u4E0D\u5B8C\u6574\u3002</body_structure>\n</type>\n\n<type name=\"project\">\n  <when_to_save>\u5F97\u77E5\u8FDB\u884C\u4E2D\u7684\u5DE5\u4F5C\u3001\u76EE\u6807\u3001\u51B3\u7B56\u3001\u622A\u6B62\u671F\u6216\u4E8B\u6545\u7684\u80CC\u666F\u52A8\u673A\u65F6\u2014\u2014\n  \u51E1\u662F\"\u8C01\u5728\u505A\u4EC0\u4E48\u3001\u4E3A\u4EC0\u4E48\u3001\u5230\u4EC0\u4E48\u65F6\u5019\"\u4E14\u65E0\u6CD5\u4ECE\u4EE3\u7801\u6216 git \u63A8\u5BFC\u7684\u4FE1\u606F\u3002\n  \u8FD9\u7C7B\u8BB0\u5FC6\u8870\u51CF\u5FEB\uFF0C\u72B6\u6001\u53D8\u5316\u65F6\u66F4\u65B0\u5B83\uFF0C\u522B\u5806\u53E0\u65B0\u6761\u76EE\u3002</when_to_save>\n  <how_to_use>\u7528\u5B83\u8865\u5168\u8BF7\u6C42\u80CC\u540E\u7684\u4E0A\u4E0B\u6587\u4E0E\u52A8\u673A\uFF0C\u8BA9\u5EFA\u8BAE\u8D34\u4F4F\u771F\u5B9E\u7EA6\u675F\u3002\n  \u4F8B\uFF1A\"\u5468\u56DB\u8D77\u51BB\u7ED3\u5408\u5E76\"\u2014\u2014\u5B58\uFF1A2026-03-05 \u8D77\u51BB\u7ED3\u5408\u5E76\uFF0C\u975E\u5173\u952E PR \u63D0\u524D\u6807\u8BB0\u3002</how_to_use>\n  <body_structure>\u4E8B\u5B9E/\u51B3\u7B56\u5148\u884C + **Why:**\uFF08\u52A8\u673A\uFF1A\u7EA6\u675F\u3001deadline\u3001\u5E72\u7CFB\u4EBA\u8981\u6C42\uFF09\n  + **How to apply:**\uFF08\u8FD9\u6761\u5982\u4F55\u5F71\u54CD\u540E\u7EED\u5EFA\u8BAE\uFF09\u3002</body_structure>\n</type>\n\n<type name=\"reference\">\n  <when_to_save>\u7528\u6237\u63D0\u5230\u672A\u6765\u4F1A\u7528\u5230\u7684\u5916\u90E8\u8D44\u6E90\u6307\u9488\uFF1AURL\u3001\u4EEA\u8868\u76D8\u3001\u5DE5\u5355\u3001\n  \u6587\u6863\u4F4D\u7F6E\u3002</when_to_save>\n  <how_to_use>\u9700\u8981\u65F6\u76F4\u63A5\u53D6\u7528\uFF0C\u4E0D\u91CD\u65B0\u68C0\u7D22\u3002</how_to_use>\n</type>\n\n## \u5982\u4F55\u7EF4\u62A4\n\n- \u66F4\u65B0\u4F18\u5148\u4E8E\u65B0\u5EFA\uFF1A\u72B6\u6001\u53D8\u4E86\u6539\u539F\u6761\u76EE\uFF0C\u4E0D\u53E6\u8D77\u4E00\u6761\uFF08\u65B0\u65E7\u5E76\u5B58\u6BD4\u6CA1\u6709\u8BB0\u5FC6\u66F4\u7CDF\uFF09\u3002\n- \u6BCF\u6761\u7684 description \u662F\u7ED9\u672A\u6765\u4F1A\u8BDD\u7684\u76F8\u5173\u6027 hook\u2014\u2014\u5199\"\u51B3\u5B9A\u4E86\u4E00\u6761\u8BB0\u5FC6\u4F1A\u4E0D\u4F1A\n  \u88AB\u60F3\u8D77\"\u7684\u4E00\u53E5\u8BDD\uFF0C\u4E0D\u5199\u6D41\u6C34\u8D26\u3002\n- [[\u540D\u5B57]] \u4E92\u76F8\u5F15\u7528\u76F8\u5173\u8BB0\u5FC6\uFF1B\u5F15\u7528\u8FD8\u4E0D\u5B58\u5728\u7684\u540D\u5B57\u662F\u5408\u6CD5\u7684\uFF0C\u5B83\u6807\u8BB0\"\u503C\u5F97\u5C06\u6765\u8865\u5199\"\u3002";
+/** Heading and framing before the `<memories>` block. Takes the absolute memory dir. */
+export declare function memoryGuideIntro(memoryDir: string): string;
+/** The file format, when_to_save / how_to_use rules, and maintenance discipline. */
+export declare const MEMORY_GUIDE_RULES = "## \u8BB0\u5FC6\u6587\u4EF6\u7684\u683C\u5F0F\n\n---\nname: <\u77ED\u6A2A\u7EBF\u5C0F\u5199\u6807\u8BC6>\ndescription: <\u4E00\u53E5\u8BDD\u76F8\u5173\u6027\u94A9\u5B50\u2014\u2014\u51B3\u5B9A\u672A\u6765\u4F1A\u8BDD\u4F1A\u4E0D\u4F1A\u60F3\u8D77\u8FD9\u6761\u8BB0\u5FC6>\nmetadata:\n  type: user | feedback | project | reference\n---\n\n<\u6B63\u6587>\n\n## \u4F55\u65F6\u5199\u5165\u8BB0\u5FC6\n\n\u7528\u6237\u660E\u786E\u8981\u6C42\u8BB0\u4F4F\u65F6\uFF0C\u7ACB\u5373\u5B58\u4E3A\u6700\u5408\u9002\u7684\u7C7B\u578B\uFF1B\u8981\u6C42\u5FD8\u8BB0\u65F6\uFF0C\u627E\u5230\u5E76\u5220\u9664\u76F8\u5173\u6587\u4EF6\u4E0E\u7D22\u5F15\u884C\u3002\n\u9664\u6B64\u4E4B\u5916\uFF0C\u5728\u5BF9\u8BDD\u4E2D\u81EA\u7136\u9047\u5230\u4EE5\u4E0B\u4FE1\u53F7\u65F6\u4E3B\u52A8\u5199\u5165\u3002\u5B58\u4E4B\u524D\u5148\u8FC7\u4E00\u9053\u7B5B\u5B50\uFF1A\n**\u80FD\u4ECE\u4EE3\u7801\u3001git \u5386\u53F2\u3001\u4ED3\u5E93\u6587\u4EF6\u91CC\u91CD\u65B0\u63A8\u5BFC\u51FA\u6765\u7684\u4E8B\u5B9E\u4E0D\u5B58**\u2014\u2014\u53EA\u5B58\u91CD\u63A8\u5BFC\u4E0D\u51FA\u6765\u7684\n\u80CC\u666F\u3001\u51B3\u7B56\u548C\u504F\u597D\u3002\u76F8\u5BF9\u65E5\u671F\u4E00\u5F8B\u8F6C\u6210\u7EDD\u5BF9\u65E5\u671F\uFF08\"\u5468\u56DB\"\u2192\"2026-10-08\"\uFF09\uFF0C\u5426\u5219\u672A\u6765\n\u7684\u4F1A\u8BDD\u65E0\u6CD5\u89E3\u8BFB\u3002\u4E00\u6761\u4E8B\u5B9E\u4E00\u4E2A\u6587\u4EF6\uFF1B\u4E0D\u786E\u5B9A\u503C\u4E0D\u503C\u5F97\u5B58\u65F6\uFF0C\u95EE\u81EA\u5DF1\"\u8FD9\u6761\u7684\u4FE1\u606F\u91CF\n\u662F\u5426\u5728'\u4E3A\u4EC0\u4E48'\u91CC\uFF0C\u800C\u4E0D\u5728'\u662F\u4EC0\u4E48'\u91CC\"\u3002\n\n<type name=\"user\">\n  <when_to_save>\u5F97\u77E5\u7528\u6237\u7684\u89D2\u8272\u3001\u6280\u672F\u6808\u3001\u7ECF\u9A8C\u6C34\u5E73\u3001\u504F\u597D\u6216\u77E5\u8BC6\u80CC\u666F\u7684\u4EFB\u4F55\u7EC6\u8282\u65F6\u3002\n  \u4F8B\u5982\u7528\u6237\u81EA\u8FF0\"\u6211\u662F\u6570\u636E\u79D1\u5B66\u5BB6\uFF0C\u5728\u67E5\u65E5\u5FD7\u7CFB\u7EDF\"\u2014\u2014\u5B58\uFF1A\u7528\u6237\u662F\u6570\u636E\u79D1\u5B66\u5BB6\uFF0C\n  \u5F53\u524D\u5173\u6CE8\u53EF\u89C2\u6D4B\u6027/\u65E5\u5FD7\u3002</when_to_save>\n  <how_to_use>\u540E\u7EED\u89E3\u91CA\u548C\u5EFA\u8BAE\u6309\u7528\u6237\u7684\u80CC\u666F\u5B9A\u5236\u6DF1\u6D45\u4E0E\u7C7B\u6BD4\uFF1B\u5BF9\u8D44\u6DF1\u5DE5\u7A0B\u5E08\n  \u4E0D\u89E3\u91CA\u57FA\u7840\u6982\u5FF5\uFF0C\u5BF9\u67D0\u9886\u57DF\u7684\u65B0\u624B\u7528\u5176\u719F\u6089\u9886\u57DF\u7684\u7C7B\u6BD4\u5207\u5165\u3002</how_to_use>\n</type>\n\n<type name=\"feedback\">\n  <when_to_save>\u4E24\u6761\u4FE1\u53F7\uFF0C\u7F3A\u4E00\u4E0D\u53EF\uFF1A\n  \uFF081\uFF09\u7EA0\u6B63\u2014\u2014\u7528\u6237\u8BF4\"\u4E0D\u662F\u8FD9\u6837\"\"\u522B\"\"\u505C\u4E0B\"\u65F6\uFF0C\u5B58\u88AB\u7EA0\u6B63\u7684\u505A\u6CD5\u4E0E\u6B63\u786E\u505A\u6CD5\uFF1B\n  \uFF082\uFF09\u786E\u8BA4\u2014\u2014\u8FD9\u662F\u66F4\u5B89\u9759\u3001\u66F4\u5BB9\u6613\u6F0F\u7684\u4FE1\u53F7\uFF1A\u7528\u6237\u63A5\u53D7\u4E86\u4F60\u4E0D\u5BFB\u5E38\u7684\u9009\u62E9\u800C\u6CA1\u6709\u5F02\u8BAE\uFF0C\n  \u6216\u660E\u786E\u8BF4\"\u5BF9\uFF0C\u5C31\u8FD9\u6837\"\"\u4FDD\u6301\u8FD9\u6837\"\u3002\u786E\u8BA4\u8FC7\u7684\u5224\u65AD\u662F\u5DF2\u9A8C\u8BC1\u7684\u65B9\u6CD5\u8BBA\uFF0C\u53EA\u5B58\u7EA0\u9519\n  \u4F1A\u8BA9\u4F60\u7684\u884C\u4E3A\u8D8A\u6765\u8D8A\u4FDD\u5B88\u3001\u504F\u79BB\u7528\u6237\u5DF2\u8BA4\u53EF\u7684\u8DEF\u3002\n  \u4F8B\uFF1A\"\u6D4B\u8BD5\u522B mock \u6570\u636E\u5E93\uFF0C\u4E0A\u6B21 mock \u8FC7\u4E86\u7EBF\u4E0A\u8FC1\u79FB\u6302\u4E86\"\u2014\u2014\u5B58\u89C4\u5219\u5E76\u5E26\u4E0A\u4E8B\u6545\u539F\u56E0\u3002\n  \u4F8B\uFF1A\"\u7ED3\u5C3E\u4E0D\u7528\u603B\u7ED3\uFF0Cdiff \u6211\u81EA\u5DF1\u4F1A\u770B\"\u2014\u2014\u5B58\uFF1A\u8BE5\u7528\u6237\u4E0D\u8981\u5C3E\u968F\u6027\u603B\u7ED3\u3002</when_to_save>\n  <how_to_use>\u8BA9\u7528\u6237\u4E0D\u5FC5\u628A\u540C\u4E00\u6761\u6307\u5BFC\u8BF4\u7B2C\u4E8C\u904D\u3002</how_to_use>\n  <body_structure>\u89C4\u5219\u5148\u884C\uFF0C\u968F\u540E\u5FC5\u5E26\u4E24\u884C\uFF1A**Why:**\uFF08\u7528\u6237\u7ED9\u7684\u7406\u7531\uFF0C\u5E38\u662F\u67D0\u6B21\n  \u4E8B\u6545\u6216\u5F3A\u504F\u597D\u2014\u2014\u77E5\u9053\u4E3A\u4EC0\u4E48\u624D\u80FD\u5224\u65AD\u8FB9\u7F18\u60C5\u51B5\u8BE5\u4E0D\u8BE5\u7834\u4F8B\uFF09\u548C **How to apply:**\n  \uFF08\u4F55\u65F6\u4F55\u5730\u751F\u6548\uFF09\u3002feedback \u7C7B\u578B\u7F3A\u8FD9\u4E24\u884C\u89C6\u4E3A\u4E0D\u5B8C\u6574\u3002</body_structure>\n</type>\n\n<type name=\"project\">\n  <when_to_save>\u5F97\u77E5\u8FDB\u884C\u4E2D\u7684\u5DE5\u4F5C\u3001\u76EE\u6807\u3001\u51B3\u7B56\u3001\u622A\u6B62\u671F\u6216\u4E8B\u6545\u7684\u80CC\u666F\u52A8\u673A\u65F6\u2014\u2014\n  \u51E1\u662F\"\u8C01\u5728\u505A\u4EC0\u4E48\u3001\u4E3A\u4EC0\u4E48\u3001\u5230\u4EC0\u4E48\u65F6\u5019\"\u4E14\u65E0\u6CD5\u4ECE\u4EE3\u7801\u6216 git \u63A8\u5BFC\u7684\u4FE1\u606F\u3002\n  \u8FD9\u7C7B\u8BB0\u5FC6\u8870\u51CF\u5FEB\uFF0C\u72B6\u6001\u53D8\u5316\u65F6\u66F4\u65B0\u5B83\uFF0C\u522B\u5806\u53E0\u65B0\u6587\u4EF6\u3002</when_to_save>\n  <how_to_use>\u7528\u5B83\u8865\u5168\u8BF7\u6C42\u80CC\u540E\u7684\u4E0A\u4E0B\u6587\u4E0E\u52A8\u673A\uFF0C\u8BA9\u5EFA\u8BAE\u8D34\u4F4F\u771F\u5B9E\u7EA6\u675F\u3002\n  \u4F8B\uFF1A\"\u5468\u56DB\u8D77\u51BB\u7ED3\u5408\u5E76\"\u2014\u2014\u5B58\uFF1A2026-03-05 \u8D77\u51BB\u7ED3\u5408\u5E76\uFF0C\u975E\u5173\u952E PR \u63D0\u524D\u6807\u8BB0\u3002</how_to_use>\n  <body_structure>\u4E8B\u5B9E/\u51B3\u7B56\u5148\u884C + **Why:**\uFF08\u52A8\u673A\uFF1A\u7EA6\u675F\u3001deadline\u3001\u5E72\u7CFB\u4EBA\u8981\u6C42\uFF09\n  + **How to apply:**\uFF08\u8FD9\u6761\u5982\u4F55\u5F71\u54CD\u540E\u7EED\u5EFA\u8BAE\uFF09\u3002</body_structure>\n</type>\n\n<type name=\"reference\">\n  <when_to_save>\u7528\u6237\u63D0\u5230\u672A\u6765\u4F1A\u7528\u5230\u7684\u5916\u90E8\u8D44\u6E90\u6307\u9488\uFF1AURL\u3001\u4EEA\u8868\u76D8\u3001\u5DE5\u5355\u3001\n  \u6587\u6863\u4F4D\u7F6E\u3002</when_to_save>\n  <how_to_use>\u9700\u8981\u65F6\u76F4\u63A5\u53D6\u7528\uFF0C\u4E0D\u91CD\u65B0\u68C0\u7D22\u3002</how_to_use>\n</type>\n\n## \u5982\u4F55\u7EF4\u62A4\n\n- \u5199\u5B8C\u8BB0\u5FC6\u6587\u4EF6\u540E\u7ACB\u5373\u5728 MEMORY.md \u8FFD\u52A0\u6216\u66F4\u65B0\u4E00\u884C\u7D22\u5F15\uFF1A`- [\u6807\u9898](\u6587\u4EF6\u540D.md) \u2014 \u94A9\u5B50`\uFF1B\u72B6\u6001\u53D8\u5316\u65F6\u539F\u6587\u4E0E\u7D22\u5F15\u884C\u4E00\u8D77\u6539\uFF0C\u522B\u8BA9\u7D22\u5F15\u8BF4\u8C0E\u3002\n- \u66F4\u65B0\u4F18\u5148\u4E8E\u65B0\u5EFA\uFF1A\u72B6\u6001\u53D8\u4E86\u6539\u539F\u6587\u4EF6\uFF0C\u4E0D\u53E6\u8D77\u4E00\u6761\uFF08\u65B0\u65E7\u5E76\u5B58\u6BD4\u6CA1\u6709\u8BB0\u5FC6\u66F4\u7CDF\uFF09\u3002\n- \u5F15\u7528\u8BB0\u5FC6\u524D\u82E5\u53D1\u73B0\u4E0E\u73B0\u5B9E\u4E0D\u7B26\uFF0C\u5F53\u573A\u4FEE\u6B63\u6216\u5220\u9664\u8BE5\u6587\u4EF6\u4E0E\u7D22\u5F15\u884C\u2014\u2014\u574F\u8BB0\u5FC6\u7684\u5371\u5BB3\u968F\u5F15\u7528\u6269\u6563\uFF0C\n  \u9000\u5F79\u4E0D\u7559\u7ED9\u7528\u6237\u3002\n- [[\u540D\u5B57]] \u4E92\u76F8\u5F15\u7528\u76F8\u5173\u8BB0\u5FC6\uFF1B\u5F15\u7528\u8FD8\u4E0D\u5B58\u5728\u7684\u540D\u5B57\u662F\u5408\u6CD5\u7684\uFF0C\u5B83\u6807\u8BB0\"\u503C\u5F97\u5C06\u6765\u8865\u5199\"\u3002";
 //# sourceMappingURL=memory-guide.d.ts.map

package/lib/memory-guide.js

@@ -1,29 +1,41 @@
 /**
- * The persistent-memory guide injected as part of the `evolve:memory-index`
- * system-prompt section (evolve v2, change two).
+ * The persistent-memory guide injected as part of the memory section.
  *
- * This text is the write-path half of the v2 plan: it teaches the model when a
- * durable memory is worth creating, which recall type it belongs to, what body
- * structure each type owes, and that the main session may write directly with
- * `evolve_add` instead of waiting for the background pipeline.
+ * This text is the write-path half of the ZCode-aligned design: it teaches
+ * the model when a durable memory is worth creating, which type it belongs
+ * to, what body structure each type owes, and that memories are plain
+ * markdown files written directly with the native file tools — the plugin
+ * registers no tools and no commands.
  *
- * Provenance: `docs/research/evolve-v2-passive-read-write-plan.md` §改动二
- * (Chinese full text, adapted from ZCode's persistent-memory prompt). Kept in
- * its own module so the wording is a single home — `memory-index.ts` only
- * composes it with the `<memories>` block.
+ * Provenance: the when_to_save taxonomy is adapted from ZCode's persistent-
+ * memory prompt (introduced here in evolve v2); the write-path wording now
+ * targets native file operations on `<workspace>/.evolve/memory/`.
  */
-/** Heading and framing before the `<memories>` block. */
-export const MEMORY_GUIDE_INTRO = `# 持久记忆
+/** Heading and framing before the `<memories>` block. Takes the absolute memory dir. */
+export function memoryGuideIntro(memoryDir) {
+    return `# 持久记忆
 
-你有一个跨会话的持久记忆系统。以下是当前记忆（已直接注入，无需查询即可使用；需要检索完整内容或确认是否有相关记忆时，调用 evolve_recall）。本会话内可以直接用 evolve_add 落盘，不必等后台流程——默认写 local，只有稳定的跨项目教训才写 global（global 写入会弹人工批准）。`;
-/** The when_to_save / how_to_use rules and maintenance discipline. */
-export const MEMORY_GUIDE_RULES = `## 何时写入记忆
+你有一个跨会话的持久记忆系统，存放在 \`${memoryDir}/\`：一事一文，\`MEMORY.md\` 是索引，其内容已注入在下方。没有专用命令或工具——直接用你的文件读写工具查看、新建、修改、删除记忆文件，并在同一会话内顺手落盘。`;
+}
+/** The file format, when_to_save / how_to_use rules, and maintenance discipline. */
+export const MEMORY_GUIDE_RULES = `## 记忆文件的格式
 
-用户明确要求记住时，立即存为最合适的类型；要求忘记时，找到并删除相关条目。
+---
+name: <短横线小写标识>
+description: <一句话相关性钩子——决定未来会话会不会想起这条记忆>
+metadata:
+  type: user | feedback | project | reference
+---
+
+<正文>
+
+## 何时写入记忆
+
+用户明确要求记住时，立即存为最合适的类型；要求忘记时，找到并删除相关文件与索引行。
 除此之外，在对话中自然遇到以下信号时主动写入。存之前先过一道筛子：
 **能从代码、git 历史、仓库文件里重新推导出来的事实不存**——只存重推导不出来的
 背景、决策和偏好。相对日期一律转成绝对日期（"周四"→"2026-10-08"），否则未来
-的会话无法解读。一条事实一个条目；不确定值不值得存时，问自己"这条的信息量
+的会话无法解读。一条事实一个文件；不确定值不值得存时，问自己"这条的信息量
 是否在'为什么'里，而不在'是什么'里"。
 
 <type name="user">
@@ -51,7 +63,7 @@ export const MEMORY_GUIDE_RULES = `## 何时写入记忆
 <type name="project">
   <when_to_save>得知进行中的工作、目标、决策、截止期或事故的背景动机时——
   凡是"谁在做什么、为什么、到什么时候"且无法从代码或 git 推导的信息。
-  这类记忆衰减快，状态变化时更新它，别堆叠新条目。</when_to_save>
+  这类记忆衰减快，状态变化时更新它，别堆叠新文件。</when_to_save>
   <how_to_use>用它补全请求背后的上下文与动机，让建议贴住真实约束。
   例："周四起冻结合并"——存：2026-03-05 起冻结合并，非关键 PR 提前标记。</how_to_use>
   <body_structure>事实/决策先行 + **Why:**（动机：约束、deadline、干系人要求）
@@ -66,8 +78,9 @@ export const MEMORY_GUIDE_RULES = `## 何时写入记忆
 
 ## 如何维护
 
-- 更新优先于新建：状态变了改原条目，不另起一条（新旧并存比没有记忆更糟）。
-- 每条的 description 是给未来会话的相关性 hook——写"决定了一条记忆会不会
-  被想起"的一句话，不写流水账。
+- 写完记忆文件后立即在 MEMORY.md 追加或更新一行索引：\`- [标题](文件名.md) — 钩子\`；状态变化时原文与索引行一起改，别让索引说谎。
+- 更新优先于新建：状态变了改原文件，不另起一条（新旧并存比没有记忆更糟）。
+- 引用记忆前若发现与现实不符，当场修正或删除该文件与索引行——坏记忆的危害随引用扩散，
+  退役不留给用户。
 - [[名字]] 互相引用相关记忆；引用还不存在的名字是合法的，它标记"值得将来补写"。`;
 //# sourceMappingURL=memory-guide.js.map

package/lib/memory-section.d.ts

@@ -0,0 +1,77 @@
+/** Name of the injected section (unique — duplicate names throw upstream). */
+export declare const MEMORY_SECTION_NAME = "evolve:memory-index";
+/** Default prompt-section order (empty 1–499 slot; upstream named slots start at 500). */
+export declare const DEFAULT_MEMORY_SECTION_ORDER = 400;
+/** Default hard character budget for the injected index. */
+export declare const DEFAULT_MAX_CHARS = 6000;
+/** Sessions whose frozen section text is kept before LRU eviction. */
+export declare const DEFAULT_FROZEN_SESSIONS = 32;
+/** The assembling agent's validated absolute cwd, or undefined when absent. */
+export declare function cwdOf(agent: unknown): string | undefined;
+/** Absolute memory directory for a workspace root. */
+export declare function memoryDirFor(cwd: string): string;
+/**
+ * Ensure `.evolve/` is ignored when the workspace is a git repository, so
+ * the memory store never shows up in git status. Best-effort hygiene: a
+ * non-git workspace (no `.git` entry at the cwd) is left untouched — no
+ * `.gitignore` is created — and any write failure is swallowed.
+ */
+export declare function ensureGitIgnored(cwd: string): void;
+/**
+ * Ensure the store exists (creating the directory and a starter index on
+ * first use), then return the trimmed index text. Any filesystem failure
+ * degrades to "" — injection must never break an assembly.
+ */
+export declare function readMemoryIndex(dir: string, bootstrap?: boolean): string;
+/** What fitting the index into the budget produced. */
+export interface IndexFit {
+    /** Index text actually shown (possibly truncated to a line boundary). */
+    text: string;
+    /** Characters dropped by the budget, 0 when the index fit whole. */
+    dropped: number;
+}
+/**
+ * Whole-line-preserving truncation of the index to `maxChars` characters.
+ * Only index rows that fit whole are shown — a partial markdown row would
+ * corrupt the line the model reads. When not even one row fits, `text` is
+ * "" and `dropped` carries the full length.
+ */
+export declare function fitIndex(index: string, maxChars: number): IndexFit;
+/** Options for {@link memorySectionText}. */
+export interface MemorySectionOptions {
+    /** Hard character budget for the injected index (default 6000). */
+    maxChars?: number;
+    /** Include the when_to_save guide (default true). */
+    guide?: boolean;
+    /** Skip store bootstrap (tests). */
+    bootstrap?: boolean;
+}
+/**
+ * Compose the full memory section for one assembling agent: the guide
+ * wrapped around the budget-bounded index, with the absolute store path
+ * handed out so the model can read and write the files directly. With the
+ * guide off and an empty index the result is "" — the prompt renderer then
+ * drops the section, so an empty workspace costs zero tokens.
+ */
+export declare function memorySectionText(agent: unknown, opts?: MemorySectionOptions): string;
+/** A per-session frozen view of the memory section text. */
+export interface FrozenMemorySection {
+    /**
+     * The section text for this agent: built on first use per agent id and
+     * reused byte-for-byte afterwards. An agent without an id is rebuilt on
+     * every call (nothing to key the cache on).
+     */
+    textFor(agent: unknown, build: (agent: unknown) => string): string;
+    /** Sessions currently frozen (test/observability hook). */
+    size(): number;
+    /** Drop every frozen session (tests; a restart rebuilds naturally). */
+    clear(): void;
+}
+/**
+ * Freeze the section text per agent id. The frozen value is what keeps the
+ * system prompt stable across a session's assemblies (prompt-cache guard);
+ * bounded by `maxSessions` with insertion-order (LRU) eviction, so a
+ * long-lived process cannot grow without limit.
+ */
+export declare function createFrozenMemorySection(maxSessions?: number): FrozenMemorySection;
+//# sourceMappingURL=memory-section.d.ts.map