memory_service

Agent memory operation service module

Attributes

Classes

MemoryService

MemoryService(
    sa_session: SASession, neo4j_session: NJSession
)

Bases: BaseService

Attributes

activity_session_dao `instance-attribute`

activity_session_dao = ActivitySessionDao(
    session=sa_session
)

agent_dao `instance-attribute`

agent_dao = AgentDao(session=sa_session)

agent_service `instance-attribute`

agent_service = AgentService(
    sa_session=sa_session, neo4j_session=neo4j_session
)

chain_service `instance-attribute`

chain_service = ChainService(
    sa_session=sa_session, neo4j_session=neo4j_session
)

collection_service `instance-attribute`

collection_service = MemoryCollectionService(
    sa_session=sa_session, neo4j_session=neo4j_session
)

memory_collection_dao `instance-attribute`

memory_collection_dao = MemoryCollectionDao(
    session=sa_session
)

memory_dao `instance-attribute`

memory_dao = MemoryDao(session=sa_session)

Functions

add_memories

add_memories(
    memories: List[AddMemoryRequest],
) -> Tuple[
    List[Tuple[int, Memory]],
    List[Tuple[int, AddMemoryRequest]],
]

Add memories in bulk

Parameters:

memories (List[AddMemoryRequest]) –

List of memory requests to be added in bulk

Returns:

List[Tuple[int, Memory]] –

Tuple[List[Tuple[int, AddMemoryRequest]], List[Tuple[int, AddMemoryRequest]]]: Indexed
List[Tuple[int, AddMemoryRequest]] –

success and failures

add_memories_stage `staticmethod`

add_memories_stage(
    memories: List[AddMemoryRequest],
) -> Tuple[
    List[Tuple[int, Memory]],
    List[Tuple[int, AddMemoryRequest]],
]

build_add_memory_requests

build_add_memory_requests(
    memories: List[str],
    session_ref: ActivitySession,
    agent_ref: Agent,
    memory_type: MemoryType = "observation",
    memos: List[str | None] | None = None,
    child_memory_pkids: List[List[str]] | None = None,
    vector_txts: List[str | None] | None = None,
    importance_scores: List[int] | None = None,
    disable_importance_chain: bool = False,
    disable_relevance_chain: bool = False,
    include_description: bool = True,
    include_special_instructions: bool = True,
    vector_txt_context: str | None = None,
    trace_session_id: str | None = None,
    trace_user_id: str | None = None,
    trace_metadata: ChainTraceMetadata | None = None,
    trace_tags: List[str] | None = None,
    trace_id: str | None = None,
) -> List[AddMemoryRequest]

Builds a list of AddMemoryRequest objects from the provided raw memory texts.

This method implements the logic that handles session settings regarding memory creation. Additionally, it will invoke the LLM to create importance scores and (optionally) generate the vector_txts list.

Parameters:

memories (List[str]) –

List of memory texts to be added.
session_ref (ActivitySession) –

The session reference.
agent_ref (Agent) –

The agent reference.
memory_type (MemoryType, default: 'observation' ) –

The memory type. Defaults to “observation”.
memos (List[str | None], default: None ) –

List of memos for each memory. Defaults to None.
child_memory_pkids (List[List[str]], default: None ) –

List of child memory PKIDs for each memory. Defaults to None.
disable_importance_chain (bool, default: False ) –

Whether to disable the importance chain. Defaults to False.
disable_relevance_chain (bool, default: False ) –

Whether to disable the relevance chain. Defaults to False.
vector_txt_context (str, default: None ) –

The vector context. Defaults to None.
trace_session_id (str, default: None ) –

The trace session ID. Defaults to None.
trace_user_id (str, default: None ) –

The trace user ID. Defaults to None.
trace_metadata (ChainTraceMetadata, default: None ) –

The trace metadata. Defaults to None.
trace_tags (List[str], default: None ) –

The trace tags. Defaults to None.
trace_id (str, default: None ) –

The trace ID. Defaults to None.

build_add_memory_requests_stage `staticmethod`

build_add_memory_requests_stage(
    memories: List[str],
    namespace: str,
    session_pkid: str,
    agent_pkid: str,
    memory_type: MemoryType = "observation",
    memos: List[str | None] | None = None,
    child_memory_pkids: List[List[str]] | None = None,
    vector_txts: List[str | None] | None = None,
    importance_scores: List[int] | None = None,
    disable_importance_chain: bool = False,
    disable_relevance_chain: bool = False,
    include_description: bool = True,
    include_special_instructions: bool = True,
    vector_txt_context: str | None = None,
    trace_session_id: str | None = None,
    trace_user_id: str | None = None,
    trace_metadata: ChainTraceMetadata | None = None,
    trace_tags: List[str] | None = None,
    trace_id: str | None = None,
) -> List[AddMemoryRequest]

Wraps build_add_memory_requests but does not rely on ORM objects bound to a long-running session/transaction. This cause issues when sub-objects are lazy loaded.

generate_importance_scores

generate_importance_scores(
    memories: List[str],
    agent_ref: Agent,
    session_ref: ActivitySession,
    include_description: bool = True,
    include_special_instructions: bool = True,
    trace_session_id: str | None = None,
    trace_user_id: str | None = None,
    trace_metadata: ChainTraceMetadata | None = None,
    trace_tags: List[str] | None = None,
    trace_id: str | None = None,
) -> List[int]

Generates importance scores for the given memories.

Parameters:

memories (List[str]) –

The list of memories to generate importance scores for.
agent_ref (Agent) –

The agent reference.
session_ref (ActivitySession) –

The session reference.
include_description (bool, default: True ) –

Whether to include the agent description in the generated agent persona. Defaults to True.
include_special_instructions (bool, default: True ) –

Whether to include the agent special instructions in the generated agent persona. Defaults to True.
trace_session_id (str, default: None ) –

The trace session ID
trace_user_id (str, default: None ) –

The trace user ID
trace_metadata (ChainTraceMetadata, default: None ) –

The trace metadata
trace_tags (List[str], default: None ) –

The trace tags
trace_id (str, default: None ) –

The trace ID

Returns:

List[int] –

List[int]: The list of importance scores.

generate_importance_scores_stage `staticmethod`

generate_importance_scores_stage(
    memories: List[str],
    namespace_pkid: str,
    agent_pkid: str,
    session_pkid: str,
    include_description: bool = True,
    include_special_instructions: bool = True,
    trace_session_id: str | None = None,
    trace_user_id: str | None = None,
    trace_metadata: ChainTraceMetadata | None = None,
    trace_tags: List[str] | None = None,
    trace_id: str | None = None,
) -> List[int]

Generate importance scores in bulk, useful for bulk operation stages.

Parameters:

memories (List[str]) –

The list of memories to generate importance scores for.
agent_pkid (str) –

The primary key ID of the agent.
session_pkid (str) –

The primary key ID of the session.
include_description (bool, default: True ) –

Whether to include the agent description in the generated agent persona. Defaults to True.
include_special_instructions (bool, default: True ) –

Whether to include the agent special instructions in the generated agent persona. Defaults to True.
trace_session_id (str, default: None ) –

The trace session ID
trace_user_id (str, default: None ) –

The trace user ID
trace_metadata (ChainTraceMetadata, default: None ) –

The trace metadata
trace_tags (List[str], default: None ) –

The trace tags
trace_id (str, default: None ) –

The trace ID

Returns:

List[int] –

List[int]: The list of importance scores.

generate_relevance

generate_relevance(
    memories: List[str],
    session_ref: ActivitySession,
    agent_ref: Agent,
    include_description: bool = False,
    include_special_instructions: bool = False,
    vector_txt_context: str | None = None,
    trace_session_id: str | None = None,
    trace_user_id: str | None = None,
    trace_metadata: ChainTraceMetadata | None = None,
    trace_tags: List[str] | None = None,
    trace_id: str | None = None,
) -> List[str | None]

Generates the vector_txt used to lookup the memory in the vector store. This is to provide situational context that can drive how the memory is recalled by the agent. For example, this can be the conversation in which the memory is created or other context that the agent is in.

Parameters:

memories (List[str]) –

The list of memories to generate relevance for.
session_ref (ActivitySession) –

The session reference.
agent_ref (Agent) –

The agent reference.
vector_txt_context (str, default: None ) –

The vector context. Defaults to None.
include_description (bool, default: False ) –

Whether to include the agent description in the generated agent persona. Defaults to False.
include_special_instructions (bool, default: False ) –

Whether to include the agent special instructions in the generated agent persona. Defaults to False.
trace_session_id (str, default: None ) –

The trace session ID. Defaults to None.
trace_user_id (str, default: None ) –

The trace user ID. Defaults to None.
trace_metadata (ChainTraceMetadata, default: None ) –

The trace metadata. Defaults to None.
trace_tags (List[str], default: None ) –

The trace tags. Defaults to None.
trace_id (str, default: None ) –

The trace ID. Defaults to None.

Returns:

List[str | None] –

List[str | None]: The list of vector_txt used to lookup the memory in the vector store.

generate_relevance_stage `staticmethod`

generate_relevance_stage(
    memories: List[str],
    namespace_pkid: str,
    session_pkid: str,
    agent_pkid: str,
    include_description: bool = True,
    include_special_instructions: bool = True,
    vector_txt_context: str | None = None,
    trace_session_id: str | None = None,
    trace_user_id: str | None = None,
    trace_metadata: ChainTraceMetadata | None = None,
    trace_tags: List[str] | None = None,
    trace_id: str | None = None,
) -> List[str | None]

Generates vector_txts with integrated session handling, useful for bulk operation stages.

Parameters:

memories (List[str]) –

The list of memories to generate relevance for.
session_pkid (str) –

The primary key ID of the session.
agent_pkid (str) –

The primary key ID of the agent.
include_description (bool, default: True ) –

Whether to include the agent description in the generated agent persona. Defaults to True.
include_special_instructions (bool, default: True ) –

Whether to include the agent special instructions in the generated agent persona. Defaults to True.
vector_txt_context (str, default: None ) –

The vector context. Defaults to None.
trace_session_id (str, default: None ) –

The trace session ID. Defaults to None.
trace_user_id (str, default: None ) –

The trace user ID. Defaults to None.
trace_metadata (ChainTraceMetadata, default: None ) –

The trace metadata. Defaults to None.
trace_tags (List[str], default: None ) –

The trace tags. Defaults to None.
trace_id (str, default: None ) –

The trace ID. Defaults to None.

Returns:

List[str | None] –

List[str | None]: The list of vector_txt used to lookup the memory in the vector store.

get_memories

get_memories(
    context: str,
    candidate_collection_pkids: List[str],
    top_k_vectors: int = 10,
    relevance_alpha: float = 1.0,
    importance_alpha: float = 1.0,
    recency_alpha: float = 1.0,
    min_score: float = 0.0,
    max_memories: int = 10,
    max_memory_strategy: str = "HARD_LIMIT",
    update_access: bool = True,
    summary_special_instructions: str = "",
    reduce_batch_size: int | None = None,
    trace_user_id: str | None = None,
    trace_session_id: str | None = None,
    trace_tags: List[str] | None = None,
    trace_id: str | None = None,
) -> GetMemoriesResponse

Retrieves memories based on the given agent and context. All memory collections bound to the agent are considered in this search.

get_memories_for_agent

get_memories_for_agent(
    agent_pkid: str,
    context: str,
    top_k_vectors: int = 10,
    relevance_alpha: float = 1.0,
    importance_alpha: float = 1.0,
    recency_alpha: float = 1.0,
    min_score: float = 0.0,
    max_memories: int = 10,
    max_memory_strategy: str = "HARD_LIMIT",
    update_access: bool = True,
    reduce_batch_size: int | None = None,
    trace_session_id: str | None = None,
    trace_tags: List[str] | None = None,
    trace_id: str | None = None,
) -> GetMemoriesResponse

Retrieves memories based on the given agent and context. All memory collections bound to the agent are considered in this search.

Memories are considered recalled when they meet the all of the following criteria:

The memory is in a collection bound to the provided agent.
The memory is not soft-deleted.
The memory has a weighted score greater than or equal to min_score.
The memory is in within the max_memories threshold.

Memory Score Calculation

The relevance score is the metric returned from the vector store. For Milvus this is either the euclidean distance (L2) or the inner product (IP) of the query vector and the memory vector. Since embedding vectors are almost always normalized the IP metric should be used.

The relevance score component is derived from the similarity metric returned by the vector store. Since IP of normalized vectors are a cosine similarity and range from -1.0 to 1.0, the algorithm scales to 0 and 1 via (IP + 1) / 2 before applying the relevance alpha weight.

The importance score component range is 1 to 10, so it is re-scaled to 0.0 to 1.0 before applying the alpha weight.

The recency score component ranged from the minimum and maximum access times in seconds of memory vectors returned by the vector store. It is re-scaled to 0.0 to 1.0 before applying the alpha weight.

The overall score range is 0.0 to 1.0 and is derived from the sum of the relevance, importance, and recency score components.

Vector Lookup

Vector lookup attempts to match the context to the vector_txt (if it was set). This allows memories to be indexed in the vector store based on the anticipated retrieval situation. This is different from a typical RAG application that will vectorize the raw text (in this case the memory) and allows agents to be tuned to their intended use cases.

top_k_vectors controls how many memories are returned by the vector store per context chunk. For example, if the input context is split into 2 chunks based on the embedding size limits, and top_k_vectors is set to 10, and the agent has 3 memory collections bound, then the vector store will return the top 10 memories for each chunk for every bound memory collection. The final number of memory vectors eligible for recall will be 60 (10 * 2 * 3).

The max_memory_strategy controls how the recalled memories are sampled.

HARD_LIMIT will sample the top scoring memories across all collections.
COLLECTION_LIMIT will sample memories evenly across all collections bound ot the agent, it is useful when a greater variety of memories is desired by spreading results across all collections.
SUMMARY will take all memories that meet the configured thresholds returned from all memory collections bound to the agent and use a LLM to perform a map-reduce operation. This methodology is useful when a summary of large amount of information is desired from all memories.

Parameters:

agent_pkid (str) –

The primary key ID of the agent.
context (str) –

The context used to retrieve memories, A simple chunking algorithm will be applied to the context to ensure it fits within the vectorizer’s maximum length.
top_k_vectors (int, default: 10 ) –

The number of top scoring vectors to retrieve per context chunk, see above. Defaults to 10.
relevance_alpha (float, default: 1.0 ) –

The weight value for the relevance score component. Defaults to 1.0.
importance_alpha (float, default: 1.0 ) –

The weight value for the importance score component. Defaults to 1.0.
recency_alpha (float, default: 1.0 ) –

The weight value for the recency score component. Defaults to 1.0
min_score (float, default: 0.0 ) –

The minimum score for a memory to be considered. Defaults to 0.0.
max_memories (int, default: 10 ) –

The maximum number of memories to return. Defaults to 10.
max_memory_strategy (str, default: 'HARD_LIMIT' ) –

The strategy to use for limiting the number of memories. Defaults to “HARD_LIMIT”.
update_access (bool, default: True ) –

Whether to update the access time of the retrieved memories. Typically this is true for chat operations and false for system-level operations such as a ReVoice. Defaults to True.
reduce_batch_size (int, default: None ) –

The batch size for reducing the memory summary. Defaults to None.
trace_session_id (str, default: None ) –

The trace session ID. Defaults to None.
trace_tags (List[str], default: None ) –

The trace tags. Defaults to None.
trace_id (str, default: None ) –

The trace ID. Defaults to None.

Returns:

GetMemoriesResponse ( GetMemoriesResponse ) –

The response object containing the retrieved memories.

pretty_print_memories `staticmethod`

pretty_print_memories(
    memories: List[RetrievedMemory],
    include_limit: int,
    precision: int = 3,
) -> List[str]

Formats a list of memories into a more human-readable format. Intended use case is to display returned memories easily in Langfuse

Parameters:

memories (List[RetrievedMemory]) –

The list of memories to format.
include_limit (int) –

The maximum number of memories to include.
precision (int, default: 3 ) –

The number of decimal places to round the scores to. Defaults to 3.

Returns:

List[str] –

List[str]: The formatted memories as a list of strings.

Functions

scale_to_unit_interval

scale_to_unit_interval(values: List[float]) -> List[float]

Scales the values in the input list so that they are between 0.0 and 1.0.

Parameters:

values (List[float]) –

A list of float values to be scaled.

Returns:

List[float] –

List[float]: A list of scaled float values between 0.0 and 1.0.

Raises:

ValueError –

If the input list is empty.

memory_service

Attributes

Classes

MemoryService

Attributes

activity_session_dao instance-attribute

agent_dao instance-attribute

agent_service instance-attribute

chain_service instance-attribute

collection_service instance-attribute

memory_collection_dao instance-attribute

memory_dao instance-attribute

Functions

add_memories

add_memories_stage staticmethod

build_add_memory_requests

build_add_memory_requests_stage staticmethod

generate_importance_scores

generate_importance_scores_stage staticmethod

generate_relevance

generate_relevance_stage staticmethod

get_memories

get_memories_for_agent

Memory Score Calculation

Vector Lookup

pretty_print_memories staticmethod

Functions

scale_to_unit_interval

activity_session_dao `instance-attribute`

agent_dao `instance-attribute`

agent_service `instance-attribute`

chain_service `instance-attribute`

collection_service `instance-attribute`

memory_collection_dao `instance-attribute`

memory_dao `instance-attribute`

add_memories_stage `staticmethod`

build_add_memory_requests_stage `staticmethod`

generate_importance_scores_stage `staticmethod`

generate_relevance_stage `staticmethod`

pretty_print_memories `staticmethod`