Python
"""
HY Memory - 抽象基类 + 统一协议
定义 WritePipeline / ReadPipeline 抽象接口,以及统一的请求/响应协议。
设计原则:
1. 统一协议 — WriteRequest/Response, ReadRequest/Response 是版本无关的
2. 可扩展 — 各版本在 extra_data 中传递版本特有的数据
3. 生命周期管理 — 通过 initialize() / close() 管理资源
"""
import re
from abc import ABC, abstractmethod
from typing import Optional, List, Dict, Any
from dataclasses import dataclass, field
from datetime import datetime
# 类型前向声明 (避免循环导入)
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from ..utils.tracer import PipelineTracer
# ================================================================
# 统一请求/响应协议
# ================================================================
@dataclass
class PipelineContext:
"""
Pipeline 执行上下文 — 贯穿整个 write/read 流程的共享状态。
公共模块可以通过此上下文传递中间结果,Pipeline 内部使用。
"""
# 请求标识
request_id: str = ""
# 用户隔离(两级: user_id + agent_id)
user_id: str = ""
agent_id: str = ""
# 会话
session_id: str = ""
# 中间结果存储 (Pipeline 内部使用)
intermediate: Dict[str, Any] = field(default_factory=dict)
# 性能追踪
start_time: Optional[datetime] = None
timings: Dict[str, float] = field(default_factory=dict)
def elapsed_ms(self) -> float:
"""返回从 start_time 到现在的毫秒数"""
if self.start_time is None:
return 0.0
return (datetime.now() - self.start_time).total_seconds() * 1000
@property
def isolation_key(self) -> str:
"""构建隔离键: {user_id}:{agent_id}"""
parts = [self.user_id or "default", self.agent_id or "default"]
return ":".join(parts)
@dataclass
class ToolCall:
"""
Assistant 发起的 tool 调用(OpenAI / Anthropic 通用化表示)。
OpenAI 风格的 `tool_calls` 数组里每个 entry、Anthropic 风格的 content
block (`type=="tool_use"`) 都规范化到这个结构。
"""
id: str = "" # 调用 id(OpenAI: tc.id;Anthropic: tool_use block id)
name: str = "" # tool 名
arguments: Dict[str, Any] = field(default_factory=dict)
# OpenAI 把 arguments 编码成 JSON 字符串;规范化层负责 json.loads 后塞进来
# Anthropic 直接给 dict;规范化层照搬
def to_dict(self) -> Dict[str, Any]:
return {"id": self.id, "name": self.name, "arguments": self.arguments}
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "ToolCall":
return cls(
id=data.get("id", ""),
name=data.get("name", ""),
arguments=data.get("arguments", {}) or {},
)
# ── 用户名字行(多真人对话专用)──
# 有名字的对话渲染成:
# 用户名叫Tim
# [user]: 我喜欢咖啡
# [John]: 我也喜欢茶
# 名字单独占一行、整段只出现一次;[user] 标签**不换成名字**,视角信息留在标签里。
# extract 用这一行给 L0 basic_info 取 name(用户不必在对话里自报姓名)。
# 各语言的模板在 hy_memory/prompts/<language>.py 的 USER_NAME_LINE;这两个旧名字保留。
_USER_NAME_LINE_ZH = "用户名叫{name}"
_USER_NAME_LINE_EN = "The user's name is {name}"
_user_name_line_res: Optional[List["re.Pattern"]] = None
def _user_name_line_patterns() -> List["re.Pattern"]:
"""每种语言一个匹配名字行的正则(L1_RAW 里可能存着任意语言的名字行)。"""
global _user_name_line_res
if _user_name_line_res is None:
from ..prompts import SUPPORTED_LANGUAGES, get_prompt
patterns = []
for code in SUPPORTED_LANGUAGES:
try:
tpl = get_prompt("USER_NAME_LINE", code)
except (ImportError, AttributeError):
continue
prefix, _, suffix = tpl.partition("{name}")
patterns.append(re.compile(
r"^" + re.escape(prefix.strip()) + r"\s*(.+?)\s*"
+ re.escape(suffix.strip()) + r"$"
))
_user_name_line_res = patterns
return _user_name_line_res
def render_user_name_line(
name: str, is_zh: bool = False, *, language: Optional[str] = None,
) -> str:
"""渲染文首的用户名字行;name 为空返回空串。
language(语言码)优先;未给时按 is_zh 在 zh-Hans / en 间选(旧行为)。
"""
name = (name or "").strip()
if not name:
return ""
from ..prompts import get_prompt
code = language or ("zh-Hans" if is_zh else "en")
return get_prompt("USER_NAME_LINE", code).format(name=name)
def parse_user_name_line(line: str) -> Optional[str]:
"""若该行是用户名字行则返回名字,否则返回 None。
L1_RAW 存的就是 get_flat_content() 的产物,回读历史时要靠这个把名字行识别出来,
否则它会被当成一条无前缀的裸消息(见 MemoryWriter._get_recent_history)。
"""
text = (line or "").strip()
for pattern in _user_name_line_patterns():
m = pattern.match(text)
if m:
return m.group(1)
return None
@dataclass
class ChatMessage:
"""单条聊天消息,兼容 OpenAI / Anthropic messages 格式(含 tool 调用)"""
role: str = "user" # user / assistant / system / tool
content: str = ""
name: Optional[str] = None
# 说话人显示名(OpenAI messages 的 `name` 字段)。多真人对话用它区分对方是谁:
# role=user → 当前记忆归属者。带 name 只用于给出"用户叫什么",标签仍渲染 [user]
# role=assistant + name → **对方真人**(不是 AI),渲染为 [<name>]
# role=assistant 无 name → AI assistant,渲染为 [assistant]
# 视角由 role 决定,name 只是显示名——两侧都可以有 name。
# role=tool 时该字段不走这里(工具名在 tool_name)。
# ── tool 扩展(仅 productivity / coding 路径使用;chat 路径忽略)──
tool_calls: List[ToolCall] = field(default_factory=list)
# role=assistant 时:发起的 tool 调用列表
# 其他 role 必为空
tool_call_id: Optional[str] = None
# role=tool 时:本消息对应的调用 id
# 其他 role 为 None
tool_name: Optional[str] = None
# role=tool 时:本消息对应的工具名(OpenAI 直接给;Anthropic 需要从前序 tool_use 反查,可空)
def to_dict(self) -> Dict[str, Any]:
d: Dict[str, Any] = {"role": self.role, "content": self.content}
if self.name:
d["name"] = self.name
if self.tool_calls:
d["tool_calls"] = [tc.to_dict() for tc in self.tool_calls]
if self.tool_call_id is not None:
d["tool_call_id"] = self.tool_call_id
if self.tool_name is not None:
d["tool_name"] = self.tool_name
return d
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "ChatMessage":
return cls(
role=data.get("role", "user"),
content=data.get("content", "") or "",
name=data.get("name") or None,
tool_calls=[ToolCall.from_dict(tc) for tc in (data.get("tool_calls") or [])],
tool_call_id=data.get("tool_call_id"),
tool_name=data.get("tool_name"),
)
def speaker_label(self) -> str:
"""渲染用的说话人标签(不含方括号)。
role=user 恒为 "user"(即使带 name),视角信息留在标签里;
对方真人(role=assistant + name)用名字;其余回退到 role。
"""
if self.role == "user":
return "user"
if self.role == "assistant" and self.name:
return self.name
return self.role
def has_tool_calls(self) -> bool:
return bool(self.tool_calls)
def is_tool_message(self) -> bool:
return self.role == "tool"
@dataclass
class WriteRequest:
"""
统一写入请求协议。
所有版本的 WritePipeline 都接收此格式的请求。
版本特有参数通过 extra 传递。
输入方式 (二选一):
1. content: str — 单条文本 (向后兼容)
2. messages: List[ChatMessage] — 多轮 (user-assistant)*N 对话
优先使用 messages,如果为空则回退到 content。
"""
# 必填 (二选一)
content: str = ""
messages: List[ChatMessage] = field(default_factory=list)
# 用户隔离
user_id: str = ""
agent_id: str = ""
# 调用来源(openclaw / cursor / codex 等),与 agent_id 正交。
source: str = "default"
# 请求追溯 id。由 client 入口显式注入(contextvar-immune),作为整条写入链路
# 落库 memory_ops / WRITE_SUMMARY / pipeline_logs 的单一真相源。空值时 writer
# 会用 contextvar 兜底。
request_id: str = ""
# 可选元数据
content_type: str = "text"
session_id: str = ""
turn_index: Optional[int] = None
role: str = "user"
assistant_content: Optional[str] = None
# 版本特有参数 (V1: agent_mode 等; V2: gate_config 等)
extra: Dict[str, Any] = field(default_factory=dict)
# 已有记忆 (V1 合并检测用)
existing_memories: Optional[List[Dict[str, Any]]] = None
# 记忆时间戳(不传则用当前时间 datetime.now())
memory_at: Optional[datetime] = None
def __post_init__(self) -> None:
from ..utils.source_filter import normalize_source
self.source = normalize_source(self.source)
# 调用方自定义的业务 meta,随本次产出的记忆一并存储、查询时原样返回。
# 纯附加负载:不 embed、不参与召回、不作过滤条件。
#
# 刻意独立于 extra:extra 混放 SDK 内部控制键(agent_mode / mode / layer),
# 与调用方的自定义键放一起会互相覆盖。
#
# 命名带 client_ 前缀是为了和 writer 内部的 "meta"(抽取结果的元信息,
# 形如 {"content","layer","tags"})区分开,二者完全无关。
client_meta: Optional[Dict[str, Any]] = None
# ── Coding memory 路径专用(chat 路径忽略)──
workspace_id: Optional[str] = None
# repo 标识。建议用 git remote URL 规范化(如 "github.com/org/repo")。
# 随经验与事实落库、召回时透出,并作为 search / list 的可选筛选条件;
# 缺失不会拒写。
branch: Optional[str] = None
# 分支名。同 workspace_id。
# 显式 prompt 语言码(canonical,见 hy_memory.prompts.SUPPORTED_LANGUAGES)。
# 由 client 入口按「per-call > MemoryConfig.language」解析后注入;None 时
# 抽取 / reconcile / 画像等各步沿用 zh/en 自动检测。
language: Optional[str] = None
# ---- 便捷方法 ----
def has_messages(self) -> bool:
"""是否有多轮对话输入"""
return bool(self.messages)
def get_user_queries(self) -> List[str]:
"""提取所有 user 角色的消息内容 (用于 embed 查 novelty)"""
return [m.content for m in self.messages if m.role == "user" and m.content.strip()]
def user_name(self) -> Optional[str]:
"""当前 user(role=user 一侧)的显示名;没有则 None。"""
for m in self.messages:
if m.role == "user" and m.name:
return m.name.strip() or None
return None
def get_flat_content(self) -> str:
"""
获取完整的文本内容:
- 如果有 messages → 拼接为对话格式
- 否则 → 返回 content
渲染格式(多真人对话):
用户名叫Tim
[user]: 我喜欢咖啡
[John]: 我也喜欢茶
无 name 时与历史行为完全一致(`[user]: ...` / `[assistant]: ...`)。
名字行只在 role=user 带 name 时出现,且整段只出现一次;语言取显式
language,未指定时按消息内容判定(与 extractor 选 zh/en prompt 同一套判据)。
"""
if not self.messages:
return self.content or ""
lines = [f"[{m.speaker_label()}]: {m.content}" for m in self.messages]
name = self.user_name()
if name:
if self.language:
name_line = render_user_name_line(name, language=self.language)
else:
from ..utils.lang_detect import is_chinese
name_line = render_user_name_line(
name, is_chinese(messages=self.messages)
)
if name_line:
lines.insert(0, name_line)
return "\n".join(lines)
def get_dialogue_text(self) -> str:
"""
获取适合 LLM 阅读的对话格式:
- 如果有 messages → 完整对话格式
- 如果有 content + assistant_content → 单轮 QA 格式
- 否则 → 原始 content
"""
if self.messages:
parts = []
for m in self.messages:
label = {"user": "用户", "assistant": "助手", "system": "系统"}.get(m.role, m.role)
parts.append(f"{label}: {m.content}")
return "\n".join(parts)
if self.assistant_content:
return f"用户: {self.content}\n助手: {self.assistant_content}"
return self.content or ""
@dataclass
class WriteResponse:
"""
统一写入响应协议。
所有版本的 WritePipeline 都返回此格式的响应。
"""
success: bool = False
# 写入结果
memory_id: str = ""
layer: str = ""
message: str = ""
# 提取的实体 (通用)
entities: List[Dict[str, Any]] = field(default_factory=list)
# 性能
elapsed_ms: float = 0.0
tokens_used: int = 0
# 错误信息
error_code: int = 0
error_message: str = ""
# 版本特有数据 (V1: routing_confidence, should_merge 等; V2: gate_passed, l2_fact_ids 等)
extra: Dict[str, Any] = field(default_factory=dict)
def to_dict(self) -> Dict[str, Any]:
return {
"success": self.success,
"memory_id": self.memory_id,
"layer": self.layer,
"message": self.message,
"entities": self.entities,
"elapsed_ms": round(self.elapsed_ms, 2),
"tokens_used": self.tokens_used,
"error_code": self.error_code,
"error_message": self.error_message,
"extra": self.extra,
}
@dataclass
class ReadRequest:
"""
统一读取请求协议。
"""
# 必填
query: str = ""
# 用户隔离
user_id: str = "" # 单用户(向后兼容)
user_ids: List[str] = field(default_factory=list) # 多用户搜索
agent_id: str = ""
# 灵活搜索过滤(list 形式)
agent_ids: List[str] = field(default_factory=list)
session_ids: List[str] = field(default_factory=list)
# 调用来源过滤。两者同时指定时语义为 IN(include) AND NOT IN(exclude),
# exclude 优先。底层 store 必须在 top-k/limit 前执行。
include_sources: List[str] = field(default_factory=list)
exclude_sources: List[str] = field(default_factory=list)
# 检索参数
limit: int = 10
layers: Optional[List[str]] = None
min_score: float = 0.4 # 通用最低分数阈值(部分 reader 用作召回门槛)
# Schema (L6) 独立召回参数
schema_min_score: float = 0.4 # Schema 路的最低分数阈值
schema_limit: int = 10 # Schema 路的最大返回数
# Proactive (Intention) 独立召回参数
intention_limit: int = 0 # Intention 路的 topk,默认 0 关闭
# 重排开关(按次生效)。False 时跳过全部重排阶段:本地 cross-encoder
# (recall.local_rerank_enabled) 与记忆关系图重排 (_apply_graph_rerank),
# 结果按召回分排序。走请求对象而非环境变量,并发请求互不影响。
rerank: bool = True
# 时间过滤
created_after: Optional[float] = None # Unix timestamp (float),只返回 gmt_created >= 此值的记忆
# 预计算的查询向量 (可选, 避免重复 embed)
query_embedding: Optional[List[float]] = None
# 会话
session_id: str = ""
# Trace / 可观测
# 如果业务方在 async_search 层已生成 request_id(推荐),会透传进来。
# reader 用它把 pipeline_logs 关联到本次 search,供 inspector 查询。
request_id: str = ""
# 版本特有参数 (V2: token_budget, use_llm_understanding 等)
extra: Dict[str, Any] = field(default_factory=dict)
def __post_init__(self) -> None:
from ..utils.source_filter import normalize_source_filters
self.include_sources, self.exclude_sources = normalize_source_filters(
self.include_sources, self.exclude_sources,
)
@dataclass
class ReadResponse:
"""
统一读取响应协议。
"""
success: bool = False
# 召回结果 (通用格式)
memories: List[Dict[str, Any]] = field(default_factory=list)
total_found: int = 0
# 性能
elapsed_ms: float = 0.0
# 错误信息
error_code: int = 0
error_message: str = ""
# 版本特有数据 (V2: context_package, query_understanding, recalled_node_ids 等)
extra: Dict[str, Any] = field(default_factory=dict)
def to_dict(self) -> Dict[str, Any]:
return {
"success": self.success,
"memories": self.memories,
"total_found": self.total_found,
"elapsed_ms": round(self.elapsed_ms, 2),
"error_code": self.error_code,
"error_message": self.error_message,
"extra": self.extra,
}
# ================================================================
# Pipeline 抽象基类
# ================================================================
class WritePipeline(ABC):
"""
写入抽象基类。
公共模块 (embed_service, vector_store, etc.) 通过构造函数注入。
Example:
class MemoryWriter(WritePipeline):
async def write(self, request, ctx):
...
"""
# Pipeline 版本标识 (子类必须覆盖)
VERSION: str = "base"
@abstractmethod
async def initialize(self) -> None:
"""
初始化 Pipeline 所需的资源。
例如: 初始化存储连接、加载模型等。
在首次使用前调用一次即可。
"""
pass
@abstractmethod
async def write(
self,
request: WriteRequest,
ctx: Optional[PipelineContext] = None,
tracer: Optional["PipelineTracer"] = None,
) -> WriteResponse:
"""
执行写入流程。
Args:
request: 统一写入请求
ctx: Pipeline 上下文 (可选, 用于传递中间状态)
Returns:
统一写入响应
"""
pass
async def close(self) -> None:
"""释放资源 (默认空实现)"""
pass
def __repr__(self) -> str:
return f"<{self.__class__.__name__} version={self.VERSION}>"
class ReadPipeline(ABC):
"""
读取抽象基类。
"""
# Pipeline 版本标识 (子类必须覆盖)
VERSION: str = "base"
@abstractmethod
async def initialize(self) -> None:
"""初始化 Pipeline 所需的资源。"""
pass
@abstractmethod
async def read(
self,
request: ReadRequest,
ctx: Optional[PipelineContext] = None,
tracer: Optional["PipelineTracer"] = None,
) -> ReadResponse:
"""
执行读取流程。
Args:
request: 统一读取请求
ctx: Pipeline 上下文
Returns:
统一读取响应
"""
pass
async def close(self) -> None:
"""释放资源 (默认空实现)"""
pass
def __repr__(self) -> str:
return f"<{self.__class__.__name__} version={self.VERSION}>"