Skip to content

eleanor.backend.service.cognitive

Cognitive service package

Attributes

__all__ module-attribute 

__all__ = [
    "DynamicPersonaService",
    "IntegrationService",
    "MemoryService",
    "MaintenanceService",
]

Classes

DynamicPersonaService 

DynamicPersonaService(
    sa_session: SASession, neo4j_session: NJSession
)

Bases: BaseService

Attributes

activity_session_dao instance-attribute 
activity_session_dao = ActivitySessionDao(
    session=sa_session
)
activity_session_participant_dao instance-attribute 
activity_session_participant_dao = (
    ActivitySessionParticipantDao(session=sa_session)
)
agent_dao instance-attribute 
agent_dao = AgentDao(session=sa_session)
chain_service instance-attribute 
chain_service = ChainService(
    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

generate_dynamic_persona 
generate_dynamic_persona(
    agent_pkid: str,
    min_memories: int | None = None,
    max_memories: int | None = None,
    collections: List[MemoryCollection] | None = None,
    reduce_batch_size: int | None = None,
    trace_session_id: Optional[str] = None,
) -> str

IntegrationService 

IntegrationService(
    sa_session: SASession, neo4j_session: NJSession
)

Bases: BaseService

Cognitive integration operation handler

Attributes

activity_session_dao instance-attribute 
activity_session_dao = ActivitySessionDao(
    session=sa_session
)
activity_session_participant_dao instance-attribute 
activity_session_participant_dao = (
    ActivitySessionParticipantDao(session=sa_session)
)
agent_dao instance-attribute 
agent_dao = AgentDao(session=sa_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)
memory_service instance-attribute 
memory_service = MemoryService(
    sa_session=sa_session, neo4j_session=neo4j_session
)

Functions

get_memories_by_session 
get_memories_by_session(
    agent_pkid: str,
    context: str,
    session_pkid: str,
    update_access: bool = True,
) -> GetMemoriesResponse

Retrieves agent memories, derive retrieval settings from session

Parameters:

  • agent_pkid (str) –

    The primary key of the agent.

  • context (str) –

    The context of the memories.

  • session_pkid (str) –

    The primary key of the session.

  • update_access (bool, default: True ) –

    Whether to update the access timestamp of the memories. Defaults to True.

Returns:

Raises:

  • ServiceError –

    If the session is not found, soft-deleted, disabled, or does not belong to the agent.

run_integration_operation 
run_integration_operation(
    session_pkids: List[str],
    memo: Optional[str] = None,
    trace_session_id: Optional[str] = None,
) -> Tuple[
    List[Tuple[int, Memory]],
    List[Tuple[int, AddMemoryRequest]],
]

MaintenanceService 

MaintenanceService(
    sa_session: SASession, neo4j_session: NJSession
)

Bases: BaseService

Attributes

activity_session_dao instance-attribute 
activity_session_dao = ActivitySessionDao(
    session=sa_session
)
activity_session_participant_dao instance-attribute 
activity_session_participant_dao = (
    ActivitySessionParticipantDao(session=sa_session)
)
agent_dao instance-attribute 
agent_dao = AgentDao(session=sa_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

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.