@team-harness/memory-algorithms 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+Tencent is pleased to support the open source community by making TencentDB Agent Memory available. 
+
+Copyright (C) 2026 Tencent.  All rights reserved. 
+
+TencentDB Agent Memory is licensed under the MIT.
+
+
+Terms of the MIT:
+--------------------------------------------------------------------
+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

@@ -0,0 +1,203 @@
+# @team-harness/memory-algorithms
+
+将对话逐层提取为原子记忆（L1）、场景经验（L2）、画像或工作准则（L3），也可从对话提取可复用的 Skill。独立 TypeScript / ESM 包，算法源自 [TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)，无需启动其服务或数据库。
+
+你提供对话、模型调用和已有知识的读取接口；算法返回带版本、证据和运行记录的变更；你的应用决定何时分析、如何保存以及是否启用结果。
+
+## 安装
+
+要求 Node.js 22 或更高版本，使用 ESM 导入。
+
+使用 npm 安装：
+
+```sh
+npm install @team-harness/memory-algorithms
+```
+
+也可以从有访问权限的源码仓库构建安装包：
+
+```sh
+git clone https://github.com/team-harness/memory-algorithms.git
+cd memory-algorithms
+npm ci
+npm pack
+```
+
+在你的应用目录安装生成的文件：
+
+```sh
+npm install /path/to/memory-algorithms/team-harness-memory-algorithms-0.1.0.tgz
+```
+
+## 提取流程
+
+| 接口 | 输入 | 返回的实体 |
+| --- | --- | --- |
+| `extractL1` | 对话消息，以及可选的历史记忆检索 | `Atom`：原子记忆，包含类型、内容及证据 |
+| `extractL2` | L1 记忆和已有场景文档 | `Document`：按场景组织的经验 |
+| `extractL3` | 场景文档、可选的已有画像及上次场景版本 | `Document`：画像或工作准则候选 |
+| `extractSkills` | 对话消息，以及可选的已有 Skill 读取接口 | `Skill`：文档、描述及配套资源候选 |
+
+典型顺序为 `L0 对话 → L1 Atom → L2 Scenario → L3 Persona`。Skill 从对话直接提取，不必等待 L3。各接口独立调用，包内不自动调度整条流程，也不保存 L0。
+
+L1/L2/L3 默认使用 `mode: "code"`，适合开发工作的事实、任务、方法和产物；`mode: "chat"` 用于个人画像、事件和指令等对话记忆。Skill 不接收 `mode`。
+
+## 第一次提取 L1
+
+下面的函数接收你实现的模型驱动，返回一次分析结果，不会写入数据库：
+
+```ts
+import {
+  extractL1,
+  type Message,
+  type ModelDriver,
+} from "@team-harness/memory-algorithms";
+
+export async function analyzeConversation(model: ModelDriver) {
+  const messages: Message[] = [{
+    id: "message-1",
+    role: "user",
+    content: "发布前必须完成数据库迁移验收。",
+    timestamp: Date.now(),
+    evidence: [{ id: "archive/item-1", version: 2 }],
+  }];
+
+  return extractL1({ model }, {
+    runId: "analysis-1",
+    scopeKey: "host-1/project-1",
+    mode: "code",
+    messages,
+  });
+}
+```
+
+`messages` 按对话顺序传入。每条消息需要稳定的 `id`、毫秒时间戳和至少一个带版本的 `evidence` 引用。角色支持 `user`、`assistant`、`tool_call`、`tool_result`。引用应能定位到应用保存的不可变对话证据；已裁剪内容标记 `completeness: "truncated"`，证据引用也可携带 `hash` 和完整性标记。
+
+`scopeKey` 是应用明确选择的分析范围，例如一个项目或一个团队。它不自动推导项目、组织或成员关系，也不代替权限校验。参与同一次分析的历史实体必须属于该范围。
+
+## 接入模型与检索
+
+所有接口的第一个参数都是 `Dependencies`。必填的 `model` 实现如下契约；包不绑定任何模型厂商 SDK：
+
+```ts
+import type {
+  ModelDriver,
+  ModelRequest,
+  ModelResponse,
+} from "@team-harness/memory-algorithms";
+
+export function createModelDriver(
+  id: string,
+  complete: (request: ModelRequest) => Promise<ModelResponse>,
+): ModelDriver {
+  return { id, complete };
+}
+```
+
+传入的 `complete` 负责一次模型 API 请求的协议转换：
+
+- 请求包含 `systemPrompt`、`messages`、JSON Schema 工具定义 `tools`、`maxOutputTokens` 和 `signal`。
+- 消息历史中的助手工具调用和工具结果必须保留调用 ID；结果消息使用 `toolCallId` 关联。
+- 响应包含 `text`、可选的 `toolCalls` 和 `finishReason`。工具调用返回 `"tool_calls"`，正常结束返回 `"stop"`；`"length"` 或 `"error"` 会使该阶段失败。
+- 工具调用的 `arguments` 应转换为解析后的参数对象。工具执行和多轮循环由本包负责，驱动只做模型传输。
+- 传递取消信号，返回模型实际报告的 `usage`；无法取得用量时省略，不要填造假的零值。
+
+只有纯文本响应、无法保留工具调用的接口不足以支持全部阶段。
+
+| 可选依赖 | 用途 | 应用需要提供 |
+| --- | --- | --- |
+| `memories` | L1 召回冲突候选、判断更新或合并 | `hybrid`，或 `fts` 与 `embed`/`vector` |
+| `skills` | Skill 提取时查找和复用已有技能 | `list`、`search`、`get` |
+| `now` / `createId` | 可控时间与 ID，便于回放或测试 | 返回当前时间 / 新 ID 的函数 |
+
+记忆检索优先使用原生 `hybrid`，否则通过 RRF（k=60）合并全文与向量排名。`fts` 接收自然语言查询，应用负责安全转换为数据库查询。没有 `memories` 时无法基于历史记忆做语义去重；检索降级记录在 `diagnostics`，应用应据此决定是否接受结果。
+
+读取接口必须执行权限过滤，返回匹配 `scopeKey` 的完整实体快照；同一实体在一次运行中保持版本一致。Skill 的 `writable` 必须来自实际权限。返回候选不等于获得正式写入授权。
+
+## 调用 L2、L3 与 Skill
+
+每个阶段使用已提交的当前实体快照。下面的函数展示调用参数；应用应在调用阶段之间完成保存与重新读取：
+
+```ts
+import {
+  extractL2, extractL3, extractSkills,
+  type Atom, type Dependencies, type Document,
+  type Message, type VersionRef,
+} from "@team-harness/memory-algorithms";
+
+export function analyzeScenarios(
+  deps: Dependencies, runId: string, scopeKey: string,
+  memories: Atom[], scenes: Document[],
+) {
+  return extractL2(deps, { runId, scopeKey, memories, scenes });
+}
+
+export function analyzePersona(
+  deps: Dependencies, runId: string, scopeKey: string,
+  scenes: Document[], persona?: Document,
+  previousSceneVersions?: VersionRef[],
+) {
+  return extractL3(deps, {
+    runId, scopeKey, scenes, persona, previousSceneVersions,
+  });
+}
+
+export function analyzeSkills(
+  deps: Dependencies, runId: string, scopeKey: string,
+  messages: Message[],
+) {
+  return extractSkills(deps, { runId, scopeKey, messages });
+}
+```
+
+首次提取 L2 时 `scenes` 传空数组，首次提取 L3 时省略 `persona`。后续传入已有快照。L3 成功提交时，一并保存本次输入的场景 `{ id, version }` 列表，下次作为 `previousSceneVersions` 传入，用于识别变化与删除；不传则重新评估现有场景。
+
+## 处理与保存结果
+
+四个接口统一返回 `ExtractionResult<T>`：
+
+| 字段 | 应用如何使用 |
+| --- | --- |
+| `status` | `completed` 完成；`partial` 仅覆盖部分输入；`failed` / `cancelled` 不可提交 |
+| `changes` | `create`、`update`、`merge`、`retire`、`skip`；`before` 是被替换的版本，`after` 是完整的新实体 |
+| `readSet` | 提交前检查所读取的历史实体版本是否仍然有效 |
+| `coverage` | 区分已处理、背景、过滤、裁剪和剩余输入 |
+| `continuation` | L1 分批续跑位置，需与本批结果一起保存 |
+| `diagnostics` | 失败原因、检索降级和输入裁剪等信息 |
+| `provenance` | 算法与上游版本、模型、输入/提示词 hash、调用次数及 token 用量 |
+
+建议将版本校验、变更应用、证据与运行记录保存、分析进度更新放在同一事务中。按 `runId`、阶段和批次实现幂等；发生版本冲突时重新读取并分析。`completed` 也可能没有变更，表示没有需要沉淀的内容。
+
+L1 的 `update` / `merge` 会产生新的 `after.id`，不是原 ID 就地更新：需要将所有 `before` 记录标为被替代，同时插入 `after` 并保留历史。Skill 一次运行可以经过多次编辑，最终版本可能增长多次，`before` 仍指向原持久版本。提交时还需重新检查权限及 Skill 名称/ID 唯一性。
+
+失败或取消时没有可提交变更，不推进分析进度。参数或依赖配置错误也可能直接抛出异常，调用层仍需捕获异常。L3 和 Skill 是候选，是否启用由应用决定。
+
+L1 的证据按记录关联；L2/L3/Skill 使用保守的整次运行输入依赖，不是逐句引用。`provenance.evidenceGranularity` 标明 `record` 或 `run`；token 用量无法取得时为 `null`。
+
+## 分批、预算与取消
+
+L1 默认每次处理最早的最多 10 条新消息，以之前最多 5 条合格消息作为背景，可通过 `maxNewMessages` / `maxBackgroundMessages` 调整。
+
+当 L1 返回 `partial` 和 `continuation` 时，先原子保存本批结果与续跑位置，再使用**同一份完整消息快照**和该 `continuation` 调用 `extractL1`。保持范围、模式、策略和窗口配置不变，下一批检索必须能读到上一批已提交的记忆。不要把续跑位置用于另一份输入或另一算法版本。
+
+每个阶段可传 `limits` 和 `signal`。主要默认预算如下：
+
+| 参数 | 默认值 | 含义 |
+| --- | --- | --- |
+| `limits.maxCalls` | 20 | 模型调用上限 |
+| `limits.maxIterations` | 16 | 工具循环迭代上限 |
+| `limits.maxInputChars` | 120000 | 输入字符预算，不是 tokenizer 精确 token 数 |
+| `limits.maxOutputTokens` | 8192 | 单次模型输出预算 |
+| `limits.timeoutMs` | 180000 | 阶段超时毫秒数 |
+
+单个超大消息或场景放不进预算时会明确失败，不自动摘要或跳过。L2/L3 暂无自动分批续跑，应用需选择有界输入。
+
+Skill 默认保留格式化对话的前 8000 / 后 32000 字符，可通过 `headChars` / `tailChars` 调整。发生截取会返回 `partial` 和诊断，但没有自动续跑位置；不能把它当作全量分析完成。包另导出 `compressMessage`、`compressMessages` 和 `applyOversizeStrategy`，仅供显式预处理，默认提取不叠加压缩。
+
+## 当前能力边界
+
+应用负责分析触发、存储、同步、权限和候选启用。本包的文档编辑工具只操作运行内存，不写应用文件或数据库；模型请求通过你提供的驱动执行，无默认遥测上传。
+
+当前算法配置为 `bounded-analysis-v1`。已完成原仓库差分、确定性演化回归，以及基于改写会话的初步真实模型评测。评测观察到模型格式错误、文档编辑成本偏高和 L3 过度推导，因此生成结果仍应作为候选审查，不能视为全面质量保证。详见 [验收结果](https://github.com/team-harness/memory-algorithms/blob/main/evaluation/results/2026-09-15.md)。
+
+完整类型随 npm 包提供，亦可查看 [API 类型](https://github.com/team-harness/memory-algorithms/blob/main/src/contracts.ts)。算法来源与适配差异见 [适配记录](upstream/changes.md)。保留上游版权，采用 [MIT 许可](LICENSE)。

package/dist/contracts.d.ts

@@ -0,0 +1,178 @@
+import type { MemoryRecord } from "./upstream/core/record/l1-writer.js";
+import type { ResolvedMemoryPrompt } from "./upstream/core/memory-prompt/types.js";
+export type Stage = "l1" | "l2" | "l3" | "skill";
+export type PromptMode = "chat" | "code";
+export interface Logger {
+    debug?(message: string): void;
+    warn?(message: string): void;
+}
+export interface EvidenceRef {
+    id: string;
+    version: string | number;
+    hash?: string;
+    completeness?: "full" | "truncated";
+}
+export interface Message {
+    id: string;
+    role: "user" | "assistant" | "tool_call" | "tool_result";
+    content: string;
+    timestamp: number;
+    evidence: EvidenceRef[];
+    completeness?: "full" | "truncated";
+}
+export interface VersionRef {
+    id: string;
+    version: number;
+}
+export interface Atom extends MemoryRecord {
+    version: number;
+    scopeKey: string;
+    evidence: EvidenceRef[];
+}
+export interface Document {
+    id: string;
+    version: number;
+    scopeKey: string;
+    filename: string;
+    content: string;
+    evidence: EvidenceRef[];
+}
+export interface SkillResource {
+    path: string;
+    content: string;
+    encoding?: "utf-8" | "base64";
+    mime_type?: string;
+    is_executable?: boolean;
+}
+export interface Skill extends Document {
+    name: string;
+    description: string;
+    resources: SkillResource[];
+    writable: boolean;
+}
+export interface Change<T> {
+    action: "create" | "update" | "merge" | "retire" | "skip";
+    before: VersionRef[];
+    after?: T;
+    reason?: string;
+}
+export interface ToolCall {
+    id: string;
+    name: string;
+    arguments: unknown;
+}
+export interface ModelMessage {
+    role: "user" | "assistant" | "tool";
+    content: string;
+    toolCalls?: ToolCall[];
+    toolCallId?: string;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface ModelRequest {
+    stage: Stage;
+    systemPrompt: string;
+    messages: ModelMessage[];
+    tools: ToolDefinition[];
+    maxOutputTokens: number;
+    signal: AbortSignal;
+}
+export interface ModelResponse {
+    text: string;
+    toolCalls?: ToolCall[];
+    finishReason: "stop" | "tool_calls" | "length" | "error";
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+export interface ModelDriver {
+    id: string;
+    complete(request: ModelRequest): Promise<ModelResponse>;
+}
+export interface Limits {
+    maxCalls: number;
+    maxIterations: number;
+    maxInputChars: number;
+    maxOutputTokens: number;
+    timeoutMs: number;
+    maxToolCalls: number;
+    maxWorkspaceChars: number;
+    maxRecallQueries: number;
+    maxExtractedMemories: number;
+}
+export interface RunInput {
+    runId: string;
+    scopeKey: string;
+    mode?: PromptMode;
+    signal?: AbortSignal;
+    limits?: Partial<Limits>;
+    strategy?: ResolvedMemoryPrompt;
+}
+export interface Continuation {
+    algorithmVersion: string;
+    inputHash: string;
+    nextIndex: number;
+    previousSceneName?: string;
+}
+export interface Coverage {
+    processed: string[];
+    background: string[];
+    filtered: string[];
+    truncated: string[];
+    remaining: string[];
+}
+export interface ExtractionResult<T> {
+    status: "completed" | "partial" | "failed" | "cancelled";
+    changes: Change<T>[];
+    readSet: VersionRef[];
+    coverage: Coverage;
+    continuation?: Continuation;
+    diagnostics: string[];
+    provenance: {
+        algorithmVersion: string;
+        upstreamCommit: string;
+        profile: "bounded-analysis-v1";
+        evidenceGranularity: "record" | "run";
+        runId: string;
+        scopeKey: string;
+        stage: Stage;
+        model: string;
+        inputHash: string;
+        promptHashes: string[];
+        calls: number;
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+        } | null;
+    };
+    sceneNames?: string[];
+    personaUpdateReason?: string;
+}
+export interface MemorySearch {
+    hybrid?(query: string, scopeKey: string, topK: number, signal?: AbortSignal): Promise<Atom[]>;
+    fts?(query: string, scopeKey: string, topK: number, signal?: AbortSignal): Promise<Atom[]>;
+    embed?(query: string, signal?: AbortSignal): Promise<number[]>;
+    vector?(embedding: number[], scopeKey: string, topK: number, signal?: AbortSignal): Promise<Atom[]>;
+}
+export interface SkillReader {
+    list(scopeKey: string, limit: number, signal?: AbortSignal): Promise<{
+        items: Skill[];
+        total: number;
+    }>;
+    search(scopeKey: string, query: string, limit: number, signal?: AbortSignal): Promise<Array<{
+        skill: Skill;
+        score: number;
+    }>>;
+    get(scopeKey: string, id: string, signal?: AbortSignal): Promise<Skill>;
+}
+export interface Dependencies {
+    model: ModelDriver;
+    memories?: MemorySearch;
+    skills?: SkillReader;
+    now?: () => Date;
+    createId?: () => string;
+}

package/dist/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export type * from "./contracts.js";
+export type { MemoryType } from "./upstream/core/record/l1-writer.js";
+export type { ResolvedMemoryPrompt } from "./upstream/core/memory-prompt/types.js";
+export { extractL1 } from "./runtime/l1.js";
+export type { L1Input } from "./runtime/l1.js";
+export { extractL2, extractL3 } from "./runtime/documents.js";
+export type { L2Input, L3Input } from "./runtime/documents.js";
+export { extractSkills } from "./runtime/skills.js";
+export type { SkillInput } from "./runtime/skills.js";
+export { ALGORITHM_VERSION, UPSTREAM_COMMIT } from "./runtime/run.js";
+export { compressMessage, compressMessages } from "./upstream/core/skill/conversation-add/message-compressor.js";
+export type { CompressibleMessage, CompressOptions } from "./upstream/core/skill/conversation-add/message-compressor.js";
+export { applyOversizeStrategy } from "./upstream/core/skill/conversation-add/oversize-strategy.js";
+export type { OversizeMessage, OversizeOptions, OversizeResult } from "./upstream/core/skill/conversation-add/oversize-strategy.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { extractL1 } from "./runtime/l1.js";
+export { extractL2, extractL3 } from "./runtime/documents.js";
+export { extractSkills } from "./runtime/skills.js";
+export { ALGORITHM_VERSION, UPSTREAM_COMMIT } from "./runtime/run.js";
+export { compressMessage, compressMessages } from "./upstream/core/skill/conversation-add/message-compressor.js";
+export { applyOversizeStrategy } from "./upstream/core/skill/conversation-add/oversize-strategy.js";

package/dist/runtime/documents.d.ts

@@ -0,0 +1,15 @@
+import type { Atom, Dependencies, Document, ExtractionResult, RunInput, VersionRef } from "../contracts.js";
+export interface L2Input extends RunInput {
+    memories: Atom[];
+    scenes: Document[];
+    maxScenes?: number;
+}
+export declare function extractL2(deps: Dependencies, input: L2Input): Promise<ExtractionResult<Document>>;
+export interface L3Input extends RunInput {
+    scenes: Document[];
+    persona?: Document;
+    previousSceneVersions?: VersionRef[];
+    totalProcessed?: number;
+    triggerReason?: string;
+}
+export declare function extractL3(deps: Dependencies, input: L3Input): Promise<ExtractionResult<Document>>;

package/dist/runtime/documents.js

@@ -0,0 +1,209 @@
+import { buildSceneExtractionPrompt } from "../upstream/core/prompts/scene-extraction.js";
+import { buildPersonaPrompt } from "../upstream/core/prompts/persona-generation.js";
+import { parseSceneBlock } from "../upstream/core/scene/scene-format.js";
+import { normalizeSceneFilename } from "../upstream/core/scene/filename-normalizer.js";
+import { renderSceneNavigation, storageNavFooter, stripSceneNavigation } from "../upstream/core/scene/scene-navigation.js";
+import { escapeXmlTags } from "../upstream/utils/sanitize.js";
+import { composeMemorySystemPrompt } from "../upstream/core/memory-prompt/composer.js";
+import { Run, coverage, hash, uniqueRefs } from "./run.js";
+import { safePath } from "./skill-workspace.js";
+import { tool, jsonSchema } from "./tools.js";
+class DocumentWorkspace {
+    run;
+    persona;
+    files = new Map();
+    written = new Set();
+    constructor(run, documents, persona = false) {
+        this.run = run;
+        this.persona = persona;
+        for (const d of documents) {
+            this.path(d.filename);
+            if (this.files.has(d.filename))
+                throw new Error("Duplicate document filename");
+            this.files.set(d.filename, d.content);
+        }
+        this.checkSize();
+    }
+    path(path) {
+        safePath(path);
+        if (path.includes("/") || !path.endsWith(".md") || (this.persona && path !== "persona.md"))
+            throw new Error("Document path outside workspace");
+    }
+    checkSize() {
+        if ([...this.files.values()].reduce((n, s) => n + s.length, 0) > this.run.limits.maxWorkspaceChars)
+            throw new Error("Document workspace budget exhausted");
+    }
+    put(path, content) {
+        this.run.check();
+        this.path(path);
+        if (!content.trim())
+            throw new Error("Empty document write");
+        const old = this.files.get(path);
+        this.files.set(path, content);
+        try {
+            this.checkSize();
+        }
+        catch (error) {
+            if (old === undefined)
+                this.files.delete(path);
+            else
+                this.files.set(path, old);
+            throw error;
+        }
+        this.written.add(path);
+        return JSON.stringify({ ok: true, path });
+    }
+    tools() {
+        return {
+            read: tool({ description: "Read a document in the current workspace.", inputSchema: jsonSchema({ type: "object", properties: { path: { type: "string" } }, required: ["path"], additionalProperties: false }), execute: async ({ path }) => {
+                    this.path(path);
+                    const value = this.files.get(path);
+                    if (value === undefined)
+                        throw new Error("Document not found");
+                    return value;
+                } }),
+            write: tool({ description: "Write a complete Markdown document.", inputSchema: jsonSchema({ type: "object", properties: { path: { type: "string" }, content: { type: "string" } }, required: ["path", "content"], additionalProperties: false }), execute: async ({ path, content }) => this.put(path, content) }),
+            edit: tool({ description: "Apply exact, unique text replacements atomically.", inputSchema: jsonSchema({ type: "object", properties: { path: { type: "string" }, edits: { type: "array", minItems: 1, items: { type: "object", properties: { oldText: { type: "string", minLength: 1 }, newText: { type: "string" } }, required: ["oldText", "newText"], additionalProperties: false } } }, required: ["path", "edits"], additionalProperties: false }), execute: async ({ path, edits }) => {
+                    this.path(path);
+                    let content = this.files.get(path);
+                    if (content === undefined)
+                        throw new Error("Document not found");
+                    for (const edit of edits) {
+                        if (content.split(edit.oldText).length !== 2)
+                            throw new Error("Edit target missing or ambiguous");
+                        content = content.replace(edit.oldText, () => edit.newText);
+                    }
+                    return this.put(path, content);
+                } }),
+        };
+    }
+}
+function index(documents) {
+    return documents.map(d => ({ filename: d.filename, ...parseSceneBlock(d.content, d.filename).meta }));
+}
+export async function extractL2(deps, input) {
+    input = { ...input, memories: structuredClone(input.memories), scenes: structuredClone(input.scenes), strategy: structuredClone(input.strategy) };
+    const run = new Run(deps, input, "l2", hash({ scope: input.scopeKey, mode: input.mode, memories: input.memories, scenes: input.scenes, maxScenes: input.maxScenes, strategy: input.strategy }));
+    const cov = coverage(input.memories.map(m => m.id));
+    try {
+        run.check();
+        const memories = input.memories.map(m => run.read(m));
+        const scenes = input.scenes.map(s => run.read(s));
+        if (!memories.length)
+            return run.result([], cov);
+        const maxScenes = input.maxScenes ?? 15;
+        if (!Number.isSafeInteger(maxScenes) || maxScenes < 2)
+            throw new Error("Invalid scene limit");
+        const entries = index(scenes);
+        // Adapted from SceneExtractor: tiered pressure to merge before adding scenes.
+        const warning = entries.length >= maxScenes ? `当前场景数量为 **${entries.length} 个**，已达到或超过 ${maxScenes} 个上限！\n**你必须先执行 MERGE 操作**，将最相似的 2-4 个场景合并为 1 个，然后再处理新记忆。\n参考合并对象：热度最低或主题高度重叠的场景。`
+            : entries.length === maxScenes - 1 ? `当前场景数量为 **${entries.length} 个**，距离上限只差 1 个！\n本次处理**只能 UPDATE 现有场景，不能 CREATE 新场景**。`
+                : entries.length >= maxScenes - 3 ? `当前场景数量为 **${entries.length} 个**，建议优先考虑 UPDATE 或主动 MERGE 相似场景。` : undefined;
+        const summaries = entries.length ? [`**当前场景总数：${entries.length} / ${maxScenes}**`, "",
+            ...entries.flatMap(e => [`### ${e.filename}`, `**热度**: ${e.heat} | **更新**: ${e.updated}`, `**summary**: ${e.summary}`, ""])].join("\n") : "";
+        const prompts = buildSceneExtractionPrompt({ memoriesJson: JSON.stringify(memories.map(m => ({ content: m.content, created_at: m.createdAt, id: m.id })), null, 2),
+            sceneSummaries: summaries || "(无已有场景)", currentTimestamp: run.time,
+            sceneCountWarning: warning, existingSceneFiles: entries.map(e => e.filename), maxScenes, promptMode: input.mode ?? "code" });
+        const workspace = new DocumentWorkspace(run, scenes);
+        const output = await run.model(composeMemorySystemPrompt(prompts.systemPrompt, input.strategy), prompts.userPrompt, workspace.tools());
+        const normalized = new Map();
+        for (const [name, content] of workspace.files) {
+            const parsed = parseSceneBlock(content, name);
+            if (content.trim() === "[DELETED]" || !parsed.content || parsed.content.trim() === "[DELETED]")
+                continue;
+            const base = normalizeSceneFilename(name);
+            let filename = base, suffix = 2;
+            while (normalized.has(filename) || (filename !== name && workspace.files.has(filename)))
+                filename = `${base.slice(0, -3)}-${suffix++}.md`;
+            normalized.set(filename, { oldName: name, content });
+        }
+        if (normalized.size > maxScenes)
+            throw new Error("Scene count exceeds the configured maximum");
+        const dependencies = uniqueRefs([...memories.flatMap(m => m.evidence), ...scenes.flatMap(s => s.evidence)]);
+        const changes = [];
+        const kept = new Set();
+        for (const [filename, file] of normalized) {
+            const old = scenes.find(s => s.filename === file.oldName);
+            if (old)
+                kept.add(old.id);
+            if (old?.content === file.content && old.filename === filename)
+                continue;
+            changes.push({ action: old ? "update" : "create", before: old ? [{ id: old.id, version: old.version }] : [], after: {
+                    id: old?.id ?? run.id(), version: (old?.version ?? 0) + 1, scopeKey: input.scopeKey,
+                    filename, content: file.content, evidence: old?.content === file.content ? old.evidence : dependencies,
+                } });
+        }
+        for (const old of scenes)
+            if (!kept.has(old.id))
+                changes.push({ action: "retire", before: [{ id: old.id, version: old.version }], reason: workspace.files.get(old.filename)?.trim() === "[DELETED]" ? "explicit-deletion" : "empty-scene-body" });
+        const newIds = changes.flatMap(c => c.after ? [c.after.id] : []);
+        if (new Set(newIds).size !== newIds.length || changes.some(c => c.action === "create" && scenes.some(s => s.id === c.after?.id)))
+            throw new Error("Duplicate generated document ID");
+        cov.processed = cov.remaining;
+        cov.remaining = [];
+        run.check();
+        const result = run.result(changes, cov);
+        result.personaUpdateReason = output.match(/\[PERSONA_UPDATE_REQUEST\]\s*(?:reason:\s*)?(.+?)\s*\[\/PERSONA_UPDATE_REQUEST\]/s)?.[1]?.trim()
+            ?? output.match(/PERSONA_UPDATE_REQUEST:\s*(.+?)(?:\n|$)/)?.[1]?.trim();
+        return result;
+    }
+    catch (error) {
+        return run.failure(error, cov);
+    }
+}
+export async function extractL3(deps, input) {
+    input = { ...input, scenes: structuredClone(input.scenes), persona: structuredClone(input.persona), strategy: structuredClone(input.strategy) };
+    const run = new Run(deps, input, "l3", hash({ scope: input.scopeKey, mode: input.mode, scenes: input.scenes, persona: input.persona, previousSceneVersions: input.previousSceneVersions, strategy: input.strategy }));
+    const cov = coverage(input.scenes.map(s => s.id));
+    try {
+        run.check();
+        const scenes = input.scenes.map(s => run.read(s));
+        const persona = input.persona ? run.read(input.persona) : undefined;
+        const previous = new Map(input.previousSceneVersions?.map(s => [s.id, s.version]));
+        const removed = [...previous.keys()].some(id => !scenes.some(s => s.id === id));
+        const changed = !persona || removed ? scenes : scenes.filter(s => previous.get(s.id) !== s.version);
+        if (!changed.length && !removed && persona) {
+            cov.processed = cov.remaining;
+            cov.remaining = [];
+            return run.result([], cov);
+        }
+        if (!scenes.length && !persona) {
+            cov.processed = [];
+            cov.remaining = [];
+            return run.result([], cov);
+        }
+        const existing = persona ? stripSceneNavigation(persona.content).trim() : undefined;
+        const changedContent = changed.map((s, i) => `### [${i + 1}] ${s.filename}\n\n\`\`\`markdown\n${s.content}\n\`\`\``).join("\n\n");
+        const changedScenesContent = changed.length
+            ? `\n\n## 📄 变化场景完整内容\n\n` +
+                `*自上次 Persona 更新后，以下 ${changed.length} 个场景发生了变化。工程已为你预加载完整内容：*\n\n` + changedContent +
+                `\n\n---\n\n` + `⚠️ **重点分析变化场景**：上述场景是自上次更新后的**新增/修改内容**，请**重点分析**这些场景中的新信息。\n`
+            : `\n\n⚠️ **无变化场景**：所有场景均已在上次 Persona 更新中分析过，本次可直接读取所有场景进行全局审视。\n`;
+        const prompts = buildPersonaPrompt({ mode: existing ? "incremental" : "first", promptMode: input.mode ?? "code", currentTime: run.time,
+            totalProcessed: input.totalProcessed ?? 0, sceneCount: scenes.length, changedSceneCount: changed.length,
+            changedScenesContent: removed ? `Previously used scenes were removed. Reassess unsupported conclusions.\n${changedScenesContent}` : changedScenesContent,
+            existingPersona: existing, triggerInfo: input.triggerReason, personaFilePath: "persona.md", checkpointPath: "" });
+        const workspace = new DocumentWorkspace(run, persona ? [{ ...persona, filename: "persona.md", content: existing ?? "" }] : [], true);
+        const { write, edit } = workspace.tools();
+        await run.model(composeMemorySystemPrompt(prompts.systemPrompt, input.strategy), prompts.userPrompt, { write, edit });
+        if (!workspace.written.has("persona.md"))
+            throw new Error("Model did not write persona.md");
+        const body = escapeXmlTags(stripSceneNavigation(workspace.files.get("persona.md")).trim());
+        if (!body)
+            throw new Error("Empty persona output");
+        const navigation = escapeXmlTags(renderSceneNavigation(index(scenes), { pathFor: e => `scene_blocks/${e.filename}`, readTool: "read", footer: storageNavFooter("read") }));
+        const content = navigation ? `${body}\n\n${navigation}\n` : body;
+        const changes = content === persona?.content ? [] : [{ action: persona ? "update" : "create",
+                before: persona ? [{ id: persona.id, version: persona.version }] : [], after: {
+                    id: persona?.id ?? run.id(), version: (persona?.version ?? 0) + 1, scopeKey: input.scopeKey,
+                    filename: "persona.md", content, evidence: uniqueRefs([...scenes.flatMap(s => s.evidence), ...(persona?.evidence ?? [])]),
+                } }];
+        cov.processed = cov.remaining;
+        cov.remaining = [];
+        run.check();
+        return run.result(changes, cov);
+    }
+    catch (error) {
+        return run.failure(error, cov);
+    }
+}