Agent Memory & History Pipelines

elsai Agents supports a highly flexible, modular memory system designed to manage agent state, conversation history length, and semantic contexts. Instead of relying on a static, single conversation buffer, elsai enables you to build custom memory pipelines that shape history dynamically.

With optional embedding and vector database integrations, your agents can retrieve relevant historic context and persist memory over time.

Installation

Memory features are optional extras on elsai-agents. Install only what your pipeline needs:

bash

# Chat history shaping (trim, LRU, TTL, summarize, JSON persistence)
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents[elsai-chat-history]==0.3.0"

# Embedding models (Azure OpenAI, AWS Bedrock)
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents[elsai-embeddings]==0.3.0"

# Vector stores (Chroma, Pinecone, Weaviate)
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents[elsai-vectordb]==0.3.0"

# Full vector memory stack (similarity + semantic memory)
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents[elsai-memory]==0.3.0"

Feature	Extra required
`ElsaiSlidingStep`, `ElsaiSummarizingStep`, `persistence="elsai_file"`	Base `elsai-agents` only
`ElsaiTrimmingStep`, `ElsaiSummarizationStep`, `ElsaiLRUStep`, `ElsaiTTLStep`, `persistence="elsai_json"`	`elsai-chat-history`
`ElsaiSimilarityStep` (vector indexing)	`elsai-chat-history` + `elsai-embeddings` + `elsai-vectordb` (or `elsai-memory`)
Azure / Bedrock embedding clients	`elsai-embeddings`
Chroma / Pinecone / Weaviate clients	`elsai-vectordb`
`MemoryConfig.similarity`, `MemoryConfig.semantic`	`elsai-memory`

Memory Pipeline Architecture

elsai divides memory management into two types of steps within a pipeline:

elsai-Native Conversation Managers: Simple conversation sizing filters designed to run in memory or persist to a local folder. No elsai extra required.
- Persistence: Requires persistence="elsai_file".
- Classes: ElsaiSlidingStep, ElsaiSummarizingStep.
elsai Shaping Pipeline Steps: Advanced strategies that trim, summarize, or age-out messages based on token limits or similarity scoring. Requires elsai-chat-history extra.
- Persistence: Requires persistence="elsai_json".
- Classes: ElsaiTrimmingStep, ElsaiSummarizationStep, ElsaiLRUStep, ElsaiTTLStep, ElsaiSimilarityStep.

IMPORTANT

To configure an agent with a custom memory pipeline, use the build_agent_with_memory builder function and configure MemoryConfig.

Pipeline Step Examples

Each snippet below shows how to register a step in MemoryConfig.pipeline. All examples use the same builder pattern:

python

from elsai_model.bedrock import BedrockModel
from elsai.integrations.memory import MemoryConfig, build_agent_with_memory

model = BedrockModel()  # or your provider

config = MemoryConfig(
    run_id="user-alice",
    pipeline=[...],  # step shown in each example
    persistence="...",  # must match step type — see each example
)

agent = build_agent_with_memory(config=config, model=model)
agent("Hello!")

Minimal native pipeline (base install)

No extra required. Sessions persist under elsai_file_sessions/ by default.

python

from elsai.integrations.memory import ElsaiSlidingStep

config = MemoryConfig(
    run_id="user-alice",
    persistence="elsai_file",  # required for native steps
    pipeline=[ElsaiSlidingStep(window_size=20, should_truncate_results=True)],
)

Token-safe support bot (trim by count and tokens)

Requires elsai-chat-history. Use one elsai shaping step per pipeline — the first shaping step selects the underlying strategy (TrimmingStrategy, TTLStrategy, etc.).

python

from elsai.integrations.memory import ElsaiTrimmingStep

config = MemoryConfig(
    run_id="session_123",
    persistence="elsai_json",
    pipeline=[ElsaiTrimmingStep(max_messages=30, max_tokens=8000, preserve_recent=3)],
)

Long-term RAG memory (trim + similarity retrieval)

Requires elsai-memory. Build similarity_setup using Embeddings and Vector Stores, then attach a retrieval hook:

python

from elsai.integrations.memory import ElsaiTrimmingStep, SimilarityRetrievalConfig

# similarity_setup = { "vector_database": {...}, "embedding_model": {...} }

config = MemoryConfig(
    run_id="session_123",
    persistence="elsai_json",
    pipeline=[ElsaiTrimmingStep(max_messages=15)],
    similarity=SimilarityRetrievalConfig(
        similarity_config=similarity_setup,
        top_k=3,
    ),
)

See Full example: trim + similarity retrieval for a complete runnable setup with Chroma and Bedrock.

Pipeline Steps Reference

Below are the supported pipeline strategy steps that you can register in MemoryConfig.pipeline:

`ElsaiSlidingStep`

Maintains a simple sliding window of the most recent messages.

Parameters:
- window_size (int): Number of recent messages to preserve. Default: 40.
- should_truncate_results (bool): Truncate oldest messages when exceeding size. Default: True.
Requires: Base elsai-agents only; persistence="elsai_file".

Example

python

from elsai.integrations.memory import ElsaiSlidingStep

config = MemoryConfig(
    run_id="user-alice",
    persistence="elsai_file",
    pipeline=[ElsaiSlidingStep(window_size=20, should_truncate_results=True)],
)

`ElsaiSummarizingStep`

Compacts old messages by summarizing them using a language model once the history grows.

Parameters:
- preserve_recent_messages (int): Number of recent messages to leave untouched. Default: 10.
- summary_ratio (float): Target ratio of summarization. Default: 0.3.
Requires: Base elsai-agents only; persistence="elsai_file".

Example

python

from elsai.integrations.memory import ElsaiSummarizingStep

config = MemoryConfig(
    run_id="user-alice",
    persistence="elsai_file",
    pipeline=[ElsaiSummarizingStep(preserve_recent_messages=8, summary_ratio=0.4)],
)

`ElsaiTrimmingStep`

Trims older messages once a limit on message count or token count is exceeded.

Parameters:
- max_messages (int | None): Maximum messages to allow. Default: 30.
- max_tokens (int | None): Optional token count threshold. Default: None.
- preserve_system (bool): Always keep the initial system prompt. Default: True.
- preserve_recent (int): Number of most recent messages to protect from trimming. Default: 3.
Requires: elsai-chat-history; persistence="elsai_json".

Example

python

from elsai.integrations.memory import ElsaiTrimmingStep

config = MemoryConfig(
    run_id="session_123",
    persistence="elsai_json",
    pipeline=[ElsaiTrimmingStep(max_messages=30, max_tokens=8000, preserve_recent=3)],
)

`ElsaiSummarizationStep`

Converts older messages in the active window into a high-level prose summary.

Parameters:
- trigger_count (int): Trigger summarization when window exceeds this size. Default: 20.
- preserve_system (bool): Keep system prompt. Default: True.
Requires: elsai-chat-history; persistence="elsai_json"; MemoryConfig.summarizer_llm.

Example

python

from elsai_model.bedrock import BedrockModel
from elsai.integrations.memory import ElsaiSummarizationStep

summarizer = BedrockModel(model_id="us.amazon.nova-lite-v1:0")  # a cheaper model is fine

config = MemoryConfig(
    run_id="session_123",
    persistence="elsai_json",
    pipeline=[ElsaiSummarizationStep(trigger_count=25, preserve_system=True)],
    summarizer_llm=summarizer,
)

`ElsaiLRUStep`

Performs Least Recently Used (LRU) eviction on conversations.

Parameters:
- max_messages (int): Maximum message window limit. Default: 30.
- preserve_system (bool): Keep system prompt. Default: True.
- preserve_recent (int): Protect the last N messages from eviction. Default: 5.
Requires: elsai-chat-history; persistence="elsai_json".

Example

python

from elsai.integrations.memory import ElsaiLRUStep

config = MemoryConfig(
    run_id="session_123",
    persistence="elsai_json",
    pipeline=[ElsaiLRUStep(max_messages=25, preserve_recent=4)],
)

`ElsaiTTLStep`

Ages out old messages from history based on elapsed time.

Parameters:
- ttl_seconds (int): Time-to-live threshold in seconds. Default: 3600 (1 hour).
- preserve_system (bool): Keep system prompt. Default: True.
- preserve_recent (int): Protect recent messages. Default: 5.
- use_last_accessed (bool): When True, TTL is based on last access time instead of message timestamp. Default: False.
Requires: elsai-chat-history; persistence="elsai_json".

Example

python

from elsai.integrations.memory import ElsaiTTLStep

config = MemoryConfig(
    run_id="session_123",
    persistence="elsai_json",
    pipeline=[ElsaiTTLStep(ttl_seconds=1800, preserve_recent=5)],  # 30 minutes
)

`ElsaiSimilarityStep`

Indexes conversation messages for similarity search using a configured vector database and embedding model. In most setups you can skip this step and put similarity_config on SimilarityRetrievalConfig instead (see Long-term RAG memory and the full example).

Parameters:
- similarity_config (dict | None): Vector DB and embedding client configuration. See Embeddings and Vector Stores.
Requires: elsai-chat-history; vector indexing also needs elsai-embeddings and elsai-vectordb (or install elsai-memory for the full stack).

Example

python

from elsai.integrations.memory import (
    ElsaiTrimmingStep,
    ElsaiSimilarityStep,
    SimilarityRetrievalConfig,
)

# similarity_setup = { "vector_database": {...}, "embedding_model": {...} }

config = MemoryConfig(
    run_id="session_123",
    persistence="elsai_json",
    pipeline=[
        ElsaiTrimmingStep(max_messages=20),
        ElsaiSimilarityStep(similarity_config=similarity_setup),
    ],
    # Retrieval hook required; config can live on the step or on SimilarityRetrievalConfig
    similarity=SimilarityRetrievalConfig(top_k=5),
)

Semantic Context Injection Hooks

To provide long-term associative memory, you can attach similarity search and semantic memory hooks directly through MemoryConfig. Both require the elsai-memory extra (chat-history + embeddings + vectordb):

bash

pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents[elsai-memory]==0.3.0"

1. Similarity Retrieval Config (`MemoryConfig.similarity`)

Automatically performs vector similarity search on user input against the conversation database and injects matching context.

Key parameters:
- similarity_config (dict): Connection configurations (includes vector DB client and embedding client).
- top_k (int): Number of matched messages to retrieve. Default: 5.
- injection_mode (str): "system_append" (appends to system prompt) or "user_preamble" (prepends to user message).
- metadata_filter (dict | None): Optional filter on stored message metadata.

Example — `system_append` (default)

python

from elsai.integrations.memory import ElsaiTrimmingStep, SimilarityRetrievalConfig

config = MemoryConfig(
    run_id="session_123",
    persistence="elsai_json",
    pipeline=[ElsaiTrimmingStep()],
    similarity=SimilarityRetrievalConfig(
        similarity_config=similarity_setup,
        top_k=5,
        injection_mode="system_append",
    ),
)

Example — `user_preamble` with metadata filter

python

config = MemoryConfig(
    run_id="session_123",
    persistence="elsai_json",
    pipeline=[ElsaiTrimmingStep()],
    similarity=SimilarityRetrievalConfig(
        similarity_config=similarity_setup,
        top_k=5,
        injection_mode="user_preamble",
        metadata_filter={"user_id": "alice"},
    ),
)

2. Semantic Memory Config (`MemoryConfig.semantic`)

Maintains abstract facts (like preferences) about a user across multiple sessions and injects them.

Key parameters:
- user_id_key (str): The metadata key matching the user ID. Default: "user_id".
- injection_mode (str): Where to insert the retrieved facts. Default: "system_append".
- query_from_last_user_message (bool): Use the latest user message as the semantic query. Default: True.
Requires: elsai-memory; an elsai shaping step in pipeline; MemoryConfig.semantic_strategy.

Example

python

from elsai.integrations.memory import ElsaiTrimmingStep, SemanticMemoryConfig

# semantic_strategy: elsai ChatHistoryManager strategy instance
# Configure via elsai-chat-history — shape depends on your app.

config = MemoryConfig(
    run_id="session_123",
    persistence="elsai_json",
    pipeline=[ElsaiTrimmingStep()],
    semantic_strategy=your_semantic_strategy,
    semantic=SemanticMemoryConfig(
        user_id_key="user_id",
        injection_mode="system_append",
        query_from_last_user_message=True,
    ),
)

Minimal Example: Sliding Window Only

No extras required — a good starting point before adding elsai shaping or vector memory.

python

from elsai_model.bedrock import BedrockModel
from elsai.integrations.memory import MemoryConfig, ElsaiSlidingStep, build_agent_with_memory

config = MemoryConfig(
    run_id="user-alice",
    persistence="elsai_file",
    pipeline=[ElsaiSlidingStep(window_size=20)],
)

model = BedrockModel()
agent = build_agent_with_memory(config=config, model=model)

result = agent("Remember that I prefer dark mode.")
print(result)

Full Example: Trim + Similarity Retrieval

Install first: This example uses trim + similarity with Chroma and Bedrock embeddings — install the full memory stack:
bash
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents[elsai-memory]==0.3.0"

Below is a complete example of creating an elsai agent with a custom memory pipeline, using a Chroma local vector database and Titan embeddings on Bedrock to run similarity searches.

python


import os
from pathlib import Path
from elsai_model.openai import OpenAIModel
from elsai.integrations.elsai_embeddings import EmbeddingBackendConfig, build_embedding_client
from elsai.integrations.elsai_vectordb import VectorBackendConfig, build_vectordb_client
from elsai.integrations.elsai_memory import (
    MemoryConfig,
    ElsaiTrimmingStep,
    SimilarityRetrievalConfig,
    build_agent_with_memory,
)

# 1. Initialize standalone Embedding & Vector DB clients
embed_client = build_embedding_client(
    EmbeddingBackendConfig(
        provider="bedrock",
        aws_region="us-east-1",
        model_name="amazon.titan-embed-text-v1"
    )
)

vector_db = build_vectordb_client(
    VectorBackendConfig(
        provider="chroma",
        collection_name="agent_history",
        persist_directory="./chroma_db",
    )
)

# 2. Build the similarity config dictionary
similarity_setup = {
    "vector_database": {
        "name": "chroma",
        "client": vector_db,
        "collection_name": "agent_history",
    },
    "embedding_model": {
        "name": "bedrock",
        "client": embed_client,
    },
}

# 3. Define your memory and persistent pipelines
memory_config = MemoryConfig(
    run_id="session_user_123",
    role="customer_support",
    persistence="elsai_json",
    pipeline=[ElsaiTrimmingStep(max_messages=15)],
    similarity=SimilarityRetrievalConfig(
        similarity_config=similarity_setup,
        top_k=3
    )
)

# 4. Spin up the agent using build_agent_with_memory

model = OpenAIModel(
    model_id="gpt-4o",
    client_args={"api_key": os.environ.get("OPENAI_API_KEY")},
)

agent = build_agent_with_memory(
    config=memory_config,
    model=model,
)

# 5. Run the agent
result = agent("What did we talk about during our last chat regarding database deployment?")
print(result)

Agent Memory & History Pipelines ​

Installation ​

Memory Pipeline Architecture ​

Pipeline Step Examples ​

Minimal native pipeline (base install) ​

Token-safe support bot (trim by count and tokens) ​

Long-term RAG memory (trim + similarity retrieval) ​

Pipeline Steps Reference ​

ElsaiSlidingStep ​

Example ​

ElsaiSummarizingStep ​

Example ​

ElsaiTrimmingStep ​

Example ​

ElsaiSummarizationStep ​

Example ​

ElsaiLRUStep ​

Example ​

ElsaiTTLStep ​

Example ​

ElsaiSimilarityStep ​

Example ​

Semantic Context Injection Hooks ​

1. Similarity Retrieval Config (MemoryConfig.similarity) ​

Example — system_append (default) ​

Example — user_preamble with metadata filter ​

2. Semantic Memory Config (MemoryConfig.semantic) ​

Example ​

Minimal Example: Sliding Window Only ​

Full Example: Trim + Similarity Retrieval ​

Agent Memory & History Pipelines

Installation

Memory Pipeline Architecture

Pipeline Step Examples

Minimal native pipeline (base install)

Token-safe support bot (trim by count and tokens)

Long-term RAG memory (trim + similarity retrieval)

Pipeline Steps Reference

`ElsaiSlidingStep`

Example

`ElsaiSummarizingStep`

Example

`ElsaiTrimmingStep`

Example

`ElsaiSummarizationStep`

Example

`ElsaiLRUStep`

Example

`ElsaiTTLStep`

Example

`ElsaiSimilarityStep`

Example

Semantic Context Injection Hooks

1. Similarity Retrieval Config (`MemoryConfig.similarity`)

Example — `system_append` (default)

Example — `user_preamble` with metadata filter

2. Semantic Memory Config (`MemoryConfig.semantic`)

Example

Minimal Example: Sliding Window Only

Full Example: Trim + Similarity Retrieval