LangChain Integration

The MemoryLayer LangChain integration (memorylayer-langchain) provides persistent, cross-session memory for LangChain applications. It implements LangChain’s BaseChatMessageHistory and BaseMemory interfaces, storing messages as episodic memories in MemoryLayer.

Installation

pip install memorylayer-langchain

This installs the integration package along with its dependencies: memorylayer-client, langchain-core>=0.3.0, langchain>=0.3.0, httpx, and pydantic>=2.0.0.

Prerequisites

A running MemoryLayer server:

pip install "memorylayer-server[openai]"   # or [google], [all], or pair with memorylayer-embed-server
memorylayer serve

Why MemoryLayer for LangChain?

Standard LangChain memory is lost when your application restarts. MemoryLayer provides true persistence — memory survives across sessions, restarts, and deployments.

Feature	LangChain Built-in	MemoryLayer
Persistence	In-memory only	Database-backed
Cross-session	No	Yes
Cross-platform	No	Python, TypeScript, HTTP
Memory types	Chat history	Episodic, semantic, procedural
Relationships	No	Typed relationship graph
Semantic search	No	Vector similarity

Memory Classes

The package provides three classes for different use cases:

Class	Interface	Use Case
`MemoryLayerChatMessageHistory`	`BaseChatMessageHistory`	LCEL chains (recommended)
`MemoryLayerMemory`	`BaseMemory`	Legacy `ConversationChain` and similar
`MemoryLayerConversationSummaryMemory`	`BaseMemory`	Legacy chains with summarized history

Quick Start (LCEL Chains)

MemoryLayerChatMessageHistory is the recommended approach for modern LangChain applications using LCEL (LangChain Expression Language).

from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.runnables.history import RunnableWithMessageHistory
from langchain_openai import ChatOpenAI
from memorylayer_langchain import MemoryLayerChatMessageHistory

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant."),
    MessagesPlaceholder(variable_name="history"),
    ("human", "{input}"),
])

llm = ChatOpenAI(model="gpt-4")
chain = prompt | llm

chain_with_history = RunnableWithMessageHistory(
    runnable=chain,
    get_session_history=lambda session_id: MemoryLayerChatMessageHistory(
        session_id=session_id,
        base_url="http://localhost:61001",
        workspace_id="ws_123",
    ),
    input_messages_key="input",
    history_messages_key="history",
)

# Use with any session - history persists automatically
response = chain_with_history.invoke(
    {"input": "Hello! My name is Alice."},
    config={"configurable": {"session_id": "user_alice"}},
)

# Later (even after restart), Alice's history is still available
response = chain_with_history.invoke(
    {"input": "What's my name?"},
    config={"configurable": {"session_id": "user_alice"}},
)

MemoryLayerChatMessageHistory

Drop-in replacement for LangChain chat history, designed for LCEL chains. Messages are isolated by session_id, allowing multiple conversations to be tracked independently.

history = MemoryLayerChatMessageHistory(
    session_id="conversation_1",
    base_url="http://localhost:61001",
    workspace_id="ws_123",
)

# Add messages
history.add_user_message("Hello!")
history.add_ai_message("Hi there!")

# Retrieve all messages (ordered by creation time)
messages = history.messages

# Clear all messages for this session
history.clear()

Supports use as a context manager for automatic resource cleanup:

with MemoryLayerChatMessageHistory(
    session_id="conversation_1",
    base_url="http://localhost:61001",
) as history:
    history.add_user_message("Hello!")
    messages = history.messages
# Client resources are cleaned up automatically

Parameters:

Parameter	Type	Default	Description
`session_id`	`str`	Required	Unique session identifier for isolating conversations
`base_url`	`str`	`"http://localhost:61001"`	MemoryLayer API URL
`api_key`	`str \| None`	`None`	API key for authentication
`workspace_id`	`str \| None`	`None`	Workspace ID for multi-tenant isolation
`timeout`	`float`	`30.0`	Request timeout in seconds
`memory_tags`	`list[str] \| None`	`None`	Additional tags added to all stored memories
`max_messages`	`int`	`1000`	Maximum number of messages to retrieve

Legacy Chains

MemoryLayerMemory

LangChain BaseMemory implementation for legacy chains. Drop-in replacement for ConversationBufferMemory.

from langchain.chains import ConversationChain
from langchain_openai import ChatOpenAI
from memorylayer_langchain import MemoryLayerMemory

memory = MemoryLayerMemory(
    session_id="customer_support_session_1",
    base_url="http://localhost:61001",
    workspace_id="ws_123",
)

llm = ChatOpenAI(model="gpt-4")
chain = ConversationChain(llm=llm, memory=memory)

chain.run("Hi, I need help with my order #12345")

Additional parameters (beyond the common ones listed above):

Parameter	Type	Default	Description
`memory_key`	`str`	`"history"`	Key used for memory variables
`human_prefix`	`str`	`"Human"`	Prefix for human messages in string format
`ai_prefix`	`str`	`"AI"`	Prefix for AI messages in string format
`input_key`	`str \| None`	`None`	Input key (auto-detected if not set)
`output_key`	`str \| None`	`None`	Output key (auto-detected if not set)
`return_messages`	`bool`	`False`	Return message objects instead of formatted string
`memory_tags`	`list[str]`	`[]`	Additional tags for stored memories

MemoryLayerConversationSummaryMemory

Returns AI-generated summaries instead of full conversation history. Uses MemoryLayer’s reflect endpoint to synthesize conversation context. Useful for long conversations where full history would exceed token limits.

from memorylayer_langchain import MemoryLayerConversationSummaryMemory

memory = MemoryLayerConversationSummaryMemory(
    session_id="long_conversation",
    base_url="http://localhost:61001",
    workspace_id="ws_123",
    max_tokens=500,
)

Additional parameters:

Parameter	Type	Default	Description
`summary_prompt`	`str \| None`	`None`	Custom prompt template for summarization (use `{session_id}` placeholder)
`max_tokens`	`int`	`500`	Maximum tokens for the summary
`include_sources`	`bool`	`False`	Include source memory IDs in the reflection

Migration from LangChain Memory

# Before (not persistent)
from langchain.memory import ConversationBufferMemory
memory = ConversationBufferMemory()

# After (persistent across restarts)
from memorylayer_langchain import MemoryLayerMemory
memory = MemoryLayerMemory(
    session_id="my_session",
    base_url="http://localhost:61001",
    workspace_id="ws_123",
)

For LCEL chains:

# Before (not persistent)
from langchain_community.chat_message_histories import ChatMessageHistory
history = ChatMessageHistory()

# After (persistent across restarts)
from memorylayer_langchain import MemoryLayerChatMessageHistory
history = MemoryLayerChatMessageHistory(
    session_id="my_session",
    base_url="http://localhost:61001",
    workspace_id="ws_123",
)

How It Works

Messages are stored as episodic memories in MemoryLayer with tags for session isolation:

Each message gets a session:<session_id> tag and a chat_message (or conversation_memory) tag
Messages include role and message_index in metadata for ordering
MemoryLayerChatMessageHistory also stores full message serialization data in metadata for lossless reconstruction of LangChain message objects
Retrieval uses semantic search with the session tag filter and min_relevance=0.0 to get all messages
Messages are sorted by message_index before being returned

Requirements

Python 3.12+
memorylayer-client — MemoryLayer Python SDK
langchain-core>=0.3.0 — LangChain core library
langchain>=0.3.0 — LangChain framework