> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remem.online/llms.txt
> Use this file to discover all available pages before exploring further.
# Building a Memory-Powered Agent: Remem Quick Start
> Learn how to build an AI agent that remembers every user across sessions using Remem — no database setup, just a few extra lines of Python.
Building an AI agent that actually remembers users is one of those features that sounds hard but turns out to be surprisingly straightforward with Remem. This guide walks you through a complete, working customer support agent that loads what it knows about a user before responding, then saves what it just learned — so the next session picks up right where the last one left off.
## What We're Building
The agent follows a simple loop on every message:
1. **User sends a message** — a support question, a preference, a fact about themselves.
2. **Agent loads memory context** — `client.context()` fetches the most relevant memories for this user before the agent says a word.
3. **Agent responds** — the LLM generates a reply with full context of who this person is.
4. **Agent saves what it learned** — `client.remember()` stores the user's message as an episodic memory.
5. **Next session** — the agent already knows the user. No re-introduction needed.
## Prerequisites
Install the required packages:
```bash theme={null}
pip install remem-py openai python-dotenv
```
Create a `.env` file with your API keys:
```bash theme={null}
REMEM_API_KEY=rm_live_xxx
OPENAI_API_KEY=sk-xxx
```
Get your Remem API key from the [dashboard](https://api.remem.online). See the [authentication guide](/authentication) for details on key types and scopes.
## Steps
Load your API keys from the `.env` file using `python-dotenv`. Never hard-code keys in source files.
```python theme={null}
from dotenv import load_dotenv
import os
load_dotenv()
REMEM_API_KEY = os.getenv("REMEM_API_KEY")
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
```
Create a `RememClient` for memory and an `OpenAI` client for the LLM. You also need an `AGENT_ID` — a stable string that scopes memories to this specific agent so different bots don't share memories.
```python theme={null}
from openai import OpenAI
from remem import RememClient
openai = OpenAI(api_key=OPENAI_API_KEY)
memory = RememClient(api_key=REMEM_API_KEY)
AGENT_ID = "support_bot"
```
Before generating a response, call `client.context()` to fetch the most relevant memories for this user. Passing `current_message` lets Remem use semantic search to surface memories most relevant to what the user just said.
```python theme={null}
context = memory.context(
user_id=user_id,
agent_id=AGENT_ID,
current_message=user_message,
top_k=10,
)
```
Format the returned memories as bullet points and inject them into the system prompt. If there are no memories yet, tell the agent this is a first conversation so it doesn't fabricate context.
```python theme={null}
memory_lines = "\n".join(f"- {m.content}" for m in context.memories)
system_prompt = f"""You are a helpful customer support agent.
What you know about this user:
{memory_lines if memory_lines else "Nothing yet — this is your first conversation."}
Use this context to give personalised, relevant responses.
Never ask for information you already know."""
```
Pass the memory-enriched system prompt and the user's message to the model:
```python theme={null}
response = openai.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_message},
],
)
agent_reply = response.choices[0].message.content
```
After responding, store the user's message as an episodic memory. It will be available in all future sessions.
```python theme={null}
memory.remember(
content=user_message,
user_id=user_id,
agent_id=AGENT_ID,
memory_type="episodic",
importance=0.5,
)
```
## Complete Example
Here's the full agent in a single file:
```python theme={null}
import os
from openai import OpenAI
from remem import RememClient
from dotenv import load_dotenv
load_dotenv()
openai = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
memory = RememClient(api_key=os.getenv("REMEM_API_KEY"))
AGENT_ID = "support_bot"
def chat(user_id: str, user_message: str) -> str:
# Step 1 — Load what we know about this user
context = memory.context(
user_id=user_id,
agent_id=AGENT_ID,
current_message=user_message, # uses semantic search
top_k=10,
)
# Step 2 — Build system prompt with memory context
memory_lines = "\n".join(f"- {m.content}" for m in context.memories)
system_prompt = f"""You are a helpful customer support agent.
What you know about this user:
{memory_lines if memory_lines else "Nothing yet — this is your first conversation."}
Use this context to give personalised, relevant responses.
Never ask for information you already know."""
# Step 3 — Call the LLM
response = openai.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_message},
],
)
agent_reply = response.choices[0].message.content
# Step 4 — Save what we learned from this message
memory.remember(
content=user_message,
user_id=user_id,
agent_id=AGENT_ID,
memory_type="episodic",
importance=0.5,
)
return agent_reply
# ── Run it ────────────────────────────────────────────────────────
if __name__ == "__main__":
USER = "user_victor"
# First session
print(chat(USER, "Hi, I'm Victor. I'm based in Lagos and I build AI agents."))
print(chat(USER, "I prefer technical, concise responses — no fluff."))
# ---- New session starts here ----
# Memory persists automatically
print(chat(USER, "Hey, what do you know about me?"))
# Agent responds with: "You're Victor, based in Lagos,
# you build AI agents, and you prefer technical concise responses."
```
## Test It Out
Run the script twice to see memory persistence in action. On the first run you introduce yourself:
```
Hi! Nice to meet you, Victor. I'm here to help — what can I assist you with today?
Got it — I'll keep my responses technical and to the point.
```
On the second run, the agent remembers everything without being told again:
```
You're Victor, based in Lagos, you build AI agents, and you prefer
short technical answers. What can I help you with today?
```
The agent never asked for your name, location, or preferences — it already knew.
## Improving Your Agent
When the agent detects a key fact about the user, store it as semantic memory with high importance so it always surfaces in future sessions:
```python theme={null}
# After the LLM responds, extract and store key facts
memory.remember(
"User is based in Lagos, Nigeria",
user_id=user_id,
agent_id=AGENT_ID,
memory_type="semantic",
importance=0.9, # always surface this
)
```
When a user corrects something, find the old memory and update it in place rather than storing a contradiction:
```python theme={null}
# Find the old memory
memories = memory.recall(
"where does this user live",
user_id=user_id,
agent_id=AGENT_ID,
top_k=1,
)
if memories:
memory.update(
memory_id=memories[0].id,
user_id=user_id,
agent_id=AGENT_ID,
new_content="User moved from Lagos to Abuja",
)
```
Session-specific context — like an order number the user is asking about — should expire automatically rather than cluttering long-term memory:
```python theme={null}
memory.remember(
"User is currently asking about order #4521",
user_id=user_id,
agent_id=AGENT_ID,
memory_type="episodic",
ttl_days=1, # gone tomorrow
)
```
## What's Next
Add persistent memory to a LangGraph agent with two extra nodes
Handle Remem errors gracefully so your agent never crashes in production
Full reference for the remember endpoint — all parameters and response fields
Full reference for the context endpoint — ranked memory retrieval