Temporal Knowledge Graph

​

How Cognee tracks time

​

Before You Start

• Complete Quickstart to understand basic operations
• Ensure you have LLM Providers configured
• Read Recall for how querying memory works
• Any built-in graph store works. The default Ladybug/Kuzu store, Neo4j, and the Postgres demo graph answer the time-window lookups with a native query; Turso, Neptune, and Neptune Analytics use a generic fallback that scans the graph and walks each candidate’s neighbourhood, which is slower on large graphs. A community adapter, such as FalkorDB or Memgraph, needs get_graph_data and get_neighborhood for that fallback, or its own get_timestamps_in_range and get_temporal_anchors
• No data is required up front — the script ingests its own dated sample text, but it starts with cognee.forget(everything=True), which wipes all existing Cognee data; run it against a setup you can afford to reset

​

Code in Action

import asyncio

import cognee
from cognee import SearchType

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

QUERIES = [
    "What happened before 2000?",
    "What happened after 2004?",
    "Events between 2001 and 2004",
]


async def main():
    await cognee.forget(everything=True)

    # The default extraction stores each date as a Timestamp node next to the usual graph.
    await cognee.remember(TEXT, dataset_name="timeline_demo", self_improvement=False)

    for query in QUERIES:
        results = await cognee.recall(
            query_text=query,
            query_type=SearchType.TEMPORAL,
            datasets=["timeline_demo"],
            top_k=15,
        )
        print(f"\nQ: {query}")
        print(f"A: {results[0].text}")


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

​

What Just Happened

​

Step 1: Remember Dated Data

await cognee.forget(everything=True)

# The default extraction stores each date as a Timestamp node next to the usual graph.
await cognee.remember(TEXT, dataset_name="timeline_demo", self_improvement=False)

​

Step 2: Ask Time-aware Questions

for query in QUERIES:
    results = await cognee.recall(
        query_text=query,
        query_type=SearchType.TEMPORAL,
        datasets=["timeline_demo"],
        top_k=15,
    )
    print(f"\nQ: {query}")
    print(f"A: {results[0].text}")

​

How Dates Are Stored

• A date covers everything it states and no more: "In 2001 version 1.0 shipped" becomes 2001 with precision year, covering all of 2001, so it stays distinguishable from 2001-01-01.
• A Timestamp node’s id is derived from timestamp_str, so every mention of the same date across chunks and documents shares one node. Timestamp nodes are not embedded.
• A date without a stated year (“on 27 April”, “later that spring”) is resolved against the last year stated earlier in the same document and handed to the extraction prompt as a hint; the chunk text itself is not changed.
• A date the LLM leaves in a form that cannot be normalized stays an ordinary Entity node.

1. Reads a time window from the question. An LLM call turns the question into one UTC window, start inclusive and end exclusive. A named year, month, or day covers that whole unit; “before X”, “until X”, “after X”, and “since X” leave one side open (see How boundary words are read).
2. Gathers candidates. It runs a hybrid search for four times top_k candidates and adds the chunks attached to Timestamp nodes inside the window, which similarity search alone tends to miss.
3. Reranks. Candidates attached to an in-window timestamp — directly, or through an entity that is — move to the front, and the rest follow in similarity order. The list is then cut to top_k.

• As precise as the question, or more precise → these all rank the same and keep their embedding-similarity order. For “in 2020”, a paragraph dated September 2020 is not pushed below a row dated 2020-09-14.
• Coarser than the question → ranked lower, and the wider the timestamp the lower it goes. For “on 18 March 1965”, a chunk dated 1965-03-18 comes before one that only says 1965.
• Open-ended window (“since 2022”, “before 1900”) → no precision preference. Every anchored candidate ranks the same and keeps its similarity order.

​

How boundary words are read

​

Relative and vague time expressions

• The content remains fully retrievable through hybrid search, including the fallback inside SearchType.TEMPORAL.
• It is invisible to the time window, so a “before 2005” query will not move it to the front.

​

Using the HTTP API

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
      }'

await cognee.forget(dataset="timeline_demo", memory_only=True)
await cognee.cognify(datasets=["timeline_demo"])

​

Full Examples

• An advanced script running temporal search over real documents is on our GitHub. Instead of the inlined four-sentence timeline above, it ingests three bundled documents (two biographies and a news article) and prints the extracted Timestamp nodes with their precision and the *_at edges tying them to entities, including a year-less “April 27” stored as 1986-04-27 (see How Dates Are Stored). It then asks each question with both SearchType.HYBRID_COMPLETION and SearchType.TEMPORAL side by side; its last question names a date absent from the documents, exercising the plain-hybrid fallback described in Relative and vague time expressions. Like the script above, it starts with cognee.forget(everything=True), and it reads the graph through get_graph_engine().get_graph_data(), an internal API that may change without notice.