v0.31.2 - update certifi to mitigate eMudhra compromise2026-10-20
Graphiti 0.31.2 是一次以修复为主的版本。核心方面,removeepisode 删除情节时会保留已陈述事实并重建摘要,addepisode_bulk 现在会记录 episode 支持的边类型;Neptune 的全文检索补上了 group 过滤,列表参数绑定问题也一并修好。安全上,MCP 与 REST 服务器默认只监听 localhost,并明确标注二者仅作参考实现,安全范围以文档说明为准。依赖方面升级 graphiti-core 到 0.31.2、MCP 服务器到 1.1.2,certifi 升至 2026.10.19。
v0.31.12026-10-15
v0.31.1 仅是一次版本号更新,将 graphiti-core 版本设为 0.31.1,无其他功能或修复变更。
v0.31.0 - gpt-6-luna as the default OpenAI model2026-10-14
Graphiti v0.31.0 更新亮点:
MCP 服务端升级到 MCP SDK 2.x,并新增按 groupid 路由的能力——MCP 工具现在会把请求送到指定 group 对应的图上,多图场景下不再串图。服务端镜像也会随 v.. 标签自动发布。
图谱质量方面,上游同步了 Zep 分支的抽取、去重与时序修复;新增 LLMRuntime 统一管理提示词与模型路由;C2 提示词成为默认的组合抽取提示;节点与边的去重接入 Jev 和 OpenAI Decisions 两个客户端。
兼容性上修复了 FalkorDB 6.x 下全文索引需用 DDL 形式创建的问题;OpenAI 默认模型由已弃用的 gpt-4.1-nano 换为 gpt-6-luna,并默认关闭 prompt caching。另有一批依赖安全升级(anyio、pyjwt、urllib3、tornado 等),以及 dev 依赖中移除 torch、CI 改用 workload identity 联邦等工程调整。
v0.30.2 - FalkorDB updates2026-09-08
graphiti 0.30.2:MCP server 现在会正确遵守 NEO4JDATABASE 环境变量并完成 Neo4j 路由;按 groupids 清空数据时不再漏掉 Saga 节点;多 group 并发场景下改用请求级 driver,隔离性更稳,装饰器分支的参数也改为按名绑定。Falkordb 的 edgefulltextsearch 去掉了每次命中都全量扫描 :Entity 的做法,检索开销明显下降。CI 侧升级了 pypi 发布 action。
mcp-v1.1.0 - Neo4j Custom Database Fix2026-09-01
mcp-v1.10 版本主要修复了 Neo4j 的数据库路由问题。此前 MCP 服务器会忽略 NEO4JDATABASE 配置:写入与搜索可能落到默认的 home database,其他操作却走配置的库,导致数据被分散在两个库中。现在所有操作统一使用配置的数据库,请在 .env 或 config.yaml 中明确设置 NEO4JDATABASE。若你之前配置了自定义库却查不到数据,建议检查 home database,早期写入可能落在那里,需要手动迁移。使用默认 neo4j 库的用户不受影响。同时更新了 graphiti-core 至 0.30.1,并修复了 CI 发布流程。
v0.30.1 - Neo4j Custom Database Fix, Search Fixes and Other Miscellaneous Fixes2026-09-01
Graphiti 0.30.0 修复了一个影响数据落库位置的长期问题:Neo4jDriver.executequery() 此前无视驱动的 database 配置,所有查询(含检索)一律打到服务器的 home database,只有基于 session 的写入才走配置的库。现在查询会正确路由到配置的数据库,未指定时默认 neo4j,同时支持单次调用覆盖:executequery(..., database_="name")。
⚠️ 行为变更:自建 Neo4j Enterprise 且把 database 参数设为非 neo4j、或服务器默认库已改名的用户需要留意——若不显式传 database,查询将改指 neo4j 而非你的 home database,请显式传库名以维持旧行为;反之,配置了自定义库后读操作现在会正确命中它,而此前经 execute_query 写入的数据可能仍留在 home database,需要迁移。用默认 neo4j 库的标准部署不受影响。
其他改动:FactResult 模型新增 sourcenodeuuid、targetnodeuuid 和 episodes 字段;边处理用平衡合并修复了跨编码器候选筛选;没有匹配实体类型的节点会保留原有属性;文档与 README 同步调整。版本号升至 0.30.0。
v0.29.3 - FalkorDB and other Optimizations2026-07-27
本次更新集中在 FalkorDB 与 MCP 的一批修复:全文搜索遇到全是停用词的查询会直接短路返回,反引号 token 与空查询不再出错;单 groupid 检索、namespace 与 ops 的 getbygroupids 读取会正确路由到对应图。MCP 侧修复了容器重启后搜索返回空结果、FalkorDB URI 用户名丢失的问题,cross-encoder 改由所配置的 provider 提供,不再硬编码 OpenAI,并新增通用结构化输出模式。Neo4j 与 Falkor 驱动在关闭时会正确取消初始化任务。实体边读取现在返回 reference_time,BFS 边搜索保留关系方向,communities 重建只清理目标 group。Docker 组合镜像可在 trixie 上构建,且不再插值宿主机 PATH。依赖方面升到 graphiti-core 0.29.3、openai 2.41、google-genai 2.8,CI 新增端到端回归测试与 Socket Firewall 校验。
v0.29.2 - FalkorDB Bug Fixes2026-06-08
Graphiti 本版重点在 MCP 服务器:补齐与核心库对齐的能力,包括双时间线、Saga、社区检测、过滤、三元组与自定义类型,并支持读取工具直接传入标量 groupid。依赖与默认模型同步升级,LLM 默认切到 gpt-5.5,推理强度随模型自动匹配;OpenAIGenericClient 默认改用 jsonschema,失败时回退 json_object。
FalkorDB 侧修复较多:新增嵌入式版本 falkordblite 支持(安装需 pin redis<8),修正 compose 端口不一致导致服务无法启动,参数中 NUL 字节问题也已清理。另外修好了 Ollama/OpenAI 兼容接口、--host/--port 命令行参数不生效,以及 MCP 环境变量覆盖范围不足的问题。Kuzu 已标记弃用,退出默认测试矩阵。
v0.29.1 - Optimizations and Efficiencies2026-05-21
Patch release covering quality and reliability improvements landed since 0.29.0.
Extraction quality
Attribute-hallucination guards (#1498) — addresses a customer report of up to 9KB of LLM meta-reasoning landing in entity attribute fields (e.g. phones,
industry). The LLM was dumping internal deliberation and echoing schema description text back into values. Three layered defenses:
1. Prompt-level: extract_attributes prompts for both nodes and edges now have hard rules forbidding parenthetical reasoning, deliberative phrases, candidate
alternatives, schema-description echoes, and null/N/A sentence stand-ins. Includes positive/negative examples.
2. Combined-extraction prompt: new OUTPUT DISCIPLINE block closes the "topic-as-Person" failure mode (full-sentence entity names) and pre-empts reasoning leaks
into fact text and relation_type.
3. Provider-level preamble: a shared applyattributeextractionpreamble on LLMClient mutates the system message across OpenAI, Anthropic, Gemini, and GLiNER2
so the "field descriptions are format specs, not values" instruction reaches every provider regardless of how structured output is wired. Sentinel-based
idempotency.
Structural backstop — capstringattributes: drops any string attribute >250 chars before it reaches the graph. Configurable per-field via Pydantic
Field(maxlength=...) or globally via GRAPHITIATTRIBUTEMAXLENGTH. Also handles list[str] (per-item + aggregate cap of maxlen 8). Required-field carve-out
retains the value with a louder WARNING rather than dropping (avoids ValidationError-ing the whole entity). Edge writes use scoped merge for over-cap drops only
— fields the LLM legitimately omitted still clear. group_id flows to the log line for tenant correlation.
Combined-extraction entity & edge precision (#1498) — targets six classes of low-quality entities (multi-choice fragments, clock times, quantities, coordinates,
imperative tip phrases, slogans) plus two systematic edge regressions (location-fragmentation through scenery intermediaries, dropped multi-episode setup
facts).
- ENTITY RULE 6 expanded into 8 sub-bullets covering the skip classes; ENTITY RULE 9 added for didactic / tutorial scaffolding.
- FACT RULE 4 strengthened around narrative announcements, forward commitments, plans, and emotional setup in conversational episodes; FACT RULE 8 added
requiring direct speaker-to-target edges over fragmenting through scenery intermediaries.
- Negative-examples block (A–G) added with paired source-and-extraction guidance per class.
Locomo 500-example eval (prompt change only):
- Entity F1: 0.674 (flat); precision −0.028, recall +0.025
- Edge volume: +7.7% over baseline; gold-edge recall +0.9pp
- Fact-text Jaccard on matched edges: 0.341 → 0.381
- Targeted entity classes on LME-derivative sample: quantities −93%, imperative tips −40%
Saga summarization
Episode-time watermarks for sagas (#1498) — saga (thread summary) timestamps now reflect originating-episode time rather than wall-clock time. SagaNode now
carries two deliberately distinct watermarks:
- lastsummarizedat (wall-clock) — the filter watermark. summarizesaga picks up any episode whose createdat > this value. Wall-clock + created_at comparison
keeps backfilled episodes reachable on the next run.
- lastsummarizedepisodevalidat (episode time) — the temporal watermark. Max valid_at across episodes covered by the current summary; advances monotonically.
Public/temporal consumers ("how recent is this summary's content in event-time?") should use this field.
sagagetepisodecontents now returns list[(content, validat)] tuples so callers can compute the watermark. getorcreatesaga renames now → created_at;
callers pass the episode's validat so a newly minted saga's createdat matches the episode that produced it.
Docker / packaging
- fix(mcp): install MCP provider extras in Docker images (#1461)
- fix(docker): mount FalkorDB volume to actual data path (#1462) — earlier mount path didn't match FalkorDB's data directory, so data wasn't actually persisted
across container restarts.
- chore(deps): bump uv group across 2 directories (#1473) — jupyterlab 4.5.7, plus indirect updates to jupyter-server 2.18.0, mistune 3.2.1, python-multipart
0.0.27.
Docs
- docs(graphiti): drop stale addepisodebulk warning (#1476) — removed an outdated docstring that warned the bulk path skipped edge invalidation and date
extraction. That hasn't been true since the bulk pipeline was rewritten to share per-episode primitives (resolveextractededges, extract_edges both run on the
bulk path).
What's Changed
docs(graphiti): drop stale addepisode_bulk edge-invalidation/date-extraction note by @prasmussen15 in https://github.com/getzep/graphiti/pull/1476
* Bump the uv group across 2 directories with 4 updates by @dependabot[bot] in https://github.com/getzep/graphiti/pull/1473
* fix(docker): mount FalkorDB volume to actual data path by @fengfeng-zi in https://github.com/getzep/graphiti/pull/1462
* fix: install MCP provider extras in Docker images by @fengfeng-zi in https://github.com/getzep/graphiti/pull/1461
* Forward-port: attribute-hallucination guards, combined-extraction precision, saga episode-time watermarks by @prasmussen15 in https://github.com/getzep/graphiti/pull/1498
* Bump graphiti-core version to 0.29.1 by @prasmussen15 in https://github.com/getzep/graphiti/pull/1499
New Contributors
* @fengfeng-zi made their first contribution in https://github.com/getzep/graphiti/pull/1462
Full Changelog: https://github.com/getzep/graphiti/compare/v0.29.0...v0.29.1
v0.29.0 - Major efficiency and Internal Architecture changes2026-04-27
Release Notes — graphiti-core 0.29.0
Summary
0.29.0 is the first of two releases focused on making ingestion meaningfully cheaper and the search pipeline easier to evolve. The headline changes:
Cheaper ingestion. A new combined node + edge extraction path lets a single LLM call cover what previously took two, and node/edge extraction can now batch multiple episodes into one prompt. Timestamp resolution (validat / invalidat) has also been split into its own step so it doesn't compete with structural fact extraction.
Search pipeline rework. A large internal restructure of graphiti_core/search/search.py lays the groundwork for upcoming search and reranker changes — no public API changes, but tracing coverage is much improved.
New saga abstraction. A summarizesaga(sagaid) API on Graphiti, backed by SagaNode and a refreshed prompt, gives a first-class way to roll up multi-episode narratives.
Quality-of-life. A facttriple episode type, episodemetadata for filtering, safer attribute merging that no longer clobbers first-class fields, and a podcast example that runs against an embedded FalkorDB with no external DB.
How this affects developers
Defaults are unchanged. Combined extraction is opt-in via usecombinedextraction=True on extractnodesandedgesbulk. Existing ingestion code keeps working as-is.
Episode indices are now 0-based. If you parse [Episode N] headers or rely on episode_indices from extraction results, update your offsets accordingly.
Kuzu users — schema migration required. RelatesToNode now expects a referencetime TIMESTAMP column. New databases get it automatically; existing stores need a one-time ALTER TABLE RelatesToNode ADD referencetime TIMESTAMP.
Custom attributes are now safer to set. Attribute dicts on nodes/edges no longer overwrite first-class fields (uuid, groupid, createdat, timestamps). If you were depending on that overwrite behavior, you'll need to set those fields directly.
New public surface to know about: Graphiti.summarizesaga(sagaid), the facttriple episode type, and EpisodicNode.episodemetadata for custom filtering keys.
Highlights
Efficiency: fewer, smarter LLM calls during ingestion
Combined node + edge extraction (feature-flagged). A single LLM call can now produce both nodes and edges for an episode. Pass usecombinedextraction=True to extractnodesandedgesbulk to opt in; default behavior is unchanged. Backed by a new prompts/extractnodesandedges.py and utils/maintenance/combinedextraction.py.
Multi-episode batched extraction. extractandresolvenodes and extractedges now accept a list of episodes, build a shared prompt with [Episode N] headers (new concatenateepisodes helper), and attach episode_indices to each extracted node/edge so callers can map results back to their source episode.
Decoupled timestamp resolution. New extracttimestamps / extracttimestampsbatch prompts let validat / invalid_at be resolved in a dedicated post-extraction step, so structural fact extraction is no longer entangled with date parsing.
Architecture
Search pipeline rework. Major restructure of graphiti_core/search/search.py (~1k lines changed) and new tracing test coverage, paving the way for upcoming search/reranker changes.
Sagas. New summarizesaga(sagaid) API on Graphiti, plus a refreshed summarizesagas prompt and supporting helpers (sagagetpreviousepisodeuuid, sagagetepisodecontents).
facttriple episode type and an episodemetadata dict on EpisodicNode for customer-defined filtering keys.
Safer attribute merging on edges and nodes — first-class fields (uuid, groupid, createdat, timestamps) are no longer overwritten when an attribute dict happens to contain a matching key.
referencetime preserved through bulk edge save, and added as a column on the Kuzu RelatesToNode schema. Existing Kuzu users may need a one-time ALTER TABLE RelatesToNode ADD referencetime TIMESTAMP.
Prompt refinements
Dedup (nodes & edges): tightened scope, looser two-entity rule in the combined extraction path.
Fact extraction: detail-preservation rule, broader entity capture for qualified objects.
Refreshed summarize_sagas prompt.
Examples / DX
examples/podcast/podcast_runner.py now runs against an embedded FalkorDB (falkordblite) with no external database, and exercises edge + node hybrid search post-ingest.
Notable internal changes
Driver tweaks in graphoperations.py and recordparsers.py.
Episode indexing is now 0-based (was 1-based in the first iteration of multi-episode extraction).
pytest bumped to 9.0.3 in server/ and mcp_server/.
Lockfile and dependency refreshes (uv group, voyageai, groq, google-genai, uvicorn, pyright, pytest-asyncio).
Coming next
The next release will continue this architectural track — expect the combined extraction path to graduate toward the default ingestion mode, additional batching across edge resolution and dedup, and follow-on search-pipeline changes building on the rework that landed here.