Memory & Integrations API Reference

This page documents the API signatures, constructor parameters, and configuration options for building agentic memory pipelines, embedding clients, and vector database clients.

Installation

API area	Extra
build_agent_with_memory, MemoryConfig, pipeline steps (trim, LRU, TTL, …)	elsai-chat-history
build_embedding_client, EmbeddingBackendConfig	elsai-embeddings
build_vectordb_client, VectorBackendConfig	elsai-vectordb
SimilarityRetrievalConfig, SemanticMemoryConfig	elsai-memory
build_semantic_strategy, build_semantic_strategy_from_env	elsai-memory
build_similarity_config, build_similarity_config_from_env	elsai-memory

pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents[elsai-chat-history]==0.3.5"
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents[elsai-embeddings]==0.3.5"
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents[elsai-vectordb]==0.3.5"
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents[elsai-memory]==0.3.5"

See Memory Overview and Installation — Memory integrations.

---

build_agent_with_memory

A builder function to instantiate a fully configured Agent equipped with custom memory pipelines and optional context injection hooks.

from elsai.integrations.memory import build_agent_with_memory

agent = build_agent_with_memory(
    config=memory_config,
    model=model_instance,
    tools=list_of_tools,
    system_prompt="Your prompt here",
)

Parameters

• config (MemoryConfig): The memory, persistence, and pipeline configurations.
• model (Model): Standalone model connector.
• tools (list[Any] | None): Optional tool functions/objects. Default: None.
• system_prompt (str | None): Optional core agent system instructions. Default: None.
• extra_hooks (list[HookProvider] | None): Additional agent lifecycle hooks. Default: None.
• agent_config (AgentConfig | None): Optional AgentConfig forwarded as Agent(config=). Default: None. Do not pass MemoryConfig here — that stays on config=.
• **agent_kwargs: Any additional keyword arguments are forwarded directly to the core Agent constructor.

---

build_semantic_strategy

Builds a semantic-memory strategy from an LLM, embedding backend, and vector database. Pass the result as MemoryConfig.semantic_strategy. Requires "elsai-agents[elsai-memory]==0.3.5".

from elsai.integrations.embeddings import EmbeddingBackendConfig
from elsai.integrations.vectordb import VectorBackendConfig
from elsai.integrations.memory import build_semantic_strategy

strategy = build_semantic_strategy(
    llm=model,
    embedding=EmbeddingBackendConfig(provider="azure"),
    vector=VectorBackendConfig(
        provider="chroma",
        collection_name="semantic_memory",
        persist_directory="./chroma_semantic",
    ),
    trigger_count=2,
)

Parameters

Parameter	Type	Default	Description
llm	Any	(required)	Live model used only for fact extraction
embedding	EmbeddingBackendConfig	(required)	Embedding backend settings
vector	VectorBackendConfig	(required)	Vector database backend settings
trigger_count	int	7	Extract facts when the message count is a multiple of this
collection_name	str | None	None	Chroma or Weaviate collection override
namespace	str | None	None	Pinecone namespace override (falls back to PINECONE_NAMESPACE)
top_k	int	5	Number of similar facts to retrieve
similarity_threshold	float	0.8	Minimum similarity for fact retrieval

---

build_semantic_strategy_from_env

Same builder, with providers taken from the environment (VECTOR_DB_PROVIDER, EMBEDDING_PROVIDER, and provider-specific credentials). Requires "elsai-agents[elsai-memory]==0.3.5".

from elsai.integrations.memory import build_semantic_strategy_from_env

strategy = build_semantic_strategy_from_env(llm=model)

Parameters

Parameter	Type	Default	Description
llm	Any	(required)	Live model used for fact extraction
trigger_count	int	7	Extract facts when the message count is a multiple of this
top_k	int	5	Number of similar facts to retrieve
similarity_threshold	float	0.8	Minimum similarity for fact retrieval
vector_provider	Literal["chroma", "pinecone", "weaviate"] | None	None	Override VECTOR_DB_PROVIDER
embedding_provider	Literal["azure", "bedrock"] | None	None	Override EMBEDDING_PROVIDER
collection_name	str | None	None	Chroma or Weaviate collection override
namespace	str | None	None	Pinecone namespace override (falls back to PINECONE_NAMESPACE)

---

build_similarity_config

Builds a similarity_config dict from an embedding backend and vector database. Pass the result as SimilarityRetrievalConfig.similarity_config or ElsaiSimilarityStep.similarity_config. Requires "elsai-agents[elsai-memory]==0.3.5".

from elsai.integrations.embeddings import EmbeddingBackendConfig
from elsai.integrations.vectordb import VectorBackendConfig
from elsai.integrations.memory import build_similarity_config

similarity_setup = build_similarity_config(
    embedding=EmbeddingBackendConfig(provider="azure"),
    vector=VectorBackendConfig(
        provider="chroma",
        collection_name="agent_history",
        persist_directory="./chroma_similarity",
    ),
    top_k=3,
)

Parameters

Parameter	Type	Default	Description
embedding	EmbeddingBackendConfig	(required)	Embedding backend settings
vector	VectorBackendConfig	(required)	Vector database backend settings
top_k	int	5	Number of similar messages to retrieve

---

build_similarity_config_from_env

Same builder, with providers taken from the environment (VECTOR_DB_PROVIDER, EMBEDDING_PROVIDER, and provider-specific credentials). Requires "elsai-agents[elsai-memory]==0.3.5".

from elsai.integrations.memory import build_similarity_config_from_env

similarity_setup = build_similarity_config_from_env(top_k=3)

Parameters

Parameter	Type	Default	Description
top_k	int	5	Number of similar messages to retrieve
vector_provider	Literal["chroma", "pinecone", "weaviate"] | None	None	Override VECTOR_DB_PROVIDER
embedding_provider	Literal["azure", "bedrock"] | None	None	Override EMBEDDING_PROVIDER
collection_name	str | None	None	Chroma or Weaviate collection override
namespace	str | None	None	Pinecone namespace override (falls back to PINECONE_NAMESPACE)

---

MemoryConfig

A configuration dataclass detailing session storage and context engineering.

from elsai.integrations.memory import MemoryConfig

Parameter	Type	Default	Description
run_id	str	(required)	Unique run or session identifier
role	str	"default"	Logical agent role name (appended to session key)
pipeline	list[PipelineStep]	[elsaiTrimmingStep()]	Ordered list of conversation manager sizing steps
persistence	Literal["elsai_json", "elsai_file"]	"elsai_json"	Storage backend medium
elsai_store_dir	Path	Path("elsai_sessions")	Store path for persistent JSON files
file_store_dir	Path	Path("elsai_file_sessions")	Directory for native file-session logs
summarizer_llm	Any | None	None	Language model used for summarization steps
semantic_strategy	Any | None	None	Abstract memory management strategies
similarity	SimilarityRetrievalConfig | None	None	Similarity retrieval hook config
semantic	SemanticMemoryConfig | None	None	Semantic memory hook config
multiagent_mode	str	"single"	Operational context validation hint

---

EmbeddingBackendConfig

Settings passed to build_embedding_client to create text embedding instances.

from elsai.integrations.embeddings import EmbeddingBackendConfig

Parameter	Type	Default	Description
provider	Literal["azure", "bedrock"]	(required)	Semantic embedding service name
model	str | None	None	Azure OpenAI model identifier
azure_api_key	str | None	None	Azure OpenAI API key
azure_endpoint	str | None	None	Azure OpenAI endpoint URL
azure_api_version	str | None	None	Azure API version identifier
azure_deployment	str | None	None	Azure model deployment name
aws_access_key_id	str | None	None	AWS access key ID
aws_secret_access_key	str | None	None	AWS secret access key
aws_session_token	str | None	None	Optional AWS session token
aws_region	str | None	None	AWS region name (e.g. us-east-1)
model_name	str | None	None	Bedrock embedding model name

---

VectorBackendConfig

Settings passed to build_vectordb_client to configure semantic persistence databases.

from elsai.integrations.vectordb import VectorBackendConfig

Parameter	Type	Default	Description
provider	Literal["chroma", "pinecone", "weaviate"]	(required)	Vector database platform name
collection_name	str | None	None	Target collection or class name
persist_directory	str | None	None	Chroma filesystem database location
index_name	str | None	None	Pinecone global index name
namespace	str | None	None	Pinecone query namespace
dimension	int | None	None	Input vector size dimension
connection_type	str | None	None	Weaviate context type ("local" or "cloud")
host	str | None	None	Weaviate local host
port	int | None	None	Weaviate local port
cluster_url	str | None	None	Weaviate cloud cluster URL
auth_credentials	Any | None	None	Weaviate cloud authentication API key
use_default_vectorizer	bool	False	Use native Weaviate embedding modules

---

SimilarityRetrievalConfig

Defines how historical context matching user input is searched and injected during execution.

from elsai.integrations.memory import SimilarityRetrievalConfig

Parameter	Type	Default	Description
similarity_config	dict | None	None	Connection map (vectordb & embeddings setup)
top_k	int	5	Quantity of matched historical messages to query
injection_mode	Literal["system_append", "user_preamble"]	"system_append"	Context injection location
metadata_filter	dict | None	None	Field-based metadata query filters

---

SemanticMemoryConfig

Configures retrieval and consolidation of abstract user facts across multi-session contexts.

from elsai.integrations.memory import SemanticMemoryConfig

Parameter	Type	Default	Description
user_id_key	str	"user_id"	Metadata lookup key for user identification
injection_mode	Literal["system_append", "user_preamble"]	"system_append"	Context injection location
query_from_last_user_message	bool	True	Extract search queries from the user's latest statement