Redis Agent Memory quickstart

Store and retrieve a conversation, then recall long-term memory with Python, HTTP, or the Iris CLI.

Build the memory for a travel assistant: save a conversation, retrieve it, and recall the user’s food preferences in a later conversation.

Before you begin

To complete this quickstart, you need:

  • A Redis Cloud account that can create Redis Agent Memory services.
  • An eligible Redis Cloud database, or permission to create one.

The database must be active, run a supported Redis version, and use a Pro or Essentials plan. It must also have a public endpoint, Redis Search, and the default user enabled.

Redis Agent Memory doesn't support Flex, Active-Active, or AWS PrivateLink databases.

For the complete list, see prerequisites and limitations.

Follow one tab throughout the page. The Python SDK and command-line interface (CLI) require Python 3.11 or later. The cURL and CLI examples use Bash and jq. The CLI reads sessions and memories but does not write them, so the CLI tab starts at Retrieve the conversation.

Create a Redis Agent Memory service

  1. Sign in to the Redis Cloud console.

  2. Select Agent Memory under Iris in the navigation menu.

  3. Select Create Agent Memory service, or New service if you already have a service. Then select Customize settings.

  4. Enter a service name, select an eligible database, and select its default user.

  5. Under Memory configuration, enter these values:

    Setting Value What it controls
    Short-term TTL 1 day How long session memory is retained.
    Long-term TTL 365 days How long long-term memories are retained.
    Extraction cadence 1 minute How often session events are processed for extraction. One minute is for this quickstart; use a longer production interval unless you need rapid extraction.

  6. Select Create.

  7. On the service's Configuration tab, select Create API key and create a key with access to the service. Copy the key and store it securely.

Warning:

Redis Cloud displays the API key's token only once. If you lose it, create a new key.

The one-minute extraction interval makes the result easier to observe in this example. For screenshots and configuration details, see create a Redis Agent Memory service.

Connect to the service

  1. For Python or CLI examples, install the unified package:

    python -m venv .venv
source .venv/bin/activate
python -m pip install 'redis-iris>=1.0.0'

  2. Open the Redis Agent Memory service in the Redis Cloud console. On the Configuration tab, copy the Store ID and the URL from the URL List. Save them with your API key in .env. Use the endpoint's base address, including https://, without the /iris/data/v1/agent-memory/... path.

    IRIS_AGENT_MEMORY_URL='<data-plane-endpoint>'
IRIS_AGENT_MEMORY_STORE_ID='<store-id>'
IRIS_AGENT_MEMORY_API_KEY='<api-key>'

  3. Load the file in the shell where you run the examples:

    set -a; source .env; set +a

  4. Expand an example to copy the complete program. Save it as quickstart.py, quickstart.cli.sh, or quickstart.sh (cURL), then run python quickstart.py, bash quickstart.cli.sh, or bash quickstart.sh.

Keep .env out of source control and keys out of application logs and model prompts. Use iris.toml profiles for several deployments.

For a self-managed service with ownership enforcement, use the authenticated client setup in Delegate a user with an agent key and replace quickstart-user with the verified user ID.

AgentMemory.from_env() reads the connection values. Its .client property exposes every Agent Memory operation; the conversation, recall, remember, and forget methods cover the common agent tasks. Check that the overall status and each feature are HEALTHY.

import time

from redis_iris.agent_memory import AgentMemory

OWNER_ID = "quickstart-user"
SESSION_ID = "travel-planning-session"

memory = AgentMemory.from_env()
health = memory.client.store_health()
print(health.status.value)
for name, feature in health.features.items():
    print(f"  {name}: {feature.status.value}")

set -euo pipefail
MEMORY_API="${IRIS_AGENT_MEMORY_URL%/}/iris/data/v1/agent-memory/stores/$IRIS_AGENT_MEMORY_STORE_ID"
OWNER_ID=quickstart-user
SESSION_ID=travel-planning-session
curl --fail-with-body --silent --show-error \
  "$MEMORY_API/health" \
  -H "Authorization: Bearer $IRIS_AGENT_MEMORY_API_KEY" | jq .

Save a conversation

Session memory is the conversation transcript. Each message is an event, stored with the conversation's session ID and the sender's actor ID. Save a user's travel plans:

conversation = memory.conversation(owner=OWNER_ID, session_id=SESSION_ID)
saved = conversation.user(
    "I am visiting Tokyo and Kyoto next month. I am vegetarian and prefer spicy food."
)
print("Saved event", saved.event_id)

jq -n --arg owner "$OWNER_ID" --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg key "$(uuidgen)" '{
  actorId: $owner,
  role: "USER",
  content: [{text: "I am visiting Tokyo and Kyoto next month. I am vegetarian and prefer spicy food."}],
  createdAt: $now,
  idempotencyKey: $key
}' > event.json
curl --fail-with-body --silent --show-error \
  -X POST "$MEMORY_API/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $IRIS_AGENT_MEMORY_API_KEY" \
  -H 'Content-Type: application/json' --data-binary @event.json | jq .

Run the write once. Repeating it with a new idempotency key adds the same message again.

Retrieve the conversation

Retrieve the session to check that the message was stored:

transcript = conversation.transcript()
print("Owner:", transcript.owner)
for event in transcript.events:
    print(event.role, event.actor_id, event.text)

curl --fail-with-body --silent --show-error \
  "$MEMORY_API/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $IRIS_AGENT_MEMORY_API_KEY" | jq '.events[] | {role, actorId, content}'

set -euo pipefail

iris agent-memory sessions show travel-planning-session
Note:

What to expect: One USER event from quickstart-user with the travel message. Redis Agent Memory adds an event ID and timestamps, so the application can recover the conversation later using only the session ID.

Recall an extracted preference

Redis Agent Memory processes session events in the background and creates long-term memories for information that may be useful in later conversations. You configured the extraction cadence to one minute when you created the service. The examples search every 10 seconds until a memory appears; the CLI runs one search, so rerun it if the result is empty.

question = "What dietary requirements and food preferences does the user have?"
for _ in range(30):  # extraction runs in the background
    known = memory.recall(question, owner=OWNER_ID)
    if known:
        break
    time.sleep(10)
print(known.as_prompt())

jq -n --arg owner "$OWNER_ID" '{
  query: "What dietary requirements and food preferences does the user have?",
  filter: {ownerId: {eq: $owner}},
  limit: 5
}' > search.json
for _ in $(seq 30); do  # extraction runs in the background
  RESULTS=$(curl --fail-with-body --silent --show-error \
    -X POST "$MEMORY_API/memories/search" \
    -H "Authorization: Bearer $IRIS_AGENT_MEMORY_API_KEY" \
    -H 'Content-Type: application/json' --data-binary @search.json)
  [ "$(jq '.items | length' <<< "$RESULTS")" -gt 0 ] && break
  sleep 10
done
jq '.items[] | {memoryId, text, memoryType}' <<< "$RESULTS"

iris agent-memory memories search \
  "What dietary requirements and food preferences does the user have?" \
  --owner quickstart-user --prompt
Note:

What to expect: Results similar to User is vegetarian and User prefers spicy food. Your application did not create these memories directly. Redis Agent Memory derived them from the session event. The exact text and memory types can vary.

The extracted memory remains searchable after the session expires, subject to the long-term memory time to live (TTL). You can change the extraction cadence and both TTLs in the Redis Agent Memory service configuration.

Clean up

Delete the quickstart session and every memory owned by quickstart-user. forget is the right-to-erasure operation and cannot be undone.

from redis_iris.agent_memory import AgentMemory

memory = AgentMemory.from_env()
forgotten = memory.forget("quickstart-user")
print(f"Deleted {forgotten.sessions} sessions and {forgotten.memories} memories")

set -euo pipefail
MEMORY_API="${IRIS_AGENT_MEMORY_URL%/}/iris/data/v1/agent-memory/stores/$IRIS_AGENT_MEMORY_STORE_ID"
AUTH="Authorization: Bearer $IRIS_AGENT_MEMORY_API_KEY"

curl --fail-with-body --silent --show-error -X DELETE \
  "$MEMORY_API/sessions/travel-planning-session" -H "$AUTH"

jq -n '{filter: {ownerId: {eq: "quickstart-user"}}, limit: 100}' > owned.json
IDS=$(curl --fail-with-body --silent --show-error -X POST "$MEMORY_API/memories/search" \
  -H "$AUTH" -H 'Content-Type: application/json' --data-binary @owned.json | jq -c '[.items[].memoryId]')
if [ "$IDS" != "[]" ]; then
  curl --fail-with-body --silent --show-error -X POST "$MEMORY_API/memories/bulk-delete" \
    -H "$AUTH" -H 'Content-Type: application/json' \
    --data "$(jq -n --argjson ids "$IDS" '{memoryIds: $ids}')" | jq .
fi

set -euo pipefail

iris agent-memory memories forget --owner quickstart-user --yes

Next steps

Generate a complete conversational agent with the AI agent builder. Select Redis Iris Conversational Assistant, then choose Python or JavaScript.

Follow the developer guide to use memory in an agent’s request cycle. For specific features, see Sessions, Custom memory types, Namespaces, and MCP.

RATE THIS PAGE
Back to top ↑