agents.memory_v2.time_weighted_retriever

Time-weighted retriever for Memory V2 system.

Based on LangChain’s time-weighted retriever patterns for long-term memory agents. Combines semantic similarity with recency weighting for optimal memory retrieval.

Reference: https://python.langchain.com/docs/versions/migrating_memory/long_term_memory_agent/

Classes

MemoryRetrievalSession

Session for managing retrieval with context and history.

TimeWeightConfig

Configuration for time-weighted retrieval.

TimeWeightedRetriever

Time-weighted retriever combining semantic similarity with recency.

Functions

create_memory_focused_retriever(vectorstore)

Create retriever optimized for memory retrieval.

create_time_weighted_retriever(vectorstore[, ...])

Factory function to create configured time-weighted retriever.

prepare_documents_for_time_retrieval(documents)

Prepare timestamped documents for time-weighted retrieval.

Module Contents

class agents.memory_v2.time_weighted_retriever.MemoryRetrievalSession(retriever, session_id=None, user_id=None)

Session for managing retrieval with context and history.

Initialize retrieval session.

Parameters:
get_session_stats()

Get session retrieval statistics.

Return type:

dict[str, Any]

retrieve_with_context(query, exclude_recent=True, context_boost=True)

Retrieve documents with session context awareness.

Parameters:

  • query (str)

  • exclude_recent (bool)

  • context_boost (bool)

Return type:

list[langchain_core.documents.Document]

class agents.memory_v2.time_weighted_retriever.TimeWeightConfig(/, **data)

Bases: pydantic.BaseModel

Configuration for time-weighted retrieval.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

class agents.memory_v2.time_weighted_retriever.TimeWeightedRetriever(vectorstore, config=None, **kwargs)

Bases: langchain_core.retrievers.BaseRetriever

Time-weighted retriever combining semantic similarity with recency.

Initialize time-weighted retriever.

Parameters:

  • vectorstore (langchain_core.vectorstores.VectorStore)

  • config (TimeWeightConfig)

class Config

Pydantic config.

get_relevant_documents_with_scores(query)

Get documents with their calculated scores for debugging.

Parameters:

query (str)

Return type:

list[tuple[langchain_core.documents.Document, float]]

update_config(**config_updates)

Update retriever configuration.

agents.memory_v2.time_weighted_retriever.create_memory_focused_retriever(vectorstore)

Create retriever optimized for memory retrieval.

Parameters:

vectorstore (langchain_core.vectorstores.VectorStore) – Vector store with memory documents

Returns:

Memory-optimized TimeWeightedRetriever

Return type:

TimeWeightedRetriever

agents.memory_v2.time_weighted_retriever.create_time_weighted_retriever(vectorstore, decay_rate=0.01, recency_weight=0.3, k=5)

Factory function to create configured time-weighted retriever.

Parameters:

  • vectorstore (langchain_core.vectorstores.VectorStore) – Vector store containing timestamped documents

  • decay_rate (float) – How quickly relevance decays per hour

  • recency_weight (float) – Weight of recency vs similarity (0.0-1.0)

  • k (int) – Number of documents to retrieve

Returns:

Configured TimeWeightedRetriever

Return type:

TimeWeightedRetriever

agents.memory_v2.time_weighted_retriever.prepare_documents_for_time_retrieval(documents)

Prepare timestamped documents for time-weighted retrieval.

Parameters:

documents (list[agents.memory_v2.message_document_converter.TimestampedDocument]) – List of timestamped documents

Returns:

List of documents ready for vector store ingestion

Return type:

list[langchain_core.documents.Document]