Time Awareness

A minimal guide to Cognee’s temporal mode. The updated example uses remember() to build temporal memory in one step, then recall() for time-aware queries. Before you start:

Complete Quickstart to understand basic operations
Ensure you have LLM Providers configured
Have data that contains dates or times

What Temporal Mode Does

Builds events and timestamps from your text during ingestion
Lets you ask time-based questions like “before 1980”, “after 2010”, or “between 2000 and 2006”
Uses SearchType.TEMPORAL to retrieve the most relevant events and answer with temporal context

Step 1: Remember Data with Temporal Mode

Remember data with temporal information by enabling temporal_cognify=True.

text = """
In 1998 the project launched. In 2001 version 1.0 shipped. In 2004 the team merged
with another group. In 2010 support for v1 ended.
"""

await cognee.remember(
    text,
    dataset_name="timeline_demo",
    temporal_cognify=True,
    self_improvement=False,
)

This simple example uses one string that gets treated as a single document. In practice, you can add multiple documents, files, or entire datasets. The temporal processing works the same way across all your data.

Step 2: Ask Time-aware Questions

Use SearchType.TEMPORAL with cognee.recall(...) to retrieve the relevant events.

from cognee.api.v1.search import SearchType

# Before / after queries
result = await cognee.recall(
    query_type=SearchType.TEMPORAL, query_text="What happened before 2000?", top_k=10
)

result = await cognee.recall(
    query_type=SearchType.TEMPORAL, query_text="What happened after 2010?", top_k=10
)

# Between queries
result = await cognee.recall(
    query_type=SearchType.TEMPORAL, query_text="Events between 2001 and 2004", top_k=10
)

# Scoped descriptions
result = await cognee.recall(
    query_type=SearchType.TEMPORAL,
    query_text="Key project milestones between 1998 and 2010",
    top_k=10,
)

remember(..., temporal_cognify=True) builds the event-and-timestamp graph for the dataset during ingestion, so there is no separate cognify() step in the updated example.

This example uses a single dataset for simplicity. In practice, you can process multiple datasets or omit dataset_name to use the default dataset.

If the query has clear dates, the retriever filters events by time and ranks them
If no dates are detected, it falls back to event or entity retrieval and still answers
Increase top_k to inspect more candidate events

Optional: Limit to Specific Datasets

result = await cognee.recall(
    query_type=SearchType.TEMPORAL,
    query_text="What happened after 2004?",
    datasets=["timeline_demo"],
    top_k=10,
)

Using the HTTP API

If your server is running, you can run temporal search via the API by setting search_type to "TEMPORAL":

curl -X POST "http://localhost:8000/api/v1/search" \
  -H "Content-Type: application/json" \
  ${TOKEN:+-H "Authorization: Bearer $TOKEN"} \
  -d '{
        "search_type": "TEMPORAL",
        "query": "What happened between 2001 and 2004?",
        "top_k": 10
      }'

The Python example above is still the easiest way to enable temporal ingestion because it lets you pass temporal_cognify=True directly to remember().

Graphiti Mode: Episode-Based Temporal Graph

Cognee also ships a second temporal path built on Graphiti-core. Instead of extracting events and timestamps from text, it stores each document as a timestamped episode directly in Neo4j. Graphiti automatically tracks entities and how facts evolve over time across episodes. If you want, you can then index those episodes into Cognee’s vector store to run standard SearchType.* queries alongside Graphiti search. When to prefer this mode:

You need a complete, immutable episode history
You want direct access to Graphiti’s graph traversal and search API
Your pipeline requires a Neo4j-backed temporal store

Otherwise, start with native temporal mode — it needs no extra dependencies and works with any supported graph store.

`temporal_cognify=True` vs. Graphiti mode

Both modes make your memory time-aware, but they work differently and are enabled in different ways:

	Native temporal mode (`temporal_cognify=True`)	Graphiti mode
How to enable	Pass `temporal_cognify=True` to `remember()` (or `cognify()`)	Call `build_graph_with_temporal_awareness()` from `cognee.tasks.temporal_awareness`; requires the `graphiti` extra
What it builds	Extracts events and timestamps from your text and adds them to Cognee’s knowledge graph	Stores each document as a timestamped episode and lets Graphiti derive how entities and facts change over time
Graph store	Any supported graph store (Ladybug default)	Neo4j / AuraDB only (hard requirement of graphiti-core)
How to query	`cognee.recall(query_type=SearchType.TEMPORAL, ...)` in the normal pipeline	`search_graph_with_temporal_awareness()` (Graphiti’s own search), optionally indexed back into Cognee’s vector store
Best for	Time-scoped questions (“before 1980”, “between 2000 and 2006”) with no extra infrastructure	Complete, immutable episode history and direct access to Graphiti’s traversal/search API

Requirements

Neo4j is a hard requirement of graphiti-core itself, not a Cognee design choice. Installing cognee[graphiti] binds your temporal store to Neo4j or AuraDB. If you want temporal search without a Neo4j dependency, use Cognee’s native SearchType.TEMPORAL (see above) — it works with any supported graph store.

Running Neo4j instance (v4.4+ or AuraDB)
Install the graphiti extra: pip install cognee[graphiti]
Set the following environment variables:

GRAPH_DATABASE_PROVIDER=neo4j
GRAPH_DATABASE_URL=bolt://localhost:7687
GRAPH_DATABASE_PASSWORD=your_neo4j_password
# Neo4j username is fixed to "neo4j" in this integration

Build and Query with Graphiti

import asyncio
import cognee
from cognee.tasks.temporal_awareness import (
    build_graph_with_temporal_awareness,
    search_graph_with_temporal_awareness,
)

async def main():
    # 1. Add your data as usual
    text = "In 1998 the project launched. In 2001 version 1.0 shipped."
    await cognee.add(text, dataset_name="graphiti_demo")

    # 2. Retrieve the Cognee Data objects for the dataset
    all_datasets = await cognee.datasets.list_datasets()
    dataset = next(d for d in all_datasets if d.name == "graphiti_demo")
    data_items = await cognee.datasets.list_data(dataset.id)

    # 3. Build the episode graph in Neo4j
    graphiti = await build_graph_with_temporal_awareness(data_items)

    # 4. Query the graph (closes the connection after search)
    results = await search_graph_with_temporal_awareness(graphiti, "What happened in 1998?")
    print(results)

asyncio.run(main())

search_graph_with_temporal_awareness closes the Neo4j connection after returning results. For multiple queries, call graphiti.search(query) directly on the returned instance and close with await graphiti.close() when finished.

Index the Episodes

After building the episode graph, pull the Neo4j data into Cognee’s vector store:

from cognee.tasks.temporal_awareness.index_graphiti_objects import (
    index_and_transform_graphiti_nodes_and_edges,
)

await index_and_transform_graphiti_nodes_and_edges()

This step requires GRAPH_DATABASE_PROVIDER=neo4j to be set. It raises a RuntimeError if the active graph engine is not Neo4j.

Full Example

Latest guide

import asyncio
import cognee


async def main():
    await cognee.forget(everything=True)
    text = """
    In 1998 the project launched. In 2001 version 1.0 shipped. In 2004 the team merged
    with another group. In 2010 support for v1 ended.
    """

    await cognee.remember(
        text,
        dataset_name="timeline_demo",
        temporal_cognify=True,
        self_improvement=False,
    )

    from cognee.api.v1.search import SearchType

    # Before / after queries
    result = await cognee.recall(
        query_type=SearchType.TEMPORAL, query_text="What happened before 2000?", top_k=10
    )

    assert result != []

    result = await cognee.recall(
        query_type=SearchType.TEMPORAL, query_text="What happened after 2010?", top_k=10
    )

    assert result != []

    # Between queries
    result = await cognee.recall(
        query_type=SearchType.TEMPORAL, query_text="Events between 2001 and 2004", top_k=10
    )

    assert result != []

    # Scoped descriptions
    result = await cognee.recall(
        query_type=SearchType.TEMPORAL,
        query_text="Key project milestones between 1998 and 2010",
        top_k=10,
    )

    assert result != []

    result = await cognee.recall(
        query_type=SearchType.TEMPORAL,
        query_text="What happened after 2004?",
        datasets=["timeline_demo"],
        top_k=10,
    )

    assert result != []


if __name__ == "__main__":
    asyncio.run(main())

Legacy guide

import asyncio
import cognee


async def main():
    text = """
    In 1998 the project launched. In 2001 version 1.0 shipped. In 2004 the team merged
    with another group. In 2010 support for v1 ended.
    """

    await cognee.add(text, dataset_name="timeline_demo")
    await cognee.cognify(datasets=["timeline_demo"], temporal_cognify=True)

    from cognee import SearchType

    # Before / after queries
    await cognee.recall(
        query_type=SearchType.TEMPORAL,
        query_text="What happened before 2000?",
        top_k=10,
    )

    await cognee.recall(
        query_type=SearchType.TEMPORAL,
        query_text="What happened after 2010?",
        top_k=10,
    )

    # Between queries
    await cognee.recall(
        query_type=SearchType.TEMPORAL,
        query_text="Events between 2001 and 2004",
        top_k=10,
    )

    # Scoped descriptions
    await cognee.recall(
        query_type=SearchType.TEMPORAL,
        query_text="Key project milestones between 1998 and 2010",
        top_k=10,
    )

    await cognee.recall(
        query_type=SearchType.TEMPORAL,
        query_text="What happened after 2004?",
        datasets=["timeline_demo"],
        top_k=10,
    )


if __name__ == "__main__":
    asyncio.run(main())

Additional examples

Additional examples about temporal awareness are available on our GitHub.

Core Concepts

Understand knowledge graph fundamentals

API Reference

Explore temporal API endpoints

Getting Started

Core Concepts

Setup Configuration

Guides

Examples

CLI

Rust SDK

TypeScript SDK

OSS

What Temporal Mode Does

Step 1: Remember Data with Temporal Mode

Step 2: Ask Time-aware Questions

Optional: Limit to Specific Datasets

Using the HTTP API

Graphiti Mode: Episode-Based Temporal Graph

`temporal_cognify=True` vs. Graphiti mode

Full Example

Additional examples

Core Concepts

API Reference

​What Temporal Mode Does

​Step 1: Remember Data with Temporal Mode

​Step 2: Ask Time-aware Questions

​Optional: Limit to Specific Datasets

​Using the HTTP API

​Graphiti Mode: Episode-Based Temporal Graph

​temporal_cognify=True vs. Graphiti mode

​Full Example

​Additional examples

Core Concepts

API Reference

What Temporal Mode Does

Step 1: Remember Data with Temporal Mode

Step 2: Ask Time-aware Questions

Optional: Limit to Specific Datasets

Using the HTTP API

Graphiti Mode: Episode-Based Temporal Graph

`temporal_cognify=True` vs. Graphiti mode

Full Example

Additional examples