Skip to main content
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

Requirements

  • 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

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.
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

import asyncio
import cognee


async def main():
    await cognee.prune.prune_data()
    await cognee.prune.prune_system(metadata=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())

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 in the updated tests/guides/temporal_recall.py guide script and the broader Cognee repository examples.

Core Concepts

Understand knowledge graph fundamentals

API Reference

Explore temporal API endpoints