graphiti-intro

Graphiti Memory Plugin for Nanobot

1. 一句话定位

Graphiti 是 temporal context graph：把交互写成 episode，再抽取带时间有效性的 entities 和 facts。

2. 核心心智模型

• Graphiti 的输入单元是 episode，不是 memory string。
• 每个事实是 graph edge，并带 valid_at / invalid_at 等时间字段。
• 事实变化时旧 edge 被 invalidated，不是简单删除。
• reference_time 是核心输入；Nanobot Adapter 必须正确传入。
• group_id 是 graph partition，应映射到 persona/run 或实验 namespace。

3. 数据模型

Group / graph partition
  |-- Episode: raw source + valid_at
  |-- EntityNode: person, preference, task, concept...
  |-- EntityEdge: fact/relation
        |-- valid_at
        |-- invalid_at
        |-- source episode ids
  |-- indexes: vector, fulltext, graph traversal

字段	来源	用途
name	turn id	episode 名称
episode_body	Nanobot messages	原始证据
source_description	session/role/scenario	provenance
reference_time	turn timestamp	fact validity anchor
source	message/json/text/fact_triple	episode 类型（4种）
group_id	persona/run	graph 隔离
entity_types/edge_types	optional IPaS schema	自定义 ontology

4. 运行时流程

Write path
Nanobot turn
  -> GraphitiPlugin formats episode
  -> add_episode(reference_time, group_id)
  -> retrieve previous episodes
  -> extract entities and edges
  -> resolve/dedupe nodes
  -> set valid_at/invalid_at
  -> save graph + provenance
 
Read path
Nanobot query
  -> search or search_
  -> hybrid semantic + keyword + graph traversal
  -> facts/nodes/edges with temporal metadata
  -> formatted prompt context

5. 原生 API

API	参数	返回值	用途
Graphiti(...)	graph driver or URI, LLM, embedder, reranker	client instance	初始化 graph runtime
add_episode	name, episode_body, source_description, reference_time, group_id	episode/nodes/edges	写入并抽取 temporal graph
add_episode_bulk	list of raw episodes	bulk results	批量构建 graph
search	query, group_ids, num_results, filters	list of EntityEdge	基础 hybrid fact search
search_	query + SearchConfig	SearchResults	高级 graph search

6. 存储后端

• README 要求 Python 3.10+，并支持 Neo4j、FalkorDB、Kuzu、Amazon Neptune。
• 默认构造在未传 graph_driver 时使用 Neo4j driver。
• 默认 LLM/embedder/reranker 使用 OpenAI 相关 client；也支持替换 LLM/embedder/cross encoder。
• Amazon Neptune 路径还涉及 OpenSearch Serverless 作为全文检索后端。

7. Nanobot 集成边界

Nanobot 概念	Graphiti 概念
session turn	episode
message text	episode body
turn timestamp	reference_time
persona/run	group_id
benchmark context	source_description / custom extraction instructions
preference schema	optional entity/edge types

不能绕过的原生路径：

• 不直接写 graph DB 节点/边。
• 不丢 reference_time。
• 不用 destructive delete 表达偏好变化。
• 不用全图 dump 替代 search/search_。

8. 性能保留原则

• 同一 session/saga 的 episode 按顺序 await 写入。
• 保留 group_id，避免跨 persona graph 污染。
• 保留 raw episode provenance，除非明确做隐私/成本实验。
• 使用 Graphiti 的 search config/reranker，不在 Adapter 里重排全部图。
• 大批量导入用 bulk/queue 策略，不阻塞 Nanobot 主循环。

9. 集成风险 + 校验清单

• 检查每个 episode 的 reference_time 非空且时区一致。
• 检查事实变化时旧 edge 出现 invalid_at，而不是消失。
• 检查不同 group_id 查询不串扰。
• 检查 search 结果保留 fact、time、source episode。
• 分别记录 add_episode latency 和 search/search_ latency。