LangChain Integration
Cross-session memory
Facts persist between chats
Semantic recall
Retrieve what matters per query
Personalised replies
Context in every system prompt
Graph exploration
Hubs, paths, neighbourhoods
Setup
Install the package and configure your environment
Basic Integration
The core fetch → inject → store pattern
The core pattern: fetch relevant memories before the LLM call, inject them into the system prompt, then store the interaction afterwards.
import asyncioimport osfrom dotenv import load_dotenvfrom langchain_openai import ChatOpenAIfrom langchain_core.messages import SystemMessage, HumanMessagefrom membrain_langchain import MembrainClient, MembrainMemoryload_dotenv()client = MembrainClient(api_key=os.environ["MEMBRAIN_API_KEY"])memory = MembrainMemory(client=client, user_id="user-123")llm = ChatOpenAI(model="gpt-4o")async def chat(user_message: str) -> str: # 1. Fetch relevant memories and build a system prompt system_prompt = await memory.build_system_prompt( query=user_message, base_prompt="You are a helpful personal assistant with long-term memory.", ) # 2. Call the LLM with enriched context response = await llm.ainvoke([ SystemMessage(content=system_prompt), HumanMessage(content=user_message), ]) # 3. Store the interaction for future recall (fire-and-forget) await memory.store_interaction(user_message, response.content) return response.contentasyncio.run(chat("I love mani dum biryani"))Core Concepts
Storage, retrieval, and direct search
Membrain stores each fact as an atomic note — one discrete piece of information. The Guardian LLM automatically links related notes and decides whether new content updates an existing memory or creates a new one.
# Store a specific fact about the user (waits for Guardian to confirm)await memory.add( content="User is vegetarian and prefers South Indian cuisine", category="dietary",)# Store with a custom scope to organise memoriesawait memory.add( content="User's project deadline is end of Q2 2026", scope=["user:user-123", "project:saas-app"], category="project",)# Store a conversation turn (fire-and-forget, non-blocking)await memory.store_interaction(user_msg="I love biryani", ai_msg="Noted!")Complete Example
A full stateful personal assistant
Advanced Patterns
RAG pipelines, chat history, agent tools, and graph ops
Use MembrainRetriever as a drop-in BaseRetriever in any LangChain RAG chain. Each memory is returned as a Document with metadata.
from langchain_openai import ChatOpenAIfrom langchain_core.prompts import ChatPromptTemplatefrom langchain_core.runnables import RunnablePassthroughfrom langchain_core.output_parsers import StrOutputParserfrom membrain_langchain import MembrainClient, MembrainRetrieverclient = MembrainClient(api_key=os.environ["MEMBRAIN_API_KEY"])retriever = MembrainRetriever( client=client, user_id="user-123", k=5, include_related=True, # include semantically linked neighbour memories)prompt = ChatPromptTemplate.from_template("""Answer the question based only on the following context:{context}Question: {question}""")def format_docs(docs): return "\n\n".join(doc.page_content for doc in docs)rag_chain = ( {"context": retriever | format_docs, "question": RunnablePassthrough()} | prompt | ChatOpenAI(model="gpt-4o") | StrOutputParser())answer = await rag_chain.ainvoke("What are the user's dietary restrictions?")Two Retrieval Patterns
Automatic injection vs. agent-driven search
FastAPI Integration
Production-ready async HTTP endpoint
Reference
Constructor parameters for all classes and functions
Important Notes
async. Always use ainvoke / await instead of sync methods.MembrainMemory and also give the agent tools for deeper exploration when needed.