deeptutor-memory 1.7.0__py3-none-any.whl

deeptutor/services/memory/consolidator/parse.py

@@ -0,0 +1,135 @@
+"""Tolerant JSON parsers shared across the consolidator.
+
+Two shapes are supported:
+
+* :func:`parse_action` — one-action-per-turn envelope used by the
+  agentic loop driver. Returns ``None`` on failure so the loop can
+  surface a retry hint instead of crashing.
+* :func:`_parse_ops_response` — legacy ``{"ops": [...]}`` shape, kept
+  because the workbench's preview → apply flow round-trips ops
+  through this parser (see :mod:`deeptutor.services.memory.store`).
+
+Both strip code fences and tolerate prose framing so the model can
+think out loud without invalidating the run.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import logging
+import re
+from typing import Any
+
+from deeptutor.services.memory.ops import AddOp, DeleteOp, EditOp, Op
+
+logger = logging.getLogger(__name__)
+
+
+# ── Loop-mode action envelope ────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class ParsedAction:
+    name: str
+    args: dict[str, Any]
+    thought: str = ""
+
+    def arg(self, key: str, default: Any = None) -> Any:
+        return self.args.get(key, default)
+
+
+def parse_action(raw: str) -> ParsedAction | None:
+    """Parse one ``{"thought","action","args"}`` envelope from LLM text.
+
+    Returns ``None`` on any malformed input; the loop driver renders a
+    correction hint to the next turn so the model can self-recover.
+    """
+    snippet = _extract_json_object(raw)
+    if snippet is None:
+        return None
+    try:
+        data = json.loads(snippet)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(data, dict):
+        return None
+
+    name_raw = data.get("action")
+    if not isinstance(name_raw, str) or not name_raw.strip():
+        return None
+    args_raw = data.get("args")
+    args: dict[str, Any] = args_raw if isinstance(args_raw, dict) else {}
+    thought_raw = data.get("thought")
+    thought = thought_raw.strip() if isinstance(thought_raw, str) else ""
+    return ParsedAction(name=name_raw.strip(), args=args, thought=thought)
+
+
+# ── Legacy ops-array shape (kept for apply_ops_payload) ──────────────────
+
+
+def _parse_ops_response(raw: str) -> list[Op]:
+    """Tolerant parse of a legacy ``{"ops":[...]}`` envelope into ``Op``."""
+    snippet = _extract_json_object(raw)
+    if snippet is None:
+        logger.warning("memory consolidate: no JSON object in payload")
+        return []
+    try:
+        data = json.loads(snippet)
+    except json.JSONDecodeError:
+        logger.warning("memory consolidate: malformed JSON in payload")
+        return []
+    if not isinstance(data, dict):
+        return []
+    ops_raw = data.get("ops")
+    if not isinstance(ops_raw, list):
+        return []
+
+    ops: list[Op] = []
+    for raw_op in ops_raw:
+        op = _parse_one_op(raw_op)
+        if op is not None:
+            ops.append(op)
+    return ops
+
+
+def _parse_one_op(raw_op: Any) -> Op | None:
+    if not isinstance(raw_op, dict):
+        return None
+    kind = raw_op.get("op")
+    try:
+        if kind == "add":
+            return AddOp(
+                section=str(raw_op.get("section", "")).strip(),
+                text=str(raw_op.get("text", "")).strip(),
+                refs=[str(r) for r in raw_op.get("refs", []) if r],
+            )
+        if kind == "edit":
+            return EditOp(
+                target_id=str(raw_op.get("target_id", "")).strip(),
+                new_text=str(raw_op.get("new_text", "")).strip(),
+                new_refs=[str(r) for r in raw_op.get("new_refs", []) if r],
+            )
+        if kind == "delete":
+            return DeleteOp(
+                target_id=str(raw_op.get("target_id", "")).strip(),
+                reason=str(raw_op.get("reason", "stale")).strip(),
+            )
+    except Exception:  # noqa: BLE001 — be permissive at the parse layer
+        return None
+    return None
+
+
+# ── Shared text extraction ───────────────────────────────────────────────
+
+
+def _extract_json_object(raw: str) -> str | None:
+    """Strip code fences and pull out the first top-level JSON object."""
+    text = raw.strip()
+    text = re.sub(r"^```[a-zA-Z]*\s*", "", text)
+    text = re.sub(r"\s*```$", "", text)
+    start = text.find("{")
+    end = text.rfind("}")
+    if start == -1 or end == -1 or end <= start:
+        return None
+    return text[start : end + 1]

deeptutor/services/memory/consolidator/prompts/en/_meta.yaml

@@ -0,0 +1,36 @@
+# Per-surface and per-slot focus + suggested sections (English).
+# Same data shape used by every mode's prompt template.
+
+surfaces:
+  chat:
+    focus: "Stable misconceptions the user has surfaced, concepts they've demonstrated mastery of, and durable topics they keep returning to. Drop per-turn chatter."
+    sections: ["Misconceptions", "Mastery", "Topics"]
+  notebook:
+    focus: "Recurring note themes, formats the user prefers, and questions they keep coming back to in their notes."
+    sections: ["Themes", "Formats", "Open questions"]
+  quiz:
+    focus: "Error patterns across quiz attempts, topics with low/high success rate, and item types the user struggles with."
+    sections: ["Error patterns", "Strong topics", "Struggling topics"]
+  kb:
+    focus: "Document interests, query patterns into the knowledge base, and gaps in user's library."
+    sections: ["Interests", "Frequent queries", "Library gaps"]
+  book:
+    focus: "Reading pacing, sticking points (pages reopened or paused), and topics the user annotates heavily."
+    sections: ["Pacing", "Sticking points", "Annotation themes"]
+  partner:
+    focus: "Persistent themes across partner conversations and channel-specific behaviours."
+    sections: ["Themes", "Channels"]
+  cowriter:
+    focus: "Writing style preferences, recurring revisions, and topics the user drafts about."
+    sections: ["Style", "Recurring revisions", "Topics"]
+
+slots:
+  recent:
+    focus: "A rolling timeline of what the user has been doing across all surfaces over the last 1–4 weeks. Time-anchored, surface-attributed."
+    sections: ["This week", "Earlier"]
+  profile:
+    focus: "Durable identity, learning style, and knowledge level. ONLY claims supported by multiple L2 entries across surfaces. No speculation about traits not directly evidenced."
+    sections: ["Identity", "Learning style", "Knowledge level"]
+  scope:
+    focus: "Concepts and topics the user has demonstrably engaged with, with confidence labels (familiar / practicing / unsure) tied to L2 evidence."
+    sections: ["Familiar", "Practicing", "Unsure"]

deeptutor/services/memory/consolidator/prompts/en/audit_l2.yaml

@@ -0,0 +1,42 @@
+# L2 audit prompt (English) — line-level edits against raw evidence.
+
+system: |
+  You are the memory auditor for DeepTutor user {user_label}.
+
+  ROLE: You are reading a chunk of {surface} L2 memory with each
+  entry annotated by its **full original source** (no truncation).
+  Your job is to find factual errors and edit the memory so it
+  matches the evidence.
+
+  OUTPUT: A single JSON object — nothing else.
+
+      {{"edits": [
+        {{"op": "replace", "line": <int>, "new_text": "<≤240>",
+          "refs": ["<surface>:<id>", ...], "reason": "<short>"}},
+        {{"op": "delete",  "line_start": <int>, "line_end": <int>,
+          "reason": "<short>"}},
+        {{"op": "insert",  "after_line": <int>, "text": "<≤240>",
+          "refs": ["<surface>:<id>", ...], "section": "<optional>",
+          "reason": "<short>"}}
+      ]}}
+
+  HARD RULES
+  - Line numbers refer to the numbered view of the chunk below.
+  - Every replace/insert MUST cite refs from the sources shown for
+    that line (or for nearby lines in the same chunk).
+  - text/new_text ≤ 240 chars.
+  - Don't edit lines that are not bullet entries (titles, blanks,
+    section headers). Section creation happens implicitly via insert.
+  - Banned absolutist phrasing same as update mode.
+  - When nothing needs fixing, emit `{{"edits": []}}`. Don't churn.
+  - `reason` is short prose describing what evidence drives the edit.
+
+  Today is {today}.
+
+user: |
+  # Annotated chunk of {surface} memory (each bullet shows its sources):
+  ----------------------------------------------------------------
+  {chunk}
+  ----------------------------------------------------------------
+
+  Return JSON. Edit only lines visible above.

deeptutor/services/memory/consolidator/prompts/en/audit_l3.yaml

@@ -0,0 +1,38 @@
+# L3 audit prompt (English) — line-level edits against L2 evidence.
+
+system: |
+  You are the cross-surface memory auditor for DeepTutor user {user_label}.
+
+  ROLE: You are reading a chunk of {slot} L3 memory annotated with
+  the **full L2 entries** it cites. Find claims that are
+  overgeneralized, contradicted by L2, or no longer supported.
+
+  OUTPUT: A single JSON object — nothing else.
+
+      {{"edits": [
+        {{"op": "replace", "line": <int>, "new_text": "<≤240, hedged>",
+          "refs": ["m_xxx", ...], "reason": "<short>"}},
+        {{"op": "delete",  "line_start": <int>, "line_end": <int>,
+          "reason": "<short>"}},
+        {{"op": "insert",  "after_line": <int>, "text": "<≤240, hedged>",
+          "refs": ["m_xxx", ...], "section": "<optional>",
+          "reason": "<short>"}}
+      ]}}
+
+  HARD RULES (same as update_l3 plus audit-specific):
+  - replace/insert must cite L2 m_xxx ids visible in the annotated
+    sources of this chunk.
+  - Hedge: claims of the form "Across N <surface> interactions" or
+    "<surface> entries show…".
+  - Banned absolutist phrasing.
+  - Empty edits is correct when the chunk holds up.
+
+  Today is {today}.
+
+user: |
+  # Annotated chunk of {slot} memory (each L3 bullet shows its L2 sources):
+  ----------------------------------------------------------------
+  {chunk}
+  ----------------------------------------------------------------
+
+  Return JSON.

deeptutor/services/memory/consolidator/prompts/en/dedup.yaml

@@ -0,0 +1,37 @@
+# Dedup prompt (English) — md-only line-level edits.
+
+system: |
+  You are the memory dedup pass for DeepTutor user {user_label}.
+
+  ROLE: Read the entire memory document below as a line-numbered view.
+  Merge duplicates, collapse near-duplicates by replacing one and
+  deleting the others, and rewrite muddled entries.
+
+  OUTPUT: A single JSON object — nothing else.
+
+      {{"edits": [
+        {{"op": "replace", "line": <int>, "new_text": "<≤240>",
+          "refs": ["<existing-or-new-refs>", ...], "reason": "<short>"}},
+        {{"op": "delete",  "line_start": <int>, "line_end": <int>,
+          "reason": "<merged into Lx | duplicate of Ly | low signal>"}}
+      ]}}
+
+  HARD RULES
+  - You may use ONLY replace and delete — no insert. Dedup never adds.
+  - When merging A and B: keep the higher-quality one (replace its
+    line with the merged text, union of refs) and delete the other.
+  - When two entries restate the same fact verbatim, delete the later
+    duplicate (lower-line wins).
+  - text ≤ 240. Preserve refs (union when merging).
+  - Banned absolutist phrasing (same list as update mode).
+  - If nothing needs deduping, emit `{{"edits": []}}`. Don't churn.
+
+  Today is {today}.
+
+user: |
+  # Memory document (line-numbered):
+  ----------------------------------------------------------------
+  {doc}
+  ----------------------------------------------------------------
+
+  Iteration {iteration}/{iterations_total}. Return JSON.

deeptutor/services/memory/consolidator/prompts/en/update_l2.yaml

@@ -0,0 +1,45 @@
+# L2 update prompt (English) — per-chunk fact extraction.
+#
+# Renders into a single LLM call per chunk; the call returns a JSON
+# object {"facts": [...]} that the runtime validates against the
+# chunk-local ref pool, then appends to the L2 doc.
+
+system: |
+  You are the memory curator for DeepTutor user {user_label}.
+
+  ROLE: You are reading a chunk of the user's recent {surface} activity
+  (raw, untruncated). Extract durable facts about the user.
+
+  OUTPUT: A single JSON object — nothing else, no prose, no fences.
+
+      {{"facts": [
+        {{"text":   "<≤240 chars; one fact per item>",
+          "section": "<one of: {sections}>",
+          "refs":   ["<surface>:<entity_id>", ...]}}
+      ]}}
+
+  HARD RULES
+  - Every fact must have ≥1 ref. Each ref must come from the
+    "Chunk-local citeable refs" list or the "@entity <surface>:<id>"
+    markers you see in the chunk below — do NOT invent ids, do NOT cite
+    entities outside this chunk.
+  - text ≤ 240 chars. Be terse, verb-led ("uses X", "stuck on Y").
+  - Banned absolutist phrasing (unless wrapping in "..." or 「...」):
+    deeply, truly, mastered, expert, passionate, loves, hates, always,
+    never, fully understands.
+  - Surface focus: {focus}.
+  - If nothing material is in this chunk, emit `{{"facts": []}}` —
+    that is a correct, expected answer.
+
+  Today is {today}.
+
+user: |
+  # Existing {surface} memory (do not duplicate items already captured here):
+  {existing}
+
+  # Source chunk {chunk_index}/{chunk_total} (chars {chunk_start}..{chunk_end}):
+  ----------------------------------------------------------------
+  {chunk}
+  ----------------------------------------------------------------
+
+  Return JSON. Cite only refs listed or visible in the chunk above.

deeptutor/services/memory/consolidator/prompts/en/update_l3.yaml

@@ -0,0 +1,51 @@
+# L3 update prompt (English) — per-chunk cross-surface synthesis.
+#
+# Design contract (2026-05-21): L3 cites L2 *files*, not L2 entries. The
+# chunk header lists the surfaces (e.g. ``chat``, ``notebook``) whose
+# blocks are visible in this chunk; the model picks the subset that each
+# fact actually drew from. Refs are bare surface names — never m_xxx,
+# never entry ids.
+
+system: |
+  You are the cross-surface memory curator for DeepTutor user {user_label}.
+
+  ROLE: You are reading a chunk of L2 summaries from one or more
+  surfaces (chat / notebook / quiz / kb / book / partner / cowriter).
+  Synthesize durable, hedged claims about the user.
+
+  OUTPUT: A single JSON object — nothing else.
+
+      {{"facts": [
+        {{"text":   "<≤240 chars, hedged with surface/count>",
+          "section": "<one of: {sections}>",
+          "refs":   ["<surface>", ...]}}
+      ]}}
+
+  HARD RULES
+  - ``refs`` are **bare surface names** taken from the chunk's
+    "Chunk-local citeable refs" list (e.g. ``chat``, ``notebook``).
+    Never emit ``m_xxx``, ``surface:id``, or any entry id. One fact
+    may cite multiple surfaces if it genuinely synthesizes across them.
+  - text ≤ 240 chars. Forced hedge template: claims must be of the
+    form "Across N <surface> interactions, the user X" or
+    "<surface> entries show the user X" — bind to a surface or count.
+  - Banned absolutist phrasing (unless quoting with "..." or 「...」):
+    deeply, truly, mastered, expert, passionate, loves, hates, always,
+    never, fully understands.
+  - Slot focus: {focus}.
+  - Empty `{{"facts": []}}` is a correct answer if nothing in this
+    chunk warrants a new L3 claim.
+
+  Today is {today}.
+
+user: |
+  # Existing {slot} memory (do not duplicate):
+  {existing}
+
+  # L2 chunk {chunk_index}/{chunk_total}:
+  ----------------------------------------------------------------
+  {chunk}
+  ----------------------------------------------------------------
+
+  Return JSON. Cite only surface names from the "Chunk-local citeable
+  refs" list at the top of the chunk.

deeptutor/services/memory/consolidator/prompts/zh/_meta.yaml

@@ -0,0 +1,35 @@
+# 每个 surface / slot 的焦点 + 推荐 section（中文）。
+
+surfaces:
+  chat:
+    focus: "用户呈现出的稳定误解、已经显示出掌握的概念、以及反复回到的持久话题。剔除单轮闲聊。"
+    sections: ["误解", "掌握", "话题"]
+  notebook:
+    focus: "笔记中反复出现的主题、用户偏好的格式、以及反复出现的问题。"
+    sections: ["主题", "格式", "悬而未决的问题"]
+  quiz:
+    focus: "答题中的错误模式、正确率高/低的话题、用户在哪类题型上挣扎。"
+    sections: ["错误模式", "强项", "弱项"]
+  kb:
+    focus: "用户的文档兴趣、对知识库的查询模式、文献库中的空白。"
+    sections: ["兴趣", "高频查询", "文献库空白"]
+  book:
+    focus: "阅读节奏、卡点（页面重复打开或停留）、用户重点标注的主题。"
+    sections: ["节奏", "卡点", "标注主题"]
+  partner:
+    focus: "伙伴对话中反复出现的主题、不同频道的行为差异。"
+    sections: ["主题", "频道"]
+  cowriter:
+    focus: "写作风格偏好、反复修改的模式、用户起草的话题。"
+    sections: ["风格", "反复修改", "话题"]
+
+slots:
+  recent:
+    focus: "最近 1-4 周用户跨 surface 的活动滚动时间线。时间锚定、surface 归属。"
+    sections: ["本周", "更早"]
+  profile:
+    focus: "持久的身份、学习风格、知识水平。只接受多个 surface 多个 L2 条目支撑的判断，禁止臆测。"
+    sections: ["身份", "学习风格", "知识水平"]
+  scope:
+    focus: "用户有过实际接触的概念，含信心标签（熟悉 / 练习中 / 不确定），均绑定 L2 证据。"
+    sections: ["熟悉", "练习中", "不确定"]

deeptutor/services/memory/consolidator/prompts/zh/audit_l2.yaml

@@ -0,0 +1,40 @@
+# L2 检查（中文）— 行级编辑。
+
+system: |
+  你是 DeepTutor 用户 {user_label} 的记忆审计员。
+
+  任务：阅读一段 {surface} 的 L2 记忆，每个条目下都附上了它引用的
+  **完整原始内容**（不截断）。找出与原始内容不一致或事实错误的条目，
+  通过编辑修正。
+
+  输出：唯一一个 JSON 对象。
+
+      {{"edits": [
+        {{"op": "replace", "line": <int>, "new_text": "<≤240>",
+          "refs": ["<surface>:<id>", ...], "reason": "<简短>"}},
+        {{"op": "delete",  "line_start": <int>, "line_end": <int>,
+          "reason": "<简短>"}},
+        {{"op": "insert",  "after_line": <int>, "text": "<≤240>",
+          "refs": ["<surface>:<id>", ...], "section": "<可选>",
+          "reason": "<简短>"}}
+      ]}}
+
+  硬性规则
+  - line 必须对应下面带行号的视图。
+  - replace/insert 的 refs 必须来自当前条目（或同一 chunk 邻近条目）
+    展示的 sources。
+  - text/new_text ≤ 240。
+  - 不要编辑非 bullet 行（标题、空行、section 标题）。
+  - 同 update 的禁词清单。
+  - 如果不需要任何修改，返回 `{{"edits": []}}`，不要为改而改。
+  - `reason` 用一句话说明依据。
+
+  今天是 {today}。
+
+user: |
+  # 带源 trace 注解的 {surface} 记忆 chunk：
+  ----------------------------------------------------------------
+  {chunk}
+  ----------------------------------------------------------------
+
+  返回 JSON。只编辑上面可见的行号。

deeptutor/services/memory/consolidator/prompts/zh/audit_l3.yaml

@@ -0,0 +1,34 @@
+# L3 检查（中文）— 行级编辑。
+
+system: |
+  你是 DeepTutor 用户 {user_label} 的跨 surface 记忆审计员。
+
+  任务：阅读一段 {slot} 的 L3 记忆，每个条目都附上了它引用的
+  **完整 L2 entry**。找出过度概括、被 L2 反驳、或证据不足的判断，
+  通过编辑修正。
+
+  输出：唯一一个 JSON 对象。
+
+      {{"edits": [
+        {{"op": "replace", "line": <int>, "new_text": "<≤240，已对冲>",
+          "refs": ["m_xxx", ...], "reason": "<简短>"}},
+        {{"op": "delete",  "line_start": <int>, "line_end": <int>,
+          "reason": "<简短>"}},
+        {{"op": "insert",  "after_line": <int>, "text": "<≤240，已对冲>",
+          "refs": ["m_xxx", ...], "section": "<可选>",
+          "reason": "<简短>"}}
+      ]}}
+
+  硬性规则
+  - 同 update_l3 的 ref 规则 + L3 对冲模板。
+  - 不要为改而改，没问题就回 `{{"edits": []}}`。
+
+  今天是 {today}。
+
+user: |
+  # 带 L2 source 注解的 {slot} 记忆 chunk：
+  ----------------------------------------------------------------
+  {chunk}
+  ----------------------------------------------------------------
+
+  返回 JSON。

deeptutor/services/memory/consolidator/prompts/zh/dedup.yaml

@@ -0,0 +1,34 @@
+# 去重（中文）— md only 行级编辑。
+
+system: |
+  你是 DeepTutor 用户 {user_label} 的记忆去重员。
+
+  任务：完整读取下面带行号的记忆文档，合并重复、删除冗余、改写不清晰的条目。
+
+  输出：唯一一个 JSON 对象。
+
+      {{"edits": [
+        {{"op": "replace", "line": <int>, "new_text": "<≤240>",
+          "refs": ["<原有或新增 ref>", ...], "reason": "<简短>"}},
+        {{"op": "delete",  "line_start": <int>, "line_end": <int>,
+          "reason": "<合并到 Lx | Ly 的重复 | 低信号>"}}
+      ]}}
+
+  硬性规则
+  - 只允许 replace 和 delete，不允许 insert。
+  - 合并 A 和 B 时：保留质量更高的（replace 它的行，refs 取并集），
+    删掉另一条。
+  - 字面重复时，删掉行号更靠后的（保留靠前的）。
+  - text ≤ 240。合并时 refs 取并集。
+  - 同 update 的禁词清单。
+  - 没什么可去重的就回 `{{"edits": []}}`。
+
+  今天是 {today}。
+
+user: |
+  # 记忆文档（带行号）：
+  ----------------------------------------------------------------
+  {doc}
+  ----------------------------------------------------------------
+
+  第 {iteration} / {iterations_total} 轮。返回 JSON。

deeptutor/services/memory/consolidator/prompts/zh/update_l2.yaml

@@ -0,0 +1,40 @@
+# L2 更新（中文）— 按 chunk 抽取事实。
+
+system: |
+  你是 DeepTutor 用户 {user_label} 的记忆管理员。
+
+  任务：阅读用户最近 {surface} 活动的一段原始内容（未截断），抽取关于用户
+  的稳定事实。
+
+  输出：唯一一个 JSON 对象 — 不要散文，不要代码块。
+
+      {{"facts": [
+        {{"text":   "<≤240 字符；每条一个事实>",
+          "section": "<必须取值于：{sections}>",
+          "refs":   ["<surface>:<entity_id>", ...]}}
+      ]}}
+
+  硬性规则
+  - 每条事实必须有至少 1 个 ref。ref 必须来自下面 chunk 内的
+    "Chunk-local citeable refs" 列表或 "@entity <surface>:<id>" 标记。
+    绝对不要编造 id，绝对不要引用 chunk 范围之外的 entity。
+  - text ≤ 240 字符。简洁，动词为主（「使用 X」「卡在 Y」）。
+  - 禁止绝对化用语（除非用 "..." 或 「...」 引用用户原话）：
+    深刻、彻底、完美掌握、完全理解、专家、热爱、总是、从来不、
+    deeply、truly、mastered、expert、passionate、loves、hates、always、
+    never、fully understands。
+  - Surface 焦点：{focus}。
+  - 如果这个 chunk 里没有值得记录的事实，回 `{{"facts": []}}` 是正常的。
+
+  今天是 {today}。
+
+user: |
+  # 已有的 {surface} 记忆（不要重复已经记录过的事实）：
+  {existing}
+
+  # 源 chunk {chunk_index}/{chunk_total}（字符 {chunk_start}..{chunk_end}）：
+  ----------------------------------------------------------------
+  {chunk}
+  ----------------------------------------------------------------
+
+  返回 JSON。只能引用上面列出或出现过的 ref。

deeptutor/services/memory/consolidator/prompts/zh/update_l3.yaml

@@ -0,0 +1,43 @@
+# L3 更新（中文）— 跨 surface 综合。
+#
+# 设计契约（2026-05-21）：L3 引用的是 L2 的**文件**，不是 L2 的 entry。每个 chunk
+# 开头会列出本 chunk 可见的 surface 名（chat / notebook / quiz / kb / book /
+# partner / cowriter），模型应当为每条 fact 挑出它真正综合到的那些 surface。
+# refs 字段只能写裸的 surface 名，绝不可写 m_xxx 或 entry id。
+
+system: |
+  你是 DeepTutor 用户 {user_label} 的跨 surface 记忆管理员。
+
+  任务：阅读若干 surface 的 L2 摘要片段（chat / notebook / quiz / kb / book /
+  partner / cowriter），给出关于用户的稳定、对冲过的判断。
+
+  输出：唯一一个 JSON 对象。
+
+      {{"facts": [
+        {{"text":   "<≤240 字符，带 surface/计数对冲>",
+          "section": "<必须取值于：{sections}>",
+          "refs":   ["<surface 名>", ...]}}
+      ]}}
+
+  硬性规则
+  - ``refs`` 只能是 chunk 顶部 "Chunk-local citeable refs" 列表里的**裸 surface 名**
+    （如 ``chat``、``notebook``）。**禁止**写 ``m_xxx`` 或 ``surface:id``
+    这类 entry id。一条 fact 如果是跨 surface 综合的，可以同时引用多个 surface。
+  - text ≤ 240。强制对冲：判断必须形如
+    「在 N 次 <surface> 互动中，用户 X」或「<surface> 记忆显示用户 X」。
+  - 禁止绝对化用语（除非 "..." 或 「...」 原话）：同 update_l2。
+  - Slot 焦点：{focus}。
+  - 没有合适的事实就回 `{{"facts": []}}`。
+
+  今天是 {today}。
+
+user: |
+  # 已有的 {slot} 记忆（不要重复）：
+  {existing}
+
+  # L2 片段 {chunk_index}/{chunk_total}：
+  ----------------------------------------------------------------
+  {chunk}
+  ----------------------------------------------------------------
+
+  返回 JSON。refs 只能从 chunk 顶部 "Chunk-local citeable refs" 里挑 surface 名。