3.2 · 时序感知与双时态模型（Temporal Awareness and Bi-Temporal Model）

时序感知与双时态模型

时间感知与双时间模型

相关源文件

本章引用的主要源码文件：

• README.md
• examples/quickstart/README.md
• graphiti_core/edges.py
• graphiti_core/nodes.py
• graphiti_core/utils/__init__.py
• graphiti_core/utils/datetime_utils.py
• graphiti_core/utils/maintenance/community_operations.py
• graphiti_core/utils/maintenance/graph_data_operations.py

本页介绍 Graphiti 的时间数据模型，该模型同时追踪事实进入系统的时间（created_at）以及它们在现实世界中成立的时间（valid_at、invalid_at）。这种双时间设计支持时间点查询、历史推理以及自动失效被矛盾的事实。

时间模型概述

Graphiti 在其数据模型中维护四个时间维度，以支持系统时间和有效时间推理：

这种设计将系统时间（我们了解到某事的时间）与有效时间（实际发生的时间）分离，支持诸如"系统在日期 X 对发生在日期 Y 的事件了解什么？"之类的查询。

来源：graphiti_core/nodes.py:98-98、graphiti_core/nodes.py:311-313、graphiti_core/edges.py:54-54、graphiti_core/edges.py:271-279

时间维度详解

created_at：系统录入时间

标题：系统录入时间可视化

created_at 时间戳记录节点或边首次添加到图数据库的时间。它代表系统时间，在实体创建时设置一次。该属性存在于所有节点（通过 Node 基类）和边（通过 Edge 基类）上。

关键行为：

• 在创建时自动设置为 utc_now() graphiti_core/nodes.py:98-98、graphiti_core/edges.py:54-54。
• 初始创建后永不修改。
• 用于系统操作的时间顺序排序。
• 与事件实际发生的时间无关。

来源：graphiti_core/nodes.py:98-98、graphiti_core/edges.py:54-54、graphiti_core/utils/datetime_utils.py:20-22

valid_at：现实世界事件时间

标题：事件时间与入库时间

valid_at 时间戳记录事件或事实在现实世界中成立的时间。这与 created_at（我们了解到它的时间）不同。

应用场景：

• EpisodicNode.valid_at：片段内容最初创建的时间（例如，消息时间戳、文档日期）graphiti_core/nodes.py:311-313。
• EntityEdge.valid_at：关系成立的时间。该时间由大语言模型（LLM）从片段内容中提取 graphiti_core/edges.py:274-276。

大语言模型（LLM）提取： 在边提取过程中，大语言模型（LLM）使用片段的 valid_at 作为参考，将相对日期解析为绝对时间戳。在 retrieve_episodes 中，valid_at 用于过滤在特定 reference_time 之前发生的片段 graphiti_core/utils/maintenance/graph_data_operations.py:80-82。

来源：graphiti_core/nodes.py:311-313、graphiti_core/edges.py:274-276、graphiti_core/utils/maintenance/graph_data_operations.py:67-90

invalid_at：事实过期时间

标题：时间失效时间线

invalid_at 时间戳记录事实在现实中不再成立的时间。该时间主要通过边解析过程中的时间矛盾检测来设置。

关键行为：

• 大多数边初始为 None graphiti_core/edges.py:277-279。
• 当新信息明确与现有事实矛盾时设置。
• 表示有效时间的终止。
• 与 valid_at 一起用于定义事实的有效性区间，以支持历史推理。

来源：graphiti_core/edges.py:277-279

expired_at：系统失效时间

标题：系统失效过程

expired_at 时间戳记录系统确定边应失效的时间。这代表失效操作的系统时间。

与 invalid_at 的区别：

• invalid_at：事实不再成立的时间（有效时间）。
• expired_at：系统记录此失效的时间（系统时间）。

用法：

• 在检测到矛盾时设置为 utc_now()。
• 将边标记为逻辑删除（软删除），使其从图的"当前"视图中移除。
• 支持系统知识随时间演变的审计追踪。

来源：graphiti_core/edges.py:271-273

时间数据结构

EpisodicNode 时间属性

标题：EpisodicNode 模型

EpisodicNode 表示离散的事件或文档：

• valid_at：事件本身的时间戳（例如，消息发送时间）graphiti_core/nodes.py:311-313。
• created_at：节点持久化到 Graphiti 的时间 graphiti_core/nodes.py:98-98。
• entity_edges：从该特定片段中提取的边 UUID 列表，用于建立来源追踪 graphiti_core/nodes.py:314-317。

来源：graphiti_core/nodes.py:307-317、graphiti_core/nodes.py:98-98

EntityEdge 时间属性

标题：EntityEdge 模型

EntityEdge 追踪事实的生命周期：

• episodes：支持或提及此事实的片段 UUID 列表 graphiti_core/edges.py:267-270。
• created_at：边首次创建的时间 graphiti_core/edges.py:54-54。
• valid_at、invalid_at：事实在现实世界中成立的时期 graphiti_core/edges.py:274-279。
• expired_at：系统将事实标记为不再活跃的时间 graphiti_core/edges.py:271-273。

来源：graphiti_core/edges.py:263-279、graphiti_core/edges.py:54-54

时间点查询

Graphiti 通过 SearchFilters 系统和数据库级别的时间过滤来支持时间查询。像 retrieve_episodes 这样的函数允许通过使用 reference_time 参数过滤 EpisodicNode.valid_at 来查询图在特定时间点的状态 graphiti_core/utils/maintenance/graph_data_operations.py:67-90。

时间搜索过滤器

SearchFilters 系统支持在所有四个时间维度上过滤搜索结果。它支持针对 created_at、valid_at、invalid_at 和 expired_at 的操作符。

标题：SearchFilters 结构

来源：graphiti_core/nodes.py:98-98、graphiti_core/edges.py:271-279、graphiti_core/utils/maintenance/graph_data_operations.py:80-82

片段来源追踪

EntityEdge 上的 episodes 数组

标题：边来源追踪

EntityEdge 上的 episodes 数组记录哪些片段提及了此事实 graphiti_core/edges.py:267-270。这允许系统将任何事实追溯回其原始来源。

来源：graphiti_core/edges.py:267-270、graphiti_core/nodes.py:314-317

EpisodicNode 上的 entity_edges 数组

EpisodicNode 上的 entity_edges 数组提供反向关系，列出从该片段中提取的所有边 graphiti_core/nodes.py:314-317。

标题：片段提取来源追踪

来源：graphiti_core/nodes.py:314-317、graphiti_core/edges.py:267-270