Python
"""
Agent Memory V2 - 核心数据模型
包含:
- 枚举类型: MemoryLayer, MemoryStatus, SourceType, UpdateType,
SchemaStatus, TriggerType, IntentionPriority, MetaCognitionTag, GapType
- 核心模型: MemoryNode (统一基类)
- 子类模型: VersionedFact, SchemaNode, IntentionNode
- 辅助模型: KnowledgeGap, TemporalEvent, UserTimeline, LifeStage
- 输出协议: MemoryContextPackage 及其子结构
- 兼容别名: MemoryEntry, MemoryMetadata, MemoryScore (保留旧接口)
"""
from enum import Enum
from typing import Optional, Dict, Any, List
from dataclasses import dataclass, field
from datetime import datetime
import uuid
# ============================================================
# 枚举类型
# ============================================================
class MemoryLayer(str, Enum):
"""
七层记忆模型 (V2 Memory Hierarchy)
L1 RAW — 原始对话层 (Append-Only, 向量数据库)
L2 FACT — 原子事实层 (版本化不可变记录)
L3 SUMMARY — 会话摘要层
L4 IDENTITY — 身份画像层 (核心画像)
L5 KNOWLEDGE — 知识图谱层 (实体/关系/主题, Graph 层, 暂未实现)
L6 SCHEMA — 心智模型层 (抽象叙事模板, Graph 层)
L7 INTENTION — 前瞻意图层 (未来待触发的意图, Graph 层)
存储分界: L0-L4 在 VDB, L5-L7 在 Graph (ultra 模式)
"""
L0_BASIC_INFO = "l0_basic_info"
L1_RAW = "l1_raw"
L2_FACT = "l2_fact"
L3_SUMMARY = "l3_summary"
L4_IDENTITY = "l4_identity"
L5_KNOWLEDGE = "l5_knowledge"
L6_SCHEMA = "l6_schema"
L7_INTENTION = "l7_intention"
# --- 旧编号兼容别名(已存储数据中的值) ---
# v2 → v3 重编号兼容
L6_IDENTITY = "l4_identity" # 旧 l6_identity → 新 l4_identity
L4_KNOWLEDGE = "l5_knowledge" # 旧 l4_knowledge → 新 l5_knowledge
L5_SCHEMA = "l6_schema" # 旧 l5_schema → 新 l6_schema
# v1 → v2 旧兼容(仍需保留)
L4_5_SCHEMA = "l6_schema" # 旧 l4_5_schema → 新 l6_schema
L5_IDENTITY = "l4_identity" # 旧 l5_identity → 新 l4_identity
L6_INTENTION = "l7_intention" # 旧 l6_intention → 新 l7_intention
# --- V1 兼容别名 ---
PROFILE = "l4_identity"
DIALOGUE = "l2_fact"
SUMMARY = "l3_summary"
KNOWLEDGE = "l5_knowledge"
RAW = "l1_raw"
@classmethod
def from_string(cls, value: str) -> "MemoryLayer":
"""从字符串创建 MemoryLayer,支持 V1/V2/V3 命名和旧编号"""
value = value.lower().strip()
# 旧编号 → 新编号映射(兼容已存储数据的 payload)
legacy_mapping = {
# v2 → v3
"l6_identity": cls.L4_IDENTITY,
"l4_knowledge": cls.L5_KNOWLEDGE,
"l5_schema": cls.L6_SCHEMA,
# v1 → v2 → v3
"l4_5_schema": cls.L6_SCHEMA,
"l5_identity": cls.L4_IDENTITY,
"l6_intention": cls.L7_INTENTION,
}
if value in legacy_mapping:
return legacy_mapping[value]
# V1 兼容映射
v1_mapping = {
"profile": cls.L4_IDENTITY,
"dialogue": cls.L2_FACT,
"summary": cls.L3_SUMMARY,
"knowledge": cls.L5_KNOWLEDGE,
"raw": cls.L1_RAW,
}
if value in v1_mapping:
return v1_mapping[value]
for layer in cls:
if layer.value == value:
return layer
raise ValueError(f"Invalid memory layer: {value}")
@classmethod
def all_layers(cls) -> List["MemoryLayer"]:
"""返回所有记忆层 (不含别名)"""
return [
cls.L0_BASIC_INFO,
cls.L1_RAW, cls.L2_FACT, cls.L3_SUMMARY,
cls.L4_IDENTITY, cls.L5_KNOWLEDGE,
cls.L6_SCHEMA, cls.L7_INTENTION,
]
class ContentType(str, Enum):
"""记忆内容类型(保留用于旧代码兼容,MemoryNode 不再使用此字段)"""
FACT = "fact"
SUMMARY = "summary"
ENTITY = "entity"
SCHEMA = "schema"
PROFILE = "profile"
INTENTION = "intention"
RAW = "raw"
HYPOTHESIS = "hypothesis"
class MemoryStatus(str, Enum):
"""记忆状态"""
ACTIVE = "active" # 当前有效
SUPERSEDED = "superseded" # 已被新版本取代(EVOLVE 演化链上的旧节点)
NEGATED = "negated" # 已被否定
CONFLICTED = "conflicted" # 存在冲突
SHADOW = "shadow" # 影子状态:低置信度推断 或 reconcile DELETE 逻辑删除
# 两种场景都不参与召回(is_latest 通常为 False)
ARCHIVED = "archived" # 已归档
class SourceType(str, Enum):
"""信息来源类型"""
EXPLICIT = "explicit" # 用户明确陈述
INFERRED = "inferred" # 系统推断
COMPOSITE = "composite" # 多证据综合
class UpdateType(str, Enum):
"""版本化事实的更新类型"""
OVERRIDE = "override" # 新值替代旧值
SUPPLEMENT = "supplement" # 补充信息
TEMPORAL = "temporal" # 时间窗口变化
NEGATE = "negate" # 否定旧信息
CONFLICT = "conflict" # 新旧冲突
class SchemaStatus(str, Enum):
"""Schema 状态"""
FORMING = "forming" # 形成中 (证据不足)
STABLE = "stable" # 稳定 (多证据支撑)
EVOLVING = "evolving" # 演化中 (有新证据修改)
DEPRECATED = "deprecated" # 已过时
class TriggerType(str, Enum):
"""意图触发类型"""
TIME_BASED = "time_based" # 时间触发
EVENT_BASED = "event_based" # 事件触发
class IntentionPriority(str, Enum):
"""意图优先级"""
HIGH = "high"
MEDIUM = "medium"
LOW = "low"
class MetaCognitionTag(str, Enum):
"""
元认知信号标记
附加在记忆条目上,让调用方 LLM 感知记忆的可靠程度和特殊性质。
"""
# 置信度相关
HIGH_CONFIDENCE = "high_confidence"
LOW_CONFIDENCE = "low_confidence"
INFERRED_NOT_STATED = "inferred_not_stated"
STALE = "stale"
# 冲突与不确定
NEEDS_CLARIFICATION = "needs_clarification"
CONFLICTED = "conflicted"
CONTEXT_DEPENDENT = "context_dependent"
# 情绪与敏感
EMOTIONALLY_SENSITIVE = "emotionally_sensitive"
POSITIVE_MEMORY = "positive_memory"
NEGATIVE_MEMORY = "negative_memory"
GOTCHA = "gotcha"
# 时间特殊性
RECENTLY_CHANGED = "recently_changed"
HISTORICAL = "historical"
TEMPORAL_CONTEXT = "temporal_context"
# 知识缺口
KNOWLEDGE_GAP = "knowledge_gap"
INCOMPLETE = "incomplete"
# 价值标记
LONG_TAIL = "long_tail"
SCHEMA_ACTIVATED = "schema_activated"
# 前瞻标记
PROACTIVE_CARE = "proactive_care"
FOLLOW_UP = "follow_up"
class GapType(str, Enum):
"""知识缺口的四种类型"""
PROFILE_INCOMPLETE = "profile_incomplete"
UNRESOLVED_CONFLICT = "unresolved_conflict"
INFERRED_UNVERIFIED = "inferred_unverified"
STALE_UNVERIFIED = "stale_unverified"
# ============================================================
# 核心模型: MemoryNode (统一基类)
# ============================================================
@dataclass
class MemoryNode:
"""
所有层级记忆的统一基类 (V2)
字段分组:
- 基础标识 (node_id, user_id, layer, content)
- 业务隔离 (agent_id, session_id)
- 时空维度 (memory_at, temporal_anchor, valid_from/until, gmt_created/modified)
- 演化图谱 (supersedes, superseded_by, is_latest) — EVOLVE 语义
- 推断注解 (speculate) — 不参与 embed
- Summary 锚点 (source_raw_memory_id) — L3_SUMMARY/L4_IDENTITY 专用
- 状态 (status)
- 置信与校准 (confidence, evidence_count, source_type)
- 情绪标记 (emotional_valence, emotional_arousal)
- 检索元数据 (access_count, last_accessed_at, embedding)
- 长尾标记 (specificity_score, rarity_score, longtail_flag)
- 元认知标记 (meta_tags, meta_hints)
- 出处追溯 (source_session_id, source_turn_index, evidence_chain)
- 扩展 (custom, tags)
"""
# === 基础标识 ===
node_id: str = ""
user_id: str = ""
layer: MemoryLayer = MemoryLayer.L1_RAW
content: str = "" # 核心语义内容,embed 只用此字段
# === 业务隔离 ===
agent_id: str = ""
session_id: str = ""
# 产生该记忆的调用来源(openclaw / cursor / codex 等)。不要与
# source_type(显式/推断/复合)或检索通道混用。
source: str = "default"
# === 归属(owner)===
# 该记忆属于谁:'user'(关于用户/用户陈述)| 'agent'(assistant 提供/用户要 agent 做的事)。
# 仅 L2_FACT / L7_INTENTION 写入;其他层(L0/L1/L3/L5/L6)留空(None)。
owner: Optional[str] = None
# === 时空维度 ===
memory_at: Optional[datetime] = None # 记忆发生时间(用户指定,可为空)
temporal_anchor: Optional[str] = None # 保留字段兼容历史数据;v0.3.45_v0 post8 起不再写入
valid_from: Optional[datetime] = None
valid_until: Optional[datetime] = None
# === 数据管理时间 ===
gmt_created: Optional[datetime] = None # 数据写入时间(系统自动)
gmt_modified: Optional[datetime] = None # 数据最后修改时间(系统自动)
# === 演化图谱(EVOLVE 语义)===
supersedes: Optional[List[str]] = None # 本节点取代的旧节点 ID 列表,全新信息为 None
superseded_by: Optional[List[str]] = None # 被哪些新节点取代(系统写入,不透出给调用方)
is_latest: bool = True # 是否链条末端;被取代时系统自动置 False
# === 推断注解(不参与 embed)===
speculate: Optional[str] = None # LLM 对复杂/模糊信号的推断注解
# === Summary 锚点(L3_SUMMARY / L4_IDENTITY)===
source_raw_memory_id: Optional[str] = None # 对应的 L1_RAW 节点 ID
# === 状态 ===
status: MemoryStatus = MemoryStatus.ACTIVE
# === 置信与校准 ===
confidence: float = 1.0
evidence_count: int = 1
source_type: SourceType = SourceType.EXPLICIT
# === 情绪标记 ===
emotional_valence: float = 0.0 # [-1, 1] 情感效价
emotional_arousal: float = 0.0 # [0, 1] 情感唤醒度
# === 检索元数据 ===
access_count: int = 0
last_accessed_at: Optional[datetime] = None
embedding: Optional[List[float]] = None
# === 长尾标记 ===
specificity_score: float = 0.0 # [0, 1] 具体度
rarity_score: float = 0.0 # [0, 1] 稀有度
longtail_flag: bool = False
# === 元认知标记 ===
meta_tags: List[MetaCognitionTag] = field(default_factory=list)
meta_hints: Dict[str, str] = field(default_factory=dict)
# === Episode(内部会话)===
# 一件事往往跨越好几次 write(十几二十轮),从中抽出的 memory 属于同一次讨论。
# 打同一个 episode_id,读侧就能用它**框出一片候选**做加权 —— 比建 O(n²) 时间边
# 便宜得多,也比"同一天"语义准确。
#
# 注意与 session_id 的区别:session_id 是**调用方给的业务隔离键**(进 isolation_key),
# 可能很长(整段会话)或干脆是 default;episode_id 是 SDK **内部按时间间隔切**的
# "一次讨论",粒度更细,且不参与隔离。
episode_id: str = ""
# === 出处追溯 ===
source_session_id: str = ""
source_turn_index: Optional[int] = None
evidence_chain: List[str] = field(default_factory=list)
# === 扩展字段 ===
custom: Dict[str, Any] = field(default_factory=dict)
tags: List[str] = field(default_factory=list)
# 与 tags 等长的 NER label(GPE/PERSON/...);主题词为空串。写入时标注,读侧 boost 用。
tag_ners: List[str] = field(default_factory=list)
def __post_init__(self):
from ..utils.source_filter import normalize_source
self.source = normalize_source(self.source)
if not self.node_id:
self.node_id = str(uuid.uuid4())
now = datetime.now()
# gmt_created/gmt_modified 是系统时间,自动填写
if self.gmt_created is None:
self.gmt_created = now
if self.gmt_modified is None:
self.gmt_modified = now
# memory_at 是记忆发生时间,由调用方指定,不自动填写
# valid_from 用 gmt_created 作为默认(数据有效从写入时开始)
if self.valid_from is None:
self.valid_from = now
@property
def memory_id(self) -> str:
"""V1 兼容: memory_id == node_id"""
return self.node_id
@property
def uid(self) -> str:
"""V1 兼容: uid == user_id"""
return self.user_id
def get_isolation_key(self) -> str:
"""隔离键: {user_id}::{agent_id}::{session_id}
session_id 为空时使用 'default_session',与 build_isolation_key 对齐。
"""
sid = self.session_id or "default_session"
return f"{self.user_id}::{self.agent_id}::{sid}"
def get_topic_scope_key(self) -> str:
"""Topic 的隔离键: {user_id}::{agent_id} —— **不含 session_id**。
为什么 Topic 要比记忆本身更宽:主题是**跨会话累积**的概念。"关于你的健康我知道
这些"不该按会话切开。而 `get_isolation_key()` 带 session,用它当 Topic 的
隔离键会让同名 tag 在每个 session 里各建一个互不相识的 Topic 节点。
如果按 session 隔离,同名 Topic 会分裂成多个节点,导致时序脊建不出边、
topic summary 反复总结同名碎片、跨会话 tag 召回不连通。
"""
return f"{self.user_id}::{self.agent_id}"
@staticmethod
def build_topic_scope_key(uid: str, agent_id: str) -> str:
"""构建 Topic 隔离键: {uid}::{agent_id}(不含 session,见 get_topic_scope_key)"""
return f"{uid}::{agent_id}"
@staticmethod
def topic_scope_of(isolation_key: str) -> str:
"""把带 session 的 isolation_key 削成 Topic 作用域(取前两段)。
供只拿到 isolation_key 的读侧使用 —— 建 Topic 与查 Topic 必须用同一个键,
否则查不到(两个后端都是 `isolation_key` 精确匹配)。
"""
if not isolation_key:
return isolation_key
parts = isolation_key.split("::")
return "::".join(parts[:2]) if len(parts) >= 2 else isolation_key
@staticmethod
def build_isolation_key(uid: str, agent_id: str, session_id: str = "default_session") -> str:
"""构建隔离键: {uid}::{agent_id}::{session_id}"""
sid = session_id or "default_session"
return f"{uid}::{agent_id}::{sid}"
@staticmethod
def parse_isolation_key(key: str) -> tuple:
"""
解析隔离键,返回 (user_id, agent_id, session_id)。
兼容多种格式:
- 4 段: (旧格式带 appid) 跳过首段 → uid::agent_id::session_id
- 3 段: uid::agent_id::session_id (标准格式)
- 2 段: uid::agent_id (session_id 默认 "default_session")
"""
parts = key.split("::")
if len(parts) >= 4:
# 兼容旧格式: 跳过 appid
return parts[1], parts[2], parts[3]
elif len(parts) == 3:
return parts[0], parts[1], parts[2]
elif len(parts) == 2:
return parts[0], parts[1], "default_session"
return "", "", ""
def to_dict(self) -> Dict[str, Any]:
"""序列化为字典"""
return {
"node_id": self.node_id,
"user_id": self.user_id,
"agent_id": self.agent_id,
"session_id": self.session_id,
"source": self.source,
"episode_id": self.episode_id,
"owner": self.owner,
"layer": self.layer.value,
"content": self.content,
"memory_at": int(self.memory_at.timestamp()) if self.memory_at else None,
"temporal_anchor": self.temporal_anchor,
"gmt_created": int(self.gmt_created.timestamp()) if self.gmt_created else None,
"gmt_modified": int(self.gmt_modified.timestamp()) if self.gmt_modified else None,
"valid_from": int(self.valid_from.timestamp()) if self.valid_from else None,
"valid_until": int(self.valid_until.timestamp()) if self.valid_until else None,
# 演化图谱
"supersedes": self.supersedes,
"superseded_by": self.superseded_by,
"is_latest": self.is_latest,
# 推断注解
"speculate": self.speculate,
# Summary 锚点
"source_raw_memory_id": self.source_raw_memory_id,
# 状态
"status": self.status.value,
# 置信与校准
"confidence": self.confidence,
"evidence_count": self.evidence_count,
"source_type": self.source_type.value,
# 情绪
"emotional_valence": self.emotional_valence,
"emotional_arousal": self.emotional_arousal,
# 检索元数据
"access_count": self.access_count,
"last_accessed_at": int(self.last_accessed_at.timestamp()) if self.last_accessed_at else None,
# 长尾标记
"specificity_score": self.specificity_score,
"rarity_score": self.rarity_score,
"longtail_flag": self.longtail_flag,
# 元认知
"meta_tags": [t.value for t in self.meta_tags],
"meta_hints": self.meta_hints,
# 出处追溯
"source_session_id": self.source_session_id,
"source_turn_index": self.source_turn_index,
"evidence_chain": self.evidence_chain,
# 扩展
"custom": self.custom,
"tags": self.tags,
"tag_ners": list(getattr(self, "tag_ners", None) or []),
# 向量(可选,clone / 序列化场景需要携带)
"embedding": self.embedding,
}
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "MemoryNode":
"""从字典反序列化(兼容旧 payload 中的废弃字段,忽略即可)"""
def parse_dt(v):
if v is None:
return None
if isinstance(v, datetime):
return v
if isinstance(v, (int, float)):
return datetime.fromtimestamp(v)
if isinstance(v, str):
return datetime.fromisoformat(v)
return None
def parse_enum(enum_cls, v, default):
if v is None:
return default
if isinstance(v, enum_cls):
return v
try:
return enum_cls(v)
except (ValueError, KeyError):
return default
meta_tags_raw = data.get("meta_tags", [])
meta_tags = []
for t in meta_tags_raw:
if isinstance(t, MetaCognitionTag):
meta_tags.append(t)
else:
try:
meta_tags.append(MetaCognitionTag(t))
except (ValueError, KeyError):
pass
return cls(
node_id=data.get("node_id", data.get("memory_id", "")),
user_id=data.get("user_id", data.get("uid", "")),
agent_id=data.get("agent_id", ""),
session_id=data.get("session_id", ""),
source=data.get("source", "default") or "default",
episode_id=data.get("episode_id", "") or "",
owner=data.get("owner") or None,
layer=parse_enum(MemoryLayer, data.get("layer"), MemoryLayer.L1_RAW),
content=data.get("content", ""),
# memory_at: 优先读 memory_at,兼容旧 key created_at
memory_at=parse_dt(data.get("memory_at") or data.get("created_at")),
temporal_anchor=data.get("temporal_anchor"),
gmt_created=parse_dt(data.get("gmt_created")),
gmt_modified=parse_dt(data.get("gmt_modified")),
valid_from=parse_dt(data.get("valid_from")),
valid_until=parse_dt(data.get("valid_until")),
# 演化图谱
supersedes=data.get("supersedes"),
superseded_by=data.get("superseded_by"),
is_latest=data.get("is_latest", True),
# 推断注解
speculate=data.get("speculate"),
# Summary 锚点
source_raw_memory_id=data.get("source_raw_memory_id"),
# 状态
status=parse_enum(MemoryStatus, data.get("status"), MemoryStatus.ACTIVE),
# 置信
confidence=data.get("confidence", 1.0),
evidence_count=data.get("evidence_count", 1),
source_type=parse_enum(SourceType, data.get("source_type"), SourceType.EXPLICIT),
# 情绪
emotional_valence=data.get("emotional_valence", 0.0),
emotional_arousal=data.get("emotional_arousal", 0.0),
# 检索元数据
access_count=data.get("access_count", 0),
last_accessed_at=parse_dt(data.get("last_accessed_at")),
embedding=data.get("embedding"),
# 长尾
specificity_score=data.get("specificity_score", 0.0),
rarity_score=data.get("rarity_score", 0.0),
longtail_flag=data.get("longtail_flag", False),
# 元认知
meta_tags=meta_tags,
meta_hints=data.get("meta_hints", {}),
# 出处
source_session_id=data.get("source_session_id", ""),
source_turn_index=data.get("source_turn_index"),
evidence_chain=data.get("evidence_chain", []),
# 扩展
custom=data.get("custom", {}),
tags=data.get("tags", []) or [],
tag_ners=list(data.get("tag_ners") or []),
)
# ============================================================
# 子类模型
# ============================================================
@dataclass
class VersionedFact(MemoryNode):
"""
L2 层的原子事实 — 版本化不可变记录
V2 §3.2: 不直接修改事实内容,而是通过 status 变迁 + SUPERSEDED_BY 边来追踪变更。
"""
update_type: Optional[UpdateType] = None
def __post_init__(self):
super().__post_init__()
if self.layer == MemoryLayer.L1_RAW:
self.layer = MemoryLayer.L2_FACT
def to_dict(self) -> Dict[str, Any]:
d = super().to_dict()
d["update_type"] = self.update_type.value if self.update_type else None
return d
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "VersionedFact":
base = MemoryNode.from_dict(data)
update_type = None
if data.get("update_type"):
try:
update_type = UpdateType(data["update_type"])
except (ValueError, KeyError):
pass
return cls(**{**base.__dict__, "update_type": update_type})
@dataclass
class SchemaNode(MemoryNode):
"""
L6 层: 心智模型 — 从多个关联事实中自动归纳的抽象叙事模板 (Graph 层)
V3 §2.2
"""
central_proposition: str = ""
supporting_evidence: List[str] = field(default_factory=list)
expected_inferences: List[str] = field(default_factory=list)
activation_threshold: float = 0.7
activation_count: int = 0
last_activated_at: Optional[datetime] = None
schema_status: SchemaStatus = SchemaStatus.FORMING
def __post_init__(self):
super().__post_init__()
self.layer = MemoryLayer.L6_SCHEMA
def to_dict(self) -> Dict[str, Any]:
d = super().to_dict()
d.update({
"central_proposition": self.central_proposition,
"supporting_evidence": self.supporting_evidence,
"expected_inferences": self.expected_inferences,
"activation_threshold": self.activation_threshold,
"activation_count": self.activation_count,
"last_activated_at": int(self.last_activated_at.timestamp()) if self.last_activated_at else None,
"schema_status": self.schema_status.value,
})
return d
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "SchemaNode":
base = MemoryNode.from_dict(data)
def parse_dt(v):
if v is None:
return None
if isinstance(v, datetime):
return v
if isinstance(v, (int, float)):
return datetime.fromtimestamp(v)
if isinstance(v, str):
return datetime.fromisoformat(v)
return None
schema_status = SchemaStatus.FORMING
if data.get("schema_status"):
try:
schema_status = SchemaStatus(data["schema_status"])
except (ValueError, KeyError):
pass
return cls(
**{**base.__dict__,
"central_proposition": data.get("central_proposition", ""),
"supporting_evidence": data.get("supporting_evidence", []),
"expected_inferences": data.get("expected_inferences", []),
"activation_threshold": data.get("activation_threshold", 0.7),
"activation_count": data.get("activation_count", 0),
"last_activated_at": parse_dt(data.get("last_activated_at")),
"schema_status": schema_status,
})
@dataclass
class IntentionNode(MemoryNode):
"""
L7 层: 前瞻性记忆 — 记住"将来要做什么" (Graph 层)
V3 §2.2
"""
trigger_type: TriggerType = TriggerType.EVENT_BASED
trigger_condition: str = ""
# 时间触发
trigger_time: Optional[datetime] = None
# 事件触发
trigger_event_pattern: Optional[str] = None
trigger_event_embedding: Optional[List[float]] = None
# 意图内容
intention_content: str = ""
priority: IntentionPriority = IntentionPriority.MEDIUM
expiry: Optional[datetime] = None
triggered: bool = False
triggered_at: Optional[datetime] = None
def __post_init__(self):
super().__post_init__()
self.layer = MemoryLayer.L7_INTENTION
def to_dict(self) -> Dict[str, Any]:
d = super().to_dict()
d.update({
"trigger_type": self.trigger_type.value,
"trigger_condition": self.trigger_condition,
"trigger_time": int(self.trigger_time.timestamp()) if self.trigger_time else None,
"trigger_event_pattern": self.trigger_event_pattern,
"intention_content": self.intention_content,
"priority": self.priority.value,
"expiry": int(self.expiry.timestamp()) if self.expiry else None,
"triggered": self.triggered,
"triggered_at": int(self.triggered_at.timestamp()) if self.triggered_at else None,
})
return d
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "IntentionNode":
base = MemoryNode.from_dict(data)
def parse_dt(v):
if v is None:
return None
if isinstance(v, datetime):
return v
if isinstance(v, (int, float)):
return datetime.fromtimestamp(v)
if isinstance(v, str):
return datetime.fromisoformat(v)
return None
trigger_type = TriggerType.EVENT_BASED
if data.get("trigger_type"):
try:
trigger_type = TriggerType(data["trigger_type"])
except (ValueError, KeyError):
pass
priority = IntentionPriority.MEDIUM
if data.get("priority"):
try:
priority = IntentionPriority(data["priority"])
except (ValueError, KeyError):
pass
return cls(
**{**base.__dict__,
"trigger_type": trigger_type,
"trigger_condition": data.get("trigger_condition", ""),
"trigger_time": parse_dt(data.get("trigger_time")),
"trigger_event_pattern": data.get("trigger_event_pattern"),
"trigger_event_embedding": data.get("trigger_event_embedding"),
"intention_content": data.get("intention_content", ""),
"priority": priority,
"expiry": parse_dt(data.get("expiry")),
"triggered": data.get("triggered", False),
"triggered_at": parse_dt(data.get("triggered_at")),
})
# ============================================================
# 辅助模型: KnowledgeGap
# ============================================================
@dataclass
class KnowledgeGap:
"""
知识缺口记录 — 描述"某个维度的信息缺失或不可靠"
V2 §5.6.2
"""
gap_id: str = ""
user_id: str = ""
domain: str = ""
gap_type: GapType = GapType.PROFILE_INCOMPLETE
importance: str = "medium" # high / medium / low
description: str = ""
related_node_ids: List[str] = field(default_factory=list)
hint: str = ""
created_at: Optional[datetime] = None
last_scanned_at: Optional[datetime] = None
resolved: bool = False
resolved_at: Optional[datetime] = None
resolve_trigger: Optional[str] = None
def __post_init__(self):
if not self.gap_id:
self.gap_id = f"gap_{uuid.uuid4().hex[:12]}"
now = datetime.now()
if self.created_at is None:
self.created_at = now
if self.last_scanned_at is None:
self.last_scanned_at = now
def to_dict(self) -> Dict[str, Any]:
return {
"gap_id": self.gap_id,
"user_id": self.user_id,
"domain": self.domain,
"gap_type": self.gap_type.value,
"importance": self.importance,
"description": self.description,
"related_node_ids": self.related_node_ids,
"hint": self.hint,
"created_at": int(self.created_at.timestamp()) if self.created_at else None,
"last_scanned_at": int(self.last_scanned_at.timestamp()) if self.last_scanned_at else None,
"resolved": self.resolved,
"resolved_at": int(self.resolved_at.timestamp()) if self.resolved_at else None,
"resolve_trigger": self.resolve_trigger,
}
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "KnowledgeGap":
def parse_dt(v):
if v is None:
return None
if isinstance(v, datetime):
return v
if isinstance(v, (int, float)):
return datetime.fromtimestamp(v)
if isinstance(v, str):
return datetime.fromisoformat(v)
return None
gap_type = GapType.PROFILE_INCOMPLETE
if data.get("gap_type"):
try:
gap_type = GapType(data["gap_type"])
except (ValueError, KeyError):
pass
return cls(
gap_id=data.get("gap_id", ""),
user_id=data.get("user_id", ""),
domain=data.get("domain", ""),
gap_type=gap_type,
importance=data.get("importance", "medium"),
description=data.get("description", ""),
related_node_ids=data.get("related_node_ids", []),
hint=data.get("hint", ""),
created_at=parse_dt(data.get("created_at")),
last_scanned_at=parse_dt(data.get("last_scanned_at")),
resolved=data.get("resolved", False),
resolved_at=parse_dt(data.get("resolved_at")),
resolve_trigger=data.get("resolve_trigger"),
)
# ============================================================
# 辅助模型: 时间系统 (Temporal)
# ============================================================
@dataclass
class LifeStage:
"""用户的一个生命阶段"""
name: str = "" # "大学时期", "在上海工作"
start_time: Optional[datetime] = None
end_time: Optional[datetime] = None
description: str = ""
def to_dict(self) -> Dict[str, Any]:
return {
"name": self.name,
"start_time": int(self.start_time.timestamp()) if self.start_time else None,
"end_time": int(self.end_time.timestamp()) if self.end_time else None,
"description": self.description,
}
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "LifeStage":
def parse_dt(v):
if v is None:
return None
if isinstance(v, datetime):
return v
if isinstance(v, (int, float)):
return datetime.fromtimestamp(v)
if isinstance(v, str):
return datetime.fromisoformat(v)
return None
return cls(
name=data.get("name", ""),
start_time=parse_dt(data.get("start_time")),
end_time=parse_dt(data.get("end_time")),
description=data.get("description", ""),
)
@dataclass
class TemporalEvent:
"""
时间线上的一个事件
V2 §6.1
"""
event_id: str = "" # 关联的 fact_id
event_description: str = ""
event_time: Optional[datetime] = None
time_precision: str = "approximate" # exact / month / quarter / year / approximate
time_description: str = "" # 原始时间描述
life_stage: Optional[str] = None
is_milestone: bool = False
def to_dict(self) -> Dict[str, Any]:
return {
"event_id": self.event_id,
"event_description": self.event_description,
"event_time": int(self.event_time.timestamp()) if self.event_time else None,
"time_precision": self.time_precision,
"time_description": self.time_description,
"life_stage": self.life_stage,
"is_milestone": self.is_milestone,
}
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "TemporalEvent":
def parse_dt(v):
if v is None:
return None
if isinstance(v, datetime):
return v
if isinstance(v, (int, float)):
return datetime.fromtimestamp(v)
if isinstance(v, str):
return datetime.fromisoformat(v)
return None
return cls(
event_id=data.get("event_id", ""),
event_description=data.get("event_description", ""),
event_time=parse_dt(data.get("event_time")),
time_precision=data.get("time_precision", "approximate"),
time_description=data.get("time_description", ""),
life_stage=data.get("life_stage"),
is_milestone=data.get("is_milestone", False),
)
@dataclass
class UserTimeline:
"""
用户的完整时间线
V2 §6.1
"""
user_id: str = ""
events: List[TemporalEvent] = field(default_factory=list)
life_stages: List[LifeStage] = field(default_factory=list)
milestone_events: Dict[str, TemporalEvent] = field(default_factory=dict)
def to_dict(self) -> Dict[str, Any]:
return {
"user_id": self.user_id,
"events": [e.to_dict() for e in self.events],
"life_stages": [s.to_dict() for s in self.life_stages],
"milestone_events": {k: v.to_dict() for k, v in self.milestone_events.items()},
}
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "UserTimeline":
return cls(
user_id=data.get("user_id", ""),
events=[TemporalEvent.from_dict(e) for e in data.get("events", [])],
life_stages=[LifeStage.from_dict(s) for s in data.get("life_stages", [])],
milestone_events={
k: TemporalEvent.from_dict(v)
for k, v in data.get("milestone_events", {}).items()
},
)
# ============================================================
# 输出协议: MemoryContextPackage
# ============================================================
@dataclass
class ProfileSummary:
"""用户画像摘要 (Layer 0, 始终返回)"""
core: str = "" # "张三, 30岁, 北京, 后端工程师"
personality: str = "" # "务实, 技术导向"
active_schemas: List[str] = field(default_factory=list)
gotchas: List[str] = field(default_factory=list)
note: str = ""
def to_dict(self) -> Dict[str, Any]:
return {
"core": self.core,
"personality": self.personality,
"active_schemas": self.active_schemas,
"gotchas": self.gotchas,
"note": self.note,
}
@dataclass
class MemoryIndexEntry:
"""索引视图条目 (Layer 1, ~100 tokens)"""
node_id: str = ""
date: str = ""
content_type: str = ""
title: str = ""
relevance: float = 0.0
meta_tags: List[str] = field(default_factory=list)
def to_dict(self) -> Dict[str, Any]:
return {
"id": self.node_id,
"date": self.date,
"type": self.content_type,
"title": self.title,
"relevance": self.relevance,
"meta_tags": self.meta_tags,
}
@dataclass
class MemorySummaryEntry:
"""摘要视图条目 (Layer 2, ~500 tokens)"""
node_id: str = ""
summary: str = ""
confidence: float = 0.0
meta_tags: List[str] = field(default_factory=list)
meta_hints: Dict[str, str] = field(default_factory=dict)
def to_dict(self) -> Dict[str, Any]:
return {
"id": self.node_id,
"summary": self.summary,
"confidence": self.confidence,
"meta_tags": self.meta_tags,
"meta_hints": self.meta_hints,
}
@dataclass
class MetaCognitionReport:
"""元认知报告"""
confidence_summary: str = ""
knowledge_gaps: List[Dict[str, Any]] = field(default_factory=list)
unresolved_conflicts: List[Dict[str, Any]] = field(default_factory=list)
stale_memories: List[Dict[str, Any]] = field(default_factory=list)
def to_dict(self) -> Dict[str, Any]:
return {
"confidence_summary": self.confidence_summary,
"knowledge_gaps": self.knowledge_gaps,
"unresolved_conflicts": self.unresolved_conflicts,
"stale_memories": self.stale_memories,
}
@dataclass
class TriggeredIntention:
"""被触发的前瞻性意图"""
trigger_reason: str = ""
intention: str = ""
priority: str = "medium"
meta_tags: List[str] = field(default_factory=list)
source_intention_id: str = ""
def to_dict(self) -> Dict[str, Any]:
return {
"trigger_reason": self.trigger_reason,
"intention": self.intention,
"priority": self.priority,
"meta_tags": self.meta_tags,
"source_intention_id": self.source_intention_id,
}
@dataclass
class ActivatedSchema:
"""被激活的 Schema"""
schema: str = ""
evidence_summary: str = ""
expected_inferences: List[str] = field(default_factory=list)
meta_tags: List[str] = field(default_factory=list)
source_schema_id: str = ""
def to_dict(self) -> Dict[str, Any]:
return {
"schema": self.schema,
"evidence_summary": self.evidence_summary,
"expected_inferences": self.expected_inferences,
"meta_tags": self.meta_tags,
"source_schema_id": self.source_schema_id,
}
@dataclass
class TemporalContext:
"""时间线上下文 (query 涉及时间时返回)"""
relevant_timeline: List[Dict[str, str]] = field(default_factory=list)
temporal_note: str = ""
def to_dict(self) -> Dict[str, Any]:
return {
"relevant_timeline": self.relevant_timeline,
"temporal_note": self.temporal_note,
}
@dataclass
class MemoryContextPackage:
"""
返回给调用方 LLM 的完整记忆上下文包
V2 §7.1: 三层渐进式披露 + 元认知信号 + 前瞻意图 + Schema + 时间线
"""
# Layer 0: 用户画像摘要 (始终返回)
profile_summary: ProfileSummary = field(default_factory=ProfileSummary)
# Layer 1: 索引视图 (~100 tokens)
index_view: List[MemoryIndexEntry] = field(default_factory=list)
# Layer 2: 摘要视图 (~500 tokens, 按需展开)
summary_view: List[MemorySummaryEntry] = field(default_factory=list)
# Layer 3: 完整内容 (按需懒加载)
full_content_ids: List[str] = field(default_factory=list)
# 元认知信号
meta_cognition: MetaCognitionReport = field(default_factory=MetaCognitionReport)
# 前瞻性意图
triggered_intentions: List[TriggeredIntention] = field(default_factory=list)
# 激活的 Schema
activated_schemas: List[ActivatedSchema] = field(default_factory=list)
# 时间线上下文
temporal_context: Optional[TemporalContext] = None
def to_dict(self) -> Dict[str, Any]:
return {
"profile_summary": self.profile_summary.to_dict(),
"index_view": [e.to_dict() for e in self.index_view],
"summary_view": [e.to_dict() for e in self.summary_view],
"full_content_ids": self.full_content_ids,
"meta_cognition": self.meta_cognition.to_dict(),
"triggered_intentions": [t.to_dict() for t in self.triggered_intentions],
"activated_schemas": [s.to_dict() for s in self.activated_schemas],
"temporal_context": self.temporal_context.to_dict() if self.temporal_context else None,
}
# ============================================================
# V1 兼容类型别名
# ============================================================
# MemoryEntry 作为 MemoryNode 的别名,保持旧代码不报错
MemoryEntry = MemoryNode
@dataclass
class MemoryMetadata:
"""
V1 兼容: 记忆元数据
新代码应直接使用 MemoryNode 的字段。此类保留用于与旧代码兼容。
"""
uid: str = ""
agent_id: str = ""
layer: MemoryLayer = MemoryLayer.L1_RAW
event_time: Optional[datetime] = None
created_at: Optional[datetime] = None
updated_at: Optional[datetime] = None
expires_at: Optional[datetime] = None
importance: float = 1.0
recency_weight: float = 1.0
access_count: int = 0
last_accessed: Optional[datetime] = None
source: Optional[str] = None
parent_id: Optional[str] = None
related_ids: List[str] = field(default_factory=list)
custom: Dict[str, Any] = field(default_factory=dict)
tags: List[str] = field(default_factory=list)
def __post_init__(self):
now = datetime.now()
if self.created_at is None:
self.created_at = now
if self.updated_at is None:
self.updated_at = now
if self.event_time is None:
self.event_time = now
def to_dict(self) -> Dict[str, Any]:
return {
"uid": self.uid,
"agent_id": self.agent_id,
"layer": self.layer.value,
"event_time": int(self.event_time.timestamp()) if self.event_time else None,
"created_at": int(self.created_at.timestamp()) if self.created_at else None,
"updated_at": int(self.updated_at.timestamp()) if self.updated_at else None,
"expires_at": int(self.expires_at.timestamp()) if self.expires_at else None,
"importance": self.importance,
"recency_weight": self.recency_weight,
"access_count": self.access_count,
"last_accessed": int(self.last_accessed.timestamp()) if self.last_accessed else None,
"source": self.source,
"parent_id": self.parent_id,
"related_ids": self.related_ids,
"custom": self.custom,
"tags": self.tags,
"tag_ners": list(self.tag_ners or []),
}
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "MemoryMetadata":
def parse_datetime(value):
if value is None:
return None
if isinstance(value, datetime):
return value
if isinstance(value, (int, float)):
return datetime.fromtimestamp(value)
if isinstance(value, str):
return datetime.fromisoformat(value)
return None
layer = data.get("layer", MemoryLayer.L1_RAW)
if isinstance(layer, str):
layer = MemoryLayer.from_string(layer)
return cls(
uid=data.get("uid", ""),
agent_id=data.get("agent_id", ""),
layer=layer,
event_time=parse_datetime(data.get("event_time")),
created_at=parse_datetime(data.get("created_at")),
updated_at=parse_datetime(data.get("updated_at")),
expires_at=parse_datetime(data.get("expires_at")),
importance=data.get("importance", 1.0),
recency_weight=data.get("recency_weight", 1.0),
access_count=data.get("access_count", 0),
last_accessed=parse_datetime(data.get("last_accessed")),
source=data.get("source"),
parent_id=data.get("parent_id"),
related_ids=data.get("related_ids", []),
custom=data.get("custom", {}),
tags=data.get("tags", []),
)
@dataclass
class MemoryScore:
"""
V1 兼容: 记忆评分
V2 使用更复杂的评分公式 (参见 core/scorer.py),此类保留兼容。
"""
semantic_score: float = 0.0
recency_score: float = 0.0
importance_score: float = 0.0
access_score: float = 0.0
semantic_weight: float = 0.5
recency_weight: float = 0.3
importance_weight: float = 0.15
access_weight: float = 0.05
@property
def final_score(self) -> float:
return (
self.semantic_score * self.semantic_weight
+ self.recency_score * self.recency_weight
+ self.importance_score * self.importance_weight
+ self.access_score * self.access_weight
)
def to_dict(self) -> Dict[str, Any]:
return {
"semantic_score": self.semantic_score,
"recency_score": self.recency_score,
"importance_score": self.importance_score,
"access_score": self.access_score,
"final_score": self.final_score,
"weights": {
"semantic": self.semantic_weight,
"recency": self.recency_weight,
"importance": self.importance_weight,
"access": self.access_weight,
},
}