@team-harness/memory-algorithms 0.1.0

package/dist/upstream/core/record/l1-extractor.d.ts

@@ -0,0 +1,33 @@
+import type { Logger } from "../../../contracts.js";
+import type { MemoryType } from "./l1-writer.js";
+interface SceneSegment {
+    scene_name: string;
+    message_ids: string[];
+    memories: Array<{
+        content: string;
+        type: string;
+        priority: number;
+        source_message_ids: string[];
+        metadata: Record<string, unknown>;
+    }>;
+}
+export type L1EmptyReason = "llm_error" | "no_json" | "parse_fail" | "not_array" | "empty_scenes";
+interface ParseExtractionOutcome {
+    scenes: SceneSegment[];
+    /** Populated iff we ended with 0 memories across all scenes. */
+    emptyReason?: L1EmptyReason;
+}
+/**
+ * Parse the LLM's JSON response into SceneSegment array.
+ * Expected format: [{scene_name, message_ids, memories: [...]}]
+ *
+ * Diagnostics contract:
+ *   - Debug-level [l1-debug] lines dump raw content on NO_JSON / PARSE_FAIL
+ *     (unchanged from prior behavior).
+ *   - The returned `emptyReason` is the CANONICAL machine-readable label —
+ *     `extractL1Memories` uses it to emit a single-line `l1-empty` warn when
+ *     the final count is 0. See L1EmptyReason for the closed set.
+ */
+export declare function parseExtractionResult(raw: string, logger?: Logger): ParseExtractionOutcome;
+export declare function normalizeType(raw: string): MemoryType | null;
+export {};

package/dist/upstream/core/record/l1-extractor.js

@@ -0,0 +1,128 @@
+import { sanitizeJsonForParse } from "../../utils/sanitize.js";
+const TAG = "[l1-parser]";
+const VALID_TYPES = ["persona", "episodic", "instruction", "work_fact", "work_task", "work_method", "work_artifact"];
+/**
+ * Parse the LLM's JSON response into SceneSegment array.
+ * Expected format: [{scene_name, message_ids, memories: [...]}]
+ *
+ * Diagnostics contract:
+ *   - Debug-level [l1-debug] lines dump raw content on NO_JSON / PARSE_FAIL
+ *     (unchanged from prior behavior).
+ *   - The returned `emptyReason` is the CANONICAL machine-readable label —
+ *     `extractL1Memories` uses it to emit a single-line `l1-empty` warn when
+ *     the final count is 0. See L1EmptyReason for the closed set.
+ */
+export function parseExtractionResult(raw, logger) {
+    try {
+        // ── Strip inline reasoning wrappers (A₂-style thinking models) ───────
+        // A₁ models (minimax-m2.7 / deepseek-v4-pro / o1 / o3 / Claude thinking)
+        // put reasoning in a separate `reasoning_content` field, so `content`
+        // itself is nothing but pure JSON — the strip below is a no-op.
+        //
+        // A₂ models (minimax-m3 / ep-2cocgw76 / GLM-4-thinking / qwq-32b / some
+        // vLLM-hosted DeepSeek-R1) inline reasoning as `<think>…</think>` inside
+        // the main `content`. Their think prose frequently contains stray `[`
+        // (message-id dumps, priority tags, and sometimes a full JSON template
+        // pre-written for "structure preview"), which fatally derails the greedy
+        // `/\[[\s\S]*\]/` array-match below by anchoring it inside the think
+        // section. So we peel `<think>` blocks BEFORE the array-match fires.
+        //
+        // Safeguards:
+        //   • non-greedy `*?` + explicit `</think>` requirement — a truncated
+        //     (max_tokens cap) think tag falls through as-is instead of eating
+        //     the rest of the response.
+        //   • `g` flag — rare multi-segment thinking is fully stripped.
+        // See docs/design/2026-09-03-l1-thinking-models-compatibility.md.
+        //
+        // NOTE: strip result goes to a new local (`stripped`) — we preserve the
+        // original `raw` so the NO_JSON / PARSE_FAIL dumps below still show
+        // exactly what came off the wire. If a future A₂ variant emits a shape
+        // this regex misses, ops need the pristine raw to diagnose it.
+        const stripped = raw.replace(/<think>[\s\S]*?<\/think>\s*/g, "");
+        // Strip markdown code block wrappers if present
+        let cleaned = stripped.trim();
+        if (cleaned.startsWith("```")) {
+            cleaned = cleaned.replace(/^```(?:json)?\s*\n?/, "").replace(/\n?```\s*$/, "");
+        }
+        // Try to extract JSON array
+        const arrayMatch = cleaned.match(/\[[\s\S]*\]/);
+        if (!arrayMatch) {
+            logger?.warn?.(`${TAG} No JSON array found in extraction response`);
+            // [l1-debug] NO_JSON — dump the full ORIGINAL raw (not the stripped
+            // version), otherwise a broken <think> variant would leave no trace.
+            const rawPreview = raw.slice(0, 2048);
+            logger?.warn?.(`${TAG} [l1-debug] NO_JSON taskId=l1-extraction, rawLen=${raw.length}, strippedLen=${stripped.length}, cleanedLen=${cleaned.length}, rawFull=${JSON.stringify(rawPreview)}${raw.length > 2048 ? `…(+${raw.length - 2048})` : ""}`);
+            return { scenes: [], emptyReason: "no_json" };
+        }
+        // Sanitize control characters inside JSON string literals that LLM may produce.
+        // Some weaker OpenAI-compatible models occasionally emit bare identifiers for
+        // numeric fields (e.g. `"priority": sheet`). Repair only known safe fields and
+        // retry once so one bad scalar does not drop the whole extraction result.
+        const sanitized = sanitizeJsonForParse(arrayMatch[0]);
+        let parsed;
+        try {
+            parsed = JSON.parse(sanitized);
+        }
+        catch (err) {
+            const repaired = repairExtractionJson(sanitized);
+            if (repaired === sanitized)
+                throw err;
+            parsed = JSON.parse(repaired);
+            logger?.warn?.(`${TAG} Repaired non-strict extraction JSON: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!Array.isArray(parsed)) {
+            logger?.warn?.(`${TAG} Extraction response is not an array`);
+            return { scenes: [], emptyReason: "not_array" };
+        }
+        const scenes = [];
+        for (const item of parsed) {
+            if (!item || typeof item !== "object")
+                continue;
+            const s = item;
+            scenes.push({
+                scene_name: typeof s.scene_name === "string" ? s.scene_name : "未知情境",
+                message_ids: Array.isArray(s.message_ids) ? s.message_ids.map(String) : [],
+                memories: Array.isArray(s.memories)
+                    ? s.memories
+                        .filter((m) => m && typeof m === "object" && typeof m.content === "string" && m.content.length > 0)
+                        .map((m) => ({
+                        content: String(m.content),
+                        type: String(m.type ?? "episodic"),
+                        priority: typeof m.priority === "number" ? m.priority : 50,
+                        source_message_ids: Array.isArray(m.source_message_ids) ? m.source_message_ids.map(String) : [],
+                        metadata: (m.metadata && typeof m.metadata === "object" ? m.metadata : {}),
+                    }))
+                    : [],
+            });
+        }
+        const totalMemories = scenes.reduce((acc, sc) => acc + sc.memories.length, 0);
+        return {
+            scenes,
+            emptyReason: totalMemories === 0 ? "empty_scenes" : undefined,
+        };
+    }
+    catch (err) {
+        logger?.warn?.(`${TAG} Failed to parse extraction result: ${err instanceof Error ? err.message : String(err)}`);
+        logger?.warn?.(`${TAG} [l1-debug] PARSE_FAIL rawLen=${raw.length}, rawFull=${JSON.stringify(raw)}`);
+        return { scenes: [], emptyReason: "parse_fail" };
+    }
+}
+function repairExtractionJson(json) {
+    return json
+        .replace(/("priority"\s*:\s*)(?!-?\d+(?:\.\d+)?\s*[,}]|"[^"\\]*(?:\\.[^"\\]*)*"\s*[,}])([\s\S]*?)(?=,\s*"(?:content|type|priority|source_message_ids|metadata)"\s*:|[}\]])/g, (_m, prefix) => `${prefix}50`)
+        .replace(/,\s*([}\]])/g, "$1");
+}
+export function normalizeType(raw) {
+    const lower = raw.toLowerCase().trim();
+    if (VALID_TYPES.includes(lower)) {
+        return lower;
+    }
+    // Handle legacy type names
+    if (lower === "episode")
+        return "episodic";
+    if (lower === "instruct")
+        return "instruction";
+    if (lower === "preference")
+        return "persona"; // fold preference into persona
+    return null;
+}

package/dist/upstream/core/record/l1-writer.d.ts

@@ -0,0 +1,95 @@
+export type MemoryType = "persona" | "episodic" | "instruction" | "work_fact" | "work_task" | "work_method" | "work_artifact";
+/** Metadata for episodic memories (activity time range) */
+export interface EpisodicMetadata {
+    activity_start_time?: string;
+    activity_end_time?: string;
+}
+/**
+ * A persisted memory record in L1 JSONL files.
+ *
+ * v3 changes from v2:
+ * - `importance: "high"|"medium"|"low"` → `priority: number` (0-100, -1 for strict global instructions)
+ * - Added `scene_name`, `source_message_ids`, `metadata`, `timestamps`
+ * - Removed `keywords` (will be rebuilt from content for search)
+ * - MemoryType reduced from 4 to 3 (removed "preference", folded into "persona")
+ */
+export interface MemoryRecord {
+    /** Unique ID for dedup updates */
+    id: string;
+    /** Memory content */
+    content: string;
+    /** Memory type: persona / episodic / instruction */
+    type: MemoryType;
+    /** Priority score: 0-100 (higher = more important), -1 = strict global instruction */
+    priority: number;
+    /** Scene name this memory belongs to */
+    scene_name: string;
+    /** Source message IDs that contributed to this memory */
+    source_message_ids: string[];
+    /** Type-specific metadata (e.g., activity_start_time for episodic) */
+    metadata: EpisodicMetadata | Record<string, never>;
+    /** Timestamp trail: all timestamps related to this memory (for merge history tracking) */
+    timestamps: string[];
+    /** Creation timestamp (ISO) */
+    createdAt: string;
+    /** Last update timestamp (ISO) */
+    updatedAt: string;
+    /** Monotonic version. New memories start at 1; update/merge increments by 1. */
+    version?: number;
+    /** Source session key (conversation channel identifier) */
+    sessionKey: string;
+    /** Source session ID (single conversation instance identifier) */
+    sessionId: string;
+    /** Optional task dimension for L0/L1 filtering. */
+    taskId?: string;
+    /**
+     * Three-dim tenancy isolation (new in this branch).
+     *
+     * `userId` / `agentId` are mandatory for new writes once gateway-level
+     * isolation enforcement is on, but kept optional on the type to avoid
+     * breaking pre-isolation call sites and tests during rollout. The SQLite
+     * upsert defaults them to '' if missing; the migration script backfills
+     * existing rows with `__legacy__`.
+     *
+     * See `docs/l0l3-tenant-isolation-design.md`.
+     */
+    teamId?: string;
+    userId?: string;
+    agentId?: string;
+}
+/**
+ * A memory as extracted by LLM (before dedup / persistence).
+ * Matches the output format of Kenty's extraction prompt.
+ */
+export interface ExtractedMemory {
+    content: string;
+    type: MemoryType;
+    priority: number;
+    source_message_ids: string[];
+    metadata: EpisodicMetadata | Record<string, never>;
+    /** Scene name this memory was extracted in */
+    scene_name: string;
+}
+export type DedupAction = "store" | "update" | "merge" | "skip";
+/**
+ * v3 batch dedup decision — one per new memory, aligned with Kenty's conflict detection prompt.
+ *
+ * Key changes:
+ * - `targetId` → `target_ids` (array, supports multi-target merge/update)
+ * - Added `merged_type`, `merged_priority`, `merged_timestamps` for cross-type merge
+ */
+export interface DedupDecision {
+    /** Which new memory this decision is about */
+    record_id: string;
+    action: DedupAction;
+    /** IDs of existing records to replace/remove (for update/merge) */
+    target_ids: string[];
+    /** Merged/updated content text (for update/merge) */
+    merged_content?: string;
+    /** Best type after merge (for update/merge, may differ from original) */
+    merged_type?: MemoryType;
+    /** Priority after merge (for update/merge) */
+    merged_priority?: number;
+    /** Union of all related timestamps (for update/merge) */
+    merged_timestamps?: string[];
+}

package/dist/upstream/core/record/l1-writer.js

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

package/dist/upstream/core/scene/filename-normalizer.d.ts

@@ -0,0 +1,6 @@
+export declare function normalizeSceneFilename(name: string): string;
+/**
+ * Return whether a filename already matches its normalized form.
+ * Faster than computing the normalized form when callers only need a yes/no.
+ */
+export declare function isNormalizedSceneFilename(name: string): boolean;

package/dist/upstream/core/scene/filename-normalizer.js

@@ -0,0 +1,30 @@
+export function normalizeSceneFilename(name) {
+    if (!name)
+        return "scene.md";
+    // Strip directory components defensively — we only normalize the basename.
+    const base = name.replace(/^.*[\\/]/, "");
+    // Detect & strip `.md` (case-insensitive). Always re-emit lowercase `.md`.
+    const lower = base.toLowerCase();
+    const hasMd = lower.endsWith(".md");
+    const stem = hasMd ? base.slice(0, -3) : base;
+    const safe = stem
+        // Replace whitespace runs (incl. NBSP, full-width space) with `-`
+        .replace(/[\s\u00A0\u3000]+/g, "-")
+        // Drop quotes, brackets, and punctuation known to break shells/markdown.
+        // Keep alphanumerics, CJK ideographs, `-`, `_`, `.`.
+        .replace(/[()[\]{}<>'"`,;:!?*|/\\=&%$#@^~+]/g, "")
+        // Collapse consecutive separators.
+        .replace(/-{2,}/g, "-")
+        .replace(/_{2,}/g, "_")
+        .replace(/\.{2,}/g, ".")
+        // Trim leading / trailing separators.
+        .replace(/^[-_.]+|[-_.]+$/g, "");
+    return (safe || "scene") + ".md";
+}
+/**
+ * Return whether a filename already matches its normalized form.
+ * Faster than computing the normalized form when callers only need a yes/no.
+ */
+export function isNormalizedSceneFilename(name) {
+    return normalizeSceneFilename(name) === name;
+}

package/dist/upstream/core/scene/scene-format.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Scene Block file format: parse and format the META-delimited Markdown files.
+ */
+export interface SceneBlockMeta {
+    created: string;
+    updated: string;
+    summary: string;
+    heat: number;
+}
+export interface SceneBlock {
+    filename: string;
+    meta: SceneBlockMeta;
+    content: string;
+}
+/**
+ * Parse a Scene Block file into structured data.
+ */
+export declare function parseSceneBlock(raw: string, filename: string): SceneBlock;
+/**
+ * Format a Scene Block back into file content.
+ */
+export declare function formatSceneBlock(meta: SceneBlockMeta, content: string): string;
+/**
+ * Format the META section.
+ */
+export declare function formatMeta(meta: SceneBlockMeta): string;

package/dist/upstream/core/scene/scene-format.js

@@ -0,0 +1,53 @@
+/**
+ * Scene Block file format: parse and format the META-delimited Markdown files.
+ */
+const META_START = "-----META-START-----";
+const META_END = "-----META-END-----";
+/**
+ * Parse a Scene Block file into structured data.
+ */
+export function parseSceneBlock(raw, filename) {
+    const startIdx = raw.indexOf(META_START);
+    const endIdx = raw.indexOf(META_END);
+    if (startIdx === -1 || endIdx === -1) {
+        // No META section — treat entire file as content
+        return {
+            filename,
+            meta: { created: "", updated: "", summary: "", heat: 0 },
+            content: raw.trim(),
+        };
+    }
+    const metaBlock = raw.slice(startIdx + META_START.length, endIdx).trim();
+    const content = raw.slice(endIdx + META_END.length).trim();
+    const meta = {
+        created: extractMetaField(metaBlock, "created"),
+        updated: extractMetaField(metaBlock, "updated"),
+        summary: extractMetaField(metaBlock, "summary"),
+        heat: parseInt(extractMetaField(metaBlock, "heat"), 10) || 0,
+    };
+    return { filename, meta, content };
+}
+/**
+ * Format a Scene Block back into file content.
+ */
+export function formatSceneBlock(meta, content) {
+    return `${formatMeta(meta)}\n\n${content}`;
+}
+/**
+ * Format the META section.
+ */
+export function formatMeta(meta) {
+    return [
+        META_START,
+        `created: ${meta.created}`,
+        `updated: ${meta.updated}`,
+        `summary: ${meta.summary}`,
+        `heat: ${meta.heat}`,
+        META_END,
+    ].join("\n");
+}
+function extractMetaField(metaBlock, field) {
+    const re = new RegExp(`^${field}:\\s*(.*)$`, "m");
+    const m = metaBlock.match(re);
+    return m ? m[1].trim() : "";
+}

package/dist/upstream/core/scene/scene-index.d.ts

@@ -0,0 +1,7 @@
+export interface SceneIndexEntry {
+    filename: string;
+    summary: string;
+    heat: number;
+    created: string;
+    updated: string;
+}

package/dist/upstream/core/scene/scene-index.js

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

package/dist/upstream/core/scene/scene-navigation.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Scene navigation: generates a summary navigation section appended to persona.md.
+ *
+ * The navigation includes **absolute** file paths so the agent can directly
+ * use read_file for on-demand scene loading (progressive disclosure).
+ */
+import type { SceneIndexEntry } from "./scene-index.js";
+/**
+ * Footer for backends addressed by storage key rather than filesystem path.
+ * The reading tool is a property of the mounted surface, not of the backend,
+ * so it is supplied by whoever assembles the two.
+ */
+export declare function storageNavFooter(readTool: string): string;
+export interface SceneNavigationRenderOptions {
+    /**
+     * Resolves an entry to the path the reader must pass back. Callers hand in
+     * the same resolver they serve reads from, so a rendered path is by
+     * construction a path that can be read (design doc D12).
+     */
+    pathFor: (entry: SceneIndexEntry) => string;
+    /** Tool the model should call, named in the intro line. */
+    readTool: string;
+    footer: string;
+}
+/**
+ * Generate the scene navigation Markdown section.
+ *
+ * @param entries - Scene index entries
+ * @param dataDir - Absolute path to the plugin data directory; when provided
+ *                  and useCos=false, paths are absolute for read_file.
+ * @param useCos  - When true, paths use scenes/ prefix and footer says tdai_read_file.
+ *
+ * ⚠️ KNOWN BROKEN — the `useCos=true` branch emits unreadable paths. Do not
+ * build on it, and do not "fix" it by renaming scenes/ -> scene_blocks/ alone.
+ *
+ * It is wrong on two levels: the directory name is a leftover from the deleted
+ * CosPathResolver design (real layout is scene_blocks/), and the emitted key
+ * also omits the profiles/{scope}/ segment, because navigation is generated
+ * against a scoped storage view while the read tool holds an unscoped root.
+ *
+ * Left unfixed deliberately: no live read path reaches it. The Proxy reads L2
+ * through /v3/scenario/ls + /v3/scenario/read, and the OpenClaw plugin builds
+ * TdaiCore without a storage adapter, so useCos is always false there. The one
+ * caller that can set useCos=true is the legacy POST /recall endpoint, which
+ * currently has no consumer.
+ *
+ * Reviving POST /recall on the main path REQUIRES fixing this first. The real
+ * fix is to make navigation and the read tool share one scoped resolver, which
+ * is tracked as P10.
+ *
+ * See docs/design/mongodb/design/2026-08-27-core-storage-abstraction-design.md
+ * (D13, §10.C3.1, known issue L6).
+ */
+export declare function generateSceneNavigation(entries: SceneIndexEntry[], dataDir?: string, useCos?: boolean): string;
+/**
+ * Render the navigation section from entries and a caller-supplied resolver.
+ *
+ * Taking `pathFor` instead of a mode flag is the point: a backend renders the
+ * paths it actually serves, so navigation and reads cannot drift apart the way
+ * the `useCos` branch above did.
+ */
+export declare function renderSceneNavigation(entries: SceneIndexEntry[], opts: SceneNavigationRenderOptions): string;
+/**
+ * Strip the scene navigation section from persona content.
+ */
+export declare function stripSceneNavigation(personaContent: string): string;

package/dist/upstream/core/scene/scene-navigation.js

@@ -0,0 +1,107 @@
+/**
+ * Scene navigation: generates a summary navigation section appended to persona.md.
+ *
+ * The navigation includes **absolute** file paths so the agent can directly
+ * use read_file for on-demand scene loading (progressive disclosure).
+ */
+import path from "node:path";
+const NAV_HEADER = "---\n## 🗺️ Scene Navigation (Scene Index)";
+const NAV_FOOTER_LOCAL = `📌 使用说明：
+- Path 是 scene block 的绝对路径，可直接使用 **read** 工具读取完整内容（参数: filePath）
+- 热度：该场景被记忆命中的累计次数，越高越重要
+- Summary：场景的核心要点摘要`;
+/**
+ * Footer for backends addressed by storage key rather than filesystem path.
+ * The reading tool is a property of the mounted surface, not of the backend,
+ * so it is supplied by whoever assembles the two.
+ */
+export function storageNavFooter(readTool) {
+    return `📌 使用说明：
+- Path 是 scene block 的存储路径，请使用 **${readTool}** 工具读取完整内容（参数: path）
+- 热度：该场景被记忆命中的累计次数，越高越重要
+- Summary：场景的核心要点摘要`;
+}
+/**
+ * Build a fire-emoji string based on heat value (visual priority cue for the agent).
+ */
+function heatEmoji(heat) {
+    if (heat >= 1000)
+        return " 🔥🔥🔥🔥🔥";
+    if (heat >= 500)
+        return " 🔥🔥🔥🔥";
+    if (heat >= 200)
+        return " 🔥🔥🔥";
+    if (heat >= 100)
+        return " 🔥🔥";
+    if (heat >= 50)
+        return " 🔥";
+    return "";
+}
+/**
+ * Generate the scene navigation Markdown section.
+ *
+ * @param entries - Scene index entries
+ * @param dataDir - Absolute path to the plugin data directory; when provided
+ *                  and useCos=false, paths are absolute for read_file.
+ * @param useCos  - When true, paths use scenes/ prefix and footer says tdai_read_file.
+ *
+ * ⚠️ KNOWN BROKEN — the `useCos=true` branch emits unreadable paths. Do not
+ * build on it, and do not "fix" it by renaming scenes/ -> scene_blocks/ alone.
+ *
+ * It is wrong on two levels: the directory name is a leftover from the deleted
+ * CosPathResolver design (real layout is scene_blocks/), and the emitted key
+ * also omits the profiles/{scope}/ segment, because navigation is generated
+ * against a scoped storage view while the read tool holds an unscoped root.
+ *
+ * Left unfixed deliberately: no live read path reaches it. The Proxy reads L2
+ * through /v3/scenario/ls + /v3/scenario/read, and the OpenClaw plugin builds
+ * TdaiCore without a storage adapter, so useCos is always false there. The one
+ * caller that can set useCos=true is the legacy POST /recall endpoint, which
+ * currently has no consumer.
+ *
+ * Reviving POST /recall on the main path REQUIRES fixing this first. The real
+ * fix is to make navigation and the read tool share one scoped resolver, which
+ * is tracked as P10.
+ *
+ * See docs/design/mongodb/design/2026-08-27-core-storage-abstraction-design.md
+ * (D13, §10.C3.1, known issue L6).
+ */
+export function generateSceneNavigation(entries, dataDir, useCos = false) {
+    return renderSceneNavigation(entries, {
+        pathFor: (e) => useCos
+            ? `scenes/${e.filename}`
+            : dataDir
+                ? path.join(dataDir, "scene_blocks", e.filename)
+                : `scene_blocks/${e.filename}`,
+        readTool: useCos ? "tdai_read_file" : "read",
+        footer: useCos ? storageNavFooter("tdai_read_file") : NAV_FOOTER_LOCAL,
+    });
+}
+/**
+ * Render the navigation section from entries and a caller-supplied resolver.
+ *
+ * Taking `pathFor` instead of a mode flag is the point: a backend renders the
+ * paths it actually serves, so navigation and reads cannot drift apart the way
+ * the `useCos` branch above did.
+ */
+export function renderSceneNavigation(entries, opts) {
+    if (entries.length === 0)
+        return "";
+    const sorted = [...entries].sort((a, b) => b.heat - a.heat);
+    const blocks = sorted.map((e) => {
+        const pathLine = `### Path: ${opts.pathFor(e)}`;
+        const heatLine = `**热度**: ${e.heat}${heatEmoji(e.heat)}${e.updated ? ` | **更新**: ${e.updated}` : ""}`;
+        const summaryLine = `Summary: ${e.summary}`;
+        return `${pathLine}\n${heatLine}\n${summaryLine}`;
+    });
+    return `${NAV_HEADER}\n*以下是当前场景记忆的索引，可根据需要 ${opts.readTool} 读取详细内容。*\n\n${blocks.join("\n\n")}\n\n${opts.footer}`;
+}
+/**
+ * Strip the scene navigation section from persona content.
+ */
+export function stripSceneNavigation(personaContent) {
+    const idx = personaContent.indexOf(NAV_HEADER);
+    if (idx === -1)
+        return personaContent;
+    return personaContent.slice(0, idx).trimEnd();
+}

package/dist/upstream/core/skill/conversation-add/message-compressor.d.ts

@@ -0,0 +1,47 @@
+/**
+ * SkillMessageCompressor — compress oversized tool_call / tool_result payloads
+ * before they enter the skill buffer.
+ *
+ * 对应设计文档 `2026-07-15-skill-trigger-in-core-design.md` §6：
+ *   - 只压 tool_call / tool_result；user / assistant / system 永不压缩
+ *   - content 字节数 > 2KB 才压缩，头 1KB + 尾 1KB + 中间占位提示
+ *   - metadata.truncated = true, metadata.original_bytes = <原始字节数>
+ *
+ * 字节切分实现说明：
+ *   直接对 Buffer 做 slice 可能截到 UTF-8 多字节字符的中间，转回 string 会
+ *   出现 U+FFFD 替换字符。这里我们对 Buffer 做切片、再 toString('utf8')，
+ *   Node 侧会把结尾/开头不完整的多字节序列替换成 U+FFFD——但整体不影响
+ *   下游 LLM review 的语义（提示语里说明了截断）。对于 tool payload 这种
+ *   通常是 ASCII/JSON 的场景，边界字符损坏概率极低；测试对齐宽松断言。
+ */
+export type CompressibleRole = "user" | "assistant" | "tool_call" | "tool_result" | "system";
+export interface CompressibleMessage {
+    role: CompressibleRole;
+    content: string;
+    /** Optional tool identity for tool_call / tool_result. */
+    tool_name?: string;
+    tool_call_id?: string;
+    timestamp?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface CompressOptions {
+    /** 字节阈值；tool 消息 content bytes > 阈值才压缩。默认 2048 (2KB)。 */
+    toolContentThresholdBytes: number;
+    /** 头部保留字节数。默认 1024 (1KB)。 */
+    headBytes: number;
+    /** 尾部保留字节数。默认 1024 (1KB)。 */
+    tailBytes: number;
+    /** 中间占位字符串。 */
+    placeholder: string;
+}
+export declare const DEFAULT_COMPRESS_OPTIONS: CompressOptions;
+/**
+ * Compress a single message. Returns a new object if compressed, otherwise
+ * returns the original message reference unchanged.
+ */
+export declare function compressMessage(msg: CompressibleMessage, optsOverride?: Partial<CompressOptions>): CompressibleMessage;
+/**
+ * Compress an array of messages. Returns a new array; unchanged messages
+ * share the original reference (identity-preserving for downstream diffing).
+ */
+export declare function compressMessages(messages: CompressibleMessage[], optsOverride?: Partial<CompressOptions>): CompressibleMessage[];