Implementation:Run llama Llama index Node Recency Postprocessors

Overview

The node recency postprocessors module provides three time-aware postprocessing strategies for reranking or filtering retrieved nodes based on temporal metadata. These postprocessors address scenarios where document recency matters, such as news feeds, patient records, project changelogs, or any corpus where newer information should take priority. This module is located at llama-index-core/llama_index/core/postprocessor/node_recency.py (224 lines).

Purpose

Standard retrieval ranks nodes by semantic similarity alone. These postprocessors introduce a temporal dimension, enabling the system to favor more recent documents. Three different strategies are provided, ranging from simple date-based sorting to embedding-aware deduplication to a time-decay scoring model inspired by memory systems.

Key Components

Class: FixedRecencyPostprocessor

A postprocessor that sorts nodes by date and returns only the most recent ones.

Fields

Field	Type	Default	Description
top_k	int	1	Number of most recent nodes to return.
date_key	str	"date"	The metadata key containing the date value.

Algorithm

1. Extracts date values from each node's metadata using self.date_key.
2. Parses dates using pandas.to_datetime().
3. Sorts node indices in descending order (most recent first) using np.flip(argsort()).
4. Returns the top top_k nodes.

Requirements

• Requires pandas for date parsing. Raises ImportError if not installed.
• Requires a query_bundle parameter. Raises ValueError if not provided.
• Each node must have the date_key in its metadata.

Class: EmbeddingRecencyPostprocessor

A more sophisticated postprocessor that sorts nodes by date and then uses embedding similarity to deduplicate older nodes that are semantically similar to newer ones.

Fields

Field	Type	Default	Description
embed_model	SerializeAsAny[BaseEmbedding]	Settings.embed_model	The embedding model used for similarity comparison.
date_key	str	"date"	The metadata key containing the date value.
similarity_cutoff	float	0.7	Cosine similarity threshold above which an older node is considered a duplicate and is removed.
query_embedding_tmpl	str	DEFAULT_QUERY_EMBEDDING_TMPL	Template for generating query embeddings from node content.

Algorithm

1. Sorts all nodes by date (most recent first) using the same pandas/numpy approach as FixedRecencyPostprocessor.
2. Computes text embeddings for all nodes in a single batch via embed_model.get_text_embedding_batch().
3. Iterates through sorted nodes from newest to oldest:
   • Skips nodes already marked for removal.
   • Generates a query embedding for the current node using the query_embedding_tmpl template.
   • Compares this query embedding against all subsequent (older) nodes.
   • If the dot product similarity exceeds similarity_cutoff, the older node is marked for removal (added to node_ids_to_skip).
4. Returns only nodes not in the skip set.

Query Embedding Template

The default template (DEFAULT_QUERY_EMBEDDING_TMPL) frames each node's content as a search query to find similar older documents:

The current document is provided.
----------------
{context_str}
----------------
Given the document, we wish to find documents that contain
similar context. Note that these documents are older
than the current document, meaning that certain details may be changed.
However, the high-level context should be similar.

Class: TimeWeightedPostprocessor

A postprocessor that combines embedding similarity scores with a time-decay factor, inspired by generative agent memory models.

Fields

Field	Type	Default	Description
time_decay	float	0.99	Decay rate per hour. Values closer to 1.0 produce slower decay; lower values produce faster decay.
last_accessed_key	str	"__last_accessed__"	Metadata key storing the Unix timestamp of last access.
time_access_refresh	bool	True	Whether to update the last-accessed timestamp on returned nodes.
now	Optional[float]	None	Optional fixed timestamp for deterministic testing. Defaults to datetime.now().timestamp().
top_k	int	1	Number of top-scoring nodes to return.

Algorithm

1. Determines the current time (from self.now or datetime.now()).
2. For each node:
   • Retrieves the embedding similarity score (defaults to 1.0 if not set).
   • Retrieves the last_accessed timestamp from metadata (defaults to now if not set).
   • Computes hours elapsed: hours_passed = (now - last_accessed) / 3600.
   • Computes time similarity: time_similarity = (1 - time_decay) ** hours_passed.
   • Computes combined score: similarity = score + time_similarity.
3. Sorts all nodes by combined score in descending order.
4. Returns the top top_k nodes as new NodeWithScore objects with updated scores.
5. If time_access_refresh is True, updates the last_accessed_key metadata to the current timestamp for all returned nodes.

Scoring Formula

combined_score = embedding_score + (1 - time_decay) ^ hours_since_last_access

With the default time_decay=0.99:

• A node accessed 0 hours ago contributes 0.01^0 = 1.0 time bonus.
• A node accessed 1 hour ago contributes 0.01^1 = 0.01 time bonus.
• A node accessed 100 hours ago contributes a negligible time bonus.

Dependencies

Module	Items Imported
datetime	datetime for current timestamp generation.
numpy	np.flip for reversing sort order, np.dot for cosine similarity.
llama_index.core.base.embeddings.base	BaseEmbedding
llama_index.core.bridge.pydantic	Field, SerializeAsAny
llama_index.core.postprocessor.types	BaseNodePostprocessor
llama_index.core.schema	MetadataMode, NodeWithScore, QueryBundle
llama_index.core.settings	Settings (for default embed model)
pandas (optional)	pd.to_datetime for date parsing. Required by FixedRecencyPostprocessor and EmbeddingRecencyPostprocessor.

Comparison of Strategies

Strategy	Approach	Complexity	Use Case
FixedRecencyPostprocessor	Pure date sorting, return top-k	O(n log n)	When only the newest documents matter, regardless of relevance.
EmbeddingRecencyPostprocessor	Date sorting + embedding deduplication	O(n^2) embedding comparisons	When newer documents should supersede semantically similar older ones.
TimeWeightedPostprocessor	Score + exponential time decay	O(n log n)	When both relevance and recency should influence ranking, with configurable decay rates.

Design Notes

• The module contains a commented-out section for an LLM-based recency inference template (DEFAULT_INFER_RECENCY_TMPL) that was designed to let the LLM decide whether a query requires recency-aware processing. This feature is not currently active.
• EmbeddingRecencyPostprocessor uses a query embedding template rather than raw text embedding for the comparison, as it optimizes for retrieval-style similarity rather than exact text matching.
• TimeWeightedPostprocessor supports a now parameter for deterministic testing and also implements an access-refresh mechanism similar to LRU caching, where returned nodes get their access timestamp updated.
• Both FixedRecencyPostprocessor and EmbeddingRecencyPostprocessor require pandas as an optional dependency for date parsing.