A minimal guide to Cognee’s temporal mode. If you already know the regular add → cognify → search flow, this adds one switch at cognify time and one search type for time-aware questions. Before you start:
  • Complete Quickstart to understand basic operations
  • Ensure you have LLM Providers configured
  • Have data that contains dates/times (years or full dates)

​
What Temporal Mode Does

  • Builds events and timestamps from your text during cognify
  • 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: Add Data

Add data with temporal information using the standard add function. 
import cognee

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")
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: Cognify with Temporal Mode

Set temporal_cognify=True to extract events/timestamps instead of the default entity-graph pipeline. 
await cognee.cognify(datasets=["timeline_demo"], temporal_cognify=True)
Only datasets you pass (or all by default) are processed. Temporal mode runs an event/timestamp pipeline and stores temporal nodes in the graph.
This example uses a single dataset for simplicity. In practice, you can process multiple datasets simultaneously by passing a list of dataset names, or omit the datasets parameter to process all available datasets.

​
Step 3: Ask Time-aware Questions

Use SearchType.TEMPORAL and phrase your query with time hints. 
from cognee.api.v1.search import SearchType

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

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

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

# Scoped descriptions
await cognee.search(
    query_type=SearchType.TEMPORAL, 
    query_text="Key project milestones between 1998 and 2010", 
    top_k=10
)
  • 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/entity graph retrieval and still answers
  • Increase top_k to inspect more candidate events

​
Optional: Limit to Specific Datasets

await cognee.search(
    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
      }'
For now, enabling temporal processing at cognify time is easiest in Python with temporal_cognify=True.

​
Full Working Example

Check examples/python/temporal_example.py for a complete script that:
  • Adds two biographies (with dates)
  • Runs cognee.cognify(temporal_cognify=True)
  • Queries with SearchType.TEMPORAL for time-aware answers

Search Types

Learn about temporal search types

Core Concepts

Understand knowledge graph fundamentals

API Reference

Explore temporal API endpoints