Handle Remem Errors Gracefully in Your Production Agent

Memory operations are network calls, and network calls can fail. The difference between a brittle agent and a production-ready one is whether it handles those failures gracefully. Remem raises specific, typed exceptions for every failure scenario so you can catch exactly the right error and respond appropriately — whether that means logging and continuing, notifying the user, or halting immediately.

Exception Hierarchy

Remem exposes five exception classes, each mapping to a specific HTTP status code and failure scenario:

Exception	HTTP Code	When It Happens
`RememError`	any	Base class — catches any Remem error not matched by a subclass
`AuthenticationError`	401	Invalid, missing, or revoked API key
`PlanLimitError`	402	Memory limit reached on your current plan
`MemoryNotFoundError`	404	Memory ID does not exist (already deleted or wrong ID)
`DuplicateMemoryError`	409	Near-identical memory (≥95% similarity) already stored

Importing Exception Classes

Import all exception classes at the top of your module:

from remem import RememClient
from remem.exceptions import (
    RememError,            # base — catches any Remem error
    AuthenticationError,   # 401 — bad or missing API key
    PlanLimitError,        # 402 — hit memory limit for your plan
    MemoryNotFoundError,   # 404 — memory ID does not exist
    DuplicateMemoryError,  # 409 — near-identical memory already stored
)

Handling Each Exception

AuthenticationError — 401

Raised when your API key is invalid, missing, or revoked. This is not a transient error — retrying with the same key will always fail.

from remem import RememClient
from remem.exceptions import AuthenticationError
import os

client = RememClient(api_key=os.getenv("REMEM_API_KEY"))

try:
    client.remember("something", user_id="u1", agent_id="bot")
except AuthenticationError:
    # Key is wrong or missing
    # Do not retry — fix the key first
    print("Invalid API key. Check your REMEM_API_KEY environment variable.")
    raise SystemExit(1)

Never retry on AuthenticationError. The key is wrong — retrying with the same key will always fail. Fix the key and redeploy.

PlanLimitError — 402

Raised when your account has reached its memory limit for the current plan. You can still read and search memories — only new writes are blocked.

from remem.exceptions import PlanLimitError

try:
    client.remember("something", user_id="u1", agent_id="bot")
except PlanLimitError as e:
    print(f"Memory limit reached: {e.detail}")
    print("Upgrade at remem.online/pricing")

Handle it gracefully in your agent by skipping the write rather than crashing:

try:
    client.remember(user_message, user_id=user_id, agent_id=agent_id)
except PlanLimitError:
    # Continue the conversation — just do not store this message
    pass

Your agent can still read and search memories when the limit is hit — only new writes are blocked. Your agent will not go blind; it just stops learning new things until you upgrade.

MemoryNotFoundError — 404

Raised when you try to update or delete a memory ID that does not exist — either because it was already deleted or the ID is wrong.

from remem.exceptions import MemoryNotFoundError

try:
    client.update(
        memory_id="non-existent-id",
        user_id="u1",
        agent_id="bot",
        new_content="something",
    )
except MemoryNotFoundError:
    # Memory was already deleted or ID is wrong
    # Safe to ignore in most cases
    pass

DuplicateMemoryError — 409

Raised when you try to store content that is already present at 95% similarity or above. This is Remem protecting your memory store from redundant data — treat it as a no-op.

from remem.exceptions import DuplicateMemoryError

try:
    client.remember(
        "User is based in Lagos, Nigeria",
        user_id="u1",
        agent_id="bot",
    )
except DuplicateMemoryError:
    # Already stored — this is safe to ignore
    pass

DuplicateMemoryError is not a real error in most cases — it means Remem protected your database from storing the same fact twice. Ignore it silently in production.

RememError — Catch-All

RememError is the base class for all Remem exceptions. Use it as a fallback to catch unexpected errors — server errors, rate limits, or anything else not matched by a specific subclass.

from remem.exceptions import RememError

try:
    client.remember("something", user_id="u1", agent_id="bot")
except RememError as e:
    print(f"Remem API error {e.status_code}: {e.detail}")

Production-Ready Pattern

This is the pattern to use in any production agent. Both helper functions are guaranteed never to raise — your agent continues regardless of what Remem returns.

from remem import RememClient
from remem.exceptions import (
    RememError,
    AuthenticationError,
    PlanLimitError,
    MemoryNotFoundError,
    DuplicateMemoryError,
)
import logging
import os

logger = logging.getLogger(__name__)
client = RememClient(api_key=os.getenv("REMEM_API_KEY"))


def safe_remember(content: str, user_id: str, agent_id: str) -> bool:
    """
    Store a memory safely. Returns True if stored, False if skipped.
    Never raises — your agent continues regardless.
    """
    try:
        client.remember(content, user_id=user_id, agent_id=agent_id)
        return True

    except DuplicateMemoryError:
        # Already stored — not an error
        return False

    except PlanLimitError:
        # Hit plan limit — log it, continue without storing
        logger.warning("Memory limit reached for user %s", user_id)
        return False

    except AuthenticationError:
        # Key is wrong — this needs immediate attention
        logger.error("Remem authentication failed — check REMEM_API_KEY")
        return False

    except RememError as e:
        # Unexpected error — log and continue
        logger.error("Remem error %s: %s", e.status_code, e.detail)
        return False


def safe_recall(query: str, user_id: str, agent_id: str) -> list:
    """
    Search memories safely. Returns empty list on any error.
    Never raises — your agent always has something to work with.
    """
    try:
        return client.recall(query, user_id=user_id, agent_id=agent_id)

    except AuthenticationError:
        logger.error("Remem authentication failed — check REMEM_API_KEY")
        return []

    except RememError as e:
        logger.error("Remem recall error %s: %s", e.status_code, e.detail)
        return []

Retry Logic

For transient server errors (5xx), use exponential backoff before giving up. Don’t retry on client errors (4xx) — those require a code or configuration fix.

import time
from remem.exceptions import RememError


def remember_with_retry(
    content: str,
    user_id: str,
    agent_id: str,
    retries: int = 3,
) -> bool:
    for attempt in range(1, retries + 1):
        try:
            client.remember(content, user_id=user_id, agent_id=agent_id)
            return True
        except RememError as e:
            if e.status_code >= 500 and attempt < retries:
                # Server error — wait and retry
                wait = 2 ** attempt   # 2s, 4s, 8s
                time.sleep(wait)
                continue
            # Not a server error or out of retries
            raise
    return False

Error Reference

HTTP Code	Exception Class	Meaning	What To Do
401	`AuthenticationError`	Invalid or missing API key	Fix the key — do not retry
402	`PlanLimitError`	Memory limit reached	Upgrade plan or skip storing
404	`MemoryNotFoundError`	Memory ID does not exist	Safe to ignore
409	`DuplicateMemoryError`	Memory already exists	Safe to ignore
5xx	`RememError`	Server error	Retry with exponential backoff

Production Checklist

Run through this checklist before shipping any agent that uses Remem in production.

Wrap every remember() call — DuplicateMemoryError is common and safe to ignore

Handle PlanLimitError gracefully — agent should continue without storing, not crash

Log AuthenticationError immediately — it means your key needs fixing

Return an empty list from recall() on error — agent degrades gracefully with no context

Add retry logic for 5xx errors — transient server issues should not kill your agent

Get Started

Concepts

Guides

Handle Remem Errors Gracefully in Your Production Agent

Exception Hierarchy

Importing Exception Classes

Handling Each Exception

AuthenticationError — 401

PlanLimitError — 402

MemoryNotFoundError — 404

DuplicateMemoryError — 409

RememError — Catch-All

Production-Ready Pattern

Retry Logic

Error Reference

Production Checklist

​Exception Hierarchy

​Importing Exception Classes

​Handling Each Exception

​AuthenticationError — 401

​PlanLimitError — 402

​MemoryNotFoundError — 404

​DuplicateMemoryError — 409

​RememError — Catch-All

​Production-Ready Pattern

​Retry Logic

​Error Reference

​Production Checklist

Exception Hierarchy

Importing Exception Classes

Handling Each Exception

AuthenticationError — 401

PlanLimitError — 402

MemoryNotFoundError — 404

DuplicateMemoryError — 409

RememError — Catch-All

Production-Ready Pattern

Retry Logic

Error Reference

Production Checklist