1274 lines
46 KiB
Python
1274 lines
46 KiB
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,
|
||
},
|
||
}
|