Quickstart: Store and Retrieve Memories with Remem

This guide walks you through everything you need to go from zero to a memory-powered AI agent. By the end you will have installed the SDK, stored a memory, retrieved it by meaning rather than keywords, and built a working agent that remembers its users across sessions.

Before You Start

You need two things before writing any code:

A Remem API key — get one free at dev.remem.online. No credit card required.
Python 3.10 or higher — check with python --version.

Your API key looks like rm_live_xxxxxxxxxxxxxxxxxxxx. It is delivered to your inbox once and cannot be shown again. Copy it somewhere safe immediately. If you lose it, email support@remem.online to have a new one issued.

Steps

Install the SDK

Install remem-py from PyPI:

pip install remem-py

Verify the installation completed correctly:

python -c "from remem import RememClient; print('Remem installed successfully')"

If you see Remem installed successfully, you are ready to move on. If you see an import error, make sure you are running Python 3.10+ and that you installed into the correct virtual environment.

Set Your API Key

Never hardcode your API key in source code. Store it in a .env file and load it at runtime:

# .env
REMEM_API_KEY=rm_live_xxx
OPENAI_API_KEY=sk-...

Then initialise the client in Python:

import os
from dotenv import load_dotenv
from remem import RememClient

load_dotenv()

client = RememClient(
    api_key=os.getenv("REMEM_API_KEY"),
    base_url="https://api.remem.online",
)

You can also pass the key directly during initialisation for quick local testing — but never commit that to version control:

# Quick local test only — do not commit this
client = RememClient(api_key="rm_live_xxx")

Store Your First Memory

Call remember() to persist something your agent has learned about a user:

result = client.remember(
    "User prefers concise bullet points over long paragraphs",
    user_id="user_123",
    agent_id="support_bot",
    memory_type="semantic",
    importance=0.8,
)

print(result.id)
# 775263ee-73af-4416-9804-1f274048ae08

The returned UUID is this memory’s permanent identifier. You can use it later to update the memory with client.update() or remove it with client.forget(). Store it if you need fine-grained control — otherwise Remem manages the lifecycle for you.

Load Context at Session Start

At the beginning of every conversation — before the user says anything — call context() to pre-load what your agent already knows:

context = client.context(
    user_id="user_123",
    agent_id="support_bot",
    top_k=10,
)

print(f"Loaded {context.total} memories")
for m in context.memories:
    print(f"  [{m.importance}] {m.content}")

# [0.8] User prefers concise bullet points over long paragraphs

context() ranks memories by a combination of recency and importance — not by query similarity — so it surfaces what matters most about this user right now, even before you know what the conversation will be about.

Search Semantically

When the user says something that needs specific context, call recall() with a natural-language query:

memories = client.recall(
    query="what are this user's communication preferences?",
    user_id="user_123",
    agent_id="support_bot",
    top_k=5,
    min_score=0.0,
)

for m in memories:
    print(f"[{m.score:.3f}] {m.content}")

# [0.891] User prefers concise bullet points over long paragraphs

The query used completely different words from the stored memory — “communication preferences” versus “bullet points over long paragraphs”. Remem found the match because it searches by meaning, not by keywords. The hybrid score of 0.891 reflects a strong semantic match combined with a high importance weight.

Inject Memory Into Your Agent

Here is the complete pattern for a memory-powered conversational agent. It loads context before every reply, builds a personalised system prompt, calls the LLM, and saves what the user shared:

import os
from openai import OpenAI
from remem import RememClient
from dotenv import load_dotenv

load_dotenv()

openai_client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
remem = RememClient(api_key=os.getenv("REMEM_API_KEY"))

AGENT_ID = "support_bot"


def chat(user_id: str, user_message: str) -> str:

    # 1 — Load context before responding
    context = remem.context(
        user_id=user_id,
        agent_id=AGENT_ID,
        current_message=user_message,
        top_k=10,
    )

    # 2 — Build system prompt with memory
    memory_lines = "\n".join(f"- {m.content}" for m in context.memories)
    system_prompt = f"""You are a helpful assistant.

What you already know about this user:
{memory_lines if memory_lines else "Nothing yet — this is a new user."}

Use this context to give personalised responses.
Never ask for information you already know."""

    # 3 — Call the LLM
    response = openai_client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user",   "content": user_message},
        ],
    )
    reply = response.choices[0].message.content

    # 4 — Save what the user told you
    remem.remember(
        content=user_message,
        user_id=user_id,
        agent_id=AGENT_ID,
        memory_type="episodic",
    )

    return reply


# Run it
print(chat("user_123", "Hi, I'm Victor. I build AI agents in Lagos."))
print(chat("user_123", "What do you know about me?"))
# Agent: "You're Victor, you build AI agents, and you're based in Lagos."

On the second message, the agent already knows who Victor is — because the first message was saved as a memory and loaded back via context() at the start of the second call. No conversation history is passed between calls. The memory layer handles persistence entirely.

What’s Next

Authentication

Understand API key format, safe storage patterns, and error codes

Memory Types

Learn when to use episodic versus semantic memory

LangGraph Guide

Add persistent memory to a LangGraph agent

Error Handling

Handle authentication, rate-limit, and network errors in production

Get Started

Concepts

Guides

Quickstart: Store and Retrieve Memories with Remem

Before You Start

Steps

What’s Next

Authentication

Memory Types

LangGraph Guide

Error Handling

​Before You Start

​Steps

​What’s Next

Authentication

Memory Types

LangGraph Guide

Error Handling

Before You Start

Steps

What’s Next