{
  "schema_version": 2,
  "id": "develop/ai/context-engine/agent-memory/quickstart",
  "title": "Redis Agent Memory quickstart",
  "url": "https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/quickstart/",
  "summary": "Store and retrieve a conversation, then recall long-term memory with Python, HTTP, or the Iris CLI.",
  "aliases": [
    "/develop/ai/context-engine/agent-memory/sdk-quickstart/",
    "/develop/ai/context-engine/agent-memory/python-sdk-quickstart/",
    "/develop/ai/context-engine/agent-memory/typescript-sdk-quickstart/",
    "/develop/ai/context-engine/agent-memory/rest-api-quickstart/",
    "/develop/ai/context-engine/agent-memory/api-examples/",
    "/operate/rc/context-engine/agent-memory/use-agent-memory/"
  ],
  "tags": [
    "docs",
    "develop",
    "ai"
  ],
  "last_updated": "2026-11-03T17:55:34-08:00",
  "page_type": "content",
  "content_hash": "dc17ac0788359285e7e1035324cc5b5c9ac8ed7d16910c31e6872d35e52861b4",
  "sections": [
    {
      "id": "code-examples",
      "title": "Code examples",
      "role": "example",
      "text": "These examples connect to Iris services using SDKs or HTTP requests with curl. Follow one language throughout each walkthrough.\n\n\nBuild the memory for a travel assistant: save a conversation, retrieve it, and recall the user’s food preferences in a later conversation."
    },
    {
      "id": "before-you-begin",
      "title": "Before you begin",
      "role": "content",
      "text": "To complete this quickstart, you need:\n\n* A Redis Cloud account that can create Redis Agent Memory services.\n* An eligible Redis Cloud database, or permission to create one.\n\nThe 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.\n\nRedis Agent Memory doesn't support Flex, Active-Active, or AWS PrivateLink databases.\n\nFor the complete list, see [prerequisites and limitations](https://redis.io/docs/latest/operate/iris/agent-memory/create-service#prerequisites-and-limitations).\n\n\nFollow 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)."
    },
    {
      "id": "create-a-redis-agent-memory-service",
      "title": "Create a Redis Agent Memory service",
      "role": "content",
      "text": "1. Sign in to the [Redis Cloud console](https://cloud.redis.io/).\n1. Select **Agent Memory** under **Iris** in the navigation menu.\n1. Select **Create Agent Memory service**, or **New service** if you already have a service. Then select **Customize settings**.\n1. Enter a service name, select an eligible database, and select its `default` user.\n1. Under **Memory configuration**, enter these values:\n\n    | Setting | Value | What it controls |\n    |:--------|:------|:-----------------|\n    | **Short-term TTL** | `1` day | How long session memory is retained. |\n    | **Long-term TTL** | `365` days | How long long-term memories are retained. |\n    | **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. |\n\n1. Select **Create**.\n1. 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.\n\n> [!WARNING]\n> Redis Cloud displays the API key's token only once. If you lose it, create a new key.\n\nThe 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)."
    },
    {
      "id": "connect-to-the-service",
      "title": "Connect to the service",
      "role": "content",
      "text": "1. For Python or CLI examples, install the unified package:\n\n    [code example]\n\n1. 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.\n\n    [code example]\n\n1. Load the file in the shell where you run the examples:\n\n    [code example]\n\n1. 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`.\n\nKeep `.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.\n\nFor 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.\n\n<a id=\"check-the-service-health\"></a>\n<a id=\"save-the-connection-values\"></a>\n\n`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`.\n\n**Available in:** Python (Iris), cURL (Iris)\n\n##### Python (Iris)\n\n[code example]\n\n##### cURL (Iris)\n\n[code example]\n\n\n\n<a id=\"1-build-conversation-context-with-session-memory\"></a>"
    },
    {
      "id": "save-a-conversation",
      "title": "Save a conversation",
      "role": "content",
      "text": "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:\n\n**Available in:** Python (Iris), cURL (Iris)\n\n##### Python (Iris)\n\n[code example]\n\n##### cURL (Iris)\n\n[code example]\n\n\n\nRun the write once. Repeating it with a new idempotency key adds the same message again."
    },
    {
      "id": "retrieve-the-conversation",
      "title": "Retrieve the conversation",
      "role": "content",
      "text": "Retrieve the session to check that the message was stored:\n\n**Available in:** Python (Iris), cURL (Iris), CLI (Iris)\n\n##### Python (Iris)\n\n[code example]\n\n##### cURL (Iris)\n\n[code example]\n\n##### CLI (Iris)\n\n[code example]\n\n\n\n> [!NOTE]\n> **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.\n\n<a id=\"2-recall-automatically-extracted-information\"></a>"
    },
    {
      "id": "recall-an-extracted-preference",
      "title": "Recall an extracted preference",
      "role": "content",
      "text": "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.\n\n**Available in:** Python (Iris), cURL (Iris), CLI (Iris)\n\n##### Python (Iris)\n\n[code example]\n\n##### cURL (Iris)\n\n[code example]\n\n##### CLI (Iris)\n\n[code example]\n\n\n\n> [!NOTE]\n> **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.\n\nThe 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)."
    },
    {
      "id": "clean-up",
      "title": "Clean up",
      "role": "content",
      "text": "Delete the quickstart session and every memory owned by `quickstart-user`. `forget` is the right-to-erasure operation and cannot be undone.\n\n**Available in:** Python (Iris), cURL (Iris), CLI (Iris)\n\n##### Python (Iris)\n\n[code example]\n\n##### cURL (Iris)\n\n[code example]\n\n##### CLI (Iris)\n\n[code example]"
    },
    {
      "id": "next-steps",
      "title": "Next steps",
      "role": "content",
      "text": "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**.\n\nFollow 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)."
    }
  ],
  "examples": [
    {
      "id": "connect-to-the-service-ex0",
      "language": "bash",
      "code": "python -m venv .venv\n    source .venv/bin/activate\n    python -m pip install 'redis-iris>=1.0.0'",
      "section_id": "connect-to-the-service"
    },
    {
      "id": "connect-to-the-service-ex1",
      "language": "dotenv",
      "code": "IRIS_AGENT_MEMORY_URL='<data-plane-endpoint>'\n    IRIS_AGENT_MEMORY_STORE_ID='<store-id>'\n    IRIS_AGENT_MEMORY_API_KEY='<api-key>'",
      "section_id": "connect-to-the-service"
    },
    {
      "id": "connect-to-the-service-ex2",
      "language": "bash",
      "code": "set -a; source .env; set +a",
      "section_id": "connect-to-the-service"
    },
    {
      "id": "connect-to-the-service-ex3",
      "language": "python",
      "code": "import time\n\nfrom redis_iris.agent_memory import AgentMemory\n\nOWNER_ID = \"quickstart-user\"\nSESSION_ID = \"travel-planning-session\"\n\nmemory = AgentMemory.from_env()\nhealth = memory.client.store_health()\nprint(health.status.value)\nfor name, feature in health.features.items():\n    print(f\"  {name}: {feature.status.value}\")",
      "section_id": "connect-to-the-service"
    },
    {
      "id": "connect-to-the-service-ex4",
      "language": "bash",
      "code": "set -euo pipefail\nMEMORY_API=\"${IRIS_AGENT_MEMORY_URL%/}/iris/data/v1/agent-memory/stores/$IRIS_AGENT_MEMORY_STORE_ID\"\nOWNER_ID=quickstart-user\nSESSION_ID=travel-planning-session\ncurl --fail-with-body --silent --show-error \\\n  \"$MEMORY_API/health\" \\\n  -H \"Authorization: Bearer $IRIS_AGENT_MEMORY_API_KEY\" | jq .",
      "section_id": "connect-to-the-service"
    },
    {
      "id": "save-a-conversation-ex0",
      "language": "python",
      "code": "conversation = memory.conversation(owner=OWNER_ID, session_id=SESSION_ID)\nsaved = conversation.user(\n    \"I am visiting Tokyo and Kyoto next month. I am vegetarian and prefer spicy food.\"\n)\nprint(\"Saved event\", saved.event_id)",
      "section_id": "save-a-conversation"
    },
    {
      "id": "save-a-conversation-ex1",
      "language": "bash",
      "code": "jq -n --arg owner \"$OWNER_ID\" --arg now \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" --arg key \"$(uuidgen)\" '{\n  actorId: $owner,\n  role: \"USER\",\n  content: [{text: \"I am visiting Tokyo and Kyoto next month. I am vegetarian and prefer spicy food.\"}],\n  createdAt: $now,\n  idempotencyKey: $key\n}' > event.json\ncurl --fail-with-body --silent --show-error \\\n  -X POST \"$MEMORY_API/sessions/$SESSION_ID/events\" \\\n  -H \"Authorization: Bearer $IRIS_AGENT_MEMORY_API_KEY\" \\\n  -H 'Content-Type: application/json' --data-binary @event.json | jq .",
      "section_id": "save-a-conversation"
    },
    {
      "id": "retrieve-the-conversation-ex0",
      "language": "python",
      "code": "transcript = conversation.transcript()\nprint(\"Owner:\", transcript.owner)\nfor event in transcript.events:\n    print(event.role, event.actor_id, event.text)",
      "section_id": "retrieve-the-conversation"
    },
    {
      "id": "retrieve-the-conversation-ex1",
      "language": "bash",
      "code": "curl --fail-with-body --silent --show-error \\\n  \"$MEMORY_API/sessions/$SESSION_ID\" \\\n  -H \"Authorization: Bearer $IRIS_AGENT_MEMORY_API_KEY\" | jq '.events[] | {role, actorId, content}'",
      "section_id": "retrieve-the-conversation"
    },
    {
      "id": "retrieve-the-conversation-ex2",
      "language": "bash",
      "code": "set -euo pipefail\n\niris agent-memory sessions show travel-planning-session",
      "section_id": "retrieve-the-conversation"
    },
    {
      "id": "recall-an-extracted-preference-ex0",
      "language": "python",
      "code": "question = \"What dietary requirements and food preferences does the user have?\"\nfor _ in range(30):  # extraction runs in the background\n    known = memory.recall(question, owner=OWNER_ID)\n    if known:\n        break\n    time.sleep(10)\nprint(known.as_prompt())",
      "section_id": "recall-an-extracted-preference"
    },
    {
      "id": "recall-an-extracted-preference-ex1",
      "language": "bash",
      "code": "jq -n --arg owner \"$OWNER_ID\" '{\n  query: \"What dietary requirements and food preferences does the user have?\",\n  filter: {ownerId: {eq: $owner}},\n  limit: 5\n}' > search.json\nfor _ in $(seq 30); do  # extraction runs in the background\n  RESULTS=$(curl --fail-with-body --silent --show-error \\\n    -X POST \"$MEMORY_API/memories/search\" \\\n    -H \"Authorization: Bearer $IRIS_AGENT_MEMORY_API_KEY\" \\\n    -H 'Content-Type: application/json' --data-binary @search.json)\n  [ \"$(jq '.items | length' <<< \"$RESULTS\")\" -gt 0 ] && break\n  sleep 10\ndone\njq '.items[] | {memoryId, text, memoryType}' <<< \"$RESULTS\"",
      "section_id": "recall-an-extracted-preference"
    },
    {
      "id": "recall-an-extracted-preference-ex2",
      "language": "bash",
      "code": "iris agent-memory memories search \\\n  \"What dietary requirements and food preferences does the user have?\" \\\n  --owner quickstart-user --prompt",
      "section_id": "recall-an-extracted-preference"
    },
    {
      "id": "clean-up-ex0",
      "language": "python",
      "code": "from redis_iris.agent_memory import AgentMemory\n\nmemory = AgentMemory.from_env()\nforgotten = memory.forget(\"quickstart-user\")\nprint(f\"Deleted {forgotten.sessions} sessions and {forgotten.memories} memories\")",
      "section_id": "clean-up"
    },
    {
      "id": "clean-up-ex1",
      "language": "bash",
      "code": "set -euo pipefail\nMEMORY_API=\"${IRIS_AGENT_MEMORY_URL%/}/iris/data/v1/agent-memory/stores/$IRIS_AGENT_MEMORY_STORE_ID\"\nAUTH=\"Authorization: Bearer $IRIS_AGENT_MEMORY_API_KEY\"\n\ncurl --fail-with-body --silent --show-error -X DELETE \\\n  \"$MEMORY_API/sessions/travel-planning-session\" -H \"$AUTH\"\n\njq -n '{filter: {ownerId: {eq: \"quickstart-user\"}}, limit: 100}' > owned.json\nIDS=$(curl --fail-with-body --silent --show-error -X POST \"$MEMORY_API/memories/search\" \\\n  -H \"$AUTH\" -H 'Content-Type: application/json' --data-binary @owned.json | jq -c '[.items[].memoryId]')\nif [ \"$IDS\" != \"[]\" ]; then\n  curl --fail-with-body --silent --show-error -X POST \"$MEMORY_API/memories/bulk-delete\" \\\n    -H \"$AUTH\" -H 'Content-Type: application/json' \\\n    --data \"$(jq -n --argjson ids \"$IDS\" '{memoryIds: $ids}')\" | jq .\nfi",
      "section_id": "clean-up"
    },
    {
      "id": "clean-up-ex2",
      "language": "bash",
      "code": "set -euo pipefail\n\niris agent-memory memories forget --owner quickstart-user --yes",
      "section_id": "clean-up"
    }
  ]
}