Python
"""Episode-scoped summary:一次讨论结束时总结一次,而不是每攒够 N 轮就重写一遍。
与固定窗口摘要的区别
--------------------------------------------------
固定窗口摘要按 user turn 数积累:每达到一个窗口就触发一次,
并且要把**上一条摘要文本喂回 LLM** 做延续/合并,旧摘要置 SHADOW。
对一次长讨论(十几二十轮、跨几次 write)来说这意味着:
turn 10 → 调 LLM(输入 10 轮)
turn 20 → 调 LLM(输入 prev_summary + 10 轮),把 turn 10 的产出作废
turn 30 → 调 LLM(输入 prev_summary + 10 轮),把 turn 20 的产出作废
付了 3 次 token、上下文还越来越长,最终只留下 1 条摘要。
Episode 划分是**免费的**(按写入时间间隔切,不用 LLM),而且天然对应"一件事"。
于是可以换成:**等这件事结束了,总结一次**。
episode 关闭 → 调 LLM(输入该 episode 的全部记忆)→ 1 条摘要,无需 merge
一次讨论只付一次 token,也不产生"写了又作废"的中间摘要。
摘要从**已抽取的记忆**出发(而不是原始对话轮),这和 topic summary 的做法一致:
记忆本身就是我们要留下的东西,且比原始轮次省 token。代价是没进记忆的闲聊细节不会进摘要 ——
对检索用途来说这是想要的行为。
状态不额外建表,存在摘要节点自己的 `custom` 里:
custom = {
"summary_kind": "episode",
"episode_id": ...,
"covered_count": N,
"source_memory_ids": [...],
}
"""
import asyncio
import logging
import hashlib
import json
import re
from datetime import datetime
from typing import Any, Dict, List, Optional
import uuid
from ..prompts import (
get_prompt,
normalize_language,
resolve_language,
with_output_language,
)
from ..utils.source_filter import merge_sources
logger = logging.getLogger(__name__)
SUMMARY_KIND_EPISODE = "episode"
SUMMARY_KIND_SESSION_EPISODE = "session_episode"
SUMMARY_KIND_DYNAMIC_EPISODE = "dynamic_episode"
SUMMARY_KIND_SERIES_EPISODE = "series_episode"
DYNAMIC_BOUNDARY_PROMPT = """You are an episodic-memory boundary detector. Split a complete conversation
into durable, independently retrievable events.
Default to merging messages that develop the same event. Split when a completed
real-world event, activity, trip, problem, achievement, plan, or purpose is followed
by another event that could be asked about separately later. Smooth social
transitions do not make different events one memory. For example, recipe/health,
painting classes, and a later skiing trip should be separate episodes.
Keep greetings, reactions, encouragement, and farewells with the event they support.
Avoid fragments containing only acknowledgements.
Return JSON only:
{{"reasoning":"brief explanation","event_count":3,"boundaries":[10,22]}}
Consistency requirement: event_count MUST equal len(boundaries)+1. If your reasoning
describes several separate events, boundaries cannot be empty. A boundary is the
1-based message number AFTER which an episode ends. Never include the final message.
Session time: {timestamp}
Messages:
{messages}
"""
DYNAMIC_BOUNDARY_CORRECTION_PROMPT = """Your previous boundary JSON was internally inconsistent.
Previous output:
{previous}
Return a corrected JSON object only. `event_count` must equal len(boundaries)+1, and
the boundary indices must correspond to the distinct events named in the reasoning.
Valid boundary range is 1 through {last_boundary}.
"""
DYNAMIC_CAPSULE_PROMPT = """Convert this ONE coherent conversation episode into a compact retrieval capsule.
The capsule will be combined with exact atomic memories already matched by search.
It should restore context and completeness without repeating every conversational turn.
Rules:
- Write a third-person narrative of roughly 100-180 English tokens.
- Preserve full names and attribution: who did or felt what.
- Preserve dates, places, numbers, named items, causes, outcomes, and whether an
event was planned or completed.
- Preserve complete short lists when the conversation provides them.
- Remove greetings, encouragement, repeated agreement, and generic advice unless
they change the event outcome.
- Do not invent or infer unstated relationships.
- Use the session timestamp to clarify relative time, while keeping the original
relation when useful.
Return JSON only:
{{"title":"specific retrieval title","summary":"compact narrative"}}
Session time: {timestamp}
Messages:
{messages}
"""
# 多语言版本见 hy_memory/prompts/<language>.py;旧名字保留为别名。
from ..prompts.en import EPISODE_SUMMARY_PROMPT # noqa: E402,F401 (re-export)
from ..prompts.zh_hans import EPISODE_SUMMARY_PROMPT as EPISODE_SUMMARY_PROMPT_ZH # noqa: E402,F401 (re-export)
SESSION_EPISODE_PROMPT = """Convert this complete conversation session into one retrieval-friendly episode narrative.
Rules:
- Write a coherent third-person account, not a bullet list and not dialogue.
- Preserve all concrete facts that could answer a later question: full person names, who did what, dates, sequence, numbers, places, reasons, feelings, decisions, and completed events versus plans.
- Resolve relative dates against the supplied session date and include the absolute date in parentheses while preserving the original relation when useful.
- Keep different people clearly attributed. Do not replace names with an ambiguous 'the user'.
- Do not add facts or general advice that was not stated.
- Be concise but complete. Return only the narrative.
Session date: {timestamp}
Conversation:
{conversation}
"""
def session_episode_id(user_id: str, agent_id: str, session_id: str) -> str:
"""Stable UUID makes explicit finalize idempotent across vector backends."""
raw = "\0".join((user_id or "", agent_id or "default_agent",
session_id or "default_session"))
return str(uuid.uuid5(uuid.NAMESPACE_URL, "hy-memory:session-episode:" + raw))
def _parse_json_object(text: str) -> dict:
raw = (text or "").strip()
if raw.startswith("```"):
raw = re.sub(r"^```(?:json)?\s*", "", raw)
raw = re.sub(r"\s*```$", "", raw)
try:
value = json.loads(raw)
except json.JSONDecodeError:
from json_repair import repair_json
value = json.loads(repair_json(raw))
if not isinstance(value, dict):
raise ValueError("episode response must be a JSON object")
return value
def _raw_messages(raw_nodes: List[Any]) -> List[dict]:
"""Recover ordered role/name messages from stored L1_RAW chunks."""
messages: List[dict] = []
pattern = re.compile(r"(?m)^\[([^\]]+)\]:\s*")
for node in raw_nodes:
content = (getattr(node, "content", "") or "").strip()
matches = list(pattern.finditer(content))
if not matches:
if content:
messages.append({
"speaker": "unknown", "content": content,
"source_raw_memory_id": node.node_id,
})
continue
for index, match in enumerate(matches):
end = matches[index + 1].start() if index + 1 < len(matches) else len(content)
body = content[match.end():end].strip()
if body:
messages.append({
"speaker": match.group(1).strip(), "content": body,
"source_raw_memory_id": node.node_id,
})
return messages
def _render_messages(messages: List[dict]) -> str:
return "\n".join(
f"[{index}] {message['speaker']}: {message['content']}"
for index, message in enumerate(messages, 1)
)
def _dynamic_episode_id(
user_id: str, agent_id: str, session_id: str, raw_digest: str,
start: int, end: int,
) -> str:
raw = "\0".join((user_id, agent_id, session_id, raw_digest, str(start), str(end)))
return str(uuid.uuid5(uuid.NAMESPACE_URL, "hy-memory:dynamic-episode:" + raw))
def _series_episode_id(
user_id: str, agent_id: str, member_ids: List[str],
) -> str:
"""Stable identity for one cross-session episode component."""
raw = "\0".join((user_id, agent_id, *sorted(set(member_ids))))
return str(uuid.uuid5(uuid.NAMESPACE_URL, "hy-memory:series-episode:" + raw))
def _series_memory_at(times: List[int]) -> Optional[datetime]:
"""Earliest member timestamp as the same local wall clock it came from.
``_node_timestamp`` produces ``datetime.timestamp()`` values. Reading them
back with ``utcfromtimestamp`` turns them into a naive *UTC* datetime, which
the vector payload later re-interprets as local time and shifts by the
machine's UTC offset.
"""
return datetime.fromtimestamp(min(times)) if times else None
def _node_timestamp(node: Any) -> Optional[int]:
value = getattr(node, "memory_at", None) or getattr(node, "gmt_created", None)
if value is None:
return None
try:
return int(value.timestamp())
except (AttributeError, TypeError, OSError, ValueError):
try:
return int(value)
except (TypeError, ValueError):
return None
def _series_episode_label(facts: List[Any], episode_count: int, session_count: int) -> tuple[str, str]:
"""Build small navigational text without copying any member L2 body."""
tag_sets = []
original_by_key: Dict[str, str] = {}
for fact in facts:
keys = set()
tags = list(getattr(fact, "tags", None) or [])
tag_ners = list(getattr(fact, "tag_ners", None) or [])
for index, tag in enumerate(tags):
text = str(tag or "").strip()
ner = str(tag_ners[index] if index < len(tag_ners) else "").upper()
if not text or ner == "PERSON":
continue
key = re.sub(r"\s+", " ", text.casefold())
if len(key) > 4 and key.endswith("s") and not key.endswith("ss"):
key = key[:-1]
keys.add(key)
original_by_key.setdefault(key, text)
if keys:
tag_sets.append(keys)
shared = set.intersection(*tag_sets) if tag_sets else set()
generic = {
"event", "events", "experience", "experiences", "activity", "activities",
"memory", "memories", "personal", "user",
}
labels = [original_by_key[key] for key in sorted(shared) if key not in generic]
title = ", ".join(labels[:3]) + " timeline" if labels else "Related events across time"
intro = (
f"A timeline of {episode_count} explicitly linked episodes "
f"across {session_count} sessions."
)
return title[:500], intro
def _series_episode_plans(nodes: List[Any], edges: List[Dict[str, Any]]) -> List[dict]:
"""Plan cross-session containers from exact provenance or typed relations.
Tags, generic semantic similarity and co-occurrence are intentionally ignored.
"""
from ..models.memory import MemoryLayer, MemoryStatus
from ..pipelines._retrieval.session_episode import parent_episode_ids
active_l2 = {
node.node_id: node for node in nodes
if getattr(node, "layer", None) == MemoryLayer.L2_FACT
and getattr(node, "status", None) == MemoryStatus.ACTIVE
and bool(getattr(node, "is_latest", True))
}
episodes = {
node.node_id: node for node in nodes
if getattr(node, "layer", None) == MemoryLayer.L3_SUMMARY
and getattr(node, "status", None) == MemoryStatus.ACTIVE
and bool(getattr(node, "is_latest", True))
and (getattr(node, "custom", None) or {}).get("summary_kind")
== SUMMARY_KIND_DYNAMIC_EPISODE
}
if len(episodes) < 2 or not active_l2:
return []
episode_ids_by_fact: Dict[str, List[str]] = {}
for fact_id, fact in active_l2.items():
item = {"node_id": fact_id, "node": fact}
episode_ids_by_fact[fact_id] = [
episode_id for episode_id in parent_episode_ids(item)
if episode_id in episodes
]
# Components are formed over facts, not episodes. A single session may discuss
# unrelated subjects, so using episode IDs as graph vertices creates bridges.
parent: Dict[str, str] = {}
evidence: List[dict] = []
def find(value: str) -> str:
parent.setdefault(value, value)
while parent[value] != value:
parent[value] = parent[parent[value]]
value = parent[value]
return value
def union(left: str, right: str) -> None:
left_root, right_root = find(left), find(right)
if left_root != right_root:
parent[right_root] = left_root
for fact_id, episode_ids in episode_ids_by_fact.items():
session_ids = {
str(getattr(episodes[episode_id], "session_id", "") or "default_session")
for episode_id in episode_ids
}
if len(episode_ids) < 2 or len(session_ids) < 2:
continue
find(fact_id)
evidence.append({
"type": "shared_l2_provenance",
"memory_id": fact_id,
"episode_ids": list(episode_ids),
})
for edge in edges or []:
if str(edge.get("relation_type") or "") != "same_series":
continue
source_id = str(edge.get("source_id") or "")
target_id = str(edge.get("target_id") or "")
source_episodes = episode_ids_by_fact.get(source_id) or []
target_episodes = episode_ids_by_fact.get(target_id) or []
source_sessions = {
str(getattr(episodes[value], "session_id", "") or "default_session")
for value in source_episodes
}
target_sessions = {
str(getattr(episodes[value], "session_id", "") or "default_session")
for value in target_episodes
}
if source_episodes and target_episodes and len(source_sessions | target_sessions) >= 2:
union(source_id, target_id)
evidence.append({
"type": "same_series",
"source_id": source_id,
"target_id": target_id,
"episode_ids": list(dict.fromkeys(source_episodes + target_episodes)),
})
components: Dict[str, List[str]] = {}
for fact_id in parent:
components.setdefault(find(fact_id), []).append(fact_id)
plans = []
for component_member_ids in components.values():
component_member_ids = sorted(set(component_member_ids))
component_episode_ids = list(dict.fromkeys(
episode_id
for fact_id in component_member_ids
for episode_id in episode_ids_by_fact.get(fact_id) or []
))
component_episodes = [episodes[episode_id] for episode_id in component_episode_ids]
session_ids = {
str(getattr(episode, "session_id", "") or "default_session")
for episode in component_episodes
}
if len(component_episode_ids) < 2 or len(session_ids) < 2:
continue
component_episodes.sort(key=lambda node: (
_node_timestamp(node) is None,
_node_timestamp(node) or 0,
node.node_id,
))
timeline = []
all_member_ids: List[str] = []
for episode in component_episodes:
member_ids = [
fact_id for fact_id in component_member_ids
if episode.node_id in (episode_ids_by_fact.get(fact_id) or [])
]
member_ids = list(dict.fromkeys(member_ids))
if not member_ids:
continue
all_member_ids.extend(member_ids)
timeline.append({
"episode_id": episode.node_id,
"session_id": str(
getattr(episode, "session_id", "") or "default_session"
),
"memory_at": _node_timestamp(episode),
"member_ids": member_ids,
})
all_member_ids = list(dict.fromkeys(all_member_ids))
# A cross-session container must connect distinct user-visible memories.
# One reconciled L2 can legitimately retain provenance from several raw
# sessions; repeating that same ID in multiple dated segments does not add
# evidence and only creates an extra L3 retrieval entry around identical
# content. Keep such provenance on the L2 itself, but do not manufacture a
# series episode unless there are at least two canonical L2 members.
if len(timeline) < 2 or len(all_member_ids) < 2:
continue
title, intro = _series_episode_label(
[active_l2[fact_id] for fact_id in all_member_ids],
len(timeline), len(session_ids),
)
component_set = set(component_member_ids)
component_evidence = []
for item in evidence:
referenced = {
str(value) for value in (
[item.get("memory_id")]
if item.get("memory_id") else
[item.get("source_id"), item.get("target_id")]
) if value
}
if referenced and referenced <= component_set:
component_evidence.append(item)
plans.append({
"episode_ids": component_episode_ids,
"session_ids": sorted(session_ids),
"member_memory_ids": all_member_ids,
"timeline": timeline,
"title": title,
"intro": intro,
"evidence": component_evidence,
})
return sorted(plans, key=lambda plan: tuple(plan["episode_ids"]))
def _choose_fact_parent(
fact: Any,
fact_vector: List[float],
episode_nodes: List[Any],
episode_embeddings: dict[str, List[float]],
) -> tuple[Any, float, str]:
"""Prefer exact raw provenance; use semantic similarity only to disambiguate."""
source_raw_ids = _source_ids(fact)
exact = [
node for node in episode_nodes
if source_raw_ids & set(
(getattr(node, "custom", None) or {}).get("source_raw_memory_ids") or []
)
]
candidates = exact or episode_nodes
if len(exact) == 1:
return exact[0], 1.0, "source_raw_unique"
parent = max(
candidates,
key=lambda node: _cosine(
fact_vector, episode_embeddings.get(node.node_id) or node.embedding or []
),
)
similarity = _cosine(
fact_vector, episode_embeddings.get(parent.node_id) or parent.embedding or []
)
return parent, similarity, "source_raw_semantic" if exact else "semantic_fallback"
def _normalized_centroid(vectors: List[List[float]]) -> List[float]:
"""Unit-normalized mean vector for an episode's referenced L2 members."""
import math
valid = [vector for vector in vectors if vector]
if not valid:
return []
width = len(valid[0])
valid = [vector for vector in valid if len(vector) == width]
if not valid:
return []
mean = [sum(vector[i] for vector in valid) / len(valid) for i in range(width)]
norm = math.sqrt(sum(value * value for value in mean))
return [value / norm for value in mean] if norm else mean
def _source_ids(node: Any) -> set[str]:
custom = getattr(node, "custom", None) or {}
values = set(str(value) for value in custom.get("source_raw_memory_ids") or [] if value)
legacy = str(getattr(node, "source_raw_memory_id", "") or "")
if legacy:
values.add(legacy)
return values
def _append_episode_membership(
fact: Any, episode_id: str, similarity: float, method: str,
) -> dict:
"""Attach an episode without erasing memberships from other source sessions."""
from ..pipelines._retrieval.session_episode import add_parent_episode_membership
return add_parent_episode_membership(
getattr(fact, "custom", None), episode_id,
similarity=similarity, method=method,
)
def _primary_episode_id(fact: Any, fallback: str) -> str:
"""Preserve the first/legacy parent when adding another membership."""
direct = str(getattr(fact, "episode_id", "") or "")
if direct:
return direct
custom = getattr(fact, "custom", None) or {}
legacy = str(custom.get("parent_episode_id") or "")
return legacy or fallback
def _word_overlap(left: str, right: str) -> float:
def words(text: str) -> set[str]:
return set(re.findall(r"[a-z0-9]+", (text or "").casefold()))
a, b = words(left), words(right)
return len(a & b) / len(a) if a else 0.0
def _assign_facts_to_segments(facts: List[Any], segments: List[dict]) -> Dict[int, List[Any]]:
"""Assign each L2 to at most one generated segment without extra embeddings."""
by_segment: Dict[int, List[Any]] = {index: [] for index in range(len(segments))}
for fact in facts:
provenance = _source_ids(fact)
exact = [
index for index, segment in enumerate(segments)
if provenance & set(segment.get("source_raw_memory_ids") or [])
]
candidates = exact or list(range(len(segments)))
if not candidates:
continue
scored = [
(
_word_overlap(
getattr(fact, "content", ""),
" ".join((segments[index].get("title") or "", segments[index].get("summary") or "")),
),
-index,
index,
)
for index in candidates
]
score, _neg_index, chosen = max(scored)
if not exact and score <= 0:
continue
by_segment[chosen].append(fact)
return by_segment
async def finalize_dynamic_episode_capsules(
*, vector_store, embed_service, llm_provider, user_id: str,
agent_id: Optional[str], session_id: str, summary_concurrency: int = 3,
language: Optional[str] = None,
) -> dict:
"""Split a completed session, create compact L3 capsules, and link its facts.
The capsule prompt is English-only; an explicit ``language`` appends that
language's output rule so the capsule text is written in it.
Boundary and summary generation are separate calls. Boundary failure degrades
to one whole-session capsule. A segmented-summary failure also retries the
session as one capsule so the write never loses the complete event context.
"""
from ..models.memory import MemoryLayer, MemoryNode, MemoryStatus, SourceType
narrow_queries = bool(getattr(
vector_store, "_supports_narrow_episode_queries", False,
))
if narrow_queries:
session_nodes = await vector_store.list_by_session(
user_id=user_id, agent_id=agent_id, limit=10000,
session_id=session_id,
status_filter=[MemoryStatus.ACTIVE, MemoryStatus.SHADOW, MemoryStatus.SUPERSEDED],
layers=[MemoryLayer.L1_RAW, MemoryLayer.L2_FACT, MemoryLayer.L3_SUMMARY],
only_latest=False, with_vectors=False, allow_raw_layer=True,
)
nodes = list(session_nodes)
else:
nodes = await vector_store.list_by_user(
user_id=user_id, agent_id=agent_id, limit=10000,
status_filter=[MemoryStatus.ACTIVE, MemoryStatus.SHADOW, MemoryStatus.SUPERSEDED],
layers=[MemoryLayer.L1_RAW, MemoryLayer.L2_FACT, MemoryLayer.L3_SUMMARY],
only_latest=False, with_vectors=False, allow_raw_layer=True,
)
session_nodes = [
n for n in nodes
if (n.session_id or "default_session") == session_id
]
raw_nodes = [n for n in session_nodes if n.layer == MemoryLayer.L1_RAW]
raw_nodes.sort(key=lambda n: (n.memory_at or n.gmt_created, n.gmt_created, n.node_id))
unique_raw_nodes, seen = [], set()
for node in raw_nodes:
normalized = re.sub(r"\s+", " ", (node.content or "").strip())
if normalized and normalized not in seen:
seen.add(normalized)
unique_raw_nodes.append(node)
raw_nodes = unique_raw_nodes
messages = _raw_messages(raw_nodes)
if not messages:
return {"status": "skipped", "reason": "no_raw_messages", "session_id": session_id}
raw_digest = hashlib.sha256(
"\0".join(re.sub(r"\s+", " ", n.content.strip()) for n in raw_nodes).encode()
).hexdigest()
current_raw_ids = {n.node_id for n in raw_nodes}
if narrow_queries:
provenance_nodes = await vector_store.list_by_source_raw_ids(
list(current_raw_ids),
user_id=user_id,
agent_id=agent_id,
limit=10000,
status_filter=[MemoryStatus.ACTIVE],
layers=[MemoryLayer.L2_FACT],
only_latest=True,
with_vectors=False,
)
nodes_by_id = {
node.node_id: node for node in [*session_nodes, *provenance_nodes]
}
nodes = list(nodes_by_id.values())
dynamic_nodes = [n for n in session_nodes
if n.layer == MemoryLayer.L3_SUMMARY
and (n.custom or {}).get("summary_kind") == SUMMARY_KIND_DYNAMIC_EPISODE]
existing = [n for n in dynamic_nodes
if (n.custom or {}).get("source_raw_sha256") == raw_digest]
existing_spans = sorted(
(int((n.custom or {}).get("message_start") or 0),
int((n.custom or {}).get("message_end") or 0))
for n in existing
)
expected_start = 1
complete_existing = bool(existing_spans)
for start, end in existing_spans:
if start != expected_start or end < start:
complete_existing = False
break
expected_start = end + 1
complete_existing = complete_existing and expected_start == len(messages) + 1
if complete_existing:
existing_embeddings = await vector_store.get_embeddings(
[n.node_id for n in existing]
)
fact_nodes = [
n for n in nodes
if n.layer == MemoryLayer.L2_FACT
and n.status == MemoryStatus.ACTIVE
and getattr(n, "is_latest", True)
and (
n in session_nodes
or bool(_source_ids(n) & current_raw_ids)
)
]
fact_embeddings = await vector_store.get_embeddings([n.node_id for n in fact_nodes])
linked = 0
members_by_episode: dict[str, list[str]] = {
node.node_id: [] for node in existing
}
for fact in fact_nodes:
vector = fact_embeddings.get(fact.node_id)
if not vector:
continue
parent, similarity, method = _choose_fact_parent(
fact, vector, existing, existing_embeddings,
)
custom = _append_episode_membership(
fact, parent.node_id, similarity, method,
)
if await vector_store.update_payload(
fact.node_id,
{
"episode_id": _primary_episode_id(fact, parent.node_id),
"custom": custom,
},
):
linked += 1
members_by_episode.setdefault(parent.node_id, []).append(fact.node_id)
for episode in existing:
member_ids = sorted(set(members_by_episode.get(episode.node_id) or []))
custom = dict(episode.custom or {})
custom["member_memory_ids"] = member_ids
custom["timeline"] = [{
"memory_at": (
int(episode.memory_at.timestamp())
if getattr(episode, "memory_at", None) else None
),
"member_ids": member_ids,
}]
await vector_store.update_payload(episode.node_id, {"custom": custom})
episode.custom = custom
return {
"status": "reused", "session_id": session_id,
"episode_ids": [n.node_id for n in existing],
"episode_count": len(existing), "raw_count": len(raw_nodes),
"linked_fact_count": linked,
"prompt_tokens": 0, "completion_tokens": 0,
}
# A previous interrupted finalize can leave only some capsules. They are safe
# to shadow because they are derived L3 nodes for this same session; regenerate
# the complete set below before relinking facts.
for node in dynamic_nodes:
await vector_store.update_payload(node.node_id, {
"status": MemoryStatus.SHADOW.value,
"is_latest": False,
})
timestamp = min((n.memory_at for n in raw_nodes if n.memory_at), default=None)
timestamp_text = timestamp.strftime("%Y-%m-%d %H:%M:%S") if timestamp else "unknown"
rendered = _render_messages(messages)
prompt_tokens = completion_tokens = 0
boundary_fallback = False
try:
boundary_response = await llm_provider.complete(
prompt=DYNAMIC_BOUNDARY_PROMPT.format(
timestamp=timestamp_text, messages=rendered,
),
max_tokens=4096,
)
prompt_tokens += getattr(boundary_response, "prompt_tokens", 0) or 0
completion_tokens += getattr(boundary_response, "completion_tokens", 0) or 0
boundary_blob = _parse_json_object(boundary_response.content)
def _validated_boundaries(blob: dict) -> List[int]:
cuts = sorted({
int(value) for value in (blob.get("boundaries") or [])
if 1 <= int(value) < len(messages)
})
event_count = int(blob.get("event_count") or 0)
if event_count != len(cuts) + 1:
raise ValueError(
f"event_count={event_count} does not match {len(cuts)} boundaries"
)
return cuts
try:
boundaries = _validated_boundaries(boundary_blob)
except ValueError:
correction = await llm_provider.complete(
prompt=DYNAMIC_BOUNDARY_CORRECTION_PROMPT.format(
previous=json.dumps(boundary_blob, ensure_ascii=False),
last_boundary=len(messages) - 1,
),
max_tokens=2048,
)
prompt_tokens += getattr(correction, "prompt_tokens", 0) or 0
completion_tokens += getattr(correction, "completion_tokens", 0) or 0
boundary_blob = _parse_json_object(correction.content)
boundaries = _validated_boundaries(boundary_blob)
boundary_reasoning = str(boundary_blob.get("reasoning") or "")
except Exception as exc:
boundaries = []
boundary_reasoning = f"fallback: {type(exc).__name__}: {exc}"
boundary_fallback = True
async def generate_segments(cuts: List[int]) -> List[dict]:
nonlocal prompt_tokens, completion_tokens
specs, start = [], 1
for segment_index, end in enumerate(cuts + [len(messages)], 1):
segment = messages[start - 1:end]
specs.append((segment_index, start, end, segment))
start = end + 1
semaphore = asyncio.Semaphore(max(1, min(16, int(summary_concurrency or 1))))
explicit_language = normalize_language(language)
async def summarize(spec):
segment_index, segment_start, segment_end, segment = spec
response = None
try:
async with semaphore:
response = await llm_provider.complete(
prompt=with_output_language(
DYNAMIC_CAPSULE_PROMPT.format(
timestamp=timestamp_text,
messages=_render_messages(segment),
),
explicit_language,
explicit=explicit_language is not None,
),
max_tokens=4096,
)
blob = _parse_json_object(response.content)
summary = str(blob.get("summary") or "").strip()
if not summary:
raise ValueError(f"empty summary for segment {segment_index}")
segment_result = {
"start": segment_start, "end": segment_end,
"title": str(blob.get("title") or "").strip(),
"summary": summary,
}
error = None
except asyncio.CancelledError:
raise
except Exception as exc:
segment_result = None
error = exc
return (
segment_result,
error,
getattr(response, "prompt_tokens", 0) or 0,
getattr(response, "completion_tokens", 0) or 0,
)
attempts = await asyncio.gather(*(summarize(spec) for spec in specs))
result = []
first_error = None
for segment_result, error, used_prompt, used_completion in attempts:
prompt_tokens += used_prompt
completion_tokens += used_completion
if error is not None:
if first_error is None:
first_error = error
continue
result.append(segment_result)
if first_error is not None:
raise first_error
return result
try:
segments = await generate_segments(boundaries)
except Exception:
if not boundaries:
raise
boundaries = []
boundary_fallback = True
boundary_reasoning = "fallback: segmented summary failed; merged complete session"
segments = await generate_segments([])
fact_nodes = [
n for n in nodes
if n.layer == MemoryLayer.L2_FACT
and n.status == MemoryStatus.ACTIVE
and getattr(n, "is_latest", True)
and (
n in session_nodes
or bool(_source_ids(n) & current_raw_ids)
)
]
fact_embeddings = await vector_store.get_embeddings([n.node_id for n in fact_nodes])
for segment in segments:
segment_raw_ids = list(dict.fromkeys(
message.get("source_raw_memory_id")
for message in messages[segment["start"] - 1:segment["end"]]
if message.get("source_raw_memory_id")
))
segment["source_raw_memory_ids"] = segment_raw_ids
members_by_segment = _assign_facts_to_segments(fact_nodes, segments)
segments = [
{**segment, "member_facts": members_by_segment[index]}
for index, segment in enumerate(segments)
if members_by_segment[index]
]
if not segments:
return {
"status": "skipped", "reason": "no_episode_members",
"session_id": session_id, "raw_count": len(raw_nodes),
"prompt_tokens": prompt_tokens, "completion_tokens": completion_tokens,
}
for segment in segments:
member_vectors = [
fact_embeddings[fact.node_id]
for fact in segment["member_facts"] if fact_embeddings.get(fact.node_id)
]
segment["embedding"] = _normalized_centroid(member_vectors)
if not segment["embedding"]:
raise ValueError("episode members have no stored embeddings")
episode_nodes = []
for segment in segments:
episode_id = _dynamic_episode_id(
user_id, agent_id or "default_agent", session_id, raw_digest,
segment["start"], segment["end"],
)
segment_raw_ids = segment["source_raw_memory_ids"]
node = MemoryNode(
node_id=episode_id, user_id=user_id,
agent_id=agent_id or "default_agent", session_id=session_id,
source=merge_sources(
getattr(member, "source", None)
for member in segment["member_facts"]
),
episode_id=episode_id, layer=MemoryLayer.L3_SUMMARY,
content=(segment["title"] or segment["summary"][:240]).strip(),
embedding=segment["embedding"], memory_at=timestamp,
source_type=SourceType.INFERRED, status=MemoryStatus.ACTIVE,
is_latest=True,
custom={
"summary_kind": SUMMARY_KIND_DYNAMIC_EPISODE,
"episode_id": episode_id,
"title": segment["title"],
"message_start": segment["start"],
"message_end": segment["end"],
"source_raw_memory_ids": segment_raw_ids,
"source_raw_sha256": raw_digest,
"boundary_fallback": boundary_fallback,
"boundary_reasoning": boundary_reasoning,
"embedding_source": "member_l2_centroid",
},
)
await vector_store.upsert(node)
episode_nodes.append(node)
linked = 0
members_by_episode: dict[str, list[str]] = {
node.node_id: [] for node in episode_nodes
}
for episode, segment in zip(episode_nodes, segments):
for fact in segment["member_facts"]:
custom = _append_episode_membership(
fact, episode.node_id, 1.0, "source_raw_lexical",
)
if await vector_store.update_payload(
fact.node_id,
{
"episode_id": _primary_episode_id(fact, episode.node_id),
"custom": custom,
},
):
linked += 1
members_by_episode.setdefault(episode.node_id, []).append(fact.node_id)
# Store references, not copied L2 text. The episode is an organization node;
# answer-visible text is assembled from the referenced L2 memories at read time.
for episode in episode_nodes:
member_ids = sorted(set(members_by_episode.get(episode.node_id) or []))
custom = dict(episode.custom or {})
custom["member_memory_ids"] = member_ids
custom["timeline"] = [{
"memory_at": (
int(episode.memory_at.timestamp())
if getattr(episode, "memory_at", None) else None
),
"member_ids": member_ids,
}]
await vector_store.update_payload(episode.node_id, {"custom": custom})
episode.custom = custom
return {
"status": "complete", "session_id": session_id,
"episode_ids": [n.node_id for n in episode_nodes],
"episode_count": len(episode_nodes), "raw_count": len(raw_nodes),
"linked_fact_count": linked, "boundary_fallback": boundary_fallback,
"prompt_tokens": prompt_tokens, "completion_tokens": completion_tokens,
}
async def finalize_series_episode_containers(
*, vector_store, graph_store, user_id: str, agent_id: Optional[str],
) -> dict:
"""Create compact multi-session episode containers without an LLM call.
Stored text is only a title plus a structural intro. Exact L2 bodies remain in
their canonical nodes and are referenced by ID from dated timeline segments.
"""
from ..models.memory import MemoryLayer, MemoryNode, MemoryStatus, SourceType
from ..pipelines._retrieval.session_episode import (
add_parent_episode_membership,
remove_parent_episode_memberships,
)
nodes = await vector_store.list_by_user(
user_id=user_id, agent_id=agent_id, limit=10000,
status_filter=[MemoryStatus.ACTIVE, MemoryStatus.SHADOW, MemoryStatus.SUPERSEDED],
layers=[MemoryLayer.L2_FACT, MemoryLayer.L3_SUMMARY],
only_latest=False, with_vectors=False,
)
active_l2 = [
node for node in nodes
if node.layer == MemoryLayer.L2_FACT
and node.status == MemoryStatus.ACTIVE
and bool(getattr(node, "is_latest", True))
]
graph_error = ""
edges = []
if graph_store is not None:
try:
edges = await graph_store.get_related_edges(
[node.node_id for node in active_l2],
max_edges=max(2000, len(active_l2) * 8),
relation_types=["same_series"],
include_temporal=False,
)
except Exception as exc:
# Exact cross-session provenance is still authoritative without graph.
graph_error = str(exc)
plans = _series_episode_plans(nodes, edges)
existing = [
node for node in nodes
if node.layer == MemoryLayer.L3_SUMMARY
and (node.custom or {}).get("summary_kind") == SUMMARY_KIND_SERIES_EPISODE
]
desired_ids = {
_series_episode_id(user_id, agent_id or "default_agent", plan["member_memory_ids"])
for plan in plans
}
existing_ids = {node.node_id for node in existing}
stale_ids = existing_ids - desired_ids
for node in existing:
if node.node_id in stale_ids:
await vector_store.update_payload(node.node_id, {
"status": MemoryStatus.SHADOW.value,
"is_latest": False,
})
l2_by_id = {node.node_id: node for node in active_l2}
# Rebuild all series memberships from the current plans. Limiting cleanup to
# stale container IDs leaves ghost members behind when a component keeps the
# same episode set but one L2 is superseded or loses its explicit relation.
if existing_ids:
for node in active_l2:
custom = remove_parent_episode_memberships(node.custom, existing_ids)
if custom != (node.custom or {}):
await vector_store.update_payload(node.node_id, {"custom": custom})
node.custom = custom
embeddings = await vector_store.get_embeddings([
member_id
for plan in plans
for member_id in plan["member_memory_ids"]
])
created_ids = []
linked_ids = set()
for plan in plans:
series_id = _series_episode_id(
user_id, agent_id or "default_agent", plan["member_memory_ids"],
)
member_vectors = [
embeddings[member_id]
for member_id in plan["member_memory_ids"]
if embeddings.get(member_id)
]
embedding = _normalized_centroid(member_vectors)
if not embedding:
continue
times = [
segment["memory_at"] for segment in plan["timeline"]
if segment.get("memory_at") is not None
]
memory_at = _series_memory_at(times)
content = f"{plan['title']}. {plan['intro']}".strip()
series = MemoryNode(
node_id=series_id, user_id=user_id,
agent_id=agent_id or "default_agent", session_id="",
source=merge_sources(
getattr(member, "source", None)
for member in active_l2
if member.node_id in set(plan["member_memory_ids"])
),
episode_id=series_id, layer=MemoryLayer.L3_SUMMARY,
content=content, embedding=embedding, memory_at=memory_at,
source_type=SourceType.INFERRED, status=MemoryStatus.ACTIVE,
is_latest=True,
custom={
"summary_kind": SUMMARY_KIND_SERIES_EPISODE,
"episode_id": series_id,
"title": plan["title"],
"intro": plan["intro"],
"source_episode_ids": plan["episode_ids"],
"source_session_ids": plan["session_ids"],
"member_memory_ids": plan["member_memory_ids"],
"timeline": plan["timeline"],
"relation_evidence": plan["evidence"],
"embedding_source": "member_l2_centroid",
},
)
await vector_store.upsert(series)
created_ids.append(series_id)
for member_id in plan["member_memory_ids"]:
fact = l2_by_id.get(member_id)
if fact is None:
continue
custom = add_parent_episode_membership(
fact.custom, series_id, similarity=1.0,
method="series_episode_explicit",
)
if await vector_store.update_payload(member_id, {"custom": custom}):
fact.custom = custom
linked_ids.add(member_id)
return {
"status": "complete", "created": len(created_ids),
"episode_ids": created_ids, "linked_fact_count": len(linked_ids),
"stale_shadowed": len(stale_ids), "prompt_tokens": 0,
"completion_tokens": 0, "graph_error": graph_error,
}
def _cosine(a: List[float], b: List[float]) -> float:
import math
den = math.sqrt(sum(x * x for x in a)) * math.sqrt(sum(x * x for x in b))
return sum(x * y for x, y in zip(a, b)) / den if den else 0.0
async def finalize_session_episode(
*, vector_store, embed_service, llm_provider, user_id: str,
agent_id: Optional[str], session_id: str,
language: Optional[str] = None,
) -> dict:
"""Create one first-class narrative from all raw chunks in a caller session.
The prompt is English-only; an explicit ``language`` appends that
language's output rule so the narrative is written in it.
This is deliberately explicit: the SDK cannot infer that the final write of a
session has arrived. Repeated calls upsert the same deterministic node id.
"""
from ..models.memory import MemoryLayer, MemoryNode, MemoryStatus, SourceType
if not user_id or not session_id:
raise ValueError("user_id and session_id are required")
nodes = await vector_store.list_by_user(
user_id=user_id, agent_id=agent_id,
limit=10000,
status_filter=[MemoryStatus.ACTIVE, MemoryStatus.SHADOW, MemoryStatus.SUPERSEDED],
layers=[MemoryLayer.L1_RAW, MemoryLayer.L2_FACT],
only_latest=False, with_vectors=False, allow_raw_layer=True,
)
eid = session_episode_id(user_id, agent_id or "default_agent", session_id)
session_nodes = [n for n in nodes if (n.session_id or "default_session") == session_id]
raw_nodes = [n for n in session_nodes if n.layer == MemoryLayer.L1_RAW]
raw_nodes.sort(key=lambda n: (n.memory_at or n.gmt_created, n.gmt_created, n.node_id))
# A runner can be interrupted after the service commits a chunk but before its
# local checkpoint advances. Resume then sends the same raw conversation again
# under a new node id. Collapse exact content replays before prompting, so retry
# recovery does not multiply the episode narrative.
unique_raw_nodes = []
seen_raw = set()
for node in raw_nodes:
normalized = re.sub(r"\s+", " ", (node.content or "").strip())
if not normalized or normalized in seen_raw:
continue
seen_raw.add(normalized)
unique_raw_nodes.append(node)
raw_nodes = unique_raw_nodes
if not raw_nodes:
return {"status": "skipped", "reason": "no_raw_memories", "session_id": session_id}
raw_ids = [n.node_id for n in raw_nodes]
raw_contents = [
re.sub(r"\s+", " ", (n.content or "").strip()) for n in raw_nodes
]
# Content-based digest remains stable when a retried chunk receives a new node id.
raw_digest = hashlib.sha256("\0".join(raw_contents).encode("utf-8")).hexdigest()
fact_nodes = [n for n in nodes
if n.layer == MemoryLayer.L2_FACT
and n.status == MemoryStatus.ACTIVE
and getattr(n, "is_latest", True)
and (
n.episode_id == eid
or n in session_nodes
or bool(_source_ids(n) & set(raw_ids))
)]
existing = await vector_store.get_by_id(eid)
if existing is not None and (getattr(existing, "custom", None) or {}).get(
"source_raw_sha256"
) == raw_digest:
linked = 0
for node in fact_nodes:
custom = _append_episode_membership(
node, eid, 1.0, "source_raw_membership",
)
if await vector_store.update_payload(
node.node_id,
{"episode_id": _primary_episode_id(node, eid), "custom": custom},
):
linked += 1
custom = dict(existing.custom or {})
custom["linked_fact_count"] = linked
await vector_store.update_payload(eid, {"custom": custom})
return {
"status": "reused", "session_id": session_id,
"episode_id": eid, "episode_memory_id": eid,
"raw_count": len(raw_nodes), "linked_fact_count": linked,
"prompt_tokens": 0, "completion_tokens": 0,
}
conversation = "\n\n".join((n.content or "").strip() for n in raw_nodes if (n.content or "").strip())
timestamp = min((n.memory_at for n in raw_nodes if n.memory_at), default=None)
timestamp_text = (
timestamp.strftime("%Y-%m-%d %H:%M:%S") if timestamp else "unknown"
)
prompt = SESSION_EPISODE_PROMPT.format(
timestamp=timestamp_text,
conversation=conversation,
)
explicit_language = normalize_language(language)
prompt = with_output_language(
prompt, explicit_language, explicit=explicit_language is not None,
)
response = await llm_provider.complete(prompt=prompt, max_tokens=3000)
narrative = (getattr(response, "content", "") or "").strip()
if not narrative:
raise RuntimeError("session episode generation returned empty content")
tags: List[str] = []
for node in fact_nodes:
for tag in node.tags or []:
if tag and tag not in tags:
tags.append(tag)
embedding = await embed_service.embed_queued(narrative)
episode = MemoryNode(
node_id=eid, user_id=user_id, agent_id=agent_id or "default_agent",
session_id=session_id, episode_id=eid, layer=MemoryLayer.L3_SUMMARY,
source=merge_sources(
getattr(node, "source", None) for node in [*raw_nodes, *fact_nodes]
),
content=narrative, embedding=embedding, memory_at=timestamp,
source_type=SourceType.INFERRED, status=MemoryStatus.ACTIVE,
is_latest=True, tags=tags[:8],
custom={
"summary_kind": SUMMARY_KIND_SESSION_EPISODE,
"episode_id": eid,
"source_raw_memory_ids": raw_ids,
"source_raw_sha256": raw_digest,
"covered_raw_count": len(raw_nodes),
"linked_fact_count": len(fact_nodes),
},
)
await vector_store.upsert(episode)
linked = 0
for node in fact_nodes:
custom = _append_episode_membership(
node, eid, 1.0, "source_raw_membership",
)
if await vector_store.update_payload(
node.node_id,
{"episode_id": _primary_episode_id(node, eid), "custom": custom},
):
linked += 1
return {
"status": "complete", "session_id": session_id,
"episode_id": eid, "episode_memory_id": eid,
"raw_count": len(raw_nodes), "linked_fact_count": linked,
"prompt_tokens": getattr(response, "prompt_tokens", 0) or 0,
"completion_tokens": getattr(response, "completion_tokens", 0) or 0,
}
async def summarize_closed_episode(
*,
vector_store,
embed_service,
llm_provider,
episode_id: str,
user_id: str,
agent_id: Optional[str] = None,
session_id: str = "",
min_memories: int = 3,
max_memories: int = 60,
temperature: Optional[float] = None,
trace=None,
language: Optional[str] = None,
) -> Optional[str]:
"""总结一个**刚刚关闭**的 episode,返回摘要节点 id(跳过则 None)。
language 为显式 prompt 语言码;None 时按记忆内容做 zh/en 自动检测。
由 writer 在检测到 episode 滚动时 fire-and-forget 调用:此时上一个 episode
不会再有新内容进来,所以这一次总结就是最终产物,不需要后续 merge / 重写。
"""
if not episode_id or not user_id:
return None
try:
from ..models.memory import MemoryLayer
nodes = await vector_store.list_by_episode(
[episode_id],
user_id=user_id,
agent_id=agent_id,
layers=[MemoryLayer.L2_FACT, MemoryLayer.L7_INTENTION],
limit=max_memories,
)
except Exception as e:
logger.debug(f"[episode-summary] fetch members failed: {e}")
return None
# 只喂 user 侧记忆:agent 侧记忆(助手说过什么)对用户画像价值低,喂进去纯是烧 token。
# 与 user-turn 计数口径一致,episode 只统计 user 侧记忆。
# owner 缺省视为 user(与落库时的默认一致)。
nodes = [
n for n in (nodes or [])
if (getattr(n, "owner", None) or "user") == "user"
]
contents = [
(getattr(n, "content", "") or "").strip()
for n in nodes
if (getattr(n, "content", "") or "").strip()
]
if len(contents) < max(2, min_memories):
# 一两条记忆的 episode 不值得单独摘要 —— 原记忆本身就够检索了
return None
from datetime import datetime as _dt
_t0 = _dt.now()
summary, prompt, tokens = await _generate(
llm_provider=llm_provider, memories=contents, temperature=temperature,
language=language,
)
_elapsed = (_dt.now() - _t0).total_seconds() * 1000
if trace is not None:
await trace(
prompt=prompt,
response=summary,
parsed={
"episode_id": episode_id,
"covered_count": len(contents),
"skipped": not summary,
},
memory_ids=[n.node_id for n in nodes if getattr(n, "node_id", "")],
elapsed_ms=_elapsed,
tokens=tokens,
)
if not summary:
return None
return await _store(
vector_store=vector_store,
embed_service=embed_service,
summary=summary,
episode_id=episode_id,
source_memory_ids=[n.node_id for n in nodes if getattr(n, "node_id", "")],
covered_count=len(contents),
user_id=user_id,
agent_id=agent_id,
session_id=session_id,
nodes=nodes,
)
async def _generate(
*, llm_provider, memories: List[str], temperature: Optional[float] = None,
language: Optional[str] = None,
) -> tuple:
"""返回 (摘要文本, 实际 prompt, token 用量) —— 后两个供埋点,线上要能复盘。"""
body = "\n".join(f"- {c}" for c in memories if c)
if not body:
return "", "", {}
explicit = normalize_language(language)
code = resolve_language(explicit, body)
prompt = get_prompt("EPISODE_SUMMARY_PROMPT", code).format(memories=body)
prompt = with_output_language(prompt, code, explicit=explicit is not None)
resp = await llm_provider.complete(
prompt=prompt,
max_tokens=400,
temperature=temperature,
)
tokens = {
"prompt": getattr(resp, "prompt_tokens", 0) or 0,
"completion": getattr(resp, "completion_tokens", 0) or 0,
"total": getattr(resp, "total_tokens", 0) or 0,
}
text = (getattr(resp, "content", "") or "").strip()
# LLM 偶尔会包一层 markdown 围栏或引号
if text.startswith("```"):
parts = text.split("```")
text = parts[1] if len(parts) > 1 else text
text = text.strip()
return text.strip().strip('"').strip("'").strip(), prompt, tokens
async def _store(
*,
vector_store,
embed_service,
summary: str,
episode_id: str,
source_memory_ids: List[str],
covered_count: int,
user_id: str,
agent_id: Optional[str],
session_id: str,
nodes: List[Any],
) -> str:
from datetime import datetime
from ..models.memory import (
MemoryLayer, MemoryNode, MemoryStatus, SourceType,
)
# 摘要的事件时间取该 episode 最后一条记忆的时间,让时间过滤把它归到讨论发生的时点,
# 而不是"总结这一刻"。
memory_at = datetime.now()
times = [
getattr(n, "memory_at", None) for n in (nodes or [])
if getattr(n, "memory_at", None)
]
if times:
memory_at = max(times)
# 沿用 episode 内记忆的 tag,让主题词也能召回到这条摘要
tags: List[str] = []
for n in (nodes or []):
for t in (getattr(n, "tags", None) or []):
if t and t not in tags:
tags.append(t)
embedding = await embed_service.embed_queued(summary)
node = MemoryNode(
user_id=user_id,
agent_id=agent_id or "default_agent",
session_id=session_id or "default_session",
source=merge_sources(getattr(n, "source", None) for n in (nodes or [])),
episode_id=episode_id,
layer=MemoryLayer.L3_SUMMARY,
content=summary,
embedding=embedding,
memory_at=memory_at,
source_type=SourceType.INFERRED,
status=MemoryStatus.ACTIVE,
is_latest=True,
tags=tags[:8],
custom={
"summary_kind": SUMMARY_KIND_EPISODE,
"episode_id": episode_id,
"covered_count": covered_count,
"source_memory_ids": list(source_memory_ids),
},
)
# 一个 episode 只总结一次 → 没有旧摘要要 SHADOW,也不进 supersedes 演化链
return await vector_store.upsert(node)