# Redis Agent Memory quickstart ```json metadata { "schema_version": 2, "title": "Redis Agent Memory quickstart", "description": "Store and retrieve a conversation, then recall long-term memory with Python, HTTP, or the Iris CLI.", "categories": ["docs","develop","ai"], "tableOfContents": {"sections":[{"id":"before-you-begin","title":"Before you begin"},{"id":"create-a-redis-agent-memory-service","title":"Create a Redis Agent Memory service"},{"id":"connect-to-the-service","title":"Connect to the service"},{"id":"save-a-conversation","title":"Save a conversation"},{"id":"retrieve-the-conversation","title":"Retrieve the conversation"},{"id":"recall-an-extracted-preference","title":"Recall an extracted preference"},{"id":"clean-up","title":"Clean up"},{"id":"next-steps","title":"Next steps"}]} , "codeExamples": [{"id":"check-the-service-health"},{"id":"save-the-connection-values"},{"codetabsId":"iris_agent_memory_quickstart-stepagent-memory-connect","difficulty":"beginner","id":"agent-memory-connect","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_agent_memory_quickstart-stepagent-memory-connect"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_agent_memory_quickstart-stepagent-memory-connect"}]},{"id":"1-build-conversation-context-with-session-memory"},{"codetabsId":"iris_agent_memory_quickstart-stepagent-memory-quickstart-save","difficulty":"beginner","id":"agent-memory-quickstart-save","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_agent_memory_quickstart-stepagent-memory-quickstart-save"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_agent_memory_quickstart-stepagent-memory-quickstart-save"}]},{"codetabsId":"iris_agent_memory_quickstart-stepagent-memory-quickstart-transcript","difficulty":"beginner","id":"agent-memory-quickstart-transcript","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_agent_memory_quickstart-stepagent-memory-quickstart-transcript"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_agent_memory_quickstart-stepagent-memory-quickstart-transcript"},{"clientId":"iris-cli","clientName":"CLI (Iris)","id":"CLI (Iris)","langId":"bash","panelId":"panel_CLI (Iris)_iris_agent_memory_quickstart-stepagent-memory-quickstart-transcript"}]},{"id":"2-recall-automatically-extracted-information"},{"codetabsId":"iris_agent_memory_quickstart-stepagent-memory-quickstart-recall","difficulty":"beginner","id":"agent-memory-quickstart-recall","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_agent_memory_quickstart-stepagent-memory-quickstart-recall"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_agent_memory_quickstart-stepagent-memory-quickstart-recall"},{"clientId":"iris-cli","clientName":"CLI (Iris)","id":"CLI (Iris)","langId":"bash","panelId":"panel_CLI (Iris)_iris_agent_memory_quickstart-stepagent-memory-quickstart-recall"}]},{"codetabsId":"iris_agent_memory_quickstart_delete-stepagent-memory-quickstart-delete","difficulty":"beginner","id":"agent-memory-quickstart-delete","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_agent_memory_quickstart_delete-stepagent-memory-quickstart-delete"},{"clientId":"iris-curl","clientName":"cURL (Iris)","id":"cURL (Iris)","langId":"bash","panelId":"panel_cURL (Iris)_iris_agent_memory_quickstart_delete-stepagent-memory-quickstart-delete"},{"clientId":"iris-cli","clientName":"CLI (Iris)","id":"CLI (Iris)","langId":"bash","panelId":"panel_CLI (Iris)_iris_agent_memory_quickstart_delete-stepagent-memory-quickstart-delete"}]}] } ``` ## Code examples These examples connect to Iris services using SDKs or HTTP requests with curl. Follow one language throughout each walkthrough. 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](https://redis.io/docs/latest/operate/iris/agent-memory/create-service#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](#retrieve-the-conversation). ## Create a Redis Agent Memory service 1. Sign in to the [Redis Cloud console](https://cloud.redis.io/). 1. Select **Agent Memory** under **Iris** in the navigation menu. 1. Select **Create Agent Memory service**, or **New service** if you already have a service. Then select **Customize settings**. 1. Enter a service name, select an eligible database, and select its `default` user. 1. 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. | 1. Select **Create**. 1. On the service's **Configuration** tab, select **Create API key** and [create a key](https://redis.io/docs/latest/operate/iris/agent-memory/create-service#connect-and-create-an-api-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](https://redis.io/docs/latest/operate/iris/agent-memory/create-service). ## Connect to the service 1. For Python or CLI examples, install the unified package: ```bash python -m venv .venv source .venv/bin/activate python -m pip install 'redis-iris>=1.0.0' ``` 1. 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. ```dotenv IRIS_AGENT_MEMORY_URL='' IRIS_AGENT_MEMORY_STORE_ID='' IRIS_AGENT_MEMORY_API_KEY='' ``` 1. Load the file in the shell where you run the examples: ```bash set -a; source .env; set +a ``` 1. 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](https://redis.io/docs/latest/develop/ai/context-engine/sdk-and-cli) for several deployments. For a self-managed service with ownership enforcement, use the authenticated client setup in [Delegate a user with an agent key](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/authentication#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`. **Available in:** Python (Iris), cURL (Iris) ##### Python (Iris) ```python 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}") ``` ##### cURL (Iris) ```bash 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: **Available in:** Python (Iris), cURL (Iris) ##### Python (Iris) ```python 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) ``` ##### cURL (Iris) ```bash 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: **Available in:** Python (Iris), cURL (Iris), CLI (Iris) ##### Python (Iris) ```python transcript = conversation.transcript() print("Owner:", transcript.owner) for event in transcript.events: print(event.role, event.actor_id, event.text) ``` ##### cURL (Iris) ```bash 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}' ``` ##### CLI (Iris) ```bash 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. **Available in:** Python (Iris), cURL (Iris), CLI (Iris) ##### Python (Iris) ```python 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()) ``` ##### cURL (Iris) ```bash 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" ``` ##### CLI (Iris) ```bash 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](https://redis.io/docs/latest/operate/iris/agent-memory/create-service#memory-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. **Available in:** Python (Iris), cURL (Iris), CLI (Iris) ##### Python (Iris) ```python 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") ``` ##### cURL (Iris) ```bash 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 ``` ##### CLI (Iris) ```bash set -euo pipefail iris agent-memory memories forget --owner quickstart-user --yes ``` ## Next steps Generate a complete conversational agent with the [AI agent builder](https://redis.io/docs/latest/develop/ai/agent-builder). Select **Redis Iris Conversational Assistant**, then choose **Python** or **JavaScript**. Follow the [developer guide](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/developer-guide) to use memory in an agent’s request cycle. For specific features, see [Sessions](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/sessions), [Custom memory types](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/long-term-memory#custom-memory-types), [Namespaces](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/namespaces), and [MCP](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/mcp).