> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Time Awareness

> Step-by-step guide to using temporal mode for time-aware queries

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](getting-started/quickstart) to understand basic operations
* Ensure you have [LLM Providers](setup-configuration/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`.

```python theme={null}
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,
)
```

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

## Step 2: Ask Time-aware Questions

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

```python theme={null}
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,
)
```

<Info>
  `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.
</Info>

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

<Tip>
  * 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
</Tip>

## Optional: Limit to Specific Datasets

```python theme={null}
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"`:

```bash theme={null}
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
      }'
```

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

## Graphiti Mode: Episode-Based Temporal Graph

Cognee also ships a second temporal path built on [Graphiti-core](https://github.com/getzep/graphiti). 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

<AccordionGroup>
  <Accordion title="Requirements" defaultOpen>
    <Note>
      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](/setup-configuration/graph-stores).
    </Note>

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

    ```bash theme={null}
    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
    ```
  </Accordion>

  <Accordion title="Build and Query with Graphiti">
    ```python theme={null}
    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())
    ```

    <Note>
      `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.
    </Note>
  </Accordion>

  <Accordion title="Index the Episodes">
    After building the episode graph, pull the Neo4j data into Cognee's vector store:

    ```python theme={null}
    from cognee.tasks.temporal_awareness.index_graphiti_objects import (
        index_and_transform_graphiti_nodes_and_edges,
    )

    await index_and_transform_graphiti_nodes_and_edges()
    ```

    <Note>
      This step requires `GRAPH_DATABASE_PROVIDER=neo4j` to be set. It raises a `RuntimeError` if the active graph engine is not Neo4j.
    </Note>
  </Accordion>
</AccordionGroup>

## Full Example

<Accordion title="Latest guide">
  ```python theme={null}
  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())
  ```
</Accordion>

<Accordion title="Legacy guide">
  ```python theme={null}
  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())
  ```
</Accordion>

## Additional examples

Additional examples about temporal awareness are available on our [GitHub](https://github.com/topoteretes/cognee/tree/main/examples/guides).

<Columns cols={2}>
  <Card title="Core Concepts" icon="brain" href="/core-concepts/overview">
    Understand knowledge graph fundamentals
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore temporal API endpoints
  </Card>
</Columns>