Graphiti synthesis
Type: agentic-system-analyses/types/agentic-system-synthesis.md
Bounded synthesis
From supplied information to retained graph state
Graphiti is a model-dependent graph-memory system, not a general agent scheduler. It extracts entities and relationships from supplied episodes, reconciles them with existing graph content, retains derived descriptions and temporal metadata, and selects context for later callers. This account covers the shipped library, REST and MCP services, maintenance, assistant instructions, example consumers and evaluators at commit 964bb11d1e7020e3cc67fab244268b0736b6c219, with applicability cutoff 2026-10-12. SRC-1 supplies inspected implementation and doctrine/design only. No target, test, example, provider or database was executed. Historical notebook outputs are not evidence of this revision's operation. External providers, graph engines and host/framework internals, and proprietary Zep, are outside the frozen evidence. See boundary and evidence and Source register.
A caller starts episode ingestion with content, source type, reference time and optional group, schemas, prior episode UUIDs and custom instructions. The coroutine owns the next steps: retrieve prior context, extract and resolve entities, extract and reconcile facts, update attributes and summaries, then request persistence. Optional saga and community work follows the core write. Models propose content and semantic judgments; code consumes identities, indices and dates. The return is a processed result or propagated exception, not an independently certified knowledge artifact. Triplets and direct entity saves are alternate admissions, so episode extraction is not a universal gate. See RT-RTE-episode-ingestion and RT-RTE-maintenance-writes.
The retained state separates raw episode content, entity descriptions, relationship fact text, symbolic lineage/temporal selectors and dense search vectors. Embeddings encode text for retrieval; they are not graph-owned model weights. Derived facts and summaries retain content and associations rather than an exposed record of model reasons. Raw-source availability depends on the write path: single ingestion can blank episode content when configured, but bulk ingestion passes unchanged content to both its initial and final writes even with raw retention disabled. Bulk also writes episodes before extraction, so a later failure can leave an earlier stage retained. A transaction-shaped helper does not establish whole-invocation atomicity. See MEM-OBJ-episodic-node, MEM-OBJ-entity-edge, MEM-OBJ-graph-metadata, MEM-OBJ-graph-embeddings, RT-RTE-bulk-ingestion and RT-CLM-write-envelope.
Service acceptance has a still narrower meaning. REST and MCP enqueue work in process-local queues; their successful admission responses do not certify completed graph writes. MCP logs job failures and continues; REST's worker handles cancellation rather than ordinary job exceptions and captures a request-scoped client. MCP's delayed worker flag and writers outside its queues prevent a global serialization guarantee. See RT-RTE-service-admission and RT-CLM-queue-completion.
Reconciliation and maintenance change availability, not source warrant
Fact extraction requests relationships stated or unambiguously implied in the episode. Without particular outputs and source comparisons, the semantic transformation remains indeterminate: a model request establishes neither checked entailment nor non-entailment. Duplicate processing has a firmer local mechanism. Normalized fact text with matching ordered endpoints can reuse an existing edge without a model contradiction check. Otherwise model duplicate/contradiction indices feed bounds checks and temporal disposition. These results have enforcing consequences for graph identity and date fields, but judge sameness or inconsistency among selected candidates, not independent world truth. Temporal invalidation retains the old edge; current-only delivery still depends on filters and recipes. See EPI-RTE-fact-extraction, EPI-RTE-fact-comparison, EPI-RTE-fact-disposition and MEM-CLM-withdrawal-scope.
Curation also differs by object. Short entity summaries can append existing fact strings directly; longer or forced branches request model summaries. Node attribute extraction overlays prior fields, whereas applicable edge extraction uses replacement. Communities reduce entity summaries; saga maintenance combines a previous summary with a bounded new episode window. Saga selection uses an ingestion-time cursor, at most 20 episodes, character/byte budgets and truncated summaries. Advancing the cursor for a truncated episode can lose its unsubmitted suffix; strict timestamp selection leaves capped-batch ties unresolved. These are implemented recurring updates, not lossless compression or evidence-consuming factual acceptance. See EPI-RTE-entity-summary, EPI-RTE-attribute-extraction, MEM-OBJ-community-node, MEM-RTE-saga-summary and MEM-CLM-saga-losslessness.
Withdrawal is likewise route-specific. MCP delegates to core removal, which selects edges by their first episode reference, even when later references remain; this does not implement the documented sole-support preservation guarantee. REST directly deletes the episode node instead of invoking that cleanup. Neither path establishes regeneration of all derived summaries, deletion of separate conversation checkpoints or retraction of already delivered text. See MEM-CLM-withdrawal-scope and EPI-CLM-cleanup-contract.
Selection becomes context through a concrete consumer
Library and service searches return requested retained material using query text, optional vectors, groups, center nodes, limits and filters. Internal processing also automatically supplies prior episodes and descriptions to extraction or summarization models. Thus a request-driven workflow can contain both a requested graph read and downstream context supply without a separate model request. Ranking chooses available context; it does not license truth. Groups scope retrieval or database routing rather than establishing principal authorization. See RT-RTE-context-retrieval, RT-RTE-episode-ingestion and MEM-RTE-saga-summary.
The representative workflow is the shipped LangGraph shoe-sales notebook, selected because its code explicitly joins retrieval, tool delegation, another model invocation, delivery and memory admission. Each chatbot invocation queries five user-centered facts and inserts bare fact strings into a system message alongside accumulated conversation. The model may request the bound shoe-search tool, which returns ten product-centered facts; the scheduler then returns to the chatbot. No-tool output terminates the graph. The widget displays streamed model strings and reports escaping exceptions, but supplies no separate answer-review node or notebook-owned retry/compensation. Display, graph termination and memory persistence are separate outcomes. See RT-RTE-conversation-loop and its workflow annotation.
After every successful model response, including tool-call responses, the notebook schedules unawaited episode ingestion. The episode combines the latest state message with new response content. Its input can therefore be human, model or tool material, including previously retrieved facts; the unconditional user-name prefix does not authenticate origin. Later facts can derive from this mixed feed, but next-step availability is not established. A separate MemorySaver checkpoint retains conversation state through external framework machinery. See RT-RTE-conversation-loop, MEM-OBJ-episodic-node and MEM-OBJ-memory-saver.
Evidence available at the consumer differs by channel. Notebook facts omit episode and temporal fields, while MCP fact/direct-edge responses retain those fields and omit embeddings. Recent-episode reads expose available raw content through another selector. Lineage UUIDs make associations inspectable without proving source fidelity. Shipped MCP rules afford procedural influence by telling assistants to apply retrieved preferences and procedures, but host loading, tool-name mapping and compliance are unresolved. See RT-BAP-facts-context, MEM-CLM-display-lineage, EPI-RTE-provenance-read and RT-BAP-memory-instructions.
What this supports, and what would change the assessment
The strongest supported learning contribution is an implemented automatic trace-fed graph update with a later model-context consumer. Session messages and tool results can produce durable descriptions that influence later context; this does not require weight training. It establishes a pathway, not improved capacity for future action. Criticism of a consumed theory improving future capacity is not established by these records. Nor do they support a four-condition theory-builder verdict: semantic reconciliation, retained descriptions and relative scores alone do not establish formulated content-directed criticism and iteration. Reflection, full autonomous theory building and exercised self-improvement remain independently unestablished, rather than being bundled into a negative judgment. Within the notebook horizon, retained graph changes can reach a live context channel, but subsequent operation causally depending on an improvement-directed change is unobserved. See RT-RTE-conversation-loop, RT-BAP-facts-context and epistemic bounded conclusion.
The shipped evaluator contributes a separate relative comparison design: build/export a model-produced baseline, build a candidate graph, reload baseline results and request model judgments. It does not establish independently certified truth or install a production successor. Character-sliced message context, non-strict pairing and default not-worse scoring limit even that intended comparison; no scores or causal effects were observed. See RT-RTE-evaluation-comparison and MEM-OBJ-graph-results.
For the scenario of accumulating conversational information for later context, Graphiti supplies a concrete production-to-consumption chain. For the different scenario of warranted temporal knowledge or complete withdrawal, inspected routes do not support the stronger promises: imported source warrant is unknown, model interpretation is unchecked, and delivery/retraction vary by path. This is not a product ranking or a system-wide epistemic grade. Pinned runs tracing writes through later consumption would establish operation and activation. Independent source/output checks and appropriately controlled later-task comparisons could establish fidelity or improved capacity. Path-consistent raw-retention controls, tested support-aware deletion and derived-state retraction, or an evidence-consuming acceptance mechanism would change the corresponding architectural assessment. None is assumed present from documentation alone. See EPI-CLM-temporal-provenance, MEM-CLM-withdrawal-scope and RT-RTE-evaluation-comparison.
Limitations
| Limitation | Affected SRC IDs and record citations | Inspected boundary | Conclusion prevented | Evidence that would resolve it |
|---|---|---|---|---|
| Implementation and doctrine only; external runtime dependencies are not frozen | SRC-1; RT-RTE-conversation-loop, RT-RTE-service-admission, RT-CMP-openai-client | Pinned Graphiti code and shipped instructions, not executed deployments or provider/backend/host internals | Successful execution, durability, host compliance, activation, improved capacity and causal benefit | Pinned end-to-end traces, dependency identities and objective-specific outcome comparisons |
| Selective inspection leaves included alternatives unresolved | SRC-1; MEM-OBJ-graph-metadata, MEM-OBJ-graph-embeddings, RT-RTE-maintenance-writes, RT-RTE-evaluation-comparison | Selected library, service, prompt, backend, example and evaluator routes | Exhaustive consumer/transform enumeration, backend parity, universal metadata roundtrips or system-complete negatives | Record-supported tracing of the remaining relevant variants and consumers |
| Source truth and semantic preservation are unchecked | SRC-1; EPI-RTE-fact-extraction, EPI-RTE-attribute-extraction, EPI-RTE-entity-summary | Imported episodes, model-generated facts/attributes/summaries and selected semantic comparisons | Certified truth, universal faithful extraction, accepted ampliative knowledge or proof of semantic novelty | Actual outputs compared with warranted sources and a scoped evidence-consuming acceptance decision |
| Raw retention, temporal filtering and delivered lineage differ by path | SRC-1; MEM-OBJ-episodic-node, MEM-CLM-display-lineage, MEM-CLM-withdrawal-scope | Single/bulk writes, notebook/MCP display and inspected default/date-aware reads | Universal raw suppression, complete source access at every consumer or current-truth-only delivery | Consistent retention controls and path-specific persistence, formatting and filtering evidence |
| Summary budgets and cursor behavior bound coverage | SRC-1; MEM-RTE-saga-summary, MEM-CLM-saga-losslessness | Capped saga selection, truncation and strict ingestion-time cursor | Lossless summaries and guaranteed eventual coverage of truncated tails or timestamp ties | Coverage-preserving cursor/tail handling plus source-to-summary fidelity and tie-case evidence |
| Withdrawal does not establish global retraction | SRC-1; MEM-CLM-withdrawal-scope, EPI-RTE-episode-removal, MEM-OBJ-memory-saver | MCP/core first-reference deletion, REST direct deletion and separate derived/checkpoint state | Shared-support preservation, service-equivalent deletion, complete forgetting or rollback | Support-aware deletion and traced repair/retraction of affected summaries, checkpoints and later deliveries |
| Attribute inventory omits a conditional clearing branch | SRC-1; EPI-RTE-attribute-extraction; report verification limit | After early returns, a supplied schema map without an applicable relation model clears prior edge attributes; no-candidate/exact-match shortcuts are not uniformly covered | Complete comparison of schema-transition withdrawal behavior; positive overlay/replacement findings remain valid | A canonical branch-complete attribute-transition record, including shortcut conditions |
| Bundled representational-form units have unequal part-level coverage | SRC-1; MEM-OBJ-episodic-node, EPI-OBJ-entity-attributes, MEM-OBJ-memory-saver, MEM-OBJ-graph-results; profile verification limit | Combined JSON/attribute and checkpoint/export units, already partial | Separate form/coverage comparisons for individual fields, payloads and associations; supported textual/symbolic union remains valid | Separately scoped operative-part classifications supported by records of each consumption path |
| Relative evaluator has a model reference and weakened context/pairing | SRC-1; RT-RTE-evaluation-comparison, MEM-OBJ-graph-results | Selected dataset, exported baseline, character-sliced context and score aggregation | Independent factual accuracy, reliable contextual comparison, automatic successor installation or component attribution | Correct contextual assembly/pairing, independently checked references, executed comparisons and separately varied components |