基本概念¶

了解 OntoMem 工作的核心概念。

Schema-First 设计¶

OntoMem 使用 Pydantic 模型来定义你的记忆结构。这确保了类型安全性和 IDE 支持。

from pydantic import BaseModel
from typing import List, Optional

class ResearcherProfile(BaseModel):
    """类型安全的研究人员档案。"""
    name: str  # 必需字段
    affiliation: str
    research_interests: List[str]
    h_index: Optional[int] = None  # 可选字段（带默认值）

优势： - ✅ IDE 自动补全和类型提示 - ✅ 自动验证 - ✅ 轻松序列化（JSON/dict） - ✅ 清晰的数据契约

唯一键 & 去重¶

每个实体都需要一个唯一键来防止重复：

memory = OMem(
    memory_schema=ResearcherProfile,
    key_extractor=lambda x: x.name,  # 提取唯一键
)

当你添加具有现有键的实体时，OntoMem 会合并它而不是创建重复。

合并策略¶

不同的场景需要不同的合并方法：

MERGE_FIELD（默认）¶

非空字段覆盖
列表被追加
简单可预测

memory = OMem(
    memory_schema=ResearcherProfile,
    key_extractor=lambda x: x.name,
    strategy_or_merger=MergeStrategy.MERGE_FIELD
)

KEEP_INCOMING¶

始终使用最新（传入）数据
适用于状态更新

KEEP_EXISTING¶

始终保留首次观察
适用于历史记录

LLM.BALANCED（LLM 驱动）¶

智能综合冲突信息
需要 LLM 客户端
最适合复杂、多面数据

混合搜索¶

OntoMem 提供两种查找记忆的方式：

1. 基于键的查询 (O(1))¶

researcher = memory.get("Yann LeCun")

快速、精确匹配。当你知道唯一键时使用。

2. 语义搜索（向量基础）¶

memory.build_index()
results = memory.search("深度学习神经网络", top_k=5)

使用嵌入来查找语义相似的实体。非常适合发现。

状态管理¶

内存中操作¶

# 添加项目
memory.add(researcher_profile)

# 查询
profile = memory.get("Yann LeCun")

# 更新（添加重复键触发合并）
memory.add(updated_profile)

# 删除
memory.remove("Yann LeCun")

# 清除所有
memory.clear()

持久化¶

# 保存状态到磁盘
memory.dump("./my_memory")

# 在新会话中加载状态
new_memory = OMem(...)
new_memory.load("./my_memory")

批量操作¶

# 一次添加多个项目
researchers = [prof1, prof2, prof3]
memory.add(researchers)

# 迭代所有项
for researcher in memory.items:
    print(researcher.name)

# 获取所有键
keys = memory.keys  # List[Any]

# 获取计数
size = memory.size  # int

下一步¶

详细了解合并策略
探索高级用法
查看示例

准备好开始了吗？ 从快速开始指南开始。